refactor(ui): converge typography onto --leading-*/--font-weight-*/--tracking-* tokens (#520 PR1) by Astro-Han · Pull Request #526 · apache/maka

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han · 2026-07-04T17:49:00Z

Summary

First PR of #520 (design-spec governance tracking issue). Converges the three ungoverned typography dimensions — line-height, font-weight, letter-spacing — onto tokens aligned to a Tailwind scale subset, plus folds font-variation-settings into font-weight and cleans up font-family minor drift. Same converge-contract pattern as #430 PR2 / #448.

Tokens added (maka-tokens.css)

Token	Value	Aligned to	Sites
`--leading-none/tight/snug/normal`	1 / 1.25 / 1.375 / 1.5	Tailwind `leading-*` (drop relaxed/loose, 0 sites)	~160
`--font-weight-normal/medium/semibold/bold`	400 / 500 / 600 / 700	Tailwind `font-*` (drop thin/extralight/light/extrabold/black)	~205
`--tracking-normal/wide/wider/widest`	0 / 0.025em / 0.05em / 0.1em	Tailwind `tracking-*` (no tight — CJK-first, roadmap §1.6 bans tightening CJK)	~62
`--font-serif`	Georgia, "Times New Roman", Times, serif	(onboarding hero)	1

Bridged to Tailwind utilities via @theme inline in styles.css (same inline-bridge pattern as --text-* / --space-*), so var(--leading-*) in CSS and leading-* in TSX share one source.

Convergence

line-height: 15 distinct bare values + one 20px magic → 4 tokens. Snug is the one tier that can't be cut (40 sites at 1.3-1.4 are 13/11px small-text dense zones; collapsing to tight/normal is ±0.1-0.2, visible on small text). Largest delta: .maka-bubble-assistant 1.68 → 1.5 (chat core, magic-number fix).
font-weight: 8 distinct (incl. mid-axis 550/620/650/680 from variable Geist) → 4 tokens. Snap: 550/620/650 → semibold (600), 680 → bold (700).
letter-spacing: 14 distinct (incl. CJK mis-tightening -0.018em) → 4 tokens. All negatives snap to --tracking-normal (0) per CJK ban. ALL-CAPS labels use --tracking-wider/widest (roadmap §4.1). 1px → --tracking-widest (0.1em ≈ 1.3px @ 13px).
font-variation-settings: dropped .maka-hero h1's "wght" 550, "wdth" 105 — wght folds into font-weight token, wdth:105 one-off dropped (hero stays distinct via size + weight + leading alone).
font-family minor: var(--mono-font, monospace) → var(--font-mono) (was a typo'd token name); redundant var(--font-mono, ui-monospace, …) fallbacks → var(--font-mono); Georgia, serif → var(--font-serif) (tokenized).

Contracts

Two new converge-contract tests, mirroring typography-converge-contract.test.ts:

font-weight-converge-contract.test.ts — bans bare font-weight numbers + normal/bold/lighter/bolder + bare weight in font: shorthand; whitelists 4 --font-weight-* tokens + inherit/initial/unset/revert; pins values; asserts @theme inline bridging.
letter-spacing-converge-contract.test.ts — bans bare letter-spacing em/px/normal/negative; whitelists 4 --tracking-* tokens + 0 + literals; pins values; asserts bridging.

(line-height-converge-contract.test.ts landed in the first commit pair of this PR.)

Verification

line-height-converge-contract: 9/9 pass
font-weight-converge-contract: 8/8 pass
letter-spacing-converge-contract: 7/7 pass
Full desktop suite: 1910/1910 pass (no regressions; +15 from the two new contracts)
renderer build: success (Tailwind v4 @theme inline same-name --leading-* / --font-weight-* / --tracking-* bridging verified)
Dual-theme screenshots (turn-narrative + first-run, light + dark): visual deltas are barely-perceptible as expected — .maka-hero h1 is the most visible (wdth 105 drop + 550→600 + tracking -0.018→0); confirmed acceptable.

Commits

refactor(ui): converge line-height onto --leading-* tokens — 25 css, 4 tokens + bridge + ~160 replacements
test(ui): lock line-height converge contract — 9 tests
refactor(ui): converge font-weight + letter-spacing + font-family minor — 28 css, 9 tokens + bridge + ~267 replacements + font-variation fold + font-family cleanup
test(ui): lock font-weight + letter-spacing converge contracts — 15 tests

Out of scope (next PRs in #520)

PR2 visual-state & motion tokens (opacity / focus-ring / motion duration+amplitude), PR3 anti-layout-shift, PR4 layout surface & sizing, PR5 Base UI small migrations + style-hook, PR6 Base UI large migrations.

Tracking issue: #520.

@theme

Add 4 --leading-* tokens (none/tight/snug/normal = 1/1.25/1.375/1.5) aligned to a Tailwind leading-scale subset (drop relaxed/loose, zero sites). Bridge --leading-* to Tailwind leading-* utilities in @theme inline. Replace ~160 bare line-height values across renderer CSS with var(--leading-*), incl. the 20px magic (plan-reminders.css) and 1.68 bubble-assistant. Snug is the one tier that can't be cut: 40 sites at 1.3-1.4 (13/11px small-text dense zones) collapse to tight/normal at ±0.1-0.2, visible on small text. Tracking issue: #520.

@theme

Add line-height-converge-contract.test.ts mirroring typography-converge-contract: ban bare line-height numbers/px/rem/normal, whitelist 4 --leading-* tokens + em + inherit/initial/unset/revert/0; pin token values; assert Tailwind @theme inline bridging. Tracking issue: #520.

@theme

…or (#520 PR1) Add --font-weight-* (4-tier: normal/medium/semibold/bold = 400/500/600/700) + --tracking-* (4-tier: normal/wide/wider/widest = 0/0.025em/0.05em/0.1em; no tight — CJK-first, roadmap §1.6 bans tightening CJK) + --font-serif tokens; bridge to Tailwind font-*/tracking-* utilities in @theme inline. Replace ~205 font-weight (550/620/650→semibold, 680→bold) + ~62 letter-spacing (negatives→normal) values across renderer CSS. Drop font-variation-settings "wght" 550 "wdth" 105 on .maka-hero h1 (wght folds into font-weight token, wdth one-off dropped). Fix font-family: var(--mono-font,…)→var(--font-mono), redundant fallbacks→var(--font-mono), Georgia,serif→var(--font-serif). Tracking issue: #520.

@theme

…PR1) Add font-weight-converge-contract.test.ts + letter-spacing-converge-contract.test.ts mirroring line-height-converge-contract: ban bare font-weight numbers/normal/bold + bare letter-spacing em/px/normal/negative; whitelist --font-weight-*/--tracking-* tokens + literals; pin token values; assert @theme inline bridging. Tracking issue: #520.

P2: readAllRendererCss now fails closed — removed the catch that silently degraded to reading only styles.css when @import expansion broke, so a missing/bad import surfaces instead of skipping styles/* (exported expandCssImports for direct testing). P2: ban non-literal font: shorthand via shared findFontShorthandOffenders — covers font-weight + line-height bypass vectors (font: 600 var(--font-size-ui) …, font: var(--font-size-ui)/1.4 …). Renderer CSS only uses font: inherit today, so the whitelist is literals-only (inherit/initial/unset/revert); no regex arms race over which shorthand component is bare. Value is extracted and checked against the literal set rather than using a negative lookahead (which backtracks \s* and matches font: inherit as an offender). P2: pin regex now ends with \s*; so drifted values fail — --font-weight-normal: 4000; no longer prefix-matches 400, --tracking-normal: 0.02em; no longer prefix-matches 0, --leading-normal: 1.55; no longer prefix-matches 1.5. P3: extracted shared font: shorthand scanner into css-test-helpers (partial de-dup of the three converge contracts; full table-driven merge left out to keep per-property invariant docs readable). New css-test-helpers.test.ts: bad @import throws with the missing path, font: shorthand literal vs non-literal, comment stripping. Tracking issue: #520.

P2: replace scattered assert.match pin regex with shared assertTokenPinnedOnce. assert.match only proved a correct declaration existed somewhere — a later overriding declaration (--font-weight-normal: 400; --font-weight-normal: 450;) still passed because the first match satisfied it, so a drifted override would slip through. assertTokenPinnedOnce parses maka-tokens.css custom property declarations and asserts each typography token is declared exactly once with the exact value (fails on duplicates and on a single drifted value). New css-test-helpers exports: parseCssCustomProps, assertTokenPinnedOnce. css-test-helpers.test.ts: assertTokenPinnedOnce unit tests (duplicate override, single drift, missing token, comment strip). Three converge contracts: pin tests use assertTokenPinnedOnce; dropped the now-redundant pin regex negative tests (they tested the old regex mechanism, now superseded). Reviewer negative cases locked: --font-weight-normal: 400; --font-weight-normal: 450; / --leading-normal: 1.5; --leading-normal: 1.55; / --tracking-normal: 0; --tracking-normal: 0.02em; all fail with 'exactly once'. Tracking issue: #520.

@theme

P2: the styles.css @theme inline bridge aliases (--leading-*/--font-weight-*/--tracking-* → var(--*)) were still checked with assert.match, so a duplicate overriding declaration (--leading-normal: var(--leading-normal); --leading-normal: 1.55;) would pass because the first match satisfied assert.match. Reused the custom property parser: bridge tests now use assertCustomPropPinnedOnce (exactly-once + exact value), same as token pin tests. Renamed assertTokenPinnedOnce → assertCustomPropPinnedOnce (the helper was never token-specific — it parses any custom property; the new name fits both maka-tokens.css definitions and styles.css bridge aliases). Reviewer negative cases locked: --font-weight-normal: var(--font-weight-normal); --font-weight-normal: 450; / --leading-normal: var(--leading-normal); --leading-normal: 1.55; / --tracking-normal: var(--tracking-normal); --tracking-normal: 0.02em; all fail with 'exactly once' (css-test-helpers.test.ts). Tracking issue: #520.

Astro-Han added 4 commits July 5, 2026 01:51

Astro-Han force-pushed the refactor/typography-converge branch from dfb801b to e772d93Compare July 4, 2026 17:54

Astro-Han added 3 commits July 5, 2026 02:20