AI agent workflow
Windsurf is fast at implementing code through Cascade, Command, and Tab. That speed makes design memory important: without a visual brief, multi-file sessions can produce components that each look slightly different. DESIGN.md gives Windsurf a stable reference for colors, spacing, density, component rules, and anti-patterns before it touches your codebase.
Before using Cascade on a multi-file UI task, place DESIGN.md in the repo root and mention it directly. Ask Cascade to inspect the relevant existing components and the DESIGN.md file before planning. A strong instruction: "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.
For Command and inline edits, include a small pointer: "Match the component states described in DESIGN.md." For Cascade sessions, open with: "Read DESIGN.md for visual rules. Audit the existing components in [directory] before planning the implementation." The result is consistent styling across all touched files without a long correction loop after the session ends.
Move from this landing page into deeper DESIGN.md references, examples, and guides.
DESIGN.md is a visual design brief that Windsurf reads before editing React, Tailwind, or shadcn code. It defines color roles, typography, spacing, component behavior, and anti-patterns — giving Cascade and Command a stable reference instead of making independent visual decisions for each edit.
Place DESIGN.md in the repo root and reference it at the start of Cascade sessions: "Follow DESIGN.md as the design source of truth. Use existing components first. Explain any conflicts before editing." For smaller Command edits, add a brief pointer: "Match the component states described in DESIGN.md."
Product mood, color tokens mapped to CSS variables or Tailwind classes, typography scale, spacing rhythm, component variants for the most common elements, page layout patterns, and explicit anti-patterns. Note which Windsurf mode each rule is most relevant for — Cascade for layout and page-level decisions, Command for component-level edits.