# DESIGN.md with GitHub Copilot

> Make GitHub Copilot follow DESIGN.md with copilot-instructions.md, a path-specific .instructions.md file or AGENTS.md. Includes a sample file.

Canonical page: https://sitepeel.dev/guides/design-md-github-copilot/

Save DESIGN.md in your repository and link it from .github/copilot-instructions.md, or from a .github/instructions file scoped to your UI code with applyTo.

Published: 2026-10-24

Tool used in this guide: [Design MD generator](https://sitepeel.dev/design-md-generator/index.md)

## How to use it

1. **Add DESIGN.md to the repository** Generate it from a site with Sitepeel, review it and commit it at the repository root.
2. **Create an instructions file** Add .github/instructions/design.instructions.md with an applyTo pattern for your UI files.
3. **Link DESIGN.md in it** Use a Markdown link with a path relative to the instructions file, plus your must-follow rules.
4. **Ask for one screen** In Copilot Chat or with the cloud agent, ask for one page and name its content and main action.
5. **Check References** Expand References above the chat response to confirm Copilot used your instructions file.

## Which Copilot instruction file to use

Copilot sends every instruction file that applies, so keep design rules in one place to avoid conflicts.

Copilot instruction files

| File | Applies to | Read by |
| --- | --- | --- |
| .github/copilot-instructions.md | The whole repository | Copilot Chat, cloud agent, code review and Copilot CLI |
| .github/instructions/NAME.instructions.md | Files matching applyTo | Chat in VS Code, Visual Studio and JetBrains; cloud agent; code review on GitHub.com; Copilot CLI |
| AGENTS.md (the nearest one wins) | Its folder and below | Cloud agent, Copilot CLI, Copilot Chat in VS Code, code review on GitHub.com |

## Sample instructions file for UI code

Save this as .github/instructions/design.instructions.md. Separate several applyTo patterns with commas. In VS Code, relative link paths resolve from the instructions file, so ../../DESIGN.md points at the repository root.

Example: .github/instructions/design.instructions.md

```
---
applyTo: "**/*.tsx,**/*.css"
---

# UI design rules

Follow [DESIGN.md](../../DESIGN.md) for all UI work.

- Use its color, typography, spacing and radius tokens. No new hex values.
- Reuse existing components and follow its Do's and Don'ts.
- If DESIGN.md has no rule for a case, say so instead of inventing one.
```

## Use AGENTS.md for Copilot cloud agent

Copilot cloud agent and Copilot CLI read AGENTS.md files anywhere in the repository; the nearest one in the folder tree takes precedence. A single CLAUDE.md or GEMINI.md in the root works too. If Codex or Cursor share the repository, put the UI section in AGENTS.md once.

- [Sample AGENTS.md section for DESIGN.md](https://sitepeel.dev/guides/design-md-codex/index.md)

## Check that Copilot followed DESIGN.md

- In Copilot Chat, expand References above the response and look for your instructions file
- Ask which DESIGN.md tokens it used, and search the diff for new hex values
- Compare the page with DESIGN.md at phone and desktop widths
- Code review reads instructions from the pull request’s head branch, not the base branch

- [Copilot still ignores the design? Check these five things](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md)

## Questions and answers

### Does GitHub Copilot read AGENTS.md?

Yes: Copilot cloud agent, Copilot CLI, Copilot Chat in VS Code and code review on GitHub.com read it. The nearest AGENTS.md in the folder tree takes precedence. Chat in Visual Studio and JetBrains uses copilot-instructions.md instead.

### Where do I put copilot-instructions.md?

In the .github folder at the root of your repository, as .github/copilot-instructions.md. It applies to requests in that repository.

### What does applyTo do in Copilot instructions?

It is a glob in the front matter of a .instructions.md file. Copilot uses that file only for matching paths, such as **/*.tsx. Separate several patterns with commas.

### Can Copilot instructions link to other files?

Yes, in VS Code: use a Markdown link such as [DESIGN.md](../DESIGN.md). Relative paths resolve from the instructions file.

## Further reading

- [GitHub Docs: Add repository custom instructions for Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
- [GitHub Docs: Support for different types of custom instructions](https://docs.github.com/en/copilot/reference/custom-instructions-support)
- [VS Code docs: Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)

## Related pages

- [What is DESIGN.md](https://sitepeel.dev/guides/what-is-design-md/index.md): DESIGN.md is a Markdown design-system file for AI coding agents. See its format, a small example, the official linter and how to make one from any site.
- [DESIGN.md with Codex](https://sitepeel.dev/guides/design-md-codex/index.md): Make OpenAI Codex follow DESIGN.md with a few lines in AGENTS.md. See where Codex looks for instructions, its size limit and how to check what loaded.
- [DESIGN.md with Cursor](https://sitepeel.dev/guides/design-md-cursor/index.md): Point Cursor at DESIGN.md with a project rule in .cursor/rules, AGENTS.md or an @ mention. Includes a sample .mdc rule and the four rule types.
- [DESIGN.md with Claude Code](https://sitepeel.dev/guides/design-md-claude-code/index.md): Import DESIGN.md into CLAUDE.md with @DESIGN.md so Claude Code follows your colors, type and spacing. Includes a sample CLAUDE.md and checks.
- [When AI ignores DESIGN.md](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md): Your agent has DESIGN.md but the UI is still wrong? Check that it loads, remove conflicting rules, name real components and verify the result.