CCDS: a design system that ships itself

The problem

A prototype made of drawings answers questions about layout. It cannot answer the questions that decide whether something ships. What the keyboard does. What a screen reader says. What happens at 375 pixels on a bad connection. Whether the spacing a designer chose exists in the system at all.

The usual fix is a prototyping tool that approximates the design system. The approximation is the problem. Anything built in it has to be rebuilt to become real, and every rebuild is a chance to quietly drop the parts that were never visible in the drawing.

So CCDS is not a mock of the design system. It imports the real component package from the internal registry and the real ClearCo 3.0 tokens, in a Vite + React + TypeScript app that a product manager can run on their own laptop. What you build in it is made of the same material as the product.

Token architecture

Tokens are tiered, and the tiers are enforced rather than described. A component names a role; it never names a color. The raw palette is internal to the token layer, so a re-theme moves one file and every surface follows.

Four checks run against that rule, and they fail a build rather than filing a ticket:

• check-token-names — a token referenced anywhere must exist.
• check-token-drift — no value drifts away from the token that owns it.
• stylelint — no raw color reaches a stylesheet.
• check-doc-refs and check-doc-index — the documentation names real things, and nothing lands undocumented.

The point is not tidiness. An unenforced rule in a design system is a preference, and preferences lose to deadlines. A rule that fails a build is the only kind that survives one.

Component contracts

UX-README/ is the design surface, written for people and machines at once. It holds the design language, the token usage rules, the accessibility standard, the personas, the information architecture, and the voice and tone. Then a specification for each component and each organism.

That audience is the part I would not change. AGENTS.md in the root exists only to point at CLAUDE.md, so Codex, Cursor, Copilot and the rest read the same instructions Claude Code does — one specification, not one per tool. An agent asked for a component reads the contract before it generates, which is the difference between a contribution and a plausible-looking near-miss.

A handful of primitives the component package does not ship — tooltip, slider, scroll area, separator, breadcrumb — live as thin repo-owned wrappers rather than as forks. The refusal matters more than the additions: every variant I declined kept the contract small enough to be read in one sitting, by a person or otherwise.

Adoption

The constraint I designed around is that nothing installs off the corporate network. Dependencies resolve through a private registry, so a fresh clone needs a real install on the VPN and nothing is vendored into git. That is a real limit on who can pick this up, and it shaped the rest. new:page scaffolds a page, so the first five minutes are not spent on setup. build:reference generates the reference, so it cannot drift from the code it documents.

I built it in two weeks, working with an agent — not something I could have written eighteen months earlier. Two days after I showed it, someone forked it into their own repository without being asked. No kickoff, no project, nobody chasing them.

I have presented a lot of proposals and I have learned to distrust a room. People nod at a good argument because nodding is polite and costs nothing. Someone taking a copy without permission is the only adoption signal I have ever trusted.

The sandbox, running

The link above (opens in a new tab) opens the thing itself rather than a description of it — every page, behind the same sign-in as this one, so it costs you nothing extra to look.

It is a reconstruction, and says so on the way in. The internal component package resolves from a private registry and cannot be installed outside the corporate network. So a stand-in reproduces its export surface on public Mantine. The application source is untouched: the same files, resolving through an alias. Rendering is Mantine's with the ClearCo anchors applied rather than the real library's, the data grid is a plain table, and the rich text editor is a textarea.

What survives the reconstruction is the part worth showing: the architecture, the token layer, the gates, and the contracts an agent reads before it generates.