Best practices for adding your design system
The quality of your design system in Bolt depends largely on the sources you give Bolt to work with.Use the best sources you have
Not all sources give Bolt the same quality of information. In general, sources that include or describe your actual component code produce the best results. You can add as many sources as needed in any combination, and you don’t necessarily need every source type.| Source type | What it provides |
|---|---|
| GitHub repositories | A strong design system repo contains component code, documentation in Markdown files, and a README that explains how to install the correct NPM packages. This gives Bolt the most complete picture of your design system. If you have a public repository, we recommend adding it. |
| NPM packages | Component code and dependencies. Bolt can get less detail from a built NPM package than from the source code itself, but NPM packages are still a strong source, especially when combined with a GitHub repo or documentation. |
| Design system websites and Storybook URLs | Component documentation and visual context. A documentation website alone produces something closer to a theme than a true design system with reusable components. Tip: Include a website alongside a GitHub repo or NPM package. Then the website adds useful context rather than serving as the main source. |
| Files | Local files like brand guidelines, component specs, or a private documentation site exported as a .zip file. You can also upload an llms.txt file, which is a condensed version of your documentation written in a format that’s easy for Bolt to read.Tip: Files work best as supporting documentation alongside a GitHub repo or NPM package. |
Make sure your sources agree
Bolt works best when your sources all have consistent information. Here are a few things to avoid:- Conflicting guidelines: If different sources have different guidelines for the same thing (like specifying two different fonts), Bolt may not be able to generate a consistent design system.
- Mixed technology: If your sources contain components in multiple frameworks, like React and Angular, Bolt may be confused about which to use. In this case, add agent instructions that tell Bolt which framework to build with.
- Unrelated design systems: Each Bolt design system should represent one coherent system. Mixing sources from unrelated design systems could produce inconsistent results.
Include complete documentation on your design system foundations
Bolt references the documentation that defines your design system standards every time it builds. This includes core elements like typography, colors, spacing, and theming. Make sure your sources thoroughly document these standards so that Bolt applies them accurately.Use agent instructions to handle complexity
Use agent instructions to give Bolt context that isn’t captured in your sources, or to help it navigate sources that are complex or unclear. Here are a few good ways to use agent instructions:- Exclude deprecated components
- Focus on one theme if your sources include several
- Identify the correct framework to use
Improve results by resyncing rather than starting over
Syncing only processes what’s changed, so it’s faster than adding a new design system. If your design system didn’t produce the results you expected, we recommend you refine your agent instructions and then sync. Here’s the approach that works best:- Review what Bolt generated and identify what’s missing or incorrect.
- Update your sources if needed, or add agent instructions to address the issue.
- Sync your design system.
Prompt effectively when building
How you prompt Bolt when building with a design system affects both the accuracy of your results and how efficiently Bolt uses tokens.Reference components by name
When you know the name of a component in your design system, use it directly in your prompts. “Add a PrimaryButton in the header” gives Bolt more to work with than “Add a button in the header.” If you’re not sure what’s available or what something is called, browse your design system in Bolt before prompting. To learn more about navigating your design system, see View your design system in Bolt.Be specific about what to change
When you prompt with precise instructions, Bolt can more accurately apply your standards to the targeted components. Bolt also has to read through less of your project code, which helps token efficiency. This is especially important when you update components after a sync or version switch. Instead of “Update my project to the latest design system,” try “Update all uses of the PrimaryButton to the new style, but leave the layout the same.” Broad instructions require Bolt to read more of your project to understand what applies, which makes results less predictable. If you need to fully update a project after syncing or switching to a new version, see Update components in an existing project for an example prompt to help with this kind of large-scale update.Why doesn’t my output match my design system?
If Bolt isn’t producing results that match your design system, the most common causes are:- Incomplete or low-quality sources: Your sources may not include enough component code or documentation for Bolt to generate a consistent design system. Review your sources against the source quality guidelines.
- Inconsistent sources: Your sources may contain conflicting guidelines, mixed technology, or unclear agent instructions. Review the source consistency guidelines and add agent instructions to address any issues.
- Prompts that are too broad: Your prompts may be too generic, which doesn’t give Bolt enough context to know which components or standards to apply. Try referencing specific component names or describing exactly what you want to change.
- Outdated design system: Your sources may have changed since you last synced, so Bolt may be working from an older version than you expect.