Give Bolt a design system

Per Bolt's documentation, a design system gives Bolt a set of visual rules (colours, typography, spacing, component styles) to follow when it builds. The stated payoff is that Bolt emits UI code built from your actual components rather than stand-in code you would replace later.

There are two tiers, and the difference matters before you plan around it:

The pre-loaded systems are a genuinely good way to see the difference a system makes: pick one, hit *Try example*, and compare the output quality against a plain prompt. What you cannot do is bend one toward your brand, because they are read-only. The moment you need your own look, you are choosing between a Team plan and the terminal.

Bolt's model is compilation, not upload. Its docs state that Bolt compiles your design system from your own sources, your component library and your design-system website, and that your design system *is defined by those sources*. When the sources change, you sync Bolt to pick up the latest version.

That is a clean model with one consequence people meet later: the compiled system is a snapshot. Between syncs, Bolt is generating from a version of your system that may no longer match what ships. This is the failure mode design-system teams already know as token drift, the designed source of truth and the shipped one diverging, and an agent that generates confidently from the stale copy produces production-ready code on the wrong foundation, faster than before. Put the sync in your release checklist, not your maintenance backlog.

Bolt is not unusual in needing sources to compile from. We checked the current documentation for every major AI builder and coding agent, and the shape is the same across all of them.

If you maintain a component library and a docs site, Bolt's compiler is the right tool and you should pay for the Team plan. If your design system is currently "whatever Bolt did on screen one", there is nothing to compile, and the rest of this page is the practical answer.

Bolt is a StackBlitz WebContainer, which means it runs a real Node environment with a real terminal in the browser. Almost nothing else in this category does. You can install packages, run generators, and write files, so a design system installs exactly as it would on your machine, with no plan gate and no compilation step.

1. 1

   Make sure the project uses shadcn/ui

   Bolt's React + Tailwind starters work well. If the project isn't shadcn-initialised yet, run npx shadcn@latest init in Bolt's terminal first.

2. 2

   Install the token set

   Run the kit's registry command in Bolt's terminal. It writes every semantic role, light and dark, into your theme, so components already referencing bg-primary repaint without being edited.

   Copy

   npx shadcn add https://identityforge.io/r/ambient-sage.json

3. 3

   Put the brief in the repo, not the chat

   This is the step people skip. The CLI writes a full DESIGN.md into the project, so the rules survive a new chat, a reload, and the next person to open the project.

   Copy

   npx --yes identityforge@latest apply ambient-sage

4. 4

   Prompt against the system

   Now build normally, and name the constraint explicitly the first few times.

   Copy

   Build a landing page using only the theme's design tokens
   and the rules in DESIGN.md. Do not add a new colour or font.

This comes up every time, and it is a reasonable instinct. The repo is the source of truth, so point the agent at it. Two things get in the way.

The first is practical: a repository is not a design system in a form an agent can apply. It is thousands of files, most of them irrelevant to a styling decision, with the actual rules distributed across a Tailwind config, a theme provider, a few CSS files and the collective memory of the team. Compilation exists precisely because something has to reduce that to tokens, a component catalogue and a set of constraints.

The second is that a repo answers *what exists* and not *what to do*. It contains a Button with five variants; it does not say which variant a destructive action gets, that you never put two accents on a screen, or what happens in dark mode on a surface that has no dark variant yet. Those are judgements, they live in prose, and if nobody wrote them down the agent will supply its own: plausibly, and differently each time.

We sampled 299 public DESIGN.md files to see how often those judgements do get written down. 76% list only preferences and never a prohibition. 69% never mention dark mode. 86% give raw hex values with no semantic role attached, which means the question "what colour is a disabled button" has no answer in the file at all.

So: link the repo if the tool supports it, and still write the rules down. What a complete file contains is in what a DESIGN.md is.

If you are going the native route and wondering whether to give Bolt an npm package, a folder structure, or a docs link, the honest answer is that it depends which tool you are feeding, and the tools genuinely disagree:

• Bolt compiles from your component library plus your design-system website, and re-syncs when those change.
• v0 wants an installable package: npm, a .tgz, or a source directory with its own package.json, and will create one from looser sources if you don't have it.
• Lovable wants React components, delivered as a dedicated Lovable project, and copies them into connected repos.
• Coding agents want neither: they want a token file and a written brief sitting in the repo.

The only artifact all four accept is the pair every one of them reduces to anyway: a complete semantic token set, and the written rules that go with it. Producing those first costs you nothing if you later publish a package, and it is the only version that works today on a free plan.

The registry item at https://identityforge.io/r/<slug>.json carries every semantic role, so Bolt never improvises the values a loose palette leaves undefined: muted text, borders, hover and active states, ring, destructive, chart series, and all of them again in dark mode. Handing over three brand colours defines three values and leaves roughly twenty-five open. See semantic colour tokens explained.

• Leaving the brief in the chat. Long builds trim context. A DESIGN.md in the project does not get trimmed.
• Assuming a pre-loaded system can be nudged toward your brand. They are read-only by design.
• Syncing only when something looks wrong. By then Bolt has been generating from a stale snapshot for weeks.
• Giving Bolt colours without roles. A palette cannot answer what a disabled control looks like, so Bolt picks: differently each screen.
• Skipping dark mode. It is not an inversion of light, and it is where improvisation shows first.