A design system your coding agent can actually hold.

DESIGN.md

A portable contract, not a config file.

Your philosophy with the sacrifices spelled out, a decision table where every choice carries an id, and tokens that point back at the decision that produced them. It stays useful pasted into a plain chat, and a designer can read it to find out why a value is what it is.

A design system, not a theme

Tokens, component contracts, and states.

Every component ships an anatomy, a state matrix — including the states that deliberately do not apply and the reason — an accessibility contract, and the token slots your decisions fill. Contrast pairs are declared, so they can be measured rather than assumed.

omd book

Your system, browsable on a local port.

Run one command and read the system back: each token beside its decision, component state matrices with their reasons, contrast measured live against the pairs you declared, and which presets your build drew from. --static writes a single HTML file for handoff.

Philosophy first, values second

The chain runs philosophy → decision table → tokens → component specs → layout grammar → build. A token value with no decision behind it fails a gate, so the system cannot quietly become a pile of improvised numbers.

A floor made of validated contracts

93 presets across four layers — fundamentals, primitives mapped to real shadcn/ui and Radix components with their ARIA APG patterns, screen genres, and reference-derived flavors. The agent selects and derives instead of inventing from zero.

Gates that name the failure

Numbered anti-slop gates cover the things AI-generated UI gets wrong in the same way every time: serif fallbacks on Korean text, focus rings on mouse clicks, native select popups, disabled states faked with opacity, wide viewports left empty. Mechanically checkable ones must be grep-verified.

Judged on screens, not source

The build renders, a critique reads the rendered screens and produces a numbered punch list, and the repair happens inside the existing system. Source-only self-grading is what lets a broken screen score well.

Provenance you can audit

440 company references ship with the package, quality-graded, with evidence for their claims. Unknown values stay absent instead of becoming plausible defaults — a missing brand fact is never filled in with a guess.

Files you own

Everything above is markdown and JSON inside your repo. No daemon, no MCP server, no API key for the core workflows — inference stays in the coding-agent session you already pay for.

Rewrite the philosophy

The stance and its sacrifices are yours to state. Change them and the decision table, the tokens, and the components follow — that is the whole point of deriving instead of theming.

Fork or extend the presets

Presets are markdown contracts in your repo. Add a genre your product needs, tighten a primitive to your accessibility bar, or drop one entirely and record why.

Tune the gates

Gates are a numbered list, not a black box. Raise a threshold, add a rule your team keeps re-learning in code review, and the next build has to answer for it.

Bring your own references

The catalog is data. Point the workflow at your own brand evidence and the derivation runs on that instead of a public reference.