How to Use DESIGN.md with GitHub Copilot
Copilot has gotten smarter about workspace context
GitHub Copilot has evolved a lot from its origins as a single-line autocomplete tool. With the introduction of Copilot Chat and advanced workspace context features, it now actively scans repository files to ground its suggestions.
But Copilot requires explicit instruction on what to read. It indexes workspace symbols and active tabs, but it does not inherently understand brand guidelines unless they're structured properly. When an engineer asks Copilot Chat to "generate a navigation bar," the model defaults to standard utility classes unless it's pointed toward a canonical source of truth. Understanding how AI models process this structured data is key, which we explore in detail in what DESIGN.md is.
The two-file pattern for Copilot users
For teams standardized on GitHub Copilot, managing context relies on a strict two-file pattern at the repository root.
The first file is .github/copilot-instructions.md. This file dictates behavioral rules, testing conventions, and architectural boundaries. It is the Copilot-native equivalent of CLAUDE.md. The second file is DESIGN.md. This file is strictly responsible for visual identity, housing all design tokens and component structures.
These files cooperate seamlessly. The .github/copilot-instructions.md file can cross-reference the visual rules by instructing Copilot: "When generating UI components, always pull spacing and color tokens from DESIGN.md at the repository root." This architecture ensures Copilot understands both how to write the code and what the code should look like. To see how this pattern compares across environments, read our guides on using DESIGN.md with Cursor and using DESIGN.md with Claude Code.
Step 1 — Get a DESIGN.md
Before configuring Copilot, you must secure a compliant file.
The fastest method is extracting one from a live URL using designmd.run. The pipeline will analyze the stylesheets and generate a structured markdown file in approximately three minutes. This approach guarantees the YAML frontmatter and component blocks are formatted correctly for AI ingestion. If your team requires an entirely custom solution, you can hand-write the file following the official specification. You can review examples of compliant files in our gallery.
Step 2 — Place the file and reference it
Once generated, place the DESIGN.md file at the absolute root of your repository.
Placement is critical because Copilot weights files at the root higher when establishing workspace context. If your team utilizes Copilot Enterprise, this approach satisfies strict data residency requirements—the design context remains securely within the repository, versioned alongside the source code.
To ensure Copilot consistently utilizes the tokens, add a directive inside your .github/copilot-instructions.md file: Always reference DESIGN.md for color variables and spacing scales when outputting frontend code.
Step 3 — Prompt patterns that work in Copilot Chat
When interacting with Copilot Chat, explicit prompting yields the best results.
Instead of writing, "Build a blue button with 16px padding," use a prompt that anchors the AI to the file: "Build a primary button component. Use the tokens defined in DESIGN.md."
You can also reference specific component blocks directly. For example, "Add the Card layout defined in DESIGN.md." Avoid prompts that bypass the context entirely, such as pasting raw hex codes into the chat box, as this trains the session to ignore the repository's source of truth.
Verifying Copilot output
After Copilot generates the code, verification is straightforward.
Perform a quick visual check against the generated CSS or styled components. If your DESIGN.md file dictates {colors.primary}: "#1A56DB", that exact hex string (or its corresponding variable mapping) must be present in the output. For robust validation, teams can write a simple unit test that asserts specific components render with the hex codes defined in the file. To understand how the broader ecosystem approaches this setup, learn more about our methodology.
Pitfalls
The primary pitfall when using Copilot is context truncation. If your DESIGN.md file spans thousands of lines detailing every granular hover state of an obscure widget, Copilot may truncate the file during the prompt ingestion phase, leading to ignored tokens. Keep the file compact, focusing on foundational variables and core components.
Also, a stale DESIGN.md file will force Copilot to generate outdated UI. When a product undergoes a redesign, you must re-extract or update the file immediately to ensure the AI's visual memory remains synchronized with your current brand guidelines.
Frequently asked questions
Does Copilot read DESIGN.md automatically?
Copilot indexes files in the workspace, but explicitly referencing the file in your .github/copilot-instructions.md or directly in the chat ensures it actively uses the tokens.
Can I keep the file in a subdirectory?
It is strongly recommended to keep it at the repository root to ensure Copilot prioritizes it alongside other critical configuration files.
Does this work with Copilot Enterprise?
Yes. Because the file lives natively in the repository, it complies with Copilot Enterprise data residency and privacy constraints.
Get Started
Get your DESIGN.md file in about 3 minutes — no account required. Visit the designmd.run homepage to start your extraction.