docs(design): codify DESIGN.md as enforced visual authority - #320
Merged
Conversation
Records the shipped "Lamplit Tome" system — warm-only palette, serif for fiction and sans for machinery, flat-by-default depth — as DESIGN.md plus an .impeccable/design.json sidecar, and adds PRODUCT.md for the durable product record. CLAUDE.md working rule #5 makes both binding. Writing the doc against the source turned up drift the doc then had to fix. The hero-card border was two near-identical literals (EFC9B4 / F0CDB8) at four call sites with no dark value at all, so dark mode drew a pale peach ring around a near-black card; it is now one JuiceTokens.borderHero with a real dark twin. The campaign identity palette shipped Indigo and Plum, the only cool values in the app's chrome — rewarmed to Mulberry and Umber, keeping five identities separated by hue and value. Stock Material colors were doing semantic work in five places (sketch toolbar, funnel, disposition, AI-ready check, tally) and now read tokens. Modals were the largest surface still on raw M3 defaults despite 60+ call sites, so sheets, dialogs and snackbars join the tome, along with disabled/focus/hover state colors that M3 rendered gray. test/design_system_test.dart makes six of the named rules mechanical rather than aspirational: One Shadow, Warm-Only, Two-Voice, identity-spine warmth, hero-border-is-a-token, and a ratchet pinning raw ColorScheme use at 131 so it can only shrink. Card and chip theming stay deliberately unthemed — a global override restyles hundreds of widgets for little gain, and the ratchet is the mechanism for retiring that debt surface by surface. Co-Authored-By: Claude <noreply@anthropic.com>
5 tasks
deepiq2022
added a commit
that referenced
this pull request
Jul 25, 2026
Browser verification of the design system caught a real defect the green suite could not see: in dark mode the primary button rendered as a pale peach with dark text. Material derives a light `primary` for dark schemes, so the app's most important control was the one element on screen not wearing Lamplight Terracotta — a flat break of DESIGN.md's Rubrication Rule. Light mode had hidden it, because the amber seed's light `primary` happens to land near the token by luck. The fill is now set from JuiceTokens at the theme in both brightnesses, with the label flipping per mode: near-white ink on the deep light clay, page-dark ink on the lifted dark clay. Also ships the primary lift, the second and last shadow DESIGN.md sanctions and the only one it had left unimplemented. It rides Material elevation with a terracotta shadowColor rather than a literal BoxShadow, so the button lifts without spending the One Shadow Rule's budget, and no call site hand-rolls it. Warm-tinted per The Warm Shadow Rule — a neutral shadow on cream paper reads as plastic. Verified in the browser at both brightnesses, alongside the rewarmed campaign identity spines from #320, which render distinct in light and dark with Umber separating from Terracotta by value as intended. Co-authored-by: John Taylor <jttaylor63@gmail.com> Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.impeccable/design.jsonsidecar, and PRODUCT.md for the durable product record. CLAUDE.md rule Campaign file export/import (BYO cloud) #5 makes both binding.#EFC9B4/#F0CDB8) at four call sites with no dark value — a pale peach ring around a near-black card. Now oneJuiceTokens.borderHerowith a real dark twin.test/design_system_test.dartmakes six named rules mechanical: One Shadow, Warm-Only, Two-Voice, identity-spine warmth, hero-border-is-a-token, and a ratchet pinning rawColorSchemeuse at 131 so it can only shrink.Card and chip theming stay deliberately unthemed: a global override restyles hundreds of widgets for little gain, and the ratchet is the mechanism for retiring that debt surface by surface.
Test plan
flutter analyzeclean (one pre-existinginfointest/embark_sheet_ui_test.dart, untouched by this change)flutter testpasses — 2192 tests, including 6 new design-system rules🤖 Generated with Claude Code