Repository navigation
docs(design): sync DESIGN.md with the renderer's real tokens; record measured drift - #82
SPhillips1337 wants to merge 3 commits into
Conversation
…measured drift - Frontmatter: add the renderer's CSS variable tokens (surface-0..4, line-1..3, text-1..4, icon, accents), named as in styles.css, alongside the existing roles they map onto. - Colors prose: it listed a palette matching neither the frontmatter nor the CSS (#0B0F14, cyan #6EE7F9 accent, ...); now matches both. - Document the shipped light theme (from styles.css). - New "Measured drift" section: ten spec-vs-app decisions with evidence and a suggested direction (muted text fails WCAG AA on every dark surface; 13px vs 14px body; 9-10px labels; 5px radius; sidebar and palette shape; secondary has no token; stray #3B82F6; light theme). Measured with Spine Design from the running renderer. Against the same dark capture, palette coverage goes 61.9% -> 99.4% (only #3B82F6 left). No app code changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Review Summary
This PR is a documentation-only sync of DESIGN.md against the running renderer. The frontmatter token additions, color prose corrections, and drift table are accurate and well-evidenced.
One blocking issue found:
The new light theme section (lines 160–164) documents secondary text colors that fail WCAG AA contrast on both light surfaces (as confirmed by drift item #10), but unlike the dark theme section it carries no accessibility warning. The dark theme Colors prose explicitly directs readers to "Measured drift" before using sub-AA tokens; the light theme section needs the same callout to prevent implementers from using #68768A for readable text without understanding its contrast failure.
Open decisions not blocking merge (all correctly deferred to the owner per the PR description):
body-mdfont size spec vs. measured 13px (drift #3)command-paletteradius/padding discrepancy (drift #7)secondarytoken with no CSS counterpart (drift #8)- Hardcoded
#3B82F6border (drift #9) - Light theme token frontmatter (drift #10)
Aside from the accessibility warning gap noted above, the changes are accurate and the drift table is a clear and useful record.
You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.
| - **Panels (#FFFFFF):** window bar, session drawer, status bar. | ||
| - **Recessed (#EEF2F7):** rail, workspace head, empty pane. | ||
| - **Lines (#DBE2EC):** borders and the pane grid. | ||
| - **Text:** #253044 primary, #5C687B and #68768A secondary. |
There was a problem hiding this comment.
🛑 Accessibility Defect: The light theme secondary text color #68768A fails WCAG AA on both documented surfaces (#EEF2F7: 4.11:1, #DBE2EC: 3.54:1), as documented in drift row #10. However, unlike the dark theme Colors section (line 146) which warns "See 'Measured drift' before using --text-3 or --text-4", the light theme section has no such callout. Implementers reading only this section will use these colors for readable text without knowing they fail the minimum 4.5:1 contrast requirement, causing the same class of accessibility bug that drift items #1 and #2 document for the dark theme.
| - **Text:** #253044 primary, #5C687B and #68768A secondary. | |
| - **Text:** #253044 primary, #5C687B and #68768A secondary. **Note: #68768A fails WCAG AA on both light surfaces (4.11:1 on #EEF2F7, 3.54:1 on #DBE2EC — see drift item 10). Do not use it for text people must read.** |
There was a problem hiding this comment.
Fixed in 89fb8bd. I re-measured all four light surfaces: #68768A passes only on the white panels (4.62:1). It fails on the canvas (#F7F9FC, 4.38:1) as well as the two surfaces you named, so the warning and row 10 now say that. #5C687B passes everywhere (5.0:1 or better).
…tcut - Layout: Ctrl+Shift+N is "new workspace" in shortcuts.ts; a new local terminal is Ctrl+Shift+T. The doc said Ctrl+Shift+N creates a terminal. - Measured drift: now also measured in the packaged Electron app with one live local session (throwaway profile, terminal contents masked); new row 11 for session-item-active (5px radius and 9px padding vs 4px/8px). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Added a second commit: measured the packaged Electron app with one live local session (in a throwaway profile; terminal contents masked). New drift row 11 ( |
…view) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|



Summary
DESIGN.mdhad drifted from the renderer: it was last changed 2026-08-31, while the CSS kept changing until 2026-10-15. This PR syncs the facts and lists the judgement calls. No app code changes.Facts, corrected:
surface-0..4,line-1..3,text-1..4,icon, accents), named as instyles.css. A comment maps the existing roles onto them.#0B0F14, a cyan#6EE7F9accent,#E6EDF3, …) that matched neither the frontmatter nor the CSS. It now matches both.styles.css.Decisions, for you: a new Measured drift table lists ten spec-vs-app differences, each with evidence and a suggested direction. The most important:
muted(--text-3) fails WCAG AA on every dark surface, includingprimary(3.66–4.1:1, on 46 text elements).--text-2passes (5.65–6.34:1).--text-4/--line-3are used for text at 1.5–2.7:1.secondaryhas no CSS token, and a stray#3B82F6border isn't a token either.How it was measured
Spine Design captured the running renderer (Vite dev server, 1280×800, dark and light themes, plus the command palette via Ctrl+Shift+R) and compared it with
DESIGN.md. Electron preload APIs were absent, so live sessions and terminals weren't measured.Test plan
#3B82F6(drift item 9) remains🤖 Generated with Claude Code