Skip to content

docs(design): sync DESIGN.md with the renderer's real tokens; record measured drift - #82

Open
SPhillips1337 wants to merge 3 commits into
mainfrom
docs/design-md-measured-sync
Open

SPhillips1337 wants to merge 3 commits into
mainfrom
docs/design-md-measured-sync

Conversation

@SPhillips1337

Copy link
Copy Markdown
Contributor

Summary

DESIGN.md had 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:

  • Frontmatter colours now include the renderer's real CSS variable tokens (surface-0..4, line-1..3, text-1..4, icon, accents), named as in styles.css. A comment maps the existing roles onto them.
  • The Colors prose listed a third palette (#0B0F14, a cyan #6EE7F9 accent, #E6EDF3, …) that matched neither the frontmatter nor the CSS. It now matches both.
  • The light theme, which ships but wasn't documented, is described from 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, including primary (3.66–4.1:1, on 46 text elements). --text-2 passes (5.65–6.34:1).
  • --text-4 / --line-3 are used for text at 1.5–2.7:1.
  • Body text is 13px against a 14px spec; there are 9–10px labels; rail buttons use a 5px radius, off the scale.
  • The session sidebar and command palette shapes differ from their component specs. secondary has no CSS token, and a stray #3B82F6 border 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

  • The frontmatter still parses: 28 colours, 4 typography entries, 12 components
  • Against the same live dark capture, palette coverage goes 61.9% → 99.4%; only #3B82F6 (drift item 9) remains
  • Owner: decide each drift row (update the spec or fix the app)

🤖 Generated with Claude Code

…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>

@amazon-q-developer amazon-q-developer Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-md font size spec vs. measured 13px (drift #3)
  • command-palette radius/padding discrepancy (drift #7)
  • secondary token with no CSS counterpart (drift #8)
  • Hardcoded #3B82F6 border (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.

Comment thread DESIGN.md Outdated
- **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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛑 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.

Suggested change
- **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.**

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@SPhillips1337

Copy link
Copy Markdown
Contributor Author

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 (session-item-active: 5px radius / 9px padding vs 4px / 8px), and a factual fix: Ctrl+Shift+N is new workspace in shortcuts.ts, new local terminal is Ctrl+Shift+T.

…view)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant