Your Design System Is Useless to AI

I built a design system the right way. Tokens in Figma, components in Storybook, documentation in Notion. It had real structure: a color primitive layer that fed semantic tokens, component docs with states and usage guidelines, a Figma library that the engineering team actually used. Six months of careful work. A real design system, not just a style guide masquerading as one.

Then I tried to use it with AI.

I asked Claude to build a data table matching our product. It came back with a light-themed, rounded-corner, Tailwind-looking thing. Soft shadows, generic header treatment, wrong fonts everywhere. Our product is dark-themed with dense rows and a separate typeface for numeric cells. The output looked like it had never seen our design system, because it hadn't. Claude is fully capable of building a dark data table. It just had no way to read the spec I'd spent months writing.

This is the gap nobody talks about. Your design system was built for humans to read in Figma and Notion. It was never structured to be consumed by a language model at session start and applied to a blank file. Those are different problems with different solutions.

Where Design Systems Break Down for AI

Figma is the home of most mature design systems, and it's nearly useless for this purpose. When Claude accesses a Figma file, it sees node IDs and vector coordinates. It can tell you a rectangle exists at a certain position. It cannot reliably extract the semantic meaning: that this dark rectangle is a frozen table header, that its background maps to a specific token, that the text inside uses a particular weight and tracking to signal hierarchy. The visual layer and the specification layer are not connected in any way a language model can follow.

Storybook does better because it's code, but it buries design decisions in implementation. To understand what color a header uses, you have to read props, trace through theme files, follow CSS-in-JS token references, and reconcile what the code actually produces with what the design intended. Possible in theory. Not how a productive session works.

Notion is the most insidious. It looks like documentation and reads well to humans, but it's prose. "The primary action button should feel confident and accessible." What font? What size? What weight? What color at rest, hover, and active? Notion wikis describe design systems the way wine reviews describe wine. Evocative and useless for specification.

What an AI actually needs to build something that matches your product is simple: exact values, explicit relationships, and a file format it can read natively. That's it.

Why Plain Markdown in a Folder Works

Obsidian stores notes as flat Markdown files on your local machine. That sounds boring. It is boring. That's the point.

Claude reads Markdown natively, without conversion, without API translation, without losing structure. You point it at a folder as project context and it can read every file. More than read, it can hold multiple files in working memory at once and reason about the relationships between them. Token files map to component docs. Component docs reference each other. The whole system is readable in a single session.

Obsidian adds one feature that matters: wiki-links. [[Surface Colors]], [[Table Component]], [[Button]]. Inside Obsidian these are clickable navigation. For Claude, they're semantic edges in a graph. When a component doc links to its token files, Claude follows the dependency. It knows the table header background comes from a specific surface color token, which comes from a specific primitive. The design system has structure, and the structure is readable.

The vault is also local-first. No server, no sync delay, no rate limits. Claude reads from disk. The loop between asking for a prototype and opening it in a browser takes seconds, not however long it takes an API to export and convert a Figma file.

The Vault Structure That Actually Works

I tried a flat pile of Markdown first. It doesn't work. Claude burns its context window figuring out which file has the color palette versus which file describes the button hover state. By the time it starts generating, it's already lost. Structure matters, and the right structure has three layers.

Tokens are raw values, nothing else. Every hex code, every font stack, every spacing unit. Primitive tokens are the palette. Semantic tokens map those primitives to usage: this color is the frozen header background, that color is the secondary text treatment on data rows. When Claude needs to know what color something should be, the answer is in a token file and only in a token file.

Components consume tokens and define anatomy. A table doc specifies exact row heights, which surface color token the header uses, the font and size applied to numeric cells, and what changes at hover and active states. Every measurement. Every color. Every state. Components link to each other too: the table doc references the tooltip, the tooltip references the dropdown, the dropdown references the overlay pattern. Claude follows this graph and builds things that compose correctly.

Patterns describe recurring interactions that span multiple components. How a disclosure panel expands and collapses. How a popover positions itself relative to its trigger. How inline form validation surfaces errors without moving layout. These are the behavioral docs, one layer above visual specification.

The Two Files That Do Most of the Work

Index.md is the table of contents. It lists every token file, every component, every pattern, and their implementation status. When Claude reads this at session start, it knows what exists without opening every document in the vault. This matters because a 30-component design system has maybe 40 files. You don't want Claude reading all of them upfront before you've asked a single question. The index gives it a map. It reads the territory on demand.

CLAUDE.md is the instruction file. It tells Claude how to behave inside this vault: read Index.md first, pull component docs only when the conversation needs them, never write to the vault without explicit instruction, always trace colors back to a token file, and treat screenshots as higher authority than documentation when they conflict. Think of it as the brief you'd write for a new designer joining the project, except this one gets read at the start of every session, not just the first one.

The most useful trick in CLAUDE.md is caching your core tokens directly in the file. Not as a reference to the token files, but the actual values, inline. Your background colors, your text hierarchy, your font stacks. Claude reads CLAUDE.md at session start, so it holds your essential tokens in working memory before it opens a single other file. The first prototype it generates doesn't need to pull a token file because it already has the values it needs.

Specificity Is the Whole Game

The difference between a component doc that works and one that doesn't is specificity. Exact pixel values and hex codes, not descriptions of intent.

"The header should have a dark background" tells Claude nothing it couldn't guess. It will pick some dark blue from its training data and it will be wrong. "Header background: --bg-header (#1B2E4A), height: 56px, text: 12px Inter SemiBold, color: --text-secondary (#8E8E96), letter-spacing: 0.08em, text-transform: uppercase" tells Claude everything it needs. The first prototype will be right.

Every component doc needs four things: an anatomy section with exact pixel values and hex colors, a tokens-used table that maps token names to values to usage, state definitions for every interactive state, and wiki-links to related components so Claude understands how they compose. Anything vague is a place where Claude will make something up.

Variant docs are a special case. A compact table variant that shares 90% of its anatomy with the base table should not repeat those 90%. It should say "same as [[Table]], except row height is 18px and header reduces to 40px." This keeps the vault honest and prevents drift. When the base table spec changes, the variant doesn't need updating because it never duplicated the shared spec in the first place.

How a Session Works

You connect the vault folder to Claude as project context. It reads CLAUDE.md and Index.md. Two files, a few seconds. Now it knows the shape of your design system and how to behave inside it.

You share whatever you're working on: a screenshot of an existing screen, a feature description, a rough sketch. Claude pulls component docs on demand. Building a settings panel? It reads the modal component, the form input docs, the relevant token files those reference. Nothing else. The context window stays focused on the problem at hand, not on reading files that have nothing to do with the current task.

Claude generates a self-contained HTML file. One file, no dependencies beyond Google Fonts. You open it in a browser. It looks like your product because it used your tokens. You give feedback: row height is off, the header needs to be sticky, add an empty state. Claude edits. You refresh. The whole loop takes minutes, not hours.

Most sessions end without touching the vault. You've generated three or four prototypes, tested a direction, maybe shown it to a stakeholder. The experiments live in a scratch folder. The vault stays clean. Occasionally a session produces something real, a component design that's been through review and is ready to document. That's when you tell Claude to save it: it creates the component doc with full anatomy, updates Index.md, links related docs. The vault grows by one. The next session starts a little further ahead.

The Compounding Effect Nobody Talks About

Week one is slow. You're writing token files, documenting your first few components, figuring out what level of detail the system actually needs. The vault has eight files. Prototypes require two or three rounds of correction before they look right.

By week six, something changes. Claude starts getting things right on the first pass. It has no memory between sessions. Nothing about the model has improved. But the vault now has 25 components, and the new thing you're building uses 12 of them. Claude reads those 12 docs, applies the tokens, and the prototype arrives looking like it belongs in your product. You stop correcting styling. You start correcting design decisions. That's a different conversation entirely, and it's the one that's actually interesting.

By month three, a full-screen feature prototype that would take a day in Figma takes 45 minutes. A new settings screen pulls from the existing nav component, the existing form pattern, the existing table tokens. The only genuinely new design work is the settings-specific layout and the novel interactions. Everything else is already in the vault, and Claude knows where to find it.

The interesting thing is not that "AI makes prototypes faster." The interesting thing is what happens to the system itself over time. Every component doc you save makes the next session more accurate. Every token file eliminates a category of error. Figma libraries don't compound this way because Figma wasn't built for AI consumption. The vault was. That difference widens every week.

What Will Burn You

One giant Markdown file. I've seen people dump an entire design system into a single 4,000-line document and wonder why Claude's output is inconsistent. Context windows are finite. By the time Claude reaches line 3,000, it's fuzzy on what it read at line 200. Split by concern: one file per token category, one file per component. Small files that link to each other will always outperform a monolith.

Documenting vibes instead of values. "The interface should feel minimal and professional." What font? What size? What weight? What color at rest, at hover, at active? "Minimal and professional" is a mood board. 14px Inter 400, color: #8E8E96, line-height: 1.5 is a spec. Claude executes specs. It cannot execute moods, and neither can your engineering team.

Saving everything. If every experiment gets committed to the vault, you'll have 40 half-finished component docs contradicting each other within a month. Treat the vault like a codebase. Prototypes go in a scratch folder. Confirmed work gets committed. The distance between those two spaces is where quality control lives.

Letting Index.md go stale. If your index says 15 components but you actually have 24, Claude will miss 9 of them on every session it doesn't happen to pull those files. Update the index every time you save a component. Thirty seconds of maintenance. Skip it and you pay in accuracy across every session until someone fixes it.

Start With Three Files

You don't need to migrate your entire design system before this becomes useful. Three files is enough to start.

Index.md listing what exists, even if the list is short. CLAUDE.md with your core rules and your most-used CSS custom properties cached inline. Colors.md with your full palette in hex values, organized by primitive and semantic layer.

That's it. Claude will generate prototypes that use the right colors and fonts on the first try. Everything else, you add as you go. Document a component after you've designed it, not before. Let the vault grow from real work, not from a documentation sprint you'll abandon by Thursday.

Six months from now, you'll have a vault with 30 components, a dozen token files, and pattern docs for the interactions that show up everywhere. New designers on your team will use it to onboard. Developers will pull the token tables as their CSS reference. And when you ask Claude to build something, it will build something that looks like your product, because you gave it the information it needed to do that.

The design system you built in Figma and Notion was built for human readers. This one is built for both. That's not a minor distinction.