Principles
A design system is a set of decisions other people have to live with. The decisions below are what make helixui a system. If you disagree with one, you’ll be fighting the framework — which might be the right call for your project, but you should know that’s what you’re choosing.
The canonical version of this list is MANIFESTO.md
at the repo root.
1. Tokens are JSON. Code is downstream.
DTCG JSON is the source of truth. CSS variables, TypeScript types, the LLM manifest, the Figma library — all build outputs.
2. Every component documents itself.
Each component owns a sibling spec.md. Three different consumers (docs
site, LLM manifest, MCP server) read the same file.
3. The cascade is your friend.
Semantic tokens reference primitives by CSS variable. DNA mutates a primitive; the cascade does the rest. No re-render. No recomputation.
4. AI is a first-class consumer.
The system is introspectable (parseable files), predictable (no surprising escape hatches), and loudly wrong when misused (validator catches invalid combinations).
5. A theme is a genome, not a switch.
22 genes. Dominance + recessives + mutations. Themes you can breed, not just configure.
6. One React tree, many surfaces.
The same <Deck> renders to DOM and exports to PPTX. The same
<Document> renders to DOM and exports to DOCX. Brand never breaks
between surfaces.
7. The system is small enough to read in one sitting.
8 packages, ~80 components, ~600 tokens. We will say no to features that don’t earn their place.
8. Accessibility is not a feature flag.
Every component ships meeting WCAG 2.1 AA. Regressions are bugs, not trade-offs.
If one of these decisions hurts your project, open a discussion. We won’t always change the system, but we’ll explain ourselves.