Skip to content

Enforce the design contract with syntax-aware token checks - #207

Merged
MaggieAppleton merged 6 commits into
mainfrom
maggie/design-token-contracts
Sep 30, 2026
Merged

MaggieAppleton merged 6 commits into
mainfrom
maggie/design-token-contracts

Conversation

@MaggieAppleton

@MaggieAppleton MaggieAppleton commented Sep 28, 2026 •

Copy link
Copy Markdown
Collaborator

Design contract

Raw style values could bypass the previous typography text check through JSX bindings, computed keys, DOM writes, Tailwind variants, or local token aliases. The new syntax-aware check covers typography, colours, radii, shadows, and motion, and verifies that the structured DESIGN record agrees with the shared theme.

  • Migrate 27 CSS declarations to equivalent shared roles; 26 inventory findings are removed (220 → 194 under the same final scanner).
  • Retain exact, explained, counted exceptions. New or stale cases fail the check, as do parser failures and attempts to hide values behind local aliases or inline detector disables.
  • Preserve the 3px quote edge, fluid typography, and existing interface appearance. The original Delete-button red is retained at Maggie’s request. Its white label measures about 4.20:1 against the default red, an intentional exception to the usual 4.5:1 AA target. Hover and pressed states remain distinct and above that target. The earlier darkening experiment was reversed.

How enforcement works

Authored styles pass through syntax parsing, shared-token policy and exact reviewed exceptions before CI

Retained Delete-button colour

Actual Delete button with the retained original red in default, hover, active, focus and disabled states

Verification

  • Bun 1.4.2 frozen install; bun run fix, bun run ci, bun run types, scanner TypeScript checks, and production build pass locally. Focused token and design-record tests pass.
  • Full local suite on this revision: 1,713 passed, two database-only skips, zero failed. All required GitHub CI passed on 09e99b2b: validation (including PostgreSQL), browser e2e, and container. CI run.
  • Real isolated PostgreSQL and AGENT=off browser fixture previously exercised sign-in, WebSocket editing, and desktop/mobile Chromium views. Document and typography captures were pixel-identical. The retained button screenshot is from that same real fixture before the temporary colour experiment.

Static analysis does not execute arbitrary imported code, runtime HTML, every CSS-in-JS API, or Web Animations calls. Exact runtime exceptions require review; using a shared colour alone does not prove contrast. Contributor guidance and the reviewed inventory are in docs/design-contract.md and scripts/design-contract/exceptions/.

The local visual HTML report, screenshots, inventory, and logs are retained under .design-audit/design-token-contracts/ in the task worktree. Generated evidence is excluded from the commit. No merge performed.

Integration with sibling design work

This branch restores the original red after the earlier contrast commits were shared with sibling branches. Those branches must align their colour, design record, and exact specimen assertion with this PR before integration. Source-owner review patches remain scoped to their recorded inputs. Required CI must rerun on each integrated branch.

@MaggieAppleton
MaggieAppleton merged commit faa8a98 into main Sep 30, 2026
3 checks passed
@MaggieAppleton
MaggieAppleton deleted the maggie/design-token-contracts branch September 30, 2026 08:26
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