Building for AI design tools: what Mixtape needed to become legible to Claude Design

It turned out "well documented for humans" and "legible to an agent" are two different things. Closing the gap surfaced bugs that had been shipping silently for months.

Three years ago we modernised Mixtape's CSS for the browser: cascade layers, container queries, modern selectors. Since then, we've also converted to Web Components, full Typescript and integrated some more modern CSS. The system got easier for developers to read and extend. What we didn't anticipate was that the next reader wouldn't be a developer at all.

In April 2026, Anthropic launched Claude Design. This tool reads a codebase during onboarding to build a model of its design system, then uses that model for every prototype it generates afterward. The same would apply to v0, Bolt, and anything else that learns a design system by reading it rather than receiving human guidance. We wanted Mixtape to onboard well.

Documented for humans isn't the same as legible to an agent

We did a full pass over the codebase in March. We worked on the assumption that AI tools generally would need something more literal than what we had before Claude Design existed as a specific thing to test against. What came out of that work was a central /docs folder covering everything from Component Architecture, Memory Management and Security to Code Quality and Troubleshooting.

Then in April, Claude Design launched so we naturally pointed it at Mixtape. The assumption held up, but not completely. A developer who hits an ambiguous instruction asks a question in Slack. An AI tool infers an answer and bakes it into every design it generates from that point on. Our docs folder was solid for a human reading it top to bottom. It wasn't quite literal enough for a tool that takes every sentence at face value.

So in May we went back and wrote a structured reference file, plus richer per-component READMEs.

What we built

The main outcome is a structured  DESIGN.md reference file, read as instruction rather than advice. It resolves every design token to its actual value rather than pointing at the source and assuming the tool will resolve it: colour.primary.colour maps to --colour-primary, which is hsl(223 100% 50%), not just a path in tokens.js.

It also says explicitly what to read and what to ignore. Read src/, docs/, and mockups/. Skip notes/, lockfiles, and build config. Specifying irrelevant files matters for resource usage as well as the quality of the output.

The full-page mockups turned out to be essential too. We point the tool at a real page composition, like a search results page built from real classes, before it generates anything from scratch. Components in isolation don't show how they're meant to sit together.

Component and class inventories with explicit "Nothing else exists - don't invent stuff" instructions, composition guidance, anti-patterns and documentation for the public token API (for example font-size: var(--button-font-size, var(--font-size)) where --button-font-size has no defined value and exists only as a public token, which Claude Design can use—once it knows about it—all feature in this file.

The result is a Mixtape that Claude Design can accurately work with. Developers aren't the only ones prototyping there now. A designer can test a layout idea, or sketch a full page composition, before it ever touches Figma, using real components and tokens instead of an approximation of them. That's the use case we're aiming for. A faster way to explore an idea, not a replacement for the judgement that goes into an actual design.

The bugs it found

Writing that reference meant checking, component by component, whether the documented class actually matched the shipped code. It mostly did. Where it didn't, the gap had been sitting there for a while.

Breadcrumb was one. React was rendering a class that didn't exist anywhere in the stylesheet:

- className={classNames("mx-nav", "mx-nav--breadcrumb", "mx-nav--inline", className)}
+ className={classNames("mx-nav", "mx-nav--breadcrumbs", "mx-nav--inline", className)}

Singular in React, plural in CSS and Twig. The React breadcrumb had been shipping un-styled, and nothing caught it because our snapshot tests only check that output hasn't changed, not that it's connected to anything. Also luckily no projects are actually using the Breadcrumb component in React yet.

Sticky had a similar issue, just inverted. The web component was querying for an older un-prefixed class that used to exist but no longer did:

- let trigger: HTMLDivElement | null = this.querySelector(".sticky__trigger")
+ let trigger: HTMLDivElement | null = this.querySelector(".mx-sticky__trigger")

The web component never found the trigger element it needed to observe, so the "is sticky" check silently never activated. Nobody had flagged it, because the stickyness still worked. The is-sticky state change is just a small, optional progressive enhancement (until scroll-state container queries have better support).

Neither bug was hard to fix. Both had been invisible for the same reason: three output formats (React, Twig, Web Components) from one source, and nothing checking that a class emitted in one place was actually targeted anywhere else. It took writing documentation an AI would take literally to notice.

Where this is heading

We're not leaving this as a one-off audit. The next step is a lint rule that cross-references every mx-* class against the CSS that's meant to style it, so this kind of drift gets caught at merge time instead of during the next big documentation sweep. More on that and some other tooling additions soon, in a follow up post.