Guides: design systems, DESIGN.md, and shadcn themes

An AI agent with no design system invents one per prompt, and it invents the same one everybody else gets. What to give it instead, what that file has to contain to actually work, and how to install it in each major tool.

Updated 2026-07-27

A design kit is a starting point. What makes it stick is enforcing tokens in every component, building on solid primitives, finding visual direction with image gen, and generating variations instead of accepting the first attempt.

Updated 2026-08-10

Install a design system into Claude Code with one command: an MCP server lets the agent browse kits, apply tokens, and follow a real DESIGN.md as it builds.

Updated 2026-08-03

Two commands install Anthropic's frontend-design plugin, and it makes one screen look good. It cannot make the twentieth screen match the first, because it carries taste and not values. Here is the install, the gap, and how to close it.

Updated 2026-08-04

A skill is a folder with a SKILL.md that Claude Code loads only when your task matches its description. That one sentence explains why most installed skills never do anything. Here is the mechanism, the file format, and a worked design skill.

Updated 2026-08-04

Codex discovers SKILL.md folders in five locations, loads them by description match or an explicit $, and shares the format with Claude Code and Cursor. Here is the anatomy, the discovery order, and a design skill you can adapt.

Updated 2026-08-04

Copilot reads instructions files nobody fills with design decisions, which is why its UI output defaults to generic. Here is the setup: copilot-instructions.md, scoped .instructions.md files, real tokens, and a DESIGN.md they point at.

Updated 2026-08-04

Gemini CLI concatenates every GEMINI.md in its hierarchy into each prompt, which makes it unusually easy to wire a design system in: one import line and the contract loads on every request. Here is the setup and the file it imports.

Updated 2026-08-04

Add Identity Forge's MCP server to Cursor: the Agent picks a design kit, writes its tokens and DESIGN.md into your project, and keeps its screens consistent.

Updated 2026-08-03

Connect Identity Forge to Windsurf's Cascade agent with a small MCP config, or use the CLI and shadcn registry, so every screen follows one design system.

Updated 2026-08-03

Make v0 build on-brand UI: hand it a design kit as a shadcn registry item plus a DESIGN.md brief, so generations use your tokens, not the default look.

Updated 2026-08-03

Most Lovable prompt lists collect one-liners. Design doesn't survive one-liners. Here is the anatomy of a design prompt that holds across sessions, with paste-ready examples.

Updated 2026-08-03

Make Lovable build on-brand: put a kit's DESIGN.md in project Knowledge and apply its tokens through the shadcn registry in the connected repo.

Updated 2026-08-03

Bolt's built-in design systems need a paid Team plan to add your own. Here is what that feature compiles from, and the setup that works on any plan using Bolt's real in-browser terminal.

Updated 2026-07-27

The standard advice is to write a design.mdc rule and you are done. It works for about three weeks. Here is why a design system does not fit in one rules file, how to split it by when each rule needs to be true, and what to put in each piece.

Updated 2026-07-27

An MCP server lets an agent query your design system instead of guessing at it. That solves wrong prop names and stale imports. It does not solve an agent that has no idea what your product should look like, and those are different problems with different fixes.

Updated 2026-07-27

Most roundups list twenty tools that do different jobs as if they were competing. Here they are grouped by the problem each one solves, with the finding that matters: not one of them produces a design system, and all of them assume you already have one.

Updated 2026-07-27

Where design decisions live in a Framer project, how DESIGN.md relates to shared styles, components, and overrides, and how to verify changes on a branch.

Updated 2026-08-03

A DESIGN.md describes a visual identity in a form a coding agent can read. We measured 299 public ones: here is the format, section by section, and the four things almost all of them omit.

Updated 2026-07-27

Four files, four jobs, one precedence order. What belongs in each, which tools read which, and why the design one is the file nobody writes.

Updated 2026-08-04

Design system documentation written for humans fails when a model reads it, and it fails in a specific, measurable way. What we found in 299 real files, and the seven changes that make guidance executable instead of descriptive.

Updated 2026-07-27

Four defaults produce the sameness: one neutral palette, one sans-serif, one border radius, one card grid. Here is where each one comes from and what to change.

Updated 2026-08-03

Six changes at the token level, each with the before and after. Prompt tweaks move one screen; these move every screen the agent builds from now on.

Updated 2026-07-27

Drift is measurable, not vibes. How to count it across a session, why it starts around screen five, and the one change that stops it accumulating.

Updated 2026-07-27

Most guides cover the tools. The thing that separates designers who ship from designers who restart is what they set up before the first prompt, and how they review a diff without being able to read code.

Updated 2026-07-27

Most consistency checklists ask whether your interface feels cohesive, which nobody can answer. This one is a list of checks with commands and pass conditions, ordered by how much drift each catches per minute spent.

Updated 2026-07-27

What a shadcn registry is, how registry.json and registry-item.json fit together, and the case the docs barely cover: shipping a whole theme (tokens, fonts, radii, light and dark) as one installable item.

Updated 2026-07-27

Measured answers to the questions palette galleries skip: whether to use pure black, how to show elevation without shadow, why accents have to move, and the roles a dark palette needs beyond five swatches.

Updated 2026-07-27

A dashboard palette has three jobs a marketing palette never has: distinguishable data series, status colours that don't collide with your brand, and greys that survive a dense table. Here is how to build one that does all three.

Updated 2026-07-27

Why SaaS products converge on the same blue-violet accent, what a palette actually has to survive in a product UI, and how to pick a distinctive one that still works on a settings table at 4pm.

Updated 2026-07-27

Every industry font guide gives you the same answer with different labels: a geometric sans for tech, a serif for law, a script for beauty. Here are pairings that actually work per sector, plus the reason the category framing keeps producing lookalike brands.

Updated 2026-07-27

Most design system roundups are link lists. This is a read of nine real systems organised by the decision each one made well (layering, enforcement, cross-platform contracts, delivery) plus the change three of them made in the last eighteen months that nobody has written up.

Updated 2026-07-27

IBM's Carbon is the largest openly licensed enterprise design system, and in 2026 it does something none of the write-ups mention: it exposes itself to AI agents over the Model Context Protocol. A practical guide to what Carbon is, how it is layered, and what the MCP server changes.

Updated 2026-07-27

Polaris React is marked deprecated and Polaris Web Components are now what Shopify apps use: loaded from a CDN script tag, not an npm dependency. What actually changed, why, and what it means for anyone maintaining a design system.

Updated 2026-07-27

Salesforce says SLDS 2 is "the foundation for the agentic design system": a decade-old enterprise design system rearchitected around CSS custom properties so that generated interfaces stay on brand. What actually changed, and what it means if you do not use Salesforce.

Updated 2026-07-27

Linear's interface is imitated constantly and reproduced badly. A close reading of what is actually observable (the weight band, the hairline, the single accent) and why the part everyone copies is not the part doing the work.

Updated 2026-07-27

Stripe ships one design system that forbids custom CSS entirely and another built almost entirely around letting you override it. Both are public, both are documented, and the line between them is the most useful thing Stripe has published about design systems.

Updated 2026-07-27

Airbnb's Design Language System is the most-cited cross-platform design system and the most misread. Its founding decision was to reject atoms and molecules outright, and the reasoning behind that choice is what makes it useful now.

Updated 2026-07-27

Spotify's Encore had to cover 45 platforms and over 2,000 device types. Its own team says the pendulum swung too far toward flexibility and had to be pulled back. That correction, and the layered structure that came out of it, is the useful part.

Updated 2026-07-27

A DESIGN.md is the written design brief your AI coding agent follows so it stops building generic UI. Here is what belongs in one, and how to generate a complete, exportable DESIGN.md from a real design system.

Updated 2026-08-04

Semantic color tokens use role names like background, primary, muted, and border instead of hue names. See all 28 roles in a live light and dark example.

Updated 2026-08-03

Packaging Apple's HIG, Material, or your own house rules as agent-readable guidance: what survives the translation from human design doc to agent instruction, what doesn't, and why platform guidelines alone still produce generic UI.

Updated 2026-07-27

Every SaaS font list recommends the same faces. Here is why, what a typeface actually has to survive in a dense product UI (tabular numerals, real weight separation, small-size legibility) and when a second family earns its place.

Updated 2026-07-27

Atomic design solved a 2013 problem: giving humans a shared vocabulary for interface parts. An agent already has the vocabulary and lacks the judgement. Which parts of the methodology survive that, and which were always scaffolding.

Updated 2026-07-27

A component library is code you can install. A design system is the set of decisions that made that code look the way it does. Confusing them is why teams install shadcn, ship a generic product, and cannot work out what went wrong.

Updated 2026-07-27

Primitive, semantic, component. The three-tier convention is close to universal and most teams still end up with tokens nobody uses. Why that happens, how to name each tier, and the test that tells you a name is wrong before it ships.

Updated 2026-07-27

Governance models were designed around the assumption that a person requests a change and a person reviews it. When an agent writes forty screens between reviews, contribution processes stop being the bottleneck and enforcement becomes the whole job.

Updated 2026-07-27

Design-to-code tools reproduce what a frame looks like. They cannot reproduce what it means, because a Figma frame does not contain that. What actually transfers, what does not, and the naming decision that closes most of the gap.

Updated 2026-07-27

What actually pairs with Avenir, rendered live instead of screenshotted. Plus the Google Fonts that stand in for it when the license doesn't travel, and complete systems built on those pairings.

Updated 2026-08-03

The sans-serifs and monos that pair with Caslon, rendered live in free Caslon revivals you can actually ship. When in doubt, use Caslon; when pairing it, read this first.

Updated 2026-08-03

The serifs and monos that pair with Proxima Nova, rendered live with the free faces that stand in for it. The internet's default font deserves a partner that isn't a default.

Updated 2026-08-03

What pairs with Gilroy's rounded geometry, rendered live with free Google Fonts stand-ins. Plus which of the free weights you can actually build a product on.

Updated 2026-08-03

Eight public brand guidelines that actually teach you something, what separates a working document from a pretty PDF, and why the next generation of guidelines has to be executable by machines, not just read by designers.

Updated 2026-08-04

Compare shadcn theme generators, broader design systems, and coding-agent handoffs by inspecting their documented outputs and exported artifacts.

Updated 2026-08-03

A pre-ship checklist for AI-generated UI: observable acceptance criteria, realistic states, issue routing, and a copyable review record.

Updated 2026-08-03

Assign rule authority in Google Stitch, diagnose inconsistent screens, test one controlled change, and verify the DESIGN.md and code handoff.

Updated 2026-08-03

How to turn brand assets into a handoff a developer can implement: ownership boundaries, an intake record, a public kit example, and acceptance checks.

Updated 2026-08-03

Map authority across Webflow variables, classes, components, and breakpoints, then verify one controlled change the way you would review a pull request.

Updated 2026-08-03

Where each shadcn typography decision lives: font packages, theme aliases, roles, component code, or DESIGN.md, with a real font swap traced through.

Updated 2026-08-03

Document a design system in Storybook without letting stories become policy: an authority map, a story coverage matrix, and one controlled change.

Updated 2026-08-03

Deprecate design tokens without breaking consumers: map dependencies, pick the replacement shape, migrate layer by layer, remove behind a hard gate.

Updated 2026-08-03

Give every FlutterFlow design decision one home, from theme values through components to exported Flutter code, and verify app and export separately.

Updated 2026-08-03

Size design system reviews by reach, not diff length: classify the change, name what must move and what must not, and record the decision.

Updated 2026-08-03

Trace a shadcn token from :root through @theme inline to bg-primary, then see what apply --preset really rewrites, with tested diffs and partial apply.

Updated 2026-08-03

Both give a coding agent a DESIGN.md. getdesign.md publishes analyses of existing brands; Identity Forge generates an original system with the semantic tokens the brief references. The structural difference decides which one fits your project.

Updated 2026-07-27