Windsurf's Cascade agent is happy to refactor a whole feature in one pass. That is great until it restyles six components using values you have never shipped.
Rules files are how you stop that, and they take a couple of minutes to set up.
Where Windsurf rules live
Windsurf reads workspace rules from .windsurf/rules/ in your project. Each file is Markdown with a small front matter block that controls activation.
Older projects use a single .windsurfrules file in the root. It still works, but the directory format lets you scope rules and split them by concern, so I would start there.
There are also global rules that apply across every project. Design belongs in the workspace, not globally, because each product has its own system.
The setup
Save DESIGN.md in your project root, then create .windsurf/rules/design-system.md:
---
trigger: always_on
---
# Design system
This project's visual contract is DESIGN.md in the repository root.
Read it before creating or editing any UI.
- Use only the colors, spacing, radius, and type styles defined in DESIGN.md.
- Follow its component rules for states, density, and layout.
- Never add a font family, shadow, or gradient it does not define.
- If a value is missing, ask rather than picking one.The trigger: always_on line is the key. It keeps the rule in context for every Cascade request instead of leaving activation to the model's judgement.
Other trigger modes
Windsurf supports a few activation modes, and the right one depends on your repo.
| Mode | When it loads | Good for |
|---|---|---|
always_on | Every request | Design contracts on UI-heavy projects |
glob | When matching files are touched | Monorepos with a separate backend |
model_decision | When the model thinks it applies | Niche rules you rarely need |
For a design system I use always_on unless the repo is mostly backend code, in which case a glob on **/*.tsx keeps the context lean.
Verify it worked
Start a new Cascade conversation and ask something with one right answer:
What is the border radius for cards in this project, and where is it defined?You want the actual value plus a reference to DESIGN.md. A vague answer means the rule is not loading. Check the folder name (.windsurf/rules/, not .windsurf/rule/) and that the front matter sits between --- lines at the very top.
Common mistakes
- Keeping both `.windsurfrules` and `.windsurf/rules/`. Pick one. Two sources of truth drift apart fast.
- Writing rules longer than the code. Windsurf caps how much rule text it will carry. A tight design contract survives; a rambling one gets trimmed in ways you cannot see.
- Not committing the folder. Rules only help the team if they are in the repo.
What this means for you
Cascade is most useful when you let it work in large steps. That only feels safe when the design constraints are locked in ahead of time.
One rules file, one DESIGN.md, and the agent's default taste stops being your problem. Grab a documented system from the library if you do not have one yet.