Your Design System Isn't Ready for AI — And That's the Product Gap

The short answer

Most design systems are built for humans reading a spec sheet and inspecting styles. They export tokens — colors, spacing, typography — and that used to be enough. But when an AI agent generates a UI from a prompt or a screenshot, tokens alone produce weak output. The AI has vocabulary but no grammar. It picks the right blue from your palette but places it in the wrong context, or uses spacing values that feel correct visually but break your component composition rules.

The missing layer is a spec file: a structured Markdown document that encodes design principles, spacing rules, component usage guidelines, and priorities. This is not a design token. This is the API contract between your design system and any AI that consumes it. The Smashing Magazine article on making design systems AI-ready calls them "spec files" — and they represent the single highest-leverage investment you can make if you ship product with code generation tools like Claude Code, Cursor, or v0.

If you treat your design system as a set of raw values and expect an agent to divine how to use them, you have shipped a product gap. Spec files close that gap by making the rules of your interface machine-readable.

Key takeaways

• Design tokens give AI vocabulary; spec files give AI grammar. Both are required for reliable AI-generated UI.
• A spec file is structured Markdown that includes spacing rules, color usage context, component composition constraints, and priority guidelines.
• Spec files must be local-first and version-controlled so agents can read them without network dependency or API friction.
• Tools like Open-Design treat spec files as the primary interface between designers, engineers, and AI — not a post-hoc documentation artifact.
• Without spec files, AI agents will invent their own "reasonable" defaults that deviate from your brand within 2–3 generations.
• The cost of creating spec files is upfront; the payoff compounds every time a prompt replaces a manual implementation.

The Real Problem: Tokens Are a Vocabulary, Not a Grammar

A design token says --spacing-md: 16px. That tells an AI how wide a gap is, but it doesn't say when to apply it. Should every sibling element have margin-bottom: 16px? Should cards maintain 16px gutters but text blocks use 8px? Should primary buttons never have icons? Tokens have no way to express these rules.

In a hand-coded project, engineers internalize these patterns. An AI does not. It will generate a UI that uses your colors correctly but violates every spacing convention you care about. The result looks branded at first glance but feels broken to the product team — and to users, it feels like a generic template with your logo on it.

This is a product gap because the design system promised consistency but delivered inconsistency at the point of AI generation. The fix is not more tokens; it's a spec format that encodes usage rules alongside values.

What a Spec File Looks Like in Practice

The Smashing Magazine article describes spec files as structured Markdown that include "spacing rules, color choices, component usage guidelines, priorities." In practice, a spec file for a button component might look like:

# Button

## Rules
- Primary buttons must use `--color-primary` and `--color-on-primary`.
- Primary buttons must not contain icons.
- Text buttons must use `--color-link` and no background.
- All buttons must have `min-height: 44px` for accessibility.
- Loading state uses a `span` with role="status" inside the button.

## Spacing
- Gap between button and adjacent text: `--spacing-lg` (24px).
- Margin inside containers: `--spacing-md` (16px) on the left.

## Composition
- Button can be wrapped in a `ButtonGroup` container that handles margin collapsing.
- Do not nest buttons inside other interactive elements.

This file lives in your design system package, versioned alongside tokens. An AI agent reads it as context before generating. The result is a primary button that never has an icon and never violates spacing rhythm.

The Open-Design Alternative: Local First, AI-Native

The open-source tool Open-Design takes this concept further. It is a local-first desktop app that manages design systems as data — not as layers in a proprietary format. It exports spec files as part of its workflow, and because it supports 259+ skills and 142+ design systems, it treats the spec file as the canonical source of truth that both humans and AI agents read.

Open-Design also integrates with 17+ CLIs including Claude Code and Cursor, meaning an agent can pull spec files locally without hitting an API. This is a crucial architectural decision: spec files must be available offline and in plain text. If your design system lives in a Figma plugin that requires network authentication, AI tooling won't reliably access it. Local-first, Markdown-based specs remove that barrier.

Tradeoffs: When Spec Files Become Bureaucracy

Spec files create value only if they stay current and lean. Over-documenting leads to stale rules that agents follow even after a design change, or to a maintenance burden that nobody wants. The line is: if a rule is obvious from the token name (e.g., "--color-error" for error states), don't restate it in a spec file. Reserve spec files for rules that require context — what elements should not occur together, or when a token usage is prohibited despite being available.

Another tradeoff is tooling. Currently, no widely adopted linter validates spec files against generated code. You will need to build custom CI for now, or rely on spot-checking. The cost of building that validation may be worthwhile only if your team generates UI from prompts multiple times per week.

Closing: Ship the Contract

The most product-minded move you can make this quarter is to pick one component — your most-used button or card — and write a spec file for it. Then give that file as context to an AI code generation tool and see if the output matches your expectations. If it doesn't, refine the file. Once it does, you have a repeatable contract. From there, expand to your full design system.

AI-generated UI is not a future trend; it is today's shipping reality. Your design system either has a grammar for that conversation, or it lets the AI make up its own. Spec files are the grammar.