The Missing Layer in Design Systems
Reasoning as Infrastructure
TL;DR: Design systems have always struggled with adoption. Not the components themselves, but the reasoning behind them. The thinking gets lost in docs nobody reads. Now there’s a way to fix this: specs that load automatically into the AI tools teams already use like Cursor and Claude Code. So what goes in the specs?
What Actually Gets Lost
I’ve worked on design systems for most of my career. The components get adopted. The reasoning doesn’t always. Smart teams build the right buttons in the wrong contexts, skip confirmation patterns, assemble UIs that technically use the system but feel off.
Design systems solve the what. Here’s a button. Here’s a card. Here’s how to use them.
But when do you use a modal vs. inline editing? What’s the confirmation pattern for destructive actions? How do you handle empty states? Why does this flow work the way it does?
The best component libraries document this. But even well-written docs get skipped. They require people to remember to read them.
For most teams, the why lives in people’s heads. Or in Notion pages nobody visits. Or in processes that can’t keep up.
You build components. You document them. You publish the library. Then someone uses the right button in the wrong context. Someone skips the confirmation on a destructive action.
The components are consistent. The thinking isn’t.
Why Now
Design systems always made sense. The problem was getting people to use them.
Now multiply that by AI. Designers and PMs in Cursor. Engineers in Claude Code. Everyone’s generating UI faster than teams can review it, and each prompt starts from zero. Same component library, totally different decisions about how things should behave. Every prompt is a fork. The drift compounds fast.
The old fix was process: design reviews, pull requests, oversight. That never scaled well, and it scales even less when everyone’s prompting AI.
Design system drift doesn't always announce itself. It builds over time. A toast that dismisses too fast. A flow that technically uses your components but ignores the interaction pattern. Each one is small. But they compound into an experience that feels inconsistent, even when every component is "correct." Users notice before teams do.
The missing layer is reasoning that loads automatically. The design system becomes infrastructure.
The Insight
Drew Breunig wrote about a software library with no code, specs and tests that any LLM can implement on demand, in any language. The library isn’t code you import. It’s a specification that tells AI how to generate code.
Chester, an engineer I work with at Sibi, read that and slacked me: “What if, instead of actual code, we invest in tools to give LLMs the context needed to implement new features in patterns consistent with our design standards?”
That question clicked. I’d been using a version of the README method with Try/Keep. Context docs that give AI what it needs to build consistently. The concepts were there. Chester’s question connected them to design systems at team scale. We’re exploring this together at Sibi.
What if your design reasoning loaded automatically, before anyone prompted anything?
Not docs people have to remember to read. Context that’s already there, in the tool they’re already using.
Most AI coding tools support this. Claude Code has claude.md, Cursor has .cursorrules. The file names vary but the principle is the same: a config file at the root of your project that the tool reads automatically. Every session starts with your specs loaded.
context
├── claude.md ← orchestration (auto-loads)
├── PROJECT.md ← who/what/why
├── SYSTEM.md ← interaction principles & guidelines
├── PATTERNS.md ← grows as you build
└── features/ ← per-feature specsThe engineer doesn’t have to adopt anything. The designer doesn’t have to remember every little principle or component. The PM doesn’t have to configure anything. It’s just there.
Design system adoption gets a lot easier when the system is the default.
If you're already building with AI and feeling the drift, this is for you. I've validated this approach solo. Try/Keep went from design to App Store in a month with consistent results. Multiplayer is the open question, and that's why I'm publishing now: to learn what breaks at scale.
The question shifts from “how do we get people to follow the system” to “what reasoning should we define?”
The Layers
The spec isn’t one monolithic doc. It’s layers that cascade. Here’s my thinking so far:
Universal principles: true across products. Confirm before delete. Validate on blur, not while typing. Toast duration and behavior. Baseline UX decisions that rarely change.
Product-level principles: tied to your users’ real conditions. For example, a field service app might optimize for offline-first, screen glare, and voice input. All driven by one fact: technicians work from vans with spotty service and no time to type.
Feature-level specs: specific interaction patterns for this flow. What the empty state says. How many items show before scroll. What actions are revealed on tap.
All three load automatically, in the right context. The person building a new feature gets universal principles, product principles, and feature specs baked into their process.
The Structure
Here's how those layers map to actual files:
claude.md is the orchestration layer. It tells AI: “Before you do anything, read these specs. Follow these rules. Reference this system.” It runs automatically. And as you learn more about what works for your team you can prompt it to add that rule to claude.md. E.g., every time we create something more than once, recommend we turn it into a component.
PROJECT.md is context. Context for your team and the LLM. What you’re building, why it exists, who it’s for.
SYSTEM.md is the taste layer. Not tokens. Those live in your component library. These are the decisions that components can’t always fully capture.
A universal principle: “Success notifications auto-dismiss after 3 seconds. Errors stay until the user acknowledges it.”
A product-specific decision: “When recommending a replacement dishwasher, explain why that dishwasher works with their home.”
A constraint: “Assume intermittent connectivity. Always show last-known state.”
These are interaction principles tied to user problems. The stuff that makes something feel designed, not just assembled. Revise as you iterate. You can include a changelog of what shifted and why - so future team members (or future you) don't have to remake decisions that already got made.
PATTERNS.md grows as you build. When you create something reusable, document it. The file starts empty and accumulates.
features/ holds specs for each feature loop. When you have a Figma design, link it via MCP. When you don’t, describe the problem and let AI propose solutions within your system.
The Taste Layer
This is the part that matters most and gets documented least.
Component libraries give you what. Buttons, inputs, cards. Even good ones with usage guidelines don’t give you when or why in a way that’s enforceable.
When you document interaction principles and tie them to real user problems, AI no longer needs to guess how your components interact.
One thing I've noticed: behavior + rationale land better than abstract rules. Not “validate on blur” but “validate after focus leaves, not while typing. Red text before they’re done typing makes it feel like they’ve made a mistake”. The reasoning makes it stick.
What I learned solo
I tested this solo when I built my app Try/Keep. Started with a rough prototype in Claude just to feel the flow, then designed a full system in Figma with tokens, components, variants. I wrote a brief (PROJECT.md) explaining what the app does and how it works. In Claude Code, I pulled in the design system via Figma MCP, added references to Apple’s Human Interface Guidelines, and captured it all in SYSTEM.md. I included rules like: if I violate iOS patterns, flag it; if we use something more than once, turn it into a component.
Then I built each feature by describing what the user is trying to accomplish, linking the Figma designs via MCP, and letting Claude Code implement it. Because context loaded automatically on every session, AI building was much more accurate.
I’d been using versions of this method solo for about a year across different projects. Try/Keep was the cleanest end-to-end test. A month later (part-time), the first version was in the App Store.
In practice
Auditing existing flows
Once you have baseline principles defined, ask: “Where have we broken these?”.
An example guideline I tested out in Sibi’s main app:
Success is brief (3s auto-dismiss), errors persist (5s+). Success messages that require dismissal interrupt flow. Users stop what they’re doing to click “X” on a message that just says “Saved.” That’s friction for no reason. But errors that vanish too quickly leave users confused. “Wait, did something fail?” Success should get out of the way. Errors should stick around until the user knows what to do.
I asked Claude to audit using system.md. It came back with specific findings: six files where toasts either had no duration, used 1000ms (too short), or showed errors for only 3 seconds.
In seconds, a mini interaction design review and I was able to commit these fixes.
The audit also reveals gaps in the principles themselves. Rules that are too rigid, or edge cases you hadn’t considered. The audit becomes a feedback loop. "Copied to clipboard" can be shorter than 3 seconds, so I adjusted the guideline to match duration to the weight of the action. The spec gets smarter as you refine it.
Building new features
Open your preferred AI coding tool in plan mode. Describe the problem you’re solving. Ask for 2-3 approaches.
Because specs load automatically, proposals use your component library, follow your interaction principles, and fit the product context. You’re not starting from scratch. You’re starting from your system.
When you have Figma designs, link them via MCP. AI sees both: what it should look like (Figma) and how it should behave (your specs).
Have it document the build as you go. Update specs when you make big changes.
Where This Goes
Pipeline integration - Chester asked, what if these specs run as automated checks? Well imagine this. A new PR gets opened. The pipeline reads SYSTEM.md and flags violations before code review. “This destructive action doesn’t have a confirmation.” “This form validates while typing instead of on blur.” Design review happens automatically, before it hits production.
Designer reference — Designers can ask “What’s our confirmation pattern for destructive actions?” and get an answer. Instead of having to hunt through Figma or asking teammates. The spec is always current because it’s what the code follows.
Onboarding — A new team member joins, they open the project, the context is already there. They don’t need three weeks of knowledge transfer. The reasoning is documented, and it loads automatically. They can ask their codebase a bunch of questions and see decisions and reasons for those systems.
AI agent context — This isn’t just for humans prompting AI. It’s for AI agents operating autonomously. An agent building a feature has the same constraints, the same principles, the same taste layer as a human would. The spec becomes the shared understanding between humans and AI.
From specs to skills — The .md structure is the simplest form. Text files that any tool can read. But these same principles can evolve into more sophisticated formats: Claude's skills system, Cursor's agent configurations.
Cascading systems — Universal UX principles like toast behavior, confirmation patterns, validation timing. These become a base layer that any project can inherit. Product-specific principles layer on top. Like CSS: base styles, then overrides. Your team’s taste encoded once, applied everywhere.
Try It
You don’t need to build this from scratch. Here are starter prompts to set up the structure.
For an existing product with a design system:
I want to set up an AI-readable design system spec for this project.
Create a config folder with:
1. **PROJECT.md** Ask me about:
- What this product is (one sentence)
- Who it's for (specific roles, not "users")
- What problems it solves (what was painful before?)
- Why those problems matter to those people
- Where it's going (what's next?)
2. **SYSTEM.md** — Include:
- A reference to our existing design system/component library (I’ll tell you where it lives)
- Section for “Interaction Principles” Two parts:
- First, ask me about the product's core philosophy: What should the user always feel in control of? What should the system handle automatically? When should we slow users down vs. get out of their way?
- Then, scan the codebase for behavioral patterns (modals vs inline, confirmation dialogs, loading states) and propose how to codify what you see. I'll tell you what's intentional vs accidental.
- Section for “Visual Preferences” (tokens over palette, component preferences)
- Section for “Gotchas” (common mistakes to avoid)
3. **PATTERNS.md** — Start empty with a header explaining: “Patterns get added here after they’re validated in code. Check existing components first.”
4. **features/** folder — Empty for now, explain that feature specs go here
5. **Update claude.md in the project root** (or create one if it doesn't exist) that tells AI:
- Always read PROJECT.md first
- Check features/ for specs before building
- Follow SYSTEM.md for design decisions
- Check PATTERNS.md before creating something new
- Add to PATTERNS.md when something reusable emerges
Ask me questions to fill in PROJECT.md and SYSTEM.md. For interaction principles, propose some based on what you observe in the code, then I’ll refine.To audit an existing codebase and draft system principles from what’s already there:
This inverts the process: instead of writing rules and auditing, have AI propose rules based on what it observes, then you decide what’s intentional vs accidental.
Analyze this codebase and draft interaction principles for SYSTEM.md.
I’m looking for patterns in HOW the UI behaves, not WHAT components exist. Focus on:
1. **User flow patterns** — How do we handle multi-step processes? Do we use modals, inline expansion, separate pages?
2. **Feedback patterns** — How do we communicate success, errors, loading states? Toasts, inline messages, modals?
3. **Data entry patterns** — How do we handle forms? Validation timing, error display, save behavior?
4. **Empty/edge states** — What happens when there’s no data? How do we guide users?
5. **Destructive actions** — How do we handle delete, remove, cancel? Confirmation patterns?
6. **Navigation patterns** — How do users move between views? Breadcrumbs, back buttons, tabs?
For each pattern you find, note:
- What the current behavior is (with file/component examples)
- Whether it seems intentional and consistent, or accidental/inconsistent
- A proposed principle statement if it should be codified
Format output as a draft SYSTEM.md with:
- Principles that ARE consistent (document these)
- Principles that SHOULD BE consistent but aren’t (flag for decision)
- Gaps where no clear pattern exists (flag for decision)
Don’t document token values or component props — those live in the design system. Focus on interaction decisions the component library can’t encode.For a new project:
I’m starting a new project and want to set up an AI-readable design system spec from the beginning.
Create a config folder with:
1. **PROJECT.md** — Ask me about:
- What I’m building
- Who it’s for
- Why it exists
- Any constraints
2. **SYSTEM.md** — Include:
- Design foundations (colors, typography, spacing, radius) — ask me or propose defaults and I'll refine
- Section for “Interaction Principles” — ask me what matters for this product’s UX
- Section for “Visual Preferences” — document early decisions so they stay consistent
3. **PATTERNS.md** — Start empty. Patterns emerge as we build.
4. **features/** folder — Empty for now
5. **Update claude.md in the project root** (or create one if it doesn't exist) that tells AI:
- Always read PROJECT.md first
- Check features/ for specs before building
- Follow SYSTEM.md for design decisions
- Check PATTERNS.md before creating something new
- Add to PATTERNS.md when something reusable emerges
Start by asking me about the product so we can fill in PROJECT.md together.The Evolution
The README Method was step one: give AI project context. This is step two: give AI design context, and make it automatic.
Components were the first generation of design systems. Tokens were the second. This is the third: the reasoning layer. The why behind the decisions, made into infrastructure.
Solo, it's one person with one context doc, shipping fast. Multiplayer, it's shared specs that auto-load. Everyone starts from the same foundation. Automated, it can be pipeline checks and agent context, design reviews that run themselves.
Once this is set up, anyone who opens the project starts with the same foundation. The context is just there. As you build, add to the system. New interaction principles go in SYSTEM.md. New composition patterns go in PATTERNS.md. Feature specs go in features/.
The spec grows with the product. These specs stay current because they’re enforced - AI reads them on every session, and violations surface immediately.
Try it, tell me what breaks. Let’s learn this together.