GitHub Copilot instructions for a design system: copilot-instructions.md and applyTo
Put the design rules every change needs in .github/copilot-instructions.md, and component or stylesheet rules in .github/instructions files with an applyTo pattern. The References list shows which files a response used.
6 min read
Which file does Copilot read?
GitHub Copilot reads repository-wide instructions from .github/copilot-instructions.md. It reads path-specific instructions from files named NAME.instructions.md in .github/instructions, each with an applyTo pattern in its frontmatter. When a path-specific file and the repository-wide file both apply, Copilot uses both.
Put the rules any change can break in the repository-wide file: where colours live, which button component to reuse, the label of the main action. Put rules for one kind of file in a path-specific file. GitHub's documentation also says Copilot can use AGENTS.md files anywhere in the repository, with the nearest one taking precedence.
Copy the repository-wide file
Save this as .github/copilot-instructions.md. It describes the fictional Wrenboard marketing site; replace the paths, label and commands with your own. Each rule names something a reviewer can find in a diff: a hex value, a second Book a demo button, a gradient.
# Wrenboard marketing site
Wrenboard is a fictional scheduling tool for small dental clinics. This repository is its marketing site, built with React and plain CSS.
## Design rules for every change
- Colours, type and spacing live in `src/styles/tokens.css`. Use its CSS variables; do not write hex, rgb or hsl values in components or pages.
- Reuse `src/components/Button.tsx` for every button and every link styled as a button.
- The primary action on every page is Book a demo. Use that exact label, once per screen.
- No gradients, glow effects, glass blur or decorative emoji.
- Do not add customer logos, testimonials, ratings or statistics. Wrenboard has none.
## Checks
- Run `npm run lint` and `npm run build` before you say a change is finished.
- Say what you checked in a browser and what you did not.Attach component rules with applyTo
Save this as .github/instructions/components.instructions.md. The applyTo pattern is a glob; src/components/**/*.tsx matches .tsx files at any depth under src/components. To list several patterns, separate them with commas, as in “**/*.ts,**/*.tsx”.
---
applyTo: "src/components/**/*.tsx"
---
# Component rules
- Props are typed in the same file. Variants are a string union, for example `variant: "primary" | "secondary"`.
- Every interactive element has a visible focus style: `outline: 2px solid var(--focus)` with `outline-offset: 2px`.
- Text inside a control is at least 16px.
- Do not add a new variant, size or colour to an existing component. Say which one you need and why.Keep a rule out of Copilot code review
Save this as .github/instructions/styles.instructions.md. The excludeAgent field with the value “code-review” stops Copilot code review from using the file, while Copilot cloud agent still reads it. Here the rule asks the author of a change to add a contrast ratio to the pull request, which is work for the agent writing the change. Without excludeAgent, both features use the file.
---
applyTo: "src/styles/**/*.css"
excludeAgent: "code-review"
---
# Token file rules
- Add a new colour only as a named variable with a comment saying where it is used.
- Text and background pairs must reach a contrast ratio of at least 4.5:1. Give the ratio in the pull request.How do you see which instructions a response used?
In VS Code, open the References section of a chat response; it lists the instruction files that were included. VS Code's documentation notes that this shows inclusion, not compliance. On GitHub, add the repository as an attachment in Copilot Chat and expand the references list to look for .github/copilot-instructions.md.
To check compliance, ask for a small change without repeating the rules, such as a new pricing link in the hero, and read the diff. Copilot code review reads instruction files from the pull request's head branch, so a rule added in a pull request applies to the review of that same pull request. On GitHub.com, path-specific files are supported for Copilot cloud agent and Copilot code review.
What was and was not tested
Copilot was not run for this article. The three files follow GitHub's and VS Code's documentation, checked on 6 November 2026. A script using the picomatch library confirmed that each applyTo pattern matches the intended files in an example project: the component pattern matched Button.tsx and Hero.tsx, and the stylesheet pattern matched tokens.css. That checks the patterns, not Copilot's own matcher.
The same rules, written as a CLAUDE.md, were run in Claude Code on a component built to break them, and the review found all six breaks. Cursor users can split them into .mdc rules in the same way.
Put the brief into practice
A launch page should make the buyer, promise, proof, and next action obvious. iter0 uses this same standard when it turns a brief or reference site into a builder-ready page.
Start your launch build