How to Use DESIGN.md with Windsurf

Windsurf's Cascade is unusually good at multi-file edits. It refactors across your whole codebase in one shot. That power comes with a risk: inconsistency at scale.

When Cascade touches ten files at once, you want all ten to look the same. DESIGN.md is the one rule file that makes that happen. Here is how to set it up.

Method 1: Paste at the top of a Cascade prompt (30 seconds)

Open a Cascade chat, paste your DESIGN.md content first, then describe the task. Windsurf will treat the pasted content as ground truth for that session.

This works well for big one-time refactors. Cascade will apply the tokens across every file it touches in that session.

Method 2: Add DESIGN.md to your project root (5 minutes)

Cascade reads project files for context before every session. Drop DESIGN.md in the project root and it becomes ambient knowledge across the whole codebase.

This is especially valuable in Windsurf because Cascade's multi-file edits benefit from a shared reference. Every file it touches in a single flow gets the same design constraints.

Method 3: Add it to .windsurfrules (10 minutes)

.windsurfrules is Windsurf's project instruction file. It works the same as .cursorrules. Add a section that tells Cascade to follow DESIGN.md for all UI work.

The last line matters most for Windsurf. When Cascade runs a multi-file flow, it will check DESIGN.md before starting, not just for the first file.

Method 4: Use the DesignMD MCP server (15 minutes, best long-term)

Windsurf supports MCP servers. Add the DesignMD server and Cascade can search the full design catalog and retrieve tokens directly into your session without any copy-pasting.

Add this to your Windsurf MCP config (usually at ~/.codeium/windsurf/mcp_config.json):

Restart Windsurf after saving. Then tell Cascade: "Search DesignMD for a clean SaaS design and apply it across all the components in /src." It will find the design, pull the tokens, and apply them in one flow.

Why DESIGN.md works especially well with Windsurf

Most AI editors touch one file at a time. Cascade touches many. That is a superpower for refactors and a liability for design consistency.

Without a design reference, Cascade will apply slightly different colors, spacing, and typography choices across different files in the same flow. You end up with something that almost matches, which is worse than not trying.

DESIGN.md gives Cascade a single source of truth to check before every file it writes. The result is multi-file output that actually looks like it came from one designer.