GitHub Copilot copilot-instructions.md

DESIGN.md + GitHub Copilot

Configuration reference: DESIGN.md include

Why Copilot Needs a DESIGN.md

Copilot works by context. It reads open files, neighboring files, and in workspace mode, the entire project. Without a DESIGN.md, the model does its best with what it has: copies patterns from other files in the project, or invents based on generic training data.

With a DESIGN.md at the root, you give Copilot:

  • Exact color palette - instead of bg-blue-500, it uses bg-brand-primary or the correct hex value
  • Typographic scale - knows that headings use Inter Bold 32px and body uses 16px/1.6
  • Spacing rules - applies an 8px grid without you correcting afterward
  • Component patterns - hover, focus and disabled states documented
  • Constraints - knows what NOT to do (no gradients, limited shadows, etc.)

The result: fewer correction iterations, less “that’s not what I wanted,” less time in code review adjusting visual details.

Step by Step Setup

1. Place DESIGN.md at the project root

Copilot needs to find the file in the workspace. The root is the canonical location:

my-project/
├── DESIGN.md          ← here
├── .github/
│   └── copilot-instructions.md
├── src/
│   └── components/
├── package.json
└── ...

If you don’t have a DESIGN.md yet, grab one from the library or generate one with the creation tool. The format uses YAML front matter with tokens and markdown prose with design rationale:

---
colors:
  primary: "#1A73E8"
  secondary: "#34A853"
  surface: "#FFFFFF"
  background: "#F8F9FA"
  text-primary: "#202124"
  text-secondary: "#5F6368"
  error: "#D93025"
typography:
  font-family-heading: "Inter, sans-serif"
  font-family-body: "Inter, sans-serif"
  scale: [12, 14, 16, 20, 24, 32, 40, 48]
  line-height-body: 1.6
  line-height-heading: 1.2
spacing:
  base: 8
  scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]
border-radius:
  small: 4
  medium: 8
  large: 16
  pill: 9999
---

# Design System — MyApp

## Philosophy

Clean, functional interface. No excessive decoration. Clear visual hierarchy through size and typographic weight, not color. Color is reserved for actions and states.

## Components

### Buttons

- **Primary**: background `primary`, white text, border-radius `medium`, padding 12px 24px
- **Secondary**: transparent background, 1px `primary` border, `primary` text
- **Ghost**: no background, no border, `primary` text, hover with `background` fill

States: hover darkens 10%, disabled opacity 0.5, focus ring 2px offset.

### Cards

Background `surface`, border-radius `large`, padding 24px, subtle shadow (0 1px 3px rgba(0,0,0,0.1)). No visible border. Hover elevates shadow.

## Constraints

- Never use gradients on backgrounds
- Maximum 2 typographic weights per page (regular + bold)
- Do not use outline on inputs — use border that changes color on focus
- Icons: stroke only, never filled

2. Create the copilot-instructions.md file

This is the key piece. GitHub Copilot automatically reads .github/copilot-instructions.md as additional context in every interaction. Create the directory if it doesn’t exist:

mkdir -p .github

Contents of .github/copilot-instructions.md:

# Instructions for GitHub Copilot

## Design System

This project uses DESIGN.md as the source of truth for visual decisions.

Before generating any UI component, form, page or style:
1. Read the DESIGN.md file at the project root
2. Use exclusively the colors, typography and spacing defined there
3. Follow the documented component patterns (buttons, cards, inputs)
4. Respect the constraints listed in the "Constraints" section

### Mandatory rules

- Colors: use only tokens from DESIGN.md, never hardcoded values
- Typography: respect the defined scale, no invented sizes
- Spacing: use multiples of the base (8px)
- Components: follow documented states (hover, focus, disabled)
- Never violate the Constraints section

### When there's no definition

If DESIGN.md doesn't cover a specific case, ask before inventing.
Prefer consistency with existing patterns over novel decisions.

3. Use @workspace context in Chat

Copilot Chat accepts explicit references with @workspace. When you want to generate something visual:

@workspace Create a responsive navbar component following the DESIGN.md

The @workspace directive forces Copilot to index the entire project, including DESIGN.md, before responding. Without it, Copilot may ignore files that aren’t open.

For more direct references:

@workspace #file:DESIGN.md Create a contact form using the tokens from this design system

The #file:DESIGN.md points explicitly to the file. Double insurance.

4. Pin DESIGN.md as context in Chat

In the Copilot Chat panel, you can click the clip icon (attach context) and add DESIGN.md as a reference file. It remains in context for the entire conversation.

5. Use in Copilot Edits mode (multi-file)

Copilot Edits lets you edit multiple files simultaneously. When starting an edits session, add DESIGN.md as a context file (read-only). This way it applies tokens across every file it modifies:

Refactor all components in src/components/ to use the DESIGN.md tokens

Concrete Usage Example

Prompt in Copilot Chat:

@workspace #file:DESIGN.md

Create a React pricing card component with:
- Plan name and price
- Feature list with checkmarks
- Primary CTA button
- "Popular" variant with visual highlight
- Responsive: stack on mobile, grid on desktop

Copilot responds with code that references the tokens:

// src/components/PricingCard.tsx
interface PricingCardProps {
  name: string;
  price: string;
  period: string;
  features: string[];
  isPopular?: boolean;
  ctaText: string;
  onCtaClick: () => void;
}

export function PricingCard({
  name, price, period, features, isPopular, ctaText, onCtaClick
}: PricingCardProps) {
  return (
    <div
      className={`
        rounded-2xl p-6 bg-white
        shadow-sm hover:shadow-md transition-shadow
        ${isPopular ? 'ring-2 ring-[#1A73E8] scale-105' : ''}
      `}
    >
      {isPopular && (
        <span className="text-xs font-bold text-[#1A73E8] uppercase tracking-wide">
          Most popular
        </span>
      )}
      <h3 className="text-2xl font-bold text-[#202124] mt-2">
        {name}
      </h3>
      <p className="mt-2">
        <span className="text-4xl font-bold text-[#202124]">{price}</span>
        <span className="text-sm text-[#5F6368]">/{period}</span>
      </p>
      <ul className="mt-6 space-y-3">
        {features.map((feature) => (
          <li key={feature} className="flex items-center gap-2 text-[#202124]">
            <CheckIcon className="w-5 h-5 text-[#34A853]" />
            <span className="text-sm">{feature}</span>
          </li>
        ))}
      </ul>
      <button
        onClick={onCtaClick}
        className="
          mt-8 w-full py-3 px-6
          bg-[#1A73E8] text-white font-medium
          rounded-lg hover:bg-[#1557B0]
          focus:ring-2 focus:ring-offset-2 focus:ring-[#1A73E8]
          disabled:opacity-50 transition-colors
        "
      >
        {ctaText}
      </button>
    </div>
  );
}

Notice: the colors #1A73E8, #34A853, #202124, #5F6368 come directly from DESIGN.md. The border-radius rounded-2xl corresponds to large: 16. Spacing follows multiples of 8. The button has all three states (hover, focus, disabled) as documented.

GitHub Copilot-Specific Tips

Use workspace-level instructions, not just chat

The copilot-instructions.md is read in EVERY interaction, including inline suggestions (that grey ghost text). If you’re typing a component and start writing code, Copilot already considers the instructions. This is more powerful than chat alone.

Prefer semantic tokens in DESIGN.md

Instead of:

colors:
  blue: "#1A73E8"

Use:

colors:
  primary: "#1A73E8"
  cta-background: "#1A73E8"

Copilot understands semantic intent better. “Primary” and “cta-background” communicate where to use the color. “Blue” says nothing about context.

Add examples in DESIGN.md

The components section with concrete examples (inline code or pseudo-code) helps Copilot generate consistent patterns. The more explicit you are, the better:

### Input

```html
<input class="w-full px-4 py-3 border border-gray-300 rounded-lg 
       focus:border-primary focus:ring-1 focus:ring-primary
       text-sm text-text-primary placeholder:text-text-secondary" />

### Combine with .editorconfig and prettier

DESIGN.md handles the visual side. Combine it with formatting tools to ensure generated code already matches the project style. Fewer manual adjustments needed.

### VS Code settings to maximize context

In `.vscode/settings.json`:

```json
{
  "github.copilot.chat.codeGeneration.instructions": [
    { "file": "DESIGN.md" }
  ]
}

This ensures DESIGN.md is always included as a code generation instruction in chat, even without @workspace.

Troubleshooting and Gotchas

Copilot ignores DESIGN.md in inline suggestions

Inline suggestions (autocomplete) have limited context. Copilot prioritizes the open file and immediate neighbors. Solutions:

  1. Keep DESIGN.md open in a tab (even if not visible)
  2. Use copilot-instructions.md because that one is always read
  3. For complex components, use Chat instead of autocomplete

Hardcoded hex values instead of CSS variables

Copilot tends to use hex directly if DESIGN.md lists hex values. If you prefer CSS variables, document it this way in DESIGN.md:

### Usage in code

Never use hex directly. Use CSS variables:
- `var(--color-primary)` instead of `#1A73E8`
- `var(--color-surface)` instead of `#FFFFFF`

The copilot-instructions.md file doesn’t work

Check:

  • It’s at .github/copilot-instructions.md (with the dot before github)
  • The repository is open as a workspace (not as a loose file)
  • Copilot Chat is on the latest version (Settings > Extensions > GitHub Copilot > Check for updates)

Conflict between DESIGN.md and Tailwind config

If you use Tailwind and have a tailwind.config.js with custom colors, Copilot can get confused between the two. Resolve by adding to copilot-instructions.md:

## CSS Framework

This project uses Tailwind CSS. The DESIGN.md tokens are mapped in tailwind.config.js.
Use custom Tailwind classes (e.g., `text-primary`, `bg-surface`) instead of arbitrary values.

Workspace context limits

Very large projects can exceed Copilot’s context window. If DESIGN.md isn’t being considered:

  1. Check that the file is under 5000 tokens (ideal: 1000-3000)
  2. Move granular details to separate files and reference them from DESIGN.md
  3. Keep DESIGN.md concise: essential tokens + brief rationale

Workspace Mode vs Inline: When to Use Each

ScenarioMethod
Create new componentChat with @workspace #file:DESIGN.md
Autocomplete inside existing componentInline (copilot-instructions.md handles it)
Visual refactoring of multiple filesCopilot Edits with DESIGN.md as context
Check if code follows the design systemChat: “does this component follow DESIGN.md?”
Generate visual testsChat with DESIGN.md reference

Conclusion and Next Step

GitHub Copilot with DESIGN.md is the most accessible combination for teams already using VS Code. No new tooling required, no workflow changes. You just add context where there was none before.

Start with the minimum: a DESIGN.md at the root and a copilot-instructions.md in .github/. After two hours of use, the difference becomes obvious. Components come out more consistent, corrections drop off, and the design system stops being a PDF nobody reads.

Next steps:

Useful links