How to use DESIGN.md with GitHub Copilot

Copilot is the tool most likely to quietly drift, because it suggests constantly and you accept fast. A slightly wrong border radius does not stop you the way a failing test does.

Custom instructions fix this at the source, and the setup is one file.

Where Copilot looks

GitHub Copilot reads custom instructions from .github/copilot-instructions.md in your repository. It applies to Copilot Chat and agent mode across VS Code, Visual Studio, and github.com, so one file covers the team.

Unlike some tools, Copilot instructions work best when they are short and concrete. Long documents get diluted.

The setup

Put DESIGN.md in your repository root, then create .github/copilot-instructions.md:

# Copilot instructions

## Design system

This project has a visual contract in DESIGN.md at the repository root.
Read it before suggesting or editing UI code.

When writing components, pages, or styles:
- Use only the color tokens, spacing scale, radius values, and type styles from DESIGN.md.
- Follow the component rules in DESIGN.md for states, density, and layout.
- Do not introduce new fonts, shadows, or gradients.
- If a needed value is missing from DESIGN.md, say so instead of choosing one.

## Stack
- React with TypeScript
- Tailwind CSS utility classes, no inline style objects
- Components live in src/components

Adjust the stack section to match your project. Copilot uses it to pick the right shape of answer, and it stops suggestions that are technically fine but wrong for your codebase.

Path-specific instructions

Here is the part most people miss. Copilot also supports scoped instruction files under .github/instructions/, each with an applyTo glob.

That is useful if only part of your repo is UI:

---
applyTo: "src/components/**/*.tsx"
---

Every component in this folder follows DESIGN.md. Use tokens only.

Scoped rules keep the design contract out of the way when you are editing an API route.

Verify it worked

Open Copilot Chat in the repo and ask:

What color should a primary button be in this project? Give the hex value and your source.

A correct answer names the token and the file. A generic answer means the instructions file is not being picked up. Check the exact path, .github/copilot-instructions.md, and that it is committed rather than sitting untracked.

In VS Code you can also confirm the file appears in the chat's references list.

Common mistakes

• Writing instructions as preferences. "We like clean design" does nothing. "Use only hex values listed in DESIGN.md" does.
• Letting the file grow. Copilot instructions compete with your actual code for attention. Keep it under a page.
• Assuming inline completions follow it. Chat and agent mode use the instructions reliably. Ghost-text completions are less predictable, so review UI suggestions with the same care you always did.

What this means for you

You get a design floor. Copilot stops inventing values, and the suggestions you accept quickly are far more likely to be correct.

Pick a system from the library, save it as DESIGN.md, add the instructions file, and the next component Copilot writes will already speak your visual language.