About
Design Schema is open source and built for two people who are often the same small business, a few months apart. One of them wants a complete, accessible design system that feels like theirs; the other wants to change what the system is. Both are first-class, and the difference between them is one document.
The adopter: “I have an idea of what I want my site to feel like”
A business owner, and the engineer helping them — increasingly an AI engineer working in a coding agent — should be able to go from a description of the feel they want to a complete, accessible, working design system without generating a single component.
That works because of how the pieces divide. The components are generated once, here, for React, web components and React Native, and shipped as packages. They contain no colors, sizes or fonts of their own — every visual value is a token reference, and a build gate makes sure of it. The theme is a short Markdown doc: a seed color, a typeface, and a few decisions (tone words and the one word it must never be, radius, density, motion). The whole token set is derived from that doc deterministically, with contrast checked for every component in light and dark.
So an adopter’s entire customisation is one document, it costs nothing to build, and every component picks it up. What they get by default: the full component set on three platforms, tokens in CSS, JavaScript and React Native forms, light and dark, WCAG 2.2 AA verified per theme, a Storybook per platform, and a docs site that describes their own system rather than this one.
The owner: “I want to change the rules and own it”
A team with the means to go further does not customise the components; it customises the schema — the docs the components are generated from — and regenerates. That is the second path, and it is what this repository itself is.
Owning it means writing or editing a component’s Markdown doc, adding requirements to the accessibility vocabulary, changing the copy templates, adding a platform target, or replacing a generation template with one that matches the team’s own conventions. The generator then regenerates exactly the targets whose docs changed, runs the gates, and records the result in a lockfile that CI checks.
This path is the only place in the system that calls a model, and a lockfile means nobody pays twice for a component whose doc has not changed. Everything after the model — type checking, the no-literals gate, contrast, and the keyboard and behavior tests derived from the spec — is deterministic and free. What the owner gets is the same output as the adopter, plus the ability to add a component that does not exist yet, change what “accessible” means for their organisation, and hand the result to their own adopters as a finished system.
What both paths share
The docs are the product. An adopter reads them on a site like this one; an AI engineer reads them through the MCP server; the generator reads them as prompts; the build reads them as constraints. When a decision changes, it changes in one file, and every projection follows. That is the property that keeps the system cheap to run and possible to own: there is no second place where the truth lives.