AI Agents
DESIGN.md for Bolt
How DESIGN.md helps bolt.new generate full-stack browser apps with stronger UI direction, cleaner components, and less generic styling.
Why Bolt needs design constraints early
Bolt by StackBlitz is powerful because it can prompt, run, edit, and deploy full-stack web applications in the browser. It can scaffold a project, install packages, run a dev server, and show a live preview without the usual local setup. That makes it excellent for fast prototypes, but the same speed can produce generic UI if the first prompt is vague. DESIGN.md helps at the exact moment where Bolt is strongest: the first build. Instead of asking for "a nice SaaS dashboard", you can give Bolt a design-system file that defines colors, typography, density, navigation, form rules, and component behavior before the app exists.
A better first prompt
The strongest Bolt prompt pairs product intent with visual constraints. Start with the application goal, then paste or attach DESIGN.md, then ask Bolt to scaffold around those rules. For example: "Build a Next.js app for a founder analytics dashboard. Follow this DESIGN.md exactly. Use the color tokens, compact card rhythm, table density, empty states, and button variants described here. Do not add decorative gradients or marketing hero sections unless the file requests them." This gives Bolt enough information to create files that feel coherent from the first preview. It also makes follow-up prompts more precise because you can point back to the same file.
What to include for full-stack prototypes
Bolt often builds more than a single component, so the DESIGN.md should cover product surfaces, not just tokens. Include page templates for landing, dashboard, settings, onboarding, detail pages, forms, and error states. Define how data tables should scan, how filters should look, how cards should group information, and how mobile layouts should collapse. If your app includes generated mock data, describe how dense or sparse the default state should be. If it includes authentication or billing pages, define the tone and structure there too. A prototype becomes much more convincing when every route shares one visual system.
Iterating without visual drift
Bolt is conversational, so the product will change through follow-up prompts. DESIGN.md keeps those follow-ups from becoming style roulette. When you ask for a new feature, include "keep the implementation aligned with DESIGN.md" and ask Bolt to reuse existing components where possible. When the preview looks off, update the design file instead of writing a longer one-off complaint. Over time, DESIGN.md becomes the reusable design memory for the project. That matters for prototypes and production code: the faster a tool can build, the more important it is to give it stable taste before it moves.
Use DESIGN.md with a real product reference
Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.
Related guides
DESIGN.md for Kiro
How to use DESIGN.md with Kiro, the AWS agentic IDE built around specs, steering, hooks, and production-minded implementation.
DESIGN.md for Windsurf
How to use DESIGN.md with Windsurf and Cascade so AI edits follow your product design system instead of default editor taste.
DESIGN.md for v0
How to use DESIGN.md with Vercel v0 to generate UI, prototypes, and full-stack app surfaces that match your real product design system.