Skip to content
helixui

GitHub Copilot

GitHub Copilot reads .github/copilot-instructions.md on every chat turn and as global context for inline completions. Drop this into your repo to make Copilot helixui-fluent:

.github/copilot-instructions.md

# Project conventions for GitHub Copilot


This project uses the **helixui** design system. helixui is AI-native:
every component documents itself in a sibling `spec.md`. Read those
when you need a component's API.


## When generating UI code


1. **Import from `@helixui/core`** for every primitive (`Button`,
   `Card`, `Stack`, `Tabs`, `Sidebar`, `Sheet`, `Dialog`,
   `AppShell`, `Form`, etc.).
2. **Use `@helixui/icons`** for icons. 238 outline + 27 filled,
   tree-shakable.
3. **Use CSS custom properties** for colors, spacing, radii, fonts —
   never hex, never px, never font names. Examples:
   - `var(--helixui-color-bg-surface-default)`
   - `var(--helixui-color-text-action-brand)`
   - `var(--helixui-space-4)`
   - `var(--helixui-radius-md)`
4. **Wrap themed regions** in `<HelixUIDNAProvider dna={…}>` from
   `@helixui/core`.


## Don'ts


- Don't write inline `style={{ color: '#...' }}` — use tokens.
- Don't import from `@mui/*`, `@chakra-ui/*`, `antd`, `radix-ui` —
  helixui has equivalents.
- Don't add a new dependency without telling the reviewer why.
- Don't remove focus rings, ARIA labels, or other a11y plumbing.


## Where to look


- `DESIGN.md` (repo root) — the canonical design-system summary.
- `node_modules/@helixui/core/dist/components/<name>/spec.md` —
  per-component contract.
- `tokens-manifest.json` — every token, machine-readable.


## Component patterns


- Layout: `Stack`, `Grid`, `Flex`, `Box`, `AppShell`, `PageHeader`,
  `Sidebar`.
- Actions: `Button`, `IconButton`, `Menu`, `Dialog`, `Popover`,
  `Sheet`, `CommandPalette`.
- Input: `TextInput`, `Textarea`, `Select`, `MultiSelect`, `Checkbox`,
  `RadioGroup`, `Switch`, `Slider`, `NumberField`, `PinInput`.
- Display: `Card`, `Badge`, `Avatar`, `Text`, `StatCard`, `Chart`,
  `Sparkline`, `Table`, `Calendar`.
- Feedback: `Toast` (via `toast` helper), `Banner`, `Callout`,
  `Skeleton`, `Spinner`, `ProgressBar`, `EmptyState`.


If unsure which to use, search `dist/components/` for a `spec.md`
whose `category` or `tags` match what you need.

What this changes

With the instructions file in place, ask Copilot:

Generate a dashboard layout with a left sidebar, a top app bar, and three stat cards across the top.

Copilot will reach for AppShell + Sidebar + PageHeader + StatCard instead of writing a <div className="dashboard"> from scratch. You can verify by checking the first 5 lines of its output — if you see import { … } from '@helixui/core', the instructions are being read.

Verifying the instructions are active

Terminal window
# In any chat, ask:
"What design system does this project use, and what's the convention
for color tokens?"

Copilot should answer “helixui” and mention CSS custom properties / --helixui-*. If it doesn’t, double-check:

  • The file is at .github/copilot-instructions.md (exact name, case sensitive).
  • You’ve reloaded the workspace.
  • Your IDE plugin is up to date.

Combine with the MCP server

Copilot Chat in VS Code 1.94+ can also speak MCP. Add the helixui MCP server to .vscode/mcp.json:

{
  "servers": {
    "helixui": {
      "type": "stdio",
      "command": "node",
      "args": ["./node_modules/@helixui/mcp/bin/server.mjs"]
    }
  }
}

Then @helixui.search from inside Copilot Chat works just like in Claude Code.