GitHub Primer

---
name: github-primer
description: Apply the GitHub Primer visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" GitHub Primer, mentions Primer, GitHub design system, Primer CSS, or describes canvas white / dark #0d1117, accent blue #0969da, bordered boxes with 6px radii — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# GitHub Primer Design System

GitHub's developer-platform system: system-font pragmatism at 14px, blue #0969da accents on white canvas (or the famous #0d1117 dark mode), subtle #d0d7de borders around 6px-radius 'Box' containers, semantic success green and danger red, 8px spacing, and functional color tokens (fg.muted, canvas.subtle) shipped as primer/primitives.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values come from the officially published token set. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as GitHub Primer.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (Primer, GitHub design system, Primer CSS, primer primitives), or describes its traits: canvas white / dark #0d1117; accent blue #0969da; bordered boxes with 6px radii; system font stack at 14px; semantic open-green and danger-red; monospace code blocks everywhere.

## Design tokens

### Color palette

- canvas.default — page background: `#ffffff` (--color-bg)
- canvas.subtle — box headers, code block backgrounds: `#f6f8fa` (--color-surface)
- fg.default — primary text: `#1f2328` (--color-text)
- fg.muted — secondary text and metadata: `#656d76` (--color-text-muted)
- accent.fg — links and interactive blue: `#0969da` (--color-accent)
- border.default — box and control outlines: `#d0d7de` (--color-border)
- success.fg — open/merged-adjacent green: `#1a7f37` (--color-success)
- danger.fg — destructive actions and closed states: `#cf222e` (--color-danger)

### Dark mode overrides

When building dark mode, override these roles (all other tokens stay the same):

- canvas.default in dark mode: `#0d1117` (--color-bg)
- canvas.subtle in dark mode: `#161b22` (--color-surface)
- fg.default in dark mode: `#e6edf3` (--color-text)
- fg.muted in dark mode: `#8d96a0` (--color-text-muted)
- accent.fg in dark mode: `#2f81f7` (--color-accent)
- border.default in dark mode: `#30363d` (--color-border)

### Typography

- Display / headings: system-ui (fallback: -apple-system, Segoe UI, Noto Sans, Helvetica, Arial, sans-serif) (ideal: Mona Sans, premium — use system-ui as the free substitute)
- Body: system-ui (fallback: -apple-system, Segoe UI, Noto Sans, Helvetica, Arial, sans-serif)
- Mono / data: ui-monospace (fallback: SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace)
- Type scale: 1.15 ratio, base 14px — computed steps: 14px / 16px / 19px / 21px / 24px / 28px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 600, line-height 1.25, letter-spacing 0
- Body: line-height 1.5, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 4, 8, 16, 24, 32, 40, 48 — 8px base scale (4px half-step): 16px box padding, 8px control gaps, 24px between page sections — dense enough for code review, loose enough for reading diffs all day.
- Border radius: sm 3px, md 6px, lg 12px, full 9999px — 6px 'medium' is the workhorse radius for boxes, buttons, and inputs; 3px for small chips, 12px for large dialogs, full for labels and avatars.
- Border treatment: 1px solid #d0d7de — Hairline borders do the structural work Primer refuses to give shadows; nested boxes divide with the same 1px stroke.

### Shadows

- btn: `0 1px 0 rgba(31, 35, 40, 0.04)` — Default buttons — a whisper of lift over the border
- overlay: `0 8px 24px rgba(140, 149, 159, 0.2)` — Dropdown menus, popovers, and hover cards
- dialog: `0 16px 32px rgba(31, 35, 40, 0.15)` — Modal dialogs

### Layout

- Max content width: 1280px
- Container capped at 1280px with 16–32px gutters
- Two-column pattern: main content plus a 296px metadata sidebar (repo/PR pages)
- Underlined tab navigation with counter pills for section switching
- Code and diffs render full-width in monospace inside bordered boxes

### Effects

- State-colored round labels and pills (open green, closed red, draft gray) built from token pairs
- Contribution-graph green scale as a data-visualization signature

### Motion

- Easing: cubic-bezier(0.33, 1, 0.68, 1); durations 80ms / 200ms / 300ms
- Overlays fade+scale in from 95% over ~200ms; most other state changes are near-instant
- Details/summary disclosure animates height briefly or not at all
- Motion never blocks a developer's flow — no page transitions

## CSS variables (drop-in)

```css
:root {
  --color-bg: #ffffff;
  --color-surface: #f6f8fa;
  --color-text: #1f2328;
  --color-text-muted: #656d76;
  --color-accent: #0969da;
  --color-border: #d0d7de;
  --color-success: #1a7f37;
  --color-danger: #cf222e;
  --radius-sm: 3px;
  --radius-md: 6px;
  --radius-lg: 12px;
  --radius-full: 9999px;
  --shadow-btn: 0 1px 0 rgba(31, 35, 40, 0.04);
  --shadow-overlay: 0 8px 24px rgba(140, 149, 159, 0.2);
  --shadow-dialog: 0 16px 32px rgba(31, 35, 40, 0.15);
  --border-default: 1px solid #d0d7de;
  --font-display: system-ui, -apple-system, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
  --font-body: system-ui, -apple-system, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
  --text-base: 14px;
  --leading-heading: 1.25;
  --leading-body: 1.5;
  --tracking-heading: 0;
  --tracking-body: 0;
  --ease: cubic-bezier(0.33, 1, 0.68, 1);
  --duration-fast: 80ms;
  --duration-base: 200ms;
  --duration-slow: 300ms;
}
```

All fonts are system fonts — nothing to load.

## Component recipes

- **Nav:** Header on canvas (dark #0d1117 in dark mode) with repo breadcrumb, then an underlined tab row: 8px-padded tabs, active tab gets a 2px #fd8c73-orange underline and 600 weight
- **Hero:** Product pages use Mona Sans display type oversized on dark; in-app 'heroes' are just a title row: repo name in 20px/600 blue-linked text with status labels
- **Card:** The Box: 1px #d0d7de border, 6px radius, no shadow, optional #f6f8fa header row with 16px padding; lists divide rows with the same hairline
- **Button (primary):** Success green #1a7f37-adjacent fill (#1f883d) with white text, 6px radius, 32px tall, 1px darker border, btn shadow; used sparingly — one green per view
- **Button (secondary):** The default button: #f6f8fa fill, 1px #d0d7de border, #24292f text; hover deepens fill to #f3f4f6
- **Form fields:** 14px input, 6px radius, 1px #d0d7de border, white fill; focus ring is a 3px rgba(9,105,218,0.3) halo around an #0969da border

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The Primer 'Box': content organized into hairline-bordered #d0d7de containers with 6px radii and canvas-subtle #f6f8fa headers — the visual grammar of every repo page, PR, and settings screen on GitHub. Spend boldness here; keep everything else quiet.

## Do

- Structure pages with bordered boxes and hairlines — reach for a border before a shadow, always
- Use functional tokens (fg.muted, canvas.subtle, border.default) so light/dark/dark-dimmed themes all resolve
- Keep one green primary button per view; everything else is the gray default button
- Set code, hashes, and counts in the monospace stack — mono is part of the brand

## Don't

- Don't add drop shadows to resting content; elevation is for transient overlays only
- Don't use pure black text — fg.default is #1f2328 on light, #e6edf3 on dark
- Don't invent status colors; open/merged/closed/draft semantics are fixed vocabulary
- Don't load display webfonts in-app — Mona Sans belongs to marketing surfaces

## Accessibility notes

- Published pairs pass AA: #1f2328 on white ~15.4:1, fg.muted #656d76 ~5.3:1, accent #0969da ~5.2:1; in dark mode keep fg.muted #8d96a0 for text and reserve darker grays for icons
- Color never carries state alone — every open/closed/merged indicator pairs an icon with the color
- The 3px accent focus halo must remain visible on both canvas colors; don't replace it with outline:none styling

## Reference sites

- Primer design system: https://primer.style
- Primer primitives (tokens): https://primer.style/foundations/primitives/color
- Primer on GitHub: https://github.com/primer

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip github-primer.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/github-primer.json

Settings → Capabilities → Skills → Upload skill → github-primer.zip