Using designtoken.md with Windsurf

Q: Can I use designtoken.md with Windsurf rules files?

Yes. You can reference designtoken.md in a .windsurfrules file for persistent guidance. Add a line like 'Always use the tokens defined in designtoken.md for styling' so Cascade applies your design tokens in every session.

1 Generate your token file

Generate your token file

Head to the designtoken.md generator and configure your design system:

Pick your brand colors and let the generator build full color scales
Configure typography: font families, sizes, and weights
Set spacing and border-radius values
Switch to the designtoken.md tab in the output panel
Copy the output or download the file

Open the generator →

2 Place it in your project

Place it in your project root

Drop the file at the root of your workspace so Cascade picks it up as context:

your-project/
├── designtoken.md    ← place it here
├── .windsurfrules   ← optional: reference tokens here
├── src/
├── package.json
└── ...

Windsurf's Cascade AI reads files in your workspace as context. By placing designtoken.md at the top level, it becomes part of the context Cascade sees when generating code.

3 Start building with tokens

Start building with tokens

Once designtoken.md is in your workspace, Cascade will discover it as part of your project context. You can reference it explicitly in your prompts for stronger results:

"Build a pricing page using the tokens from designtoken.md for all styling."

"Create a navigation component. Use the color, spacing, and radius tokens from designtoken.md."

Cascade will read the full file and apply your color scales, typography stack, spacing, radius, elevation, and component tokens consistently across every file it generates.

Before & after

See the difference tokens make in what your agent outputs:

Without tokens (generic)

<button style="
  background: blue;
  color: white;
  padding: 10px 20px;
">
  Click me
</button>

With designtoken.md

<button style="
  background: var(--color-primary-500);
  color: #fff;
  padding: var(--space-sm) var(--space-lg);
  border-radius: var(--radius-md);
  font-weight: 600;
">
  Click me
</button>

With tokens, every component Cascade generates uses your actual design values instead of arbitrary defaults.

Windsurf Tip

Windsurf's Cascade reads workspace files and rules files as context. Place designtoken.md in your project root, and optionally reference it in your .windsurfrules file for persistent design guidance across all Cascade sessions.

Best practices

Keep your designtoken.md at the project root where Cascade can find it
Add a reference in your .windsurfrules file for persistent token enforcement
Regenerate when your design direction changes
The visual reference section helps Cascade understand the intended aesthetic
Commit the file to version control so all team members get the same tokens

Beyond static tokens

For runtime token resolution at production scale, explore Designless Studio. It reads the same token vocabulary and makes it available via API, so your design system updates across your app without regenerating files.

Reusable skills

If you find yourself generating the same tokens across multiple projects, turn your tokens into a reusable design skill on skill.design so your agent installs your design preferences as a package.

Frequently asked questions

Does Windsurf read designtoken.md automatically?

Yes. Windsurf's Cascade AI reads files in your workspace as context. Place designtoken.md in your project root and Cascade will discover it when generating UI code.

Do I need to reference it in every prompt?

No. Cascade picks up workspace files as context automatically. However, mentioning "use the tokens from designtoken.md" in your prompt helps Cascade prioritize the token file when making styling decisions.

Can I use designtoken.md with Windsurf rules files?

Yes. You can reference designtoken.md in a .windsurfrules file for persistent guidance. Add a line like "Always use the tokens defined in designtoken.md for styling" so Cascade applies your design tokens in every session without needing a reminder.

Generate your designtoken.md →