refactor(css): consolidate token strata into maka-tokens (Round C)

apps/desktop/src/renderer/maka-tokens.css

@@ -15,6 +15,25 @@
      - Multi-layer soft shadows with very low opacity (0.06) instead of one heavy shadow.
      - System UI fonts with optical antialiasing.
      - 13px base font, 4px spacing unit → dense but readable.
+
+   ── Token authority (Round C consolidation) ────────────────────────────────
+   This file is the single source of truth for design tokens. Authority order
+   when two token names describe the same thing:
+     1. AUTHORITATIVE — the --background / --foreground family (+ --accent, the
+        status colors, and the derived --foreground-N / alpha / border / state
+        / spacing / radius / typography / elevation scales). New code consumes
+        these.
+     2. COMPATIBILITY ALIASES — the --color-bg-* / --color-text-* /
+        --color-border-* names (see "color-system compatibility aliases" in
+        :root). Kept only for existing consumers. Do NOT add new --color-*
+        aliases and do NOT point new components at them; use the --background
+        family instead.
+   Alias policy: an alias is defined as `var(--<authoritative-token>)` (or a
+   thin color-mix of one) and never holds an independent value, so themes and
+   palettes only ever retune the authoritative token. reference-shell.css and
+   styles/theme-glass.css now hold LAYOUT and GLASS-MATERIAL rules only — no
+   token definitions live there anymore (the darwin glass token overrides were
+   relocated here; see "DARWIN GLASS" below).
 ============================================================================ */
 
 /* =============================================================================
@@ -27,38 +46,14 @@
      oklch() gives perceptually uniform lightness, keeping subtle surface and
      status colors calibrated.
 
-     History: started as cool blue-gray (hue 265), then briefly moved
-     to warm cream (hue 80) to mirror a single-canvas reference design
-     where sidebar + main area share the same background and
-     separation comes from hairline borders + radius rather than a
-     darker shell behind lighter cards.
-
-     PR-DEFAULT-CANVAS-DEYELLOW-0 (@yuejing 2026-05-30, WAWQAQ msg
-     `bfee559d`): de-yellowed by shifting hue 80 → 250 (cool neutral).
-     The warm-cream tone read as visibly yellow against the chrome
-     accents and felt odd as a default. Same hue family as the azure
-     palette but with lower chroma so the default stays subtler.
-
-     PR-PARCHMENT-DEFAULT-0 (@yuejing 2026-06-20, WAWQAQ msg `00dcaf3a`
-     "/goal 像素级模仿 reference implementation"): nudged back toward reference implementation's
-     `light-parchment` baseline (warm off-white).
-
-     PR-GRAY-CARD-LIFT-0 (@yuejing 2026-06-20, WAWQAQ msg `a49dbd1e`
-     "整个的底板应该是灰色的, content surface 应该是白色的"):
-     WAWQAQ pivoted off the warm-parchment family to reference implementation's plain
-     `light` theme. There:
-       --color-bg-layout (shell canvas)  : #fdfdfd ≈ near-white
-       --color-bg-container (card)       : #ffffff pure white
-       --color-fill-tertiary (chip)      : #f9f9f9 light gray
-       --color-border-tertiary           : #e6e6e6
-       --color-text                      : #141414 near-black
-     The user's intent now reads as: the shell behind everything is a
-     near-white glass plate, the cards lift off it as pure white. We
-     translate to oklch with a tiny warm chroma so the sidebar reads
-     more like 参考实现's translucent macOS surface than a flat gray slab.
-
-     `--surface-canvas` is the shell-level background (what `.appFrame`
-     paints behind everything); `--background` is what cards paint. */
+     Current model (owner decision 2026-06-20, WAWQAQ msg `a49dbd1e`
+     "整个的底板应该是灰色的, content surface 应该是白色的"): a near-white glass
+     shell plate (--surface-canvas) with pure-white content cards (--background)
+     lifting off it — separation comes from the plate + radius + hairlines, not
+     a darker shell. Earlier warm-parchment / hue-80 "cream" experiments were
+     superseded (de-yellowed to a cool-neutral hue, then flattened to plain
+     white). --surface-canvas is what `.appFrame` paints behind everything;
+     --background is what cards paint. */
   --background: oklch(1.000 0 0);
   /* PR-UI-FRAME-4 (2026-06-22): pull back from the heavy gray plate.
      参考实现's sidebar is a light glass-like near-white gradient, with
@@ -212,6 +207,22 @@
   --user-message-bubble: var(--chat-user-bg);
   --selection:     oklch(from var(--accent) l c h / 0.2);
 
+  /* === color-system compatibility aliases ===
+     Legacy `--color-*` names that predate the --background family, relocated
+     here from reference-shell.css (Round C). Kept as thin aliases for the few
+     consumers still on them: `--color-bg-container` backs the agents content
+     surface (reference-shell.css) + darwin glass card; `--color-border-tertiary`
+     the composer border (composer.css); `--color-text-quaternary` the darwin
+     sidebar label text (theme-glass.css). Authoritative source is the token
+     each aliases — see the token README at the top of this file. Do NOT add
+     new --color-* names.
+     `--color-bg-container` is the one shipped exception where the alias name is
+     the canonical handle for the content-card surface (resolves to
+     --background); it carries its darwin overrides in "DARWIN GLASS" below. */
+  --color-bg-container: var(--background);
+  --color-border-tertiary: color-mix(in srgb, var(--border) 92%, transparent);
+  --color-text-quaternary: var(--muted-foreground);
+
   /* === shadow opacity (subtle in light, stronger in dark) === */
   --shadow-border-opacity: 0.08;
   --shadow-blur-opacity:   0.06;
@@ -649,6 +660,26 @@
   --bot-brand-default: var(--accent);
 }
 
+/* =============================================================================
+   DARWIN GLASS — color-alias overrides for the macOS vibrancy shell
+   (relocated from styles/theme-glass.css, Round C). Unlayered + the
+   html[data-os="darwin"] selector on purpose: the override must outrank the
+   :root aliases above (0,1,1 > 0,1,0) and beat any @layer declaration. The
+   glass MATERIAL rules (backdrop-filter, transparency) stay in theme-glass.css.
+
+   Re-anchored on --background (not a warm/zinc literal) so hue/chroma follow
+   the active palette; card↔canvas separation is the canvas/vibrancy's job, so
+   the content card == the palette background.
+============================================================================= */
+html[data-os="darwin"] {
+  --color-bg-container: var(--background);
+  --color-text-quaternary: oklch(from var(--foreground) l c h / 0.45);
+}
+html[data-os="darwin"].dark {
+  /* Dark glass lifts the card one lightness step off the darker shell. */
+  --color-bg-container: oklch(from var(--background) calc(l + 0.035) c h);
+}
+
 /* =============================================================================
    PR-UI-2 (@yuejing 2026-05-22): base46-inspired palette catalog
    ---------------------------------------------------------------

apps/desktop/src/renderer/reference-shell.css

@@ -3,31 +3,17 @@
    reference implementation compiled CSS or brand assets here. */
 
 :root {
-  --color-bg-base: var(--background);
-  --color-bg-container: var(--background);
-  --color-bg-elevated: var(--background-elevated);
-  --color-bg-layout: var(--surface-canvas);
-  --color-bg-spotlight: oklch(from var(--background) calc(l - 0.03) c h);
-  --color-text-base: var(--foreground);
-  --color-text: var(--foreground);
-  --color-text-secondary: var(--foreground-secondary);
-  --color-text-tertiary: var(--muted-foreground);
-  --color-text-quaternary: var(--muted-foreground);
-  --color-border: var(--border);
-  --color-border-secondary: var(--border);
-  --color-fill: var(--foreground-8);
-  --color-fill-secondary: var(--foreground-10);
-  --color-fill-tertiary: var(--foreground-3);
-  --color-fill-quaternary: var(--foreground-2);
-  /* PR-UI-ALIGN-2 (2026-06-21): card/container hairlines must be clearly
-     visible (≈#e6e6e6) so the floating content card, skill list and task cards
-     read as distinct surfaces like 参考实现 — the old 60% washed them out. */
-  --color-border-tertiary: color-mix(in srgb, var(--border) 92%, transparent);
+  /* Agents layout-shell locals only. The color-system tokens this shell once
+     referenced (--color-bg-container / --color-border-tertiary /
+     --color-text-quaternary) were consolidated into maka-tokens.css alongside
+     the --background family they alias; the dead --color-* / --color-fill-* /
+     settings-nav strata were removed (Round C, zero consumers). See the token
+     README at the top of maka-tokens.css. */
+
   /* Flat neutral shell/backplate. This must never be a gradient; the
      white content surface reads through radius + shadow on top. */
   --agents-layout-bg: var(--surface-canvas);
   --agents-content-area-bg: var(--color-bg-container);
-  --agents-fade-bg: var(--agents-content-area-bg);
   /* reference layout-derived values (2026-06-20 WAWQAQ ef6b2852).
      The original 8px/12px we shipped at 7013f0f read too loose vs the
      real bundle's 4px gap + 6px radius.
@@ -36,7 +22,6 @@
      6px was geometrically present but optically invisible against a
      same-color shell. */
   --agents-content-area-gap: 4px;
-  --settings-nav-row-selected-bg: var(--color-fill-secondary);
 }
 
 [data-agents-page] {

apps/desktop/src/renderer/styles/theme-glass.css

@@ -50,61 +50,16 @@ html[data-os="darwin"] .maka-session-panel {
 
 /* =============================================================================
    PR-QODERWORK-GLASS-RESHIP-L3-L6-L7 (WAWQAQ msg `c71b4dcb` thread,
-   2026-06-30). The original PR-QODERWORK-GLASS-LAYERED-0 push tried to
-   ship 5 layers (L1+L2+L3+L6+L7) but only the L1 vibrancy unblock
-   actually landed on main via the squash-merge of PR #329 (`7d008d51`).
-   The follow-up commit `023b90b2` was force-pushed but never merged, so
-   for the past 3 days users have been seeing the QoderWork "classic"
-   look despite the substrate being correctly enabled. This block
-   re-ships L3 + L6 + L7 from that delta — L2 (blur 8px → 24px) and L1
-   (blur on layout root not panel) are still out of scope because they
-   need real-window verification of the blur strength before pinning a
-   number, and the panel-vs-layout-root attribution needs a coordinated
-   move of the existing 8px rule above. Shipping the high-confidence
-   ones first.
+   2026-06-30): re-shipped the QoderWork light-glass / dark-glass look on
+   darwin vibrancy. L3 + L7 — the material + list-label rules — live below.
+   L6 — the neutral-glass color TOKENS this file used to override on darwin
+   (--color-bg-container / --color-text-quaternary, light + dark) — moved to
+   maka-tokens.css (Round C) so every token definition has one home. The
+   html[data-os="darwin"] override there stays unlayered on purpose so it still
+   outranks the :root aliases (0,1,1 > 0,1,0). Only glass-MATERIAL rules and
+   the darwin text/label overrides remain in this file.
 ============================================================================= */
 
-/* L6 — warm-toned color tokens from QoderWork's `light-glass` theme,
-   extracted by @maka-审美专家 from `/tmp/qoder-asar/out/renderer/`
-   reference bundle. Component-level CSS plugs into these so palette
-   swaps don't need callsite rewrites. Scoped to macOS so non-glass
-   platforms keep their existing neutral tokens. */
-/* UNLAYERED on purpose: reference-shell.css defines the same custom
-   properties in an unlayered :root block, and unlayered declarations
-   beat @layer ones regardless of specificity — inside @layer base this
-   entire warm glass palette was silently dead (the documented
-   "parchment glass" never shipped). html[data-os] (0,1,1) outranks
-   :root (0,1,0), so the darwin override now actually applies. */
-html[data-os="darwin"] {
-  /* Neutral-cool glass (owner decision 2026-07-03): the QoderWork
-     light-glass extraction was warm ivory (#fdfcfa/#faf9f6/#f5f3ee),
-     which read beige against vibrancy blur. zinc-family equivalents
-     keep the same lightness steps but zero warm cast. */
-  /* PALETTE-LEAK-0: the zinc hex here (#fafafa) overrode reference-shell's
-     var(--background)-derived container for ALL of darwin, so the main
-     content pane ignored palette switches entirely. Re-anchor on
-     --background so hue/chroma follow the active palette.
-     CONTENT-SURFACE-CONTRAST (maintainer, 2026-07-09): the extra −0.015
-     step made the content card visibly off-white (measured 0.985) and
-     collapsed the card↔canvas contrast to Δ0.009 — "内容面不是纯白，
-     和左边对比不够". The card is the palette background, full stop;
-     separation is the canvas/sidebar's job (surface-canvas −0.024 +
-     vibrancy), matching the reference's white-card-on-gray-shell. */
-  --color-bg-container: var(--background);
-  --color-text-quaternary: oklch(from var(--foreground) l c h / 0.45);
-}
-
-/* Dark-mode variants for the darwin glass palette. The light hexes above
-   are QoderWork light-glass extractions; reused verbatim in dark mode they
-   sat under near-white foreground text and the parchment surfaces glowed
-   against the dark shell, so the dark variants below re-tune lightness. */
-html[data-os="darwin"].dark {
-  /* PALETTE-LEAK-0: same derivation as the light block — dark default
-     background (l=0.205) resolves to the previous 0.24 literal. */
-  --color-bg-container: oklch(from var(--background) calc(l + 0.035) c h);
-}
-
-
 /* L7 — group label was 9.5px UPPERCASE + 0.08em tracking on the
    sidebar, which read as "old Windows admin tool" not "macOS native
    sidebar". QoderWork uses plain quaternary text at body size. Drop

notes/frontend-simplification-map-2026-07-13.md

@@ -40,10 +40,22 @@ dist/**/*.test.js). Real finds verified by hand before acting.
      defaultPermissionMode (L215-228)
   Preserve PR-FE-BUG-HUNT-0 stable identities; re-pin app-shell-effect-stability
   contracts per move. Target: app-shell.tsx < 900 lines, zero behavior change.
-- [ ] **C — CSS strata consolidation** — maka-tokens.css 1509 lines carries historical
-  strata (hue-80 era comments, reference-shell.css + theme-glass.css parallel token
-  systems: --color-bg-* vs --background families). Merge the glass/reference layers'
-  live tokens into maka-tokens, delete dead strata, one token README header.
+- [x] **C — SHIPPED (refactor/css-token-consolidation): CSS strata consolidation.**
+  Census (machine-generated, var() consumers across all CSS+TSX): reference-shell.css
+  23 defined → 16 dead (removed), 3 live color-aliases moved to maka-tokens
+  (--color-bg-container/--color-border-tertiary/--color-text-quaternary), 4 live
+  layout-locals kept in-file (--agents-layout-bg/--agents-content-area-bg/-gap,
+  --sidebar-width). theme-glass.css 2 token overrides (darwin --color-bg-container light+dark,
+  --color-text-quaternary) relocated to maka-tokens; glass-material + text/label RULES stay.
+  maka-tokens.css: added token-authority README (authoritative --background family vs
+  compatibility --color-* aliases, alias policy) + condensed the superseded hue-80 archaeology
+  (it named deleted tokens). Both themes migrated (light :root + .dark + darwin light/dark).
+  NO computed value changed — pure reorg; the shipped `--color-bg-container: var(--background)`
+  exception kept as-is. maka-tokens internal 0-consumer tokens are all governance-contract
+  scale members (z-index/control-height/spacing/radius/406) — re-pinned, NOT deleted.
+  Gates: desktop 2397/2397, ui 125/125, typecheck 0, check-dead-css clean, knip desktop+ui 0,
+  auditor exit 0. CDP light+dark captures (turn-narrative/module-skills/settings-general/first-run)
+  before/after — no visual diff.
 - [ ] **D — duplicate helper sweep (measured SMALL — the convergence campaign paid
   off)** — real dups found: formatBytes ×3 (artifact-preview-registry.ts:317,
   tool-activity/preview-utils.ts:14, voice formatVoiceBytes) → one shared util;