[Task] Design token system debt log (drift, redundancy, dual systems)

[Astro-Han]

Goal

Single tracking log for all design-token system debt — redundant aliases, source-of-truth drift between docs/DESIGN.md and runtime theme.css, and parallel-system overlaps. No commitment to clear every entry on a fixed timeline. Entries are resolved opportunistically as the UI rewrite work in #601 (and follow-ups) touches the relevant surfaces.

Scope and intent

This issue is intentionally not a cleanup PR queue. It is a record so the next person who edits typography, colors, spacing, or theme files can pull from a single place rather than rediscovering the same debts. Each entry below states the current observed state and what decision is required, not a scheduled fix.

Findings

Category A · Real dead tokens and stray hardcoded values (low-risk to clean opportunistically)

Either duplicate an existing token, live outside the docs/DESIGN.md spec, or are hardcoded values that should be token references. Safe to delete or fix the next time someone is in the relevant file for an unrelated reason.

• --font-size-hierarchy (13px, identical to --font-size-base). 9 callsites in packages/ui are all mechanical, no semantic distinction.
• --brand-danger and --brand-danger-hover. Upstream-inherited aliases for --error. docs/DESIGN.md uses --error exclusively for the danger semantic (see L326-330). Zero callsites in packages/.
• Hardcoded border-radius: 6px in packages/ui/src/components/message-part.css L42 (user-message-attachment) and L374. Value is correct (matches --radius-sm = 6px from the project frontmatter) but missed token-ization. Two callsites, both safe to replace with var(--radius-sm).

Category B · DESIGN.md ↔ runtime drift (needs source-of-truth decision)

Where the design source and the runtime disagree. Resolve when the affected component surface is next touched.

• Light --surface-sunken value. docs/DESIGN.md L135 and docs/design/colors_and_type.css declare #F4F0EC as an independent third neutral tier reserved for inline code and code-block headers. packages/ui/src/styles/theme.css declares #faf9f7 (identical to --bg-cream) and carries the comment light alias → bg-cream; no third neutral tier. The runtime stance contradicts the design source. Decide which is canonical: either DESIGN.md drops the third tier (matching runtime), or runtime restores #F4F0EC (matching design).
• Dark --surface-sunken is too dark to see inline-code decoration. docs/DESIGN.md reserves --surface-sunken for inline code; in dark theme its value (#16130F) sits below --bg-base (#1A1714), so the decoration disappears. docs/design/ui_kits/desktop/styles.css already routes .pw-agent-text code, .pw-chip, .pw-tool, .pw-input, .pw-kbd to --surface-base (one tier above bg) instead. The fix is either lifting the dark sunken value, or dropping the "sunken" semantic and renaming the token to reflect the actual usage.

Category C · Parallel-system overlap (resolves with rewrite progress)

Two parallel token systems express the same concept. Picking one and deprecating the other is a real design call, not a cleanup.

• Typography: --type-* vs --font-size-*. docs/DESIGN.md L195-208 specs nine --type-* composite tokens (each bundles weight, size, line-height, family). Only --type-body is actually used (three callsites). The remaining eight (--type-display, --type-h1, --type-h2, --type-h3, --type-caption, --type-mono, --type-mono-small, --type-kbd) have zero component callsites. Components use the older --font-size-* family (45+ callsites for --font-size-small alone). Decide whether the rewrite migrates components to font: var(--type-*), or whether --type-* is dropped in favor of the existing per-property tokens.
• --font-size-small (13px, identical to --font-size-base). 45 callsites in packages/ui plus three .ts files. The name implies smaller-than-base but the value is the same. Three options to evaluate when the typography decision above is taken: delete and migrate to --font-size-base; re-tune --font-size-small to 12px so the scale (small < base < large) reads honestly; or keep --font-size-small and remove --font-size-base from the public surface.
• Radii: Tailwind --radius-* vs project --radius-* (same name, different scale, different values). Tailwind utility radii in packages/ui/src/styles/tailwind/index.css L59-63 are rem-based (xs=0.125rem / sm=0.25rem / md=0.375rem / lg=0.5rem / xl=0.875rem → 2 / 4 / 6 / 8 / 14 px). Project radii in docs/DESIGN.md frontmatter L72-76 are explicit px (sm=6 / md=10 / lg=14 / pill=9999). Same name md disagrees on value: Tailwind rounded-md = 6px, project var(--radius-md) = 10px. Components mixing the two namespaces get unexpectedly different geometry — for example dock attachments (packages/app/src/components/prompt-input/image-attachments.tsx) use Tailwind rounded-md and render at 6px, while W1 preview docs/design/preview/message-flow.html originally locked file chips at var(--radius-md) = 10px. Decide whether to align values, or document the dual-namespace as the deliberate design (Tailwind = utility shorthand for fine-grained pixel control, project tokens = product-design coarser scale).

Category D · Already resolved (recorded for completeness, no action)

Closed locally in docs/ only (which is .git/info/exclude'd per AGENTS.md and not in git):

• --icon-chev was reverted before reaching packages/. All preview and scratch files now use the existing --icon-base. The chevron paragraph in docs/DESIGN.md was rewritten to drop the new-token rationale; the 12-px chev size carries the secondary-symbol hierarchy on its own.
• --bg-strong removed. Nine real callsites in docs/design/ui_kits/desktop/styles.css rewired to --surface-base (same value as the deleted alias). Dead declarations purged from colors_and_type.css and nine preview files.
• docs/DESIGN.md frontmatter deviations: ledger expanded from two entries to thirteen, capturing previously inline-only exceptions (kbd off-grid padding, dialog text-only buttons, branch dirty three-button dialog, popover inline search row, discard armed button, branch popover width 280, settings nav width 240, hotkey hover dashed-to-solid, app picker multi-color icon, file-type vendor icons, Lucide library) so the ledger is now the only formal record of sanctioned exceptions.

Not problems (forward-looking spec, keep)

Tokens with zero current callsites that are nonetheless intentional. They are part of the docs/DESIGN.md frontmatter scale and reserved for future components.

• --radius-pill (9999px). docs/DESIGN.md frontmatter L75 explicitly defines the pill tier ("pill": 9999). Reserved for badge / chip / tag / avatar shapes the rewrite has not yet built.
• --space-xl (20px), --space-2xl (24px), --space-3xl (32px), --space-4xl (48px), --space-5xl (64px). docs/DESIGN.md frontmatter L62-70 declares the full xs through 5xl spacing scale. Reserved for layouts the rewrite has not yet built.

Pointers

• Replaces slice fix(config): wait for background installs on dispose #3 U from [Feature] UI rewrite v2 Area A: message flow modular rollout #601 inventory comment 4456099179. The proposed --fg-secondary and --icon-chev tokens both turned out to be redundant with existing ones, so slice U was cancelled (see [Feature] UI rewrite v2 Area A: message flow modular rollout #601 comment 4459413309).
• docs/DESIGN.md frontmatter deviations: ledger is the only formal record of sanctioned design exceptions; new exceptions go there, not inline in body text.
• Likely files for any future Category-A cleanup: packages/ui/src/styles/theme.css, packages/ui/src/theme/themes/pawwork.json, packages/ui/src/styles/utilities.css, packages/ui/src/components/list.css, packages/ui/src/components/tabs.css, packages/ui/src/components/toast.css, packages/ui/src/components/message-part.css.

Verification (when an entry is eventually closed)

Whichever Category-A entry ships as a cleanup PR:

• bun --cwd packages/app run typecheck clean.
• bun test packages/ui green (theme-parity test ensures pawwork.json mirrors theme.css).
• grep -rn <removed-token> packages/ returns zero hits after the PR.
• Visual diff zero for direct aliases (Category A); visual diff inspection required for Category B and C entries that actually change rendered values.

Execution mode

Agent should investigate and propose a plan first for any Category B or C entry. Category A can be cleaned directly when the surrounding code is being modified for another reason; do not open a standalone PR just for Category A.

[Astro-Han]

Token system redesign — design spec (iteration 10)

Resolves the typography composite-token / --surface-sunken mis-use / radii dual-namespace / Cat A dead-code debts catalogued above. Nine prior rounds of crosscheck plus full consumer-surface grep collapsed five earlier assumptions: (a) --surface-sunken is not "reserved for inline code" — it has 24 callsites serving five distinct semantic roles, of which only 1 is inline code; (b) PawWork already has the right tokens for hover and active states (--row-hover-overlay, --row-active-overlay); (c) callsite-level migration decisions cannot all be pre-judged in the spec — only the architecture and the unambiguous bug-fixes can; (d) --radius-xs and --radius-xl are NOT zero-callsite Tailwind defaults — rounded-xs ships at one production site, rounded-xl at six, and var(--radius-xs) at one CSS site; (e) markdown.css .shiki (code-block fence) currently has no background at all, only a border — applying --code-surface is an additive change introducing a new alpha overlay, not a literal replacement. v9 sweeps the xs/xl callsites in PR0 before deleting the tokens; treats .shiki as an explicit additive change; covers DESIGN.md frontmatter rounded.pill and three preview-HTML prose references; and corrects the PR1 baseline note (the soon-to-be-deleted Tailwind aliases currently DO resolve through theme.css primitives on dev). PR0 retires Cat A, closes radii dual-namespace including xs/xl/pill sweep, introduces --code-surface, and fixes the four icon-button hover sites that explicitly violate docs/DESIGN.md ### Icon button; everything else about --surface-sunken is preserved as a legitimate "secondary content surface" token. PR1 and PR2 cover typography and are unchanged in scope from earlier rounds (only verification wording fixed).

Architecture

CSS variables in packages/ui/src/styles/theme.css are the source of truth for theme-dependent values (typography, surface, color, radii). The Tailwind theme surface is packages/ui/src/styles/tailwind/index.css (Tailwind v4 CSS-first @theme block). For radii, theme.css :root and the Tailwind @theme block both declare --radius-sm/md/lg with identical pixel values — the redundant-but-synchronized declaration lets plain CSS consumers (component CSS files that only import theme.css; preview HTML doing the same) and Tailwind-generated utilities share the same value. The theme-parity test enforces value equality between the two declaration sites.

Typography uses @utility rules (one per role) in tailwind/index.css to bundle font-family + font-size + font-weight + line-height + (display/h1 only) letter-spacing into a single class. A parallel docs/design/preview/_utilities.css mirrors the nine roles as plain CSS classes referencing the same theme.css variables. A new typography-utility-parity test asserts the two surfaces enumerate the same nine roles and reference the same CSS variables, normalizing the selector wrapper difference (@utility name {…} vs .name {…}) and comparing the per-role property set with its var() references.

--surface-sunken is preserved as a generic secondary content surface. Earlier iterations of this spec planned to retire it on the assumption that its only consumer was inline code; that assumption was wrong (full grep returned 24 callsites in five role categories, only one of which is inline code). The runtime token continues to serve tabs, session-turn surfaces, accordion content, the app-level inset background, the settings-keybinds active row, the dialog-connect-provider swatch, and a handful of test/playground references. docs/DESIGN.md L179 is rewritten to describe --surface-sunken as a secondary content surface (light value #FAF9F7 is an alias of --bg-cream; dark value #16130F is independently one tier below --bg-cream to give dark mode a deeper inset surface). The earlier "reserved for inline code" language was aspirational and does not match runtime usage.

--code-surface is introduced as a separate single token for inline code and code-block backgrounds, using alpha overlay (Notion / Radix path) — this gives code its own visual identity (neutral grey via alpha) distinct from the secondary content surface (warm cream). The token is theme-aware: one name, three declaration sites (light :root, dark [data-color-scheme="dark"], @media (prefers-color-scheme: dark) first-paint mirror) following the project's standard theme-dependent pattern. Its light value rgba(0, 0, 0, 0.04) happens to coincide with --hover-overlay and --row-hover-overlay, but the three are intentionally separate semantic tokens — a future tone shift to one should not drag the others along.

No primitive layer for typography (no --font-size-13 raw-value tokens). Semantic tokens hold the numeric values directly. PawWork has nine typography roles and a single developer; an extra indirection level offers little value and adds reading friction.

Token inventory

New CSS variables in theme.css :root

Typography (PR1, 29 net new):

Nine --font-size-* (display/h1/h2/h3/body/caption/mono/mono-small/kbd) at 28/20/16/13/13/13/13/12/11px. Nine --font-weight-* (display/h1/h2/h3/kbd at 500; body/caption/mono/mono-small at 400). Nine --line-height-* at unitless ratio (1.3/1.3/1.5/1.5/1.6/1.3/1.5/1.5/1.3). Two --letter-spacing-* (display at -0.32px, h1 at -0.16px) promoted from previously-inline values. The two existing --font-family-* tokens (sans/mono, theme.css L20-21) are reused unchanged.

Code surface (PR0, 1 new theme-dependent variable):

A single --code-surface declared in all three theme blocks — light :root at rgba(0, 0, 0, 0.04); dark [data-color-scheme="dark"] and @media (prefers-color-scheme: dark) first-paint mirror at rgba(255, 255, 255, 0.06). Theme switching is automatic at consumer sites. Both inline code and code block reference this single token. Semantically separate from --hover-overlay, --row-hover-overlay, and --row-active-overlay despite value overlap with the first two.

Total new variables across the redesign: 30 (29 typography + 1 code surface). Two --font-family-* tokens reused unchanged.

Modified Tailwind @theme block (packages/ui/src/styles/tailwind/index.css)

Border radius (PR0): change --radius-sm/md/lg values from rem-based Tailwind defaults (0.25rem/0.375rem/0.5rem = 4/6/8px) to PawWork project pixel values (6/10/14px), matching theme.css :root L70-72. Delete --radius-xs and --radius-xl AFTER sweeping their callsites (see "PR0 callsite migrations" below): rounded-xs (1 site) migrates to rounded-sm (2px → 6px); rounded-xl (6 sites) migrates to rounded-lg (the remap makes --radius-lg = 14px, exactly matching the old --radius-xl value of 0.875rem = 14px, so this is a value-preserving rename); var(--radius-xs) (1 CSS site) migrates to var(--radius-sm). Do not add --radius-pill; Tailwind v4's built-in rounded-full covers the "fully rounded" utility, and the three preview-HTML consumers of var(--radius-pill) migrate to inline 9999px. var(--radius-full) is NOT a valid migration target because Tailwind v4's @theme { --*: initial } reset (tailwind/index.css L10) wipes the default --radius-full; consumers reading var(--radius-full) would get an unset value. rounded-full class form is unaffected: Tailwind v4 emits the rounded-full utility from a builtin, not from a --radius-full theme token, so the --*: initial wipe does not break the class.

Typography (PR2): remove the --text-sm/base/lg/xl fontSize aliases and the eight @theme aliases that currently reference soon-to-be-deleted primitives (--font-weight-regular, --font-weight-medium, --leading-lg, --leading-xl, --leading-2xl, --tracking-normal, --tracking-tight, --tracking-tightest). After removal, the Tailwind utilities they generated (text-sm, text-base, text-lg, text-xl, font-regular, font-medium, leading-lg, leading-xl, leading-2xl, tracking-normal, tracking-tight, tracking-tightest) stop being emitted. PR2 sweep covers all callsites of these classes.

Typography (PR1): add nine @utility text-* rules outside the @theme block. Each rule bundles font-family, font-size, font-weight, line-height, and (for display/h1 only) letter-spacing by referencing the new theme.css variables. Mono roles bundle font-family: var(--font-family-mono) inline so a single class carries family + size + weight + line-height. Sans roles reference var(--font-family-sans) directly.

Removed CSS variables across PR0 and PR2

PR0 removals (non-typography):

• --brand-danger and --brand-danger-hover from theme.css (Cat A dead code, 0 callsite). Theme-parity test's SAME_IN_DARK set is updated to drop these names.
• --radius-pill from theme.css L73 and pawwork.json. Three preview-HTML consumers (docs/design/preview/{message-flow.html:279, titlebar.html:191, iconbtn.html:48}) migrate to inline border-radius: 9999px. docs/DESIGN.md L340 (Round floating variant) is updated to describe the value as 9999px inline rather than var(--radius-pill).
• --radius-xs and --radius-xl from tailwind/index.css @theme block, after sweeping their 8 production callsites (see "PR0 callsite migrations" below).

PR0 does NOT remove --surface-sunken or --color-surface-sunken. The token is preserved for the 19+ legitimate secondary-surface callsites; only the four icon-button hover mis-uses and one inline-code callsite migrate (see "PR0 callsite migrations" below).

PR2 removals (typography):

• All nine composite --type-* tokens in theme.css (display through kbd).
• Seven primitive font-size tokens in theme.css: --font-size-x-small (12), --font-size-small (13), --font-size-base (13), --font-size-hierarchy (13, Cat A dead-code), --font-size-large (16), --font-size-x-large (20), --font-size-2x-large (28).
• Two old weight tokens in theme.css: --font-weight-regular (400), --font-weight-medium (500).
• Four old line-height tokens in theme.css: --line-height-normal (130%), --line-height-large (150%), --line-height-x-large (180%), --line-height-2x-large (200%).
• Three old letter-spacing tokens in theme.css: --letter-spacing-normal (0), --letter-spacing-tight (-0.16px), --letter-spacing-tightest (-0.32px).
• Four Tailwind fontSize alias tokens in tailwind/index.css @theme: --text-sm, --text-base, --text-lg, --text-xl.
• Eight additional Tailwind alias tokens in tailwind/index.css @theme: --font-weight-regular, --font-weight-medium, --leading-lg, --leading-xl, --leading-2xl, --tracking-normal, --tracking-tight, --tracking-tightest. These reference soon-to-be-deleted primitives and must be removed alongside them. Their generated utility classes (font-regular, font-medium, leading-lg, leading-xl, leading-2xl, tracking-normal, tracking-tight, tracking-tightest) are swept in PR2.

Reason for full deletion of --text-sm/base/lg/xl instead of aliasing to new role tokens: text-sm/base/lg/xl express size-step semantics ("smaller / default / larger"), the new text-caption/body/h1/… express role semantics ("this text plays role X"); keeping aliases means a permanent two-way naming choice at every callsite, which a one-person project tends to settle as permanent debt.

PR0 callsite migrations (the only --surface-sunken consumers that change)

packages/ui/src/components/markdown.css L104: inline code background var(--surface-sunken) → var(--code-surface). Aligns inline code with code block in using the alpha overlay path. Code-block fence at L313 (.shiki rule): add background: var(--code-surface); to the rule. This is an additive change — .shiki currently has only font, padding, border-radius, border, no background declaration at all, so the rule starts inheriting whatever surface it sits on. After the addition, code blocks gain a deliberate alpha overlay matching DESIGN.md Code & diff. This is a visible visual change — the PR0 desktop pass and screenshot record both light and dark before/after.

Icon-button hover bug fixes (per docs/DESIGN.md L336: "30×30 ghost square… hover overlays --row-active-overlay (6%)"):

• packages/ui/src/components/file-search.tsx L44, L53, L63: hover:bg-surface-sunken → hover:bg-row-active-overlay. These are 26×26 icon-only buttons (prev / next / close in the find-in-file panel) that should follow the icon-button hover overlay convention, not paint a cream solid color.
• packages/app/src/components/dialog-select-server.tsx L576: hover:bg-surface-sunken → hover:bg-row-active-overlay for the same reason.

Hardcoded radius fixes:

• packages/ui/src/components/message-part.css L367: border-radius: 6px → var(--radius-sm). (L42 and L374 cited in earlier iterations are stale — L42 already uses var(--radius-sm); L367 inside [data-component="bash-output"] is the sole remaining 6px literal in this file.)

--radius-xs and --radius-xl callsite sweep (must complete before deleting either token):

• packages/ui/src/components/message-part.css L1130 (&:focus-visible { border-radius: var(--radius-xs) }): var(--radius-xs) → var(--radius-sm). The visual shift is 2px → 6px on a focus-visible outline-offset corner; acceptable per the "accept the new project value as default" rule and not on a hot visual surface.
• packages/app/src/components/dialog-select-server.tsx L558 (license badge tag): rounded-xs → rounded-sm. Value shifts 2px → 6px on a small text badge — visible but acceptable; PR description records the change with a screenshot.
• packages/app/src/pages/session/files-tab.tsx L128, packages/app/src/components/debug-bar.tsx L404, packages/app/src/components/status-popover.tsx L50, L58, packages/app/src/components/status-popover-body.tsx L249, L252: rounded-xl → rounded-lg. Value is preserved exactly (old --radius-xl = 0.875rem = 14px; new --radius-lg = 14px), so this is a name-only sweep with zero visual change. The PR description notes this is a value-preserving rename.

Preview HTML --radius-pill migrations (per --radius-pill deletion):

• docs/design/preview/iconbtn.html L48: border-radius:var(--radius-pill) → border-radius:9999px.
• docs/design/preview/titlebar.html L191: same.
• docs/design/preview/message-flow.html L279: same.

--surface-sunken callsites intentionally preserved (no change in PR0)

These remain on --surface-sunken because they serve roles where the cream-tone secondary content surface is the correct visual treatment, not a bug:

• Content surfaces (16 callsites total): packages/ui/src/components/tabs.css (8 lines), packages/ui/src/components/session-turn.css (4 lines), packages/ui/src/components/accordion.css L55, packages/app/src/index.css L122, plus two playground references in packages/ui/src/components/timeline-playground.stories.tsx.
• packages/app/src/components/settings-keybinds.tsx L424 active-row treatment (intentional solid-cream + 1px border + fg-weak active design; not a hover state — a selected/captured state).
• packages/app/src/components/dialog-connect-provider.tsx L299, L381 color swatch (16×8 px w-4 h-2 favicon-row placeholder; cream-tone solid is a deliberate placeholder color).
• packages/ui/src/components/select.test.tsx L105-111 negative assertion (verifies a settings variant does not hover with sunken; the assertion remains relevant under the preserved-sunken design).
• packages/app/e2e/models/model-picker-visual.spec.ts L50, L83, L121 cssColor(page, "--surface-sunken") reads (the E2E suite continues to work because the token is preserved with its current values).

A standalone follow-up may later audit whether settings-keybinds active and the swatch role should migrate to dedicated tokens; that work is out of scope for this redesign.

Tokenless surface (PR0 migrates raw rgba literals where they should reference --code-surface instead)

Any remaining raw rgba(0, 0, 0, 0.04) or rgba(255, 255, 255, 0.06) literals in packages/ui/src/components/ that semantically belong to code surfaces migrate to var(--code-surface) in PR0. The same literals legitimately appear in theme.css and colors.css for --hover-overlay/--row-hover-overlay/--row-active-overlay declarations and in pawwork.json for the shadow-modal definition — these are not migrated. Pre-PR0 grep of these literals in packages/ui/src/components/ returns zero today (inline code at markdown.css L104 reads through var(--surface-sunken), not the literal; .shiki has no background at all). Post-PR0 grep also returns zero; the verification value is preventing future regressions where someone re-introduces a raw alpha literal instead of var(--code-surface).

Migration — three PRs

Strict serial: PR0 → PR1 → PR2. Each PR cannot open until the previous lands on dev. PR0 closes Cat A and non-typography debts; PR1 introduces typography infrastructure without touching component callsites; PR2 sweeps the typography callsites and deletes the orphan tokens with a parity test locking the cleanup in.

PR0 — code-surface introduction, radii alignment, four hover bug fixes, Cat A cleanup

Files touched:

• packages/ui/src/styles/theme.css: add --code-surface in all three theme blocks (light rgba(0, 0, 0, 0.04), two dark blocks at rgba(255, 255, 255, 0.06)); delete --brand-danger, --brand-danger-hover, --radius-pill.
• packages/ui/src/styles/tailwind/index.css @theme block: delete --radius-xs and --radius-xl; change --radius-sm/md/lg to 6/10/14 px values matching theme.css.
• packages/ui/src/components/markdown.css: inline code (L104) var(--surface-sunken) → var(--code-surface); code-block fence at .shiki rule (L313) gains background: var(--code-surface); (additive, no prior background declaration).
• packages/ui/src/components/file-search.tsx (L44, L53, L63): hover:bg-surface-sunken → hover:bg-row-active-overlay.
• packages/app/src/components/dialog-select-server.tsx (L576): hover:bg-surface-sunken → hover:bg-row-active-overlay. L558 (separate concern, same file): rounded-xs → rounded-sm.
• packages/ui/src/components/message-part.css: L367 border-radius: 6px → var(--radius-sm); L1130 var(--radius-xs) → var(--radius-sm).
• Six rounded-xl → rounded-lg value-preserving renames (no visual change; old --radius-xl 0.875rem = 14px = new --radius-lg):
  • packages/app/src/pages/session/files-tab.tsx L128
  • packages/app/src/components/debug-bar.tsx L404
  • packages/app/src/components/status-popover.tsx L50
  • packages/app/src/components/status-popover.tsx L58
  • packages/app/src/components/status-popover-body.tsx L249
  • packages/app/src/components/status-popover-body.tsx L252
• docs/design/preview/iconbtn.html L48 (CSS rule), docs/design/preview/titlebar.html L191, docs/design/preview/message-flow.html L279: var(--radius-pill) → inline 9999px.
• docs/design/preview/iconbtn.html L295 (prose): replace <code>--radius-pill</code> mentions with <code>9999px</code> so the doc text matches the CSS rule.
• docs/design/preview/radii.html L94 (token swatch row): remove the --radius-pill row entirely (the token no longer exists; the doc should not advertise a deleted token).
• docs/design/preview/badges-pills.html L150 (migration note prose): replace <code>--radius-xs</code> → <code>--radius-sm</code> with <code>radius-sm</code> (drop the stale token-name mention), so the broad verification grep can run inclusively across all of docs/.
• packages/ui/src/theme/themes/pawwork.json: sync removals (brand-danger, brand-danger-hover, radius-pill) and addition (code-surface in light and dark).
• packages/ui/test/theme-parity.test.ts: drop brand-danger/brand-danger-hover from SAME_IN_DARK. Add new top-level test cases (outside the REGULATED_PREFIXES loop): (a) assert theme.css :root and the Tailwind @theme block declare --radius-sm/md/lg with equal pixel values; (b) assert --code-surface is declared in all three theme blocks (light :root, dark [data-color-scheme="dark"], @media (prefers-color-scheme: dark) first-paint mirror) with the expected light vs dark values; (c) assert --code-surface is present in pawwork.json under both light and dark sections. Add a code comment in the test file noting that code and radius are intentionally outside REGULATED_PREFIXES and handled by these standalone assertions, so future contributors don't get confused.
• docs/DESIGN.md: section-anchored checklist (line numbers below are diagnostic-only; treat the section heading as the authoritative anchor):
  • Frontmatter colors.neutralsLight.surfaceSunken: change value from "#F4F0EC" to "#FAF9F7". (YAML header matches the runtime alias; the legacy aspirational value retires.)
  • Frontmatter rounded section: delete the "pill": 9999 line; keep only sm/md/lg.
  • Frontmatter colors section: do NOT add codeSurface entries. DESIGN.md L145 explicitly states alpha-overlay tokens are composed in theme.css from the base palette and do not appear in frontmatter; --code-surface is alpha-overlay-shaped, so it follows the same rule. The token lives only in theme.css and pawwork.json.
  • Frontmatter colors.brand.dangerLight / dangerLight.hover (and dark counterparts) if present: delete.
  • Frontmatter deviations: ledger: add brand-danger retirement, radius-pill retirement, and the surfaceSunken value correction.
  • Neutrals paragraph (under ## Color → Neutrals): rewrite the --surface-sunken sentence to describe it as a secondary content surface (light = --bg-cream alias #FAF9F7; dark #16130F one tier below --bg-cream). Remove "reserved for inline code" wording. Add a parallel sentence introducing --code-surface as a separate alpha-overlay token for code surfaces only.
  • Shapes section: "Four radius tiers: --radius-sm/md/lg/pill = 6/10/14/9999. No in-between, no xs / xl / frame." → "Three radius tiers: --radius-sm/md/lg = 6/10/14. No in-between, no xs / xl / pill / frame. Fully-rounded surfaces use Tailwind's builtin rounded-full utility or inline border-radius: 9999px in plain CSS / preview HTML."
  • Components → Icon button → Round floating variant: replace --radius-pill token mention with inline 9999px (matches the iconbtn.html prose update).
  • Components → Code & diff → code-block shell paragraph (the one starting "Code-block shell: rgba(0,0,0,0.04) alpha overlay plus radius-md, no border …"): replace rgba(0,0,0,0.04) with var(--code-surface). Note two pre-existing drifts between this paragraph and .shiki implementation: (i) the doc says radius-md but .shiki uses var(--radius-sm); (ii) the doc says "no border" but .shiki has border: 0.5px solid var(--border-weak). PR0 does NOT touch either drift — both are filed as a single follow-up (Code-block shell alignment with DESIGN.md). The PR description explicitly lists both so reviewers do not expect them fixed here.
  • Components → Code & diff → Inline labels paragraph: .ic migration — ".ic: mono-small plus --surface-sunken plus --fg-strong" → ".ic: mono-small plus --code-surface plus --fg-strong".
  • Leave the Tool-call rows → Expanded paragraph (about result body using --bg-cream) alone — it describes a different surface than the conversation code block.

PR0 verification:

• bun --cwd packages/app run typecheck clean.
• bun test packages/ui (including the updated theme-parity) green.
• rg "var\(--brand-danger" packages/ returns zero.
• rg -e 'var\(--radius-pill\)' -e '--radius-pill\b' packages/ docs/ returns zero. (Covers both CSS-var consumers and bare token mentions in DESIGN.md and preview HTML prose.)
• rg "hover:bg-surface-sunken" packages/ returns zero (the four migrated sites are the only consumers).
• rg "rgba\(0,\s*0,\s*0,\s*0\.04\)|rgba\(255,\s*255,\s*255,\s*0\.06\)" packages/ui/src/components/ (no file-type filter) returns zero (markdown.css inline code and code block route through var(--code-surface); other components do not need raw literals in CSS, TS, or TSX form).
• rg -e 'rounded-xs\b' -e 'rounded-xl\b' -e '--radius-xs\b' -e '--radius-xl\b' packages/ docs/design/preview/ returns zero — the xs/xl sweep is complete before the token delete.
• rg "rounded-(sm|md|lg)" packages/ -c records the exact count in the PR description. The radii remap silently changes rounded-sm/md/lg values (4→6, 6→10, 8→14) at every callsite. Visual review of every callsite uses the fallback rule below.
• bun run dev:desktop — manual pass covering: inline code background (light + dark), code block (light + dark), file-search prev / next / close hover (light + dark), dialog-select-server icon hover (light + dark), dialog-select-server license badge (formerly rounded-xs 2px → rounded-sm 6px), --surface-sunken consumers still in use (tabs, session-turn, accordion, settings-keybinds active row, dialog-connect-provider swatch) render unchanged; rounded-* surfaces (session list rows, dialogs, dock attachments, chips, picker items, popovers, attachments, debug-bar, status-popover, files-tab card) render correctly at the new project pixel values; the six rounded-xl → rounded-lg renames produce zero visual change (14px both sides).

Fallback rule for rounded-sm/md/lg semantic change:

• Default behaviour: accept the new value across all callsites (sm 4→6, md 6→10, lg 8→14). PawWork's project scale is the intended pixel target for every rounded surface unless visual review surfaces concrete evidence otherwise.
• Per-callsite exception: if a surface where the larger value breaks design intent surfaces during the Electron pass (small icon button becoming ovaloid, tightly-grouped row where the radius dominates), retreat that single callsite to inline border-radius: <original-px> or a smaller project tier. PR description records each exception with file:line and visual reason.
• Visual-review scope: the Electron pass enumerates the surface list above. Callsites outside the list (inner settings tabs, edge-case modals, debug surfaces) are not individually inspected; the PR description explicitly accepts the silent-regression risk for these. Post-merge regressions in unaudited surfaces are fixed with targeted inline literals as follow-ups.

PR1 — typography infrastructure (zero packages/* CSS callsite churn)

Introduces the new typography token set, Tailwind @utility rules, the preview _utilities.css, and the typography-utility-parity test. Component code keeps using --type-* / --font-size-small / etc. — these tokens are not deleted yet.

Files touched:

• packages/ui/src/styles/theme.css: add 29 new typography variables at :root (9 size + 9 weight + 9 line-height + 2 letter-spacing). Keep all existing --type-*, --font-size-* primitive scale, --font-weight-*, --line-height-*, --letter-spacing-* in place — PR2 removes them.
• packages/ui/src/styles/tailwind/index.css: keep --text-sm/base/lg/xl and the eight other @theme aliases in place for now (PR2 deletes); add nine @utility text-* rules outside @theme referencing the new theme.css variables.
• packages/ui/src/theme/themes/pawwork.json: sync the 29 new variables.
• docs/design/preview/_utilities.css (new file): nine class definitions matching the nine @utility rules. Each class references the same theme.css variables for size/weight/line-height/family/letter-spacing.
• docs/design/preview/*.html: every preview gets <link rel="stylesheet" href="_utilities.css"> in the head; sed-replace font:var(--type-X) → class="text-X". Color is no longer baked into role classes; preview HTML preserves or adds inline style="color: …" where the legacy --type-caption had baked --fg-weak.
• docs/DESIGN.md: rewrite the Typography section (anchor: ## Typography heading; line numbers in DESIGN.md drift). Describe the new per-property semantic scheme and the role-class utility surface. Note that color is intentionally orthogonal. Extend frontmatter deviations: ledger if any preview file ends up overriding the new spec.
• packages/ui/test/typography-utility-parity.test.ts (new): for each of the nine roles, asserts both tailwind/index.css @utility rule and docs/design/preview/_utilities.css class definition exist. Extracts the property set from each side (selector wrapper @utility name {…} vs .name {…} ignored). Parity is per-role identical property set with identical var() references: whatever each role declares on one side, the other side declares the same set with the same var() references. display and h1 legitimately carry letter-spacing while the other seven roles do not — the test does not enforce a uniform set across all roles, only intra-role identity. If one side declares an extra property (e.g. font-feature-settings) that the other side lacks for the same role, parity fails.

PR1 verification:

• bun --cwd packages/app run typecheck clean.
• bun test packages/ui — theme-parity + the new typography-utility-parity green.
• Preflight collision grep: rg '\b(text-display|text-h1|text-h2|text-h3|text-body|text-caption|text-mono|text-mono-small|text-kbd)\b' packages/ docs/design/preview/ returns zero. Any preexisting use of these class names (in packages/ source or preview HTML markup) would mean PR1's new utilities silently start applying; if found, rename or sweep in this PR before adding the new utilities.
• Pre/post utility-class sanity check for font-regular, font-medium, leading-lg, leading-xl, leading-2xl, tracking-normal, tracking-tight, tracking-tightest: render a test page using each utility once before this PR's branch lands and once after; computed styles must match. Verified pre-PR1 state: the Tailwind @theme aliases (e.g. --font-weight-regular: var(--font-weight-regular)) currently resolve through the same-named primitives declared in theme.css :root (which are still present pre-PR2), so the utility classes DO render functional styles today. PR1 adds the new role utilities alongside; PR2 deletes both the Tailwind aliases and the theme.css primitives. After PR2 the listed utility classes stop being emitted entirely — every callsite must have been swept to the new role utilities in PR2. Pre/post comparison thus shows: pre-PR1 functional, post-PR1 still functional (alias path intact), post-PR2 the classes are gone and the sweep is complete.
• bun run dev:desktop — confirm zero visual change in packages/* (component code still consumes old tokens, which still exist).
• Open every preview HTML file by double-click; confirm role classes render at the expected size/weight/line-height (DevTools computed values match the W1 spec).
• Render docs/DESIGN.md typography section in a markdown viewer; confirm internal consistency.

PR2 — typography sweep, dead-token cleanup

Migrates all typography callsites to the new role utilities (HTML/JSX) and per-property CSS variables (CSS files), then deletes the old tokens and the eight additional Tailwind aliases.

Files touched:

• packages/ui/src/**/*.css and packages/app/src/**/*.css: for every callsite of var(--type-X) / var(--font-size-{x-small,small,base,hierarchy,large,x-large,2x-large}) / var(--font-weight-{regular,medium}) / var(--line-height-{normal,large,x-large,2x-large}) / var(--letter-spacing-{normal,tight,tightest}), replace with per-property CSS variables for the appropriate role (var(--font-size-caption), var(--font-weight-caption), var(--line-height-caption), etc.). CSS files cannot use utility classes — they use the CSS variables directly. The role mapping requires per-surface judgement.
• packages/ui/src/**/*.tsx and packages/app/src/**/*.tsx: for callsites in className and inline style, use the new Tailwind utility classes (text-display through text-kbd). Sweep all uses of text-sm/text-base/text-lg/text-xl, font-regular/font-medium, leading-lg/leading-xl/leading-2xl, tracking-normal/tracking-tight/tracking-tightest to the appropriate role utility (or remove if redundant).
• packages/ui/src/styles/theme.css: delete all 9 --type-*; delete 7 --font-size-* primitive scale; delete --font-weight-{regular,medium}; delete --line-height-{normal,large,x-large,2x-large}; delete --letter-spacing-{normal,tight,tightest}. Confirm --font-family-{sans,mono} stay.
• packages/ui/src/styles/tailwind/index.css @theme block: delete --text-sm/--text-base/--text-lg/--text-xl; delete the eight additional aliases --font-weight-regular, --font-weight-medium, --leading-lg, --leading-xl, --leading-2xl, --tracking-normal, --tracking-tight, --tracking-tightest. Confirm --font-sans and --font-mono stay.
• packages/ui/src/theme/themes/pawwork.json: sync all removals.
• packages/ui/test/no-dead-tokens.test.ts (new): for each removed token name and each removed Tailwind utility class name, grep packages/ and docs/design/preview/ and assert zero matches. The test uses multiple -e flags (one per banned token / class) rather than a single fragile alternation regex. For CSS custom-property bans (--type-*, --text-sm, etc.), each pattern uses a right-side-only PCRE word boundary like -e '--text-sm\b' — left-side \b does not work because the leading - is non-word and the typical preceding character (( or whitespace) is also non-word, so \b--text-sm\b would silently fail to match var(--text-sm). Right-side \b correctly distinguishes --text-sm from --text-smaller. For utility class bans (text-sm, font-medium, etc.), both-side \b works because the class name's first character is a word character. An -g '!packages/ui/test/no-dead-tokens.test.ts' glob exclusion prevents the test file's own banned-token list from self-matching. The list covers: nine --type-* names; seven primitive --font-size-* names; --font-weight-regular, --font-weight-medium; four --line-height-* old names; three --letter-spacing-* old names; four --text-{sm,base,lg,xl} aliases; eight --leading-{lg,xl,2xl} and --tracking-{normal,tight,tightest} aliases; and the Tailwind class forms (text-sm, text-base, text-lg, text-xl, font-regular, font-medium, leading-lg, leading-xl, leading-2xl, tracking-normal, tracking-tight, tracking-tightest) matched across .tsx, .ts, .html, .css. Plus a positive assertion that --font-family-sans, --font-family-mono, the nine new --font-size-*, the nine new --font-weight-*, the nine new --line-height-*, and the two new --letter-spacing-{display,h1} exist in theme.css.
• docs/DESIGN.md: minor sync only.

PR2 verification:

• bun --cwd packages/app run typecheck clean.
• bun test packages/ui — theme-parity + typography-utility-parity + the new no-dead-tokens green.
• bun run dev:desktop — manual pass: session list / message timeline / dock / settings / dialogs / chips / tools — visual parity vs pre-PR2 dev.
• Existing W1 E2E suites green; no regression.

Risks and mitigations

Radii silent semantic change in PR0. rounded-sm/md/lg shift from 4/6/8 to 6/10/14 px at every callsite. Mitigation: PR0 verification's exact callsite count + visual review of every callsite within the listed surfaces; fallback rule defaults to accepting the new value but allows per-callsite exceptions documented in the PR description. Callsites outside the listed surfaces accept silent-regression risk; post-merge issues fix as targeted follow-ups.

Hover bug fix visual change in PR0. Four icon-button hover sites currently render cream solid (--surface-sunken); after the fix they render --row-active-overlay 6% alpha. Mitigation: change is per docs/DESIGN.md L336 icon-button hover spec, not a new design call. PR0 manual Electron pass explicitly verifies the four sites (file-search prev/next/close, dialog-select-server icon) render the alpha overlay in both light and dark.

--surface-sunken preservation. The token continues to serve 19+ legitimate callsites across tabs, session-turn, accordion, app-level inset, settings-keybinds active row, dialog-connect-provider swatch, and tests. Mitigation: PR0 explicitly enumerates these as preserved; no verification command requires var(--surface-sunken) to return zero. The token's current light value #FAF9F7 (alias of --bg-cream) and dark value #16130F are accepted as the runtime truth; the earlier docs/DESIGN.md #F4F0EC aspirational value is removed from the spec text.

CSS-side migration target in PR2. Component CSS files cannot use Tailwind utility classes — they must use per-property CSS variables directly. Mitigation: no-dead-tokens test covers both CSS-variable form and class form across packages/ and docs/design/preview/.

Two-surface utility class parity. Tailwind @utility rules and preview _utilities.css classes must stay in sync. Mitigation: typography-utility-parity test normalizes selector wrappers and compares per-role property sets with their var() references.

Caption default color leak. The legacy --type-caption baked --fg-weak in. Mitigation: during PR2 sweep, every caption callsite is reviewed for the color it should carry; text-fg-weak (or another color class) is added explicitly. Missing the color class renders caption in inherited base color, which is visibly darker and caught in the desktop pass.

Mono utility composition. The new @utility text-mono/text-mono-small/text-kbd rules bundle font-family: var(--font-family-mono) inline, so a single class carries both size and family. Mitigation: PR1 verification confirms each mono @utility rule includes font-family; PR2 sweep collapses any existing text-mono font-mono pair.

Radii dual declaration in theme.css and @theme. After PR0 both sites declare --radius-sm/md/lg with identical pixel values. Mitigation: theme-parity test asserts equality between the two declaration sites. Drift would fail CI.

PR1 utility class name collision. If packages/ or preview HTML already has any callsite using text-display, text-h1, etc. as a class name, PR1's new utility would silently start styling those callsites. Mitigation: PR1 preflight grep returns zero before merging across both packages/ and docs/design/preview/.

Code surface value coincidence with hover overlays. --code-surface light value matches --hover-overlay and --row-hover-overlay. These tokens are intentionally separate semantic units — a future tone shift to one should not drag the others along. Mitigation: spec wording (this section and the inventory) explicitly notes the semantic independence.

Out of scope

Role-set trimming for typography (whether nine roles is the right count) is a product decision. Audit of whether settings-keybinds active-row, dialog-connect-provider swatch, and timeline-playground references should migrate to dedicated tokens is a follow-up. Color/surface/border/icon naming reorg, spacing token vs Tailwind spacing overlap, shadow/duration/motion token review — separate concerns. New evidence during PR2 sweep gets filed as separate entries here, not folded back into this redesign.

Rollback

Each PR is independently revertable. PR0 is a cleanup with one additive surface (the --code-surface token) and two visible behavior changes (radii values, icon-button hover style); git revert PR0 restores dev exactly modulo those visual rollbacks. PR1 adds new tokens and utility rules without touching consumers; git revert PR1 removes them while the old token set is intact. PR2 deletes old tokens; git revert PR2 brings them back; the swept callsites can stay on the new utility classes (still defined post-PR1) without functional change. Reverting all three lands back at the current dev HEAD.

Follow-ups (post-merge)

Role-set product decision (display vs h1 separation; body vs caption at the same size and weight; h3 vs body); --surface-sunken consumer audit for settings-keybinds active, dialog-connect-provider swatch, and timeline-playground references; color/surface/border naming reorg; spacing token dual-namespace audit; Code-block shell alignment with DESIGN.md (.shiki radius drift --radius-sm vs spec radius-md, plus border drift 0.5px solid --border-weak vs spec "no border"). None of these block this redesign — they are flagged here so future work has a starting point.