How to Use DESIGN.md Across a Team

A solo developer with a DESIGN.md gets consistent AI output. A team of four developers without one gets four different products inside a single codebase.

Here is what that looks like in practice: everyone is using Claude Code or Cursor. Every developer is prompting slightly differently. Nobody is pointing at the same design reference. By week three, every PR looks like it came from a different company.

The fix is simple. One file. In the repo. Committed. Here is how to set it up.

Step 1: Commit DESIGN.md to the repo root

Drop the file at the root of the repository. Not in docs/. Not in design/. The root.

AI tools look for context files in predictable places. The root is where CLAUDE.md lives, where .cursorrules lives, where the project-level configuration lives. DESIGN.md belongs there too.

Commit it. Version it. Treat it like code.

Step 2: Reference it in your AI config files

The DESIGN.md does nothing on its own if the AI tools do not know to read it. You need to reference it in the files each tool reads for project context.

Copy the same instruction into .windsurfrules as well. The message is the same: read the file, follow the tokens.

Now every developer on the team, using any AI coding tool, gets the same design context automatically. No extra prompting. No "remember to use our design system" in every session.

Step 3: Add design review to your PR process

AI tools follow the DESIGN.md well but not perfectly. Add a design pass to your code review checklist. It takes 30 seconds per PR and catches the 10% of cases where the AI hardcoded a value or missed a token.

When something fails the checklist, do not just fix the code. Fix the DESIGN.md if needed, or add a note to the component guidelines so the AI does better next time. The file gets smarter with use.

Step 4: Update it as a team

Here is the failure mode to avoid: one developer decides the primary color should be slightly different and changes DESIGN.md without telling anyone. Now the AI tools are generating new components in a different color than everything that already exists.

Treat DESIGN.md updates like dependency updates. Discussed. PR reviewed. Intentional. If you are going to change the primary color, that is a team conversation, and the PR that changes it should include visual before/afters.

Nobody needs to learn Figma. Nobody needs to sit through a design walkthrough. The file is the source of truth, and changing it is a meaningful decision.

Monorepo setup

If you have multiple apps in a monorepo, the question is whether they share a visual language.

Same brand, different apps (consumer site + internal dashboard): one DESIGN.md at the root works. The dashboard might be darker and more dense, but it uses the same primary color and type scale.

Different brands (acquired company with its own identity): separate DESIGN.md files per app. Put them in each app directory. Reference them in app-level CLAUDE.md and .cursorrules files.

The meeting you do not have to have

This is the underrated benefit. When design decisions are in a file that lives in the repo, "why does this button look different?" becomes answerable without a Figma walkthrough or a Slack thread that goes nowhere.

You open DESIGN.md. You see what the button should look like. You see what the AI generated. You find the delta. You fix it.

Three minutes. Not three days.

Design consistency is a coordination problem. DESIGN.md solves coordination problems by making the answer to "what should this look like?" findable in 10 seconds by anyone on the team, including the AI.