DESIGN.MD & AI

How to use DESIGN.md with 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.

Sitepeel2 min readOctober 24, 2026

Tool used in this guide: Design MD generator

“Give Copilot your design rules.” copilot-instructions.md in the .github folder says to follow DESIGN.md, and Copilot’s suggestion uses its colors. — Copilot’s instructions file sends it to DESIGN.md.

In short

Copilot reads its own instruction files, not DESIGN.md: link the design file from one of them
Scope design rules to UI files with applyTo in .github/instructions
Copilot cloud agent and Copilot CLI also read AGENTS.md
The References list in Copilot Chat shows which instructions were used

Add DESIGN.md to the repository

Generate it from a site with Sitepeel, review it and commit it at the repository root.

Create an instructions file

Add .github/instructions/design.instructions.md with an applyTo pattern for your UI files.

Link DESIGN.md in it

Use a Markdown link with a path relative to the instructions file, plus your must-follow rules.

Ask for one screen

In Copilot Chat or with the cloud agent, ask for one page and name its content and main action.

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

Design MD generator in the Sitepeel interface — Design MD generator in actionExplore the tool

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.

TipAdd excludeAgent: "code-review" to the front matter if you don’t want code review to apply these rules.

.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

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

A few useful 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.

TAKE A CLOSER LOOK

Your next starting point is already on the web.

Inspect it. Understand it. Build something of your own.

Add to ChromeFree install Try the free tools