refactor(ui): converge font-size to two-tier token scale (#430 PR2) by Astro-Han · Pull Request #437 · apache/maka

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.

Astro-Han · 2026-07-02T16:57:53Z

Summary

Ban bare Npx/Nremfont-size across all renderer CSS. 413 sites collapse into a three-tier token scale: --font-size-base (15px), --font-size-ui (13px), and --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15.

Why

Issue #430 PR2. Maka's frontend had 436 bare font-size values across 22 CSS files — 9/10/11/12/12.5/13/13.5/14px plus rem-encoded meta (0.7-0.875rem under the 15px root). These were drift, not a deliberate ladder. The radius converge contract (#406) proved this pattern works; this PR applies it to typography.

An initial 2-tier attempt (base 15 / ui 13) was too aggressive: 150+ sites of dense meta (9-11px timestamps, badges, kbd, overlines) inflated to 13px, flattening the visual hierarchy between low-priority meta and chrome text. A third tier at 11px restores that distinction. Peer research across 8 projects confirmed 3-4 tiers is the norm; 2 was the fewest.

Closes#430

Scope

Changed:

Token definitions (maka-tokens.css): three-tier scale — --font-size-base: 15px (body/prose), --font-size-ui: 13px (chrome/control), --font-size-caption: 11px (dense meta).
Tailwind alias (styles.css @theme inline): --text-xs → caption, --text-sm → ui, --text-base → base.
CSS convergence (22 files, 413 sites):
- 9/10/10.5/11/11.5px and 0.68-0.78rem → var(--font-size-caption) (196 sites)
- 12/12.5/13/13.5/14px and 0.8-0.95rem → var(--font-size-ui) (217 sites)
- 15px → var(--font-size-base)
Heading em scaling: h1-h4 from px to em (1.4667/1.2667/1.0667/0.9333em off body 15).
Contract test: bans bare Npx/Nrem; pins 15/13/11; verifies Tailwind alias mappings.
Docs (docs/design-system.md §1.3): synced to three-tier scale.

Rebased onto main (11 new commits). Conflicts with PR #441 (--accent semantic split) resolved by keeping main's color tokens + our font-size tokens.

Not included:

TSX inline fontSize scanning (0 sites exist).
Spacing converge (refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430 PR3) — separate PR.
Icon size converge — out of scope per refactor(ui): converge design-token magic numbers (motion, typography, spacing) #430.

Verification

npm test — 1680 tests, 1678 pass, 2 fail. Both failures are pre-existing on main (PR refactor(ui): split --accent into semantic aliases, lock call-site governance #441 changed --accent to --link in tool-activity.tsx but visible-copy-hygiene-contract.test.ts still expects --accent). Not caused by this PR.
npm run build — succeeds.
typography-converge-contract.test.ts — all 8 cases pass.
Screenshot capture for 6 scenarios (permission-destructive, first-run, streaming-sidebar, artifact-pane, settings-general, settings-appearance).

Review responses

P1 docs inconsistency: Fixed — docs/design-system.md §1.3 synced to three-tier (15/13/11).
P1 permission text at caption: Pushed back — all permission dialog selectors were originally 11px; caption (11px) is faithful convergence with zero visual regression. The suggestion to "restore to ui" would increase 11px→13px, a visual redesign beyond this PR's scope.
P2 mechanical vs semantic caption mapping: Acknowledged as follow-up — semantic re-evaluation is a separate audit, not a blocker on token convergence.
P2 em bypass in test: Pushed back — em is relative; the contract bans absolute values (px/rem), not relative scaling. Selector whitelists for em would be brittle.

Ban bare Npx/Nrem font-size across all renderer CSS. 413 sites collapse into three tiers: --font-size-base (15px), --font-size-ui (13px), --font-size-caption (11px). Bubble h1-h4 switch from px to em off body 15. Mapping: 9/10/10.5/11/11.5px + sub-0.8rem -> --font-size-caption (11px) 12/12.5/13/13.5/14px + 0.8-0.95rem -> --font-size-ui (13px) 15px -> --font-size-base (15px) Tailwind: --text-xs→caption, --text-sm→ui, --text-base→base. Contract test bans bare px/rem; pins 15/13/11; verifies alias mappings. Docs synced to three-tier scale.

…430 PR2) - settingsField small: --font-size-ui (13px) → --font-size-base (15px) to clear the 14px legibility floor noted in the prior comment. - contract test: remove unused EM_RE and duplicate bare px/rem scan; 8 tests → 7, same coverage.

Scanner now flags bare px/rem inside font: shorthand (e.g. 'font: 12px/1.4 var(--font-sans)') so the bypass route is locked. Added positive and negative cases; 9 tests, all pass.