refactor(client): drop rationale comments, name the icon control width

Review feedback from @malenacaroline on #3915: the theme pass carried too
many comments, and they explain decisions rather than code.

Remove 64 lines of rationale prose across 12 files. Everything taken out
described *why* a value was chosen - which palette entry MUI derives what
from, why a weight stays put, why a gradient lifts off `main`. That belongs
in the PR description and commit history, not in an `sx` block where it
goes stale the moment the palette moves.

Two comments deliberately stay:
- `StatusBox`: alpha() *replaces* the alpha channel rather than multiplying,
  so the faint grid depends on `divider` being an opaque hex. That is a live
  trap, not a design note.
- `Table`: the `isRowSelected` JSDoc documents a real limitation of the prop
  (desktop table only), which a caller needs to know.

Section labels (// Blues, // Hooks) are untouched.

Also name the last bare number beside CONTROL_HEIGHT: the header icon links
were `width: 36` next to `height: CONTROL_HEIGHT`. Now ICON_CONTROL_WIDTH.
The other two `width: 36` sites are a switch track and a logo tile - same
number, unrelated concepts, left alone.

Gates: tsc clean, build ✓, format-check clean, lint unchanged from develop
(12 errors, all pre-existing in untouched files).
This commit is contained in:
gorkem-bwl committed 2026-09-03 13:30:34 -04:00
1 parent de8eb53dd4
commit 17822b7cf6
13 files changed
+9 -66

No files matched your search

@@ -8,9 +8,6 @@ interface IconProps {
color?: string;
}
// 16 is the house size: 17 call sites ask for it explicitly against 2 for 20,
// and the sidebar clamps to 16 in CSS. A 20px default put icons above the cap
// height of the 13px text they sit beside.
const Icon = ({ icon: Icon, size = 16, strokeWidth = 1.5, color }: IconProps) => {
return (
<Icon
@@ -37,12 +37,6 @@ export const OfflineBanner = ({ visible }: OfflineBannerProps) => {
left: 0,
right: 0,
zIndex: theme.zIndex.snackbar,
// `error.dark` rather than `main`: in dark mode `main` is light
// enough that MUI derives near-black contrastText, which reads as
// a warning rather than an outage on the one surface where
// urgency matters. `dark` keeps a solid red bar with white text
// in both modes, and leaves `main` alone for the ~30 places that
// use it as text or a chart mark on a dark ground.
backgroundColor: theme.palette.error.dark,
color: "#FFFFFF",
px: theme.spacing(8),
@@ -6,7 +6,7 @@ import { Link as RouterLink } from "react-router-dom";
import { useTranslation } from "react-i18next";
import { useTheme } from "@mui/material/styles";
import { ChevronLeft, HelpCircle, FileText, Code } from "lucide-react";
import { CONTROL_HEIGHT } from "@/Utils/Theme/constants";
import { CONTROL_HEIGHT, ICON_CONTROL_WIDTH } from "@/Utils/Theme/constants";
import type { ReactNode } from "react";
@@ -110,9 +110,6 @@ export const PageHeader = ({
fontSize: 14,
color: theme.palette.text.secondary,
lineHeight: 1.55,
// Wide enough to hold a one-line page description at this
// size; still a cap, so it wraps rather than running the
// full width of a large monitor.
maxWidth: "108ch",
}}
>
@@ -145,7 +142,7 @@ export const PageHeader = ({
display: "inline-flex",
alignItems: "center",
justifyContent: "center",
width: 36,
width: ICON_CONTROL_WIDTH,
height: CONTROL_HEIGHT,
color: theme.palette.text.secondary,
borderRight:
@@ -19,15 +19,8 @@ export const GradientBox = ({ children, palette, sx, interactive }: GradientBox)
const isSmall = useMediaQuery(theme.breakpoints.down("md"));
const isLight = theme.palette.mode === "light";
const paper = theme.palette.background.paper;
// In light mode `paper` is white, and lightening white is a no-op - the
// gradient collapses flat. Darken slightly towards the page ground instead.
const paperStart = isLight ? darken(paper, 0.02) : lighten(paper, 0.08);
const paperEnd = paper;
// Both ends stay close to `main` so MUI's derived `contrastText` still
// applies - that is white on the dark light-mode fills and near-black on
// the lighter dark-mode ones, so a bigger lift would break one or other.
// `light` is a mid-tone used for status dots and chart marks, too pale to
// use here, so the lift comes off `main` instead.
const bg = palette
? `linear-gradient(135deg, ${lighten(theme.palette[palette].main, 0.12)} 0%, ${theme.palette[palette].main} 100%)`
: `linear-gradient(135deg, ${paperStart} 0%, ${paperEnd} 100%)`;
@@ -220,10 +220,6 @@ export function DataTable<
"& .MuiTableBody-root .MuiTableRow-root:last-child .MuiTableCell-root": {
borderBottom: "none",
},
// Cells paint `background.paper`, so a background set on the row
// never shows. Selection and hover both have to be applied at
// cell level, and selection has to come first so hover layers
// on top of it rather than replacing it.
"& .MuiTableBody-root .MuiTableRow-root.is-selected .MuiTableCell-root": {
backgroundColor: theme.palette.action.selected,
},
@@ -49,10 +49,6 @@ export const Tab = (props: CustomTabProps) => {
alignItems: "flex-start",
color: theme.palette.text.secondary,
"&.Mui-selected": {
// Weight stays put, as on ToggleButton: bolding the active tab
// widens it, shifting every tab to its right and dragging the
// indicator to a moving target. Colour and the indicator are
// already carrying the state.
color: theme.palette.primary.main,
},
"&:hover": {