Windsurf .windsurfrules

DESIGN.md + Windsurf

Configuration reference: DESIGN.md reference

Prerequisites

  • Windsurf installed and configured
  • A project with an initialized Git repository
  • A DESIGN.md file — grab one from the library or generate with the design-md skill

Setup

1. Place your DESIGN.md

Drop the file at the project root:

my-project/
├── DESIGN.md
├── .windsurfrules
├── src/
└── ...

2. Create the .windsurfrules

.windsurfrules is the config file Windsurf reads automatically. Create it at the project root:

# .windsurfrules

## Visual rules
Read the DESIGN.md file at the project root before generating any visual component.
Follow strictly the rules defined in DESIGN.md for colors, typography, spacing, and components.

Specific rules:
- Use ONLY colors from the Colors section of DESIGN.md
- Follow the typographic scale from the Typography section
- Respect spacing from the Spacing section
- Apply component patterns with all states (hover, disabled, focus)
- Never violate constraints from the Do's and Don'ts section

3. Verify the setup

Ask Windsurf to generate a component:

Create a responsive navbar following the project's design system

Windsurf should read .windsurfrules, which points to DESIGN.md, and apply the visual rules you defined.

4. Refine with framework context

Add framework-specific instructions to .windsurfrules:

## Framework
This project uses React + Tailwind CSS.
When generating components, use Tailwind classes that match DESIGN.md values.
Example: if DESIGN.md defines spacing base 4px, use classes like p-1, p-2, p-4.

Troubleshooting

  • Windsurf doesn’t read .windsurfrules — check that the file is at the project root (not inside a subfolder). The name must be exactly .windsurfrules (with the leading dot).
  • Visual rules ignored — Windsurf may prioritize prompt context over .windsurfrules. Reinforce in your prompt: “follow the project’s DESIGN.md”.
  • Wrong colors or spacing — check that DESIGN.md has concrete values (hex, px, rem) and not vague descriptions. The agent needs numbers, not “large font”.
  • Inconsistency between sessions — Windsurf re-reads .windsurfrules on each session. If rules change, the next session already picks up the updated version.

Useful combinations

  • DESIGN.md + detailed .windsurfrules — use .windsurfrules for general project instructions (framework, conventions, structure) and DESIGN.md for specific visual rules. Keep responsibilities separate.
  • Do’s and Don’ts section — this section has the most impact on Windsurf’s output. Explicit constraints (“no shadows beyond 2 levels”) prevent the generic patterns the agent tends to generate on its own.
  • DESIGN.md + CSS variables — if your project uses CSS custom properties, align DESIGN.md names with the variables: --color-primary in CSS corresponds to brand-primary in DESIGN.md. The agent connects them automatically.

Next steps

Useful links