AI Agents
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.
Why Windsurf benefits from a visual brief
Windsurf is an AI IDE built around flow: Cascade for larger agentic work, inline Command for focused edits, and Tab for fast context-aware suggestions. That speed is exactly why design memory matters. When an editor can change several files quickly, visual drift can happen quickly too. One prompt may create a polished card, the next may add a mismatched button, and a later edit may introduce another spacing system. DESIGN.md gives Windsurf a stable reference point. It tells the agent what "good" means inside this product: not just correct React, but correct hierarchy, density, color usage, typography, motion, empty states, and component states.
Use it with Cascade
Before using Cascade on a UI task, place DESIGN.md in the repo root or a docs folder and mention it directly. Ask Cascade to inspect the relevant existing components and the DESIGN.md file before planning. A strong instruction is: "Follow DESIGN.md as the design source of truth. Use existing components first. If implementation conflicts with DESIGN.md, explain the conflict before editing." This keeps large edits from becoming visual rewrites. It also helps Windsurf reason about which local patterns to reuse: a dashboard table, a profile header, a sidebar, a form, or a post card may already have the right style in the codebase.
Use it with Command and Tab
Inline edits are smaller, but they can still break consistency. DESIGN.md helps with micro-decisions: should this button be filled or outline, should the label be sentence case, should a card have a border, should the empty state be calm or sales-like, should icons appear in text buttons, should error text be red or neutral? When using Command, include a small pointer: "Match the component states described in DESIGN.md." For Tab-style suggestions, the value is indirect: once the surrounding code follows a clear design system, autocomplete suggestions inherit better context. The file becomes a durable source of taste that surrounds the edit.
What a Windsurf-ready DESIGN.md includes
A useful file includes a short product mood, token names, typography rules, spacing rhythm, component variants, page patterns, accessibility requirements, and "do not do this" examples. It should also name the editor workflow: Cascade can plan and implement full screens; Command can patch specific components; Tab can complete repeated UI structures. That way the agent is not only told the design rules, it is told how to apply them in the editor. The best result is boring in the right way: fewer surprise styles, fewer cleanup passes, and more UI that looks like it belongs to the same product.
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 Bolt
How DESIGN.md helps bolt.new generate full-stack browser apps with stronger UI direction, cleaner components, and less generic styling.
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.