From cb116648e8aa6d811a5f785f2fa417ed3d234f3d Mon Sep 17 00:00:00 2001 From: jackwener Date: Mon, 13 Jul 2026 20:55:14 +0800 Subject: [PATCH] refactor(css): consolidate token strata into maka-tokens (Round C) Two parallel token systems coexisted: the --color-bg-*/--color-text-* family (reference-shell.css + theme-glass.css) vs the authoritative --background/--foreground family. Nobody knew which was canonical. Census (machine-generated, var() consumers across all CSS+TSX): - reference-shell.css: 23 defined -> 16 dead (removed), 3 live color aliases (--color-bg-container/--color-border-tertiary/ --color-text-quaternary) moved to maka-tokens, 4 live layout-locals (--agents-layout-bg/--agents-content-area-bg/-gap, --sidebar-width) kept in-file with their layout rules. - theme-glass.css: 2 darwin token overrides (--color-bg-container light+dark, --color-text-quaternary) relocated to maka-tokens; all glass-material + text/label rules stay. maka-tokens.css now owns every token definition and carries a token-authority README (authoritative --background family vs compatibility --color-* aliases + alias policy). Both themes migrated (:root + .dark + darwin light/dark). Superseded hue-80 archaeology condensed (it named the deleted tokens). Pure reorganization: no computed value changed. The shipped `--color-bg-container: var(--background)` exception kept as-is. maka-tokens internal zero-consumer tokens are governance-contract scale members (z-index/control-height/spacing/radius/406) and were 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: 7/8 byte-identical, 1 rasterization-drift-only (eyeball identical). --- apps/desktop/src/renderer/maka-tokens.css | 95 ++++++++++++------- apps/desktop/src/renderer/reference-shell.css | 29 ++---- .../src/renderer/styles/theme-glass.css | 61 ++---------- .../frontend-simplification-map-2026-07-13.md | 20 +++- 4 files changed, 94 insertions(+), 111 deletions(-) diff --git a/apps/desktop/src/renderer/maka-tokens.css b/apps/desktop/src/renderer/maka-tokens.css index 13bbcc7e33..0e3b804378 100644 --- a/apps/desktop/src/renderer/maka-tokens.css +++ b/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(--)` (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 --------------------------------------------------------------- diff --git a/apps/desktop/src/renderer/reference-shell.css b/apps/desktop/src/renderer/reference-shell.css index a56cd5d6a7..4f4f38fe1f 100644 --- a/apps/desktop/src/renderer/reference-shell.css +++ b/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] { diff --git a/apps/desktop/src/renderer/styles/theme-glass.css b/apps/desktop/src/renderer/styles/theme-glass.css index 3b0baf675d..c49cb16e8b 100644 --- a/apps/desktop/src/renderer/styles/theme-glass.css +++ b/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 diff --git a/notes/frontend-simplification-map-2026-07-13.md b/notes/frontend-simplification-map-2026-07-13.md index fe3f9e03bf..e281d79eaa 100644 --- a/notes/frontend-simplification-map-2026-07-13.md +++ b/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;