refactor(ui): govern all border-radius via --radius-* tokens (#406 gap 4) by Astro-Han · Pull Request #418 · apache/maka

Astro-Han · 2026-07-01T21:14:50Z

Summary

Migrate every hardcoded border-radius: Npx literal in renderer CSS and every rounded-[Npx] arbitrary value in TSX to the token system (--radius-control 6px / --radius-surface 8px / --radius-modal 12px / --radius-pill 999px). Delete the --card-radius and --agents-content-area-radius intermediate variables; their call sites now reference the canonical tokens directly.

Why

Part of #406 (gap 4 — radius governance). The audit in #406 found 292 border-radius declarations across 14 distinct values and two competing token systems. This PR consolidates to a single token system with per-component-type radius tiers. Gap 4 of 6; #406 remains open until all gaps land.

Scope

Changed:

175+ CSS sitesborder-radius: Npx → var(--radius-*) across 20 CSS files
26 TSX sitesrounded-[Npx] / rounded-[.25rem] → rounded-[var(--radius-*)] across 6 TSX files
Deleted intermediate variables: --card-radius: 6px and --agents-content-area-radius: 12px removed; call sites now use var(--radius-control) / var(--radius-modal) directly
Intermediate value classification (by component type, not nearest):
- 2/3/4/5px → control (6px): button / input / chip / kbd / inline code / scrollbar thumb / checkbox
- 7px → control (6px) or surface (8px): action button / input / nav item → control; alert banner → surface
- 9px → surface (8px): icon plate / logo plate
- 10px → surface (8px) or modal (12px): card / toast / notice / table / tool-card → surface; modal → modal
- Non-symmetric shorthand (e.g. blockquote 0 8px 8px 0) → per-corner token references
Contract test: radius-converge-contract.test.ts now scans the full CSS and TSX source tree, banning bare Npxborder-radius or rounded-[Npx] that is not a var(--radius-*) reference (0 / 50% / inherit / initial / calc(...token...) exempt)
Affected tests: 6 contract tests that asserted literal Npx values updated to assert token references
Docs: docs/design-system.md §1.4 updated with alias system and new contract rule
Comments: chat.tsx "Values are LITERAL" comment updated to reflect token adoption

Not included:

gap 5 accent semantic split call-site migration (216 var(--accent) sites)
gap 6 borders-as-shadows
Deleting input.tsx / textarea.tsx (gap 1 cleanup, zero imports but out of scope)

Verification

npm --workspace @maka/desktop test: 1645 tests pass, 0 fail
npm run typecheck: all packages pass
Storybook design-tokens story visual check: control / surface / modal / pill tiers render correctly

User-facing impact

Visual changes are minimal: some 10px cards/notices move to 8px, 9px logos move to 8px, 7px buttons move to 6px. These are 1-2px differences that do not affect layout (radius does not occupy layout space).

Reviewer notes

Intermediate value classification is by component type, not nearest rounding. A 10px modal goes to 12px (not 8px); a 10px card goes to 8px (not 12px).
--card-radius and --agents-content-area-radius intermediate variables are deleted; call sites use tokens directly. If per-surface tuning is needed later, semantic aliases can be re-introduced.
chat.tsx bubble user variant comment previously said "the visual refresh, not this governance pass, owns adopting the scale" — this PR adopts the token per user confirmation (full convergence).

…l scan, value pinning Address code review on PR #418: - P2: replace permissive --radius-* regex with explicit whitelist (control/surface/modal/pill + button/sm/md/lg/xl aliases); typos and private tokens now fail the contract - P2: scan border-{top,bottom}-{left,right}-radius longhand and rounded-{t,tr,tl,b,br,bl,l,r}-[...] directional utilities, not just shorthand and rounded-[...] - P2: pin each canonical token's resolved px value (6/8/12/999) so a silent edit of --radius-modal is caught - P3: collapse CSS collection to a single readAllRendererCss() entry — it already recursively unfolds styles.css imports (which include maka-tokens.css and the styles/ tree); remove the duplicate scans - P3: sync the stale header comment (was '8px modal / 10px code block', now matches docs/design-system.md §1.4: surface 8px, modal 12px)

…contract test Address code review round 2 on PR #418: P2: Button/Input/Toggle/SelectItem/TabsTrigger used rounded-md/rounded-lg (surface 8px) but are control components — must use rounded-sm (control 6px). Migrate all control components in packages/ui to rounded-sm; surface components (TabsList, SelectPopup, ToggleGroup, Item, Menu popup, Alert, Toolbar, EmptyState) keep rounded-md. input/textarea/input-group primitives also move to rounded-sm with calc(var(--radius-sm)-1px) inner ring. session-list-panel nav rows and row actions move to rounded-sm. P2: ALLOWED_ROUNDED_ARBITRARY and CALC_TOKEN_RE only matched the shape --radius-* without checking the whitelist. Extract isWhitelistedVar() and isWhitelistedCalc() that both validate against RADIUS_TOKEN_WHITELIST. CSS var(), CSS calc(), TSX rounded-[var(...)], and TSX calc(...) now share one validation path. Add negative-case tests: typos (var(--radius-modla)) and private tokens (var(--radius-private)) must fail in both var() and calc() contexts. P3: Collapse collectTsxOffenders into a single pass (was called twice). Remove docs/design-system.md text-content assertion (not a production behavior check). Remove redundant >12px CSS test (covered by whitelist + value pinning). Contract is now 4 focused tests: CSS whitelist, TSX whitelist, control-class usage, token value pinning.

…, logical radius Address code review round 3 on PR #418: P2: Badge was classified as control (6px) but docs/design-system.md §1.4 requires badge to use --radius-pill (999px). Both Badge implementations (packages/ui/src/ui.tsx and packages/ui/src/primitives/badge.tsx) moved to rounded-[var(--radius-pill)]. Contract updated to assert Badge uses pill tier, not control. P2: control contract only banned rounded-md/lg (negative check) but did not positively assert the expected class. Replace with a COMPONENT_RADIUS table that maps each component to its expected tier (control/surface/pill) and asserts both presence of the correct class and absence of wrong-tier classes. A control component using rounded-[var(--radius-surface)] now fails. P2: calc() only validated token whitelist, not direction. calc(var (--radius-modal) + 20px) would pass and break the 12px cap. isWhitelisted Calc now rejects +Npx addition and multipliers > 1; only subtraction (inner-ring shrink like calc(var(--radius-sm) - 1px)) passes. Negative cases added. P2: TSX regex missed Tailwind logical radius utilities (rounded-s/se/ ee-[...]) and CSS regex missed logical longhand (border-start-start- radius etc.). Both scan paths extended with s/e/ss/se/es/ee and logical properties. P3: Removed packages/ui/src/primitives/textarea.tsx from control contract — it has zero production imports (dead primitive, gap 1 cleanup target). Adding test dependencies on dead modules cements them. input.tsx and input-group.tsx kept (still imported by search-modal.tsx and index.ts).

… match guard Address code review round 4 on PR #418: P2: .maka-code used --radius-control (6px) and .maka-skeleton-card used --radius-modal (12px) with a stale comment referencing the old 'cards 12, modals 16-18' scale. Both are surface elements per docs/design-system.md §1.4 — code block and card both map to --radius-surface (8px). Fixed both declarations and deleted the stale comment. Added a selector contract that asserts these two classes use var(--radius-surface). P2: checkComponentTier() silently passed when its regex matched 0 blocks, giving false confidence. InputPrimitive was such a case — the file exports 'function Input', not 'InputPrimitive'. Added a matched counter; 0 matches now reports 'stale contract entry or renamed component'. Removed the dead primitives/input.tsx entry (zero production imports, gap 1 deletion target). P2: isWhitelistedCalc was a blacklist (rejected +Npx and *[2-9]), leaving gaps like *1.5, /0.5, and --1px. Replaced with a positive allowlist regex: only calc(var(--radius-whitelisted) - <positive>px) passes. Added negative cases for multiplication, division, double-negative, and zero subtraction. P3: Removed primitives/input.tsx from COMPONENT_RADIUS — it is a dead shadcn leftover with zero production imports. Keeping it in the contract would cement a module slated for deletion.

…tract Address code review round 5 on PR #418: P2: .settingsPermissionRefresh (covers shared Button) used --radius-surface (8px) — Button is control, changed to --radius-control (6px). .settingsCapabilityGuidanceActions code (block code) used --radius-control (6px) — block code is surface, changed to --radius-surface (8px). P2: Component tier contract lacked modal tier — DialogPopup uses rounded-xl (modal 12px) but was not covered. Added 'modal' to Tier union and TIER_CLASS map, added DialogPopup to COMPONENT_RADIUS. Expanded selector contract to cover .maka-composer-inner (modal), .settingsPermissionRefresh (control), and .settingsCapabilityGuidanceActions code (surface). Verified: --radius-button has 3 production call sites in maka-tokens.css (lines 840, 866, 1604) — not a dead alias, kept in whitelist.

… --radius-button Address code review round 6 on PR #418: P2: TSX scanner missed Tailwind rounded-(...) shorthand (e.g. rounded-(--thumb-size) in menu.tsx) and rounded-4xl+ utilities. Extended ROUNDED_RE to cover rounded-(...), directional/logical rounded-*- (...) and rounded-[2-9]xl. Added negative-case tests for rounded-(--private), rounded-se-(--private), rounded-4xl, rounded-9xl. Non-radius custom properties like --thumb-size are exempt (not --radius-* tokens). P2: Component tier contract only checked class names, not arbitrary/calc token references inside the block. InputGroup (control) had **:[textarea_button]:rounded-[calc(var(--radius-md)-1px)] — a surface token inside a control component. Fixed to --radius-sm. Contract now extracts every --radius-* reference in the component block and validates against TIER_TOKENS[expectedTier]. A control component using --radius-md/surface now fails. P3: --radius-button was a --radius-control alias with 3 production call sites (.maka-sidebar-row, .maka-sidebar-button, line 1604 button). All 3 migrated to --radius-control directly. Deleted the alias definition, docs reference, whitelist entry, and alias value pinning. Added a stale-reference contract test that asserts --radius-button appears nowhere in renderer CSS or maka-tokens.css. Verified: zero grep hits across the entire codebase.

…can, thumb-size cleanup Address code review round 7 on PR #418 with a full-repo tier audit instead of point-fixing only reported selectors. Audit method: grepped every border-radius: var(--radius-*) declaration across all renderer CSS (~200 sites), judged each against the four-tier system (control 6px / surface 8px / modal 12px / pill 999px), and fixed all 26 mismatched selectors in one pass. Tier fixes (26 selectors): modal→surface: .settingsPermissionIntro, .settingsPermissionError, .settingsCapabilityRow, .settingsOsPermissionList, .settingsHealthIntro, .settingsHealthError, .settingsBotList button, .settingsBotHero, .settingsBotStatusGrid div, .settingsRows, .settingsNotice, .settingsAboutLogo, .settingsAboutPrivacy, .settingsWechatQrFrame, .settingsWechatQrState, .providerUnavailableNotice, .maka-firstrun-list, .maka-first-run-checklist, .providerLogo, .maka-turn[search-highlight] surface→modal: .settingsModal, .maka-palette-modal modal→control: .maka-onboarding-quickchat-submit, .enabledEmptyChip, .maka-browser-address surface→control: .settingsWechatQrClose Selector contract expanded from 5 to 28 entries, covering every selector that was wrong in the audit. The contract now catches any future tier drift on these high-value selectors. TSX scanner: extended ROUNDED_RE to cover directional/logical scale classes (rounded-s-2xl, rounded-t-3xl, rounded-se-4xl, etc.). Added negative cases. menu.tsx: rounded-(--thumb-size) was a non-radius custom property exempt from token governance. The thumb is a square element that morphs to a rounded shape on active — rounded-full is the correct static state (a square with border-radius == side length IS a circle). Removed the --thumb-size exemption from the contract. Existing tests updated: permissions-unified-card-contract (list 12→8px surface), command-palette-a11y-copy-contract (palette 8→12px modal).

…humb-size exception Address code review round 8 on PR #418: P2: .settingsHealthRefresh (Button override) used --radius-surface, changed to --radius-control (consistent with .settingsPermissionRefresh). P2: 5 card/panel selectors used --radius-control but are surface elements: .maka-plan-shell (page card), .maka-daily-review-panel, .maka-daily-review-info, .maka-daily-review-archive-body (daily review cards), .settingsPermissionSummaryTile (summary tile). All changed to --radius-surface. P2: selector-tier contract upgraded from presence-check to all-blocks-must-match semantics. Every border-radius in every matching block for each listed selector must equal the expected token. A stale entry (selector not found) also fails. Added the 6 newly-fixed selectors to the contract (now 34 entries). P3: --thumb-size morph animation exception deleted. The active-state morph value rounded-[var(--thumb-size)/calc(var(--thumb-size)*1.10)] is replaced with rounded-full — the thumb is always circular (a square with border-radius == side length is a circle), so border-radius animation is unnecessary. No exceptions remain in the TSX scanner.

…p 4) Migrate every hardcoded border-radius literal (Npx) in renderer CSS and every rounded-[Npx] arbitrary value in TSX to the token system (--radius-control 6px / --radius-surface 8px / --radius-modal 12px / --radius-pill 999px). Delete the --card-radius and --agents-content-area-radius intermediate variables; their call sites now reference the canonical tokens directly. Intermediate values (2/3/4/5/7/9/10px) collapse to the nearest component-type tier: button/input/chip/kbd/inline-code → control, card/popover/code-block/toast/notice/table → surface, modal/composer → modal, pill/badge/dot → pill. Non-symmetric shorthand (e.g. blockquote 0 8px 8px 0) now uses per-corner token references. The radius-converge-contract test now scans the full CSS and TSX source tree, banning any bare Npx border-radius or rounded-[Npx] that is not a var(--radius-*) reference (0/50%/inherit/initial exempt). Six existing contract tests that asserted literal Npx values are updated to assert the token references. Closes#406 gap 4.