As UI generation moves from manual handoffs to agent-driven workflows, a single, human-friendly file that encodes both exact token values and design intent becomes essential. This project treats a DESIGN.md file as the canonical source-of-truth: machine-readable tokens (YAML front matter) for deterministic outputs and prose for the why — enabling automated tooling to make safe changes, run accessibility checks, and emit interoperable token formats.
What Sets It Apart
- Combines normative tokens + human rationale: tokens give exact values agents need; prose explains purpose and constraints so agents act on semantics, not just variables. This reduces regression risk when agents modify themes.
- Tooling-first UX: a CLI and programmatic linter that surface broken token refs, WCAG contrast issues, and token diffs — so agents can validate changes before committing them.
- Interoperability targets: exporters for Tailwind (JSON/CSS) and a DTCG (W3C design tokens) emitter make the format practical for real projects and existing build systems.
Who It's For and Trade-offs
Great fit if you coordinate agent-driven UI generation, maintain cross-platform design tokens, or need a single writable artifact where designers and agents co-author intent. It helps teams that want automated linting, token diffs, and deterministic exports into CSS/Tailwind. Look elsewhere if you only need a binary design system (pure styleguide UI) without prose, or if you require a finalized, versioned spec with long-term stability guarantees — the format is alpha and evolving, so adopters should expect breaking changes and iterate with the project.
Where It Fits
Think of this as the bridge between design tokens (W3C-style) and practical engineering workflows: it complements design-token libraries and CI by adding a prose layer for instruction to agents and a linter/exporter to slot into pipelines. Use it where automation, accessibility checks, and token interoperability matter more than fixed-format stability.
