Overview
GitHub's design system is a highly systematized, token-driven visual language engineered for developer productivity and accessibility. It prioritizes semantic clarity through a vast set of named color roles (background, surface, border, foreground, emphasis, muted) that adapt seamlessly across light, dark, and high-contrast themes. The system is functional-first — every visual decision is justified by utility, contrast, and legibility rather than decoration.
Signature traits: semantic token architecture, adaptive light/dark/high-contrast theming, monospace code typography, restrained neutral palette with precise accent blue, multi-level elevation via box shadows, accessibility-first contrast ratios.
Colors
| Role | Token | Hex | Usage |
|------|-------|-----|-------|
| Background | --bgColor-default | #ffffff | Page backgrounds |
| Surface | --bgColor-muted | #f6f8fa | Card/panel backgrounds, inset areas |
| Text Primary | --fgColor-default | #1f2328 | Headings, body copy |
| Text Secondary | --fgColor-muted | #59636e | Captions, placeholders, metadata |
| Border | --borderColor-default | #d1d9e0 | Dividers, input outlines |
| Accent | --bgColor-accent-emphasis | #0969da | CTAs, links, focus rings |
| Accent Muted | --bgColor-accent-muted | #ddf4ff | Accent backgrounds, highlights |
| Danger | --bgColor-danger-emphasis | #cf222e | Error states, destructive actions |
| Success | --bgColor-success-emphasis | #1f883d | Success states, primary button |
| Attention | --bgColor-attention-emphasis | #9a6700 | Warning states |
| Done | --bgColor-done-emphasis | #8250df | Merged/done states |
| Severe | --bgColor-severe-emphasis | #bc4c00 | Severe warning states |
| Sponsors | --bgColor-sponsors-emphasis | #bf3989 | Sponsor highlights |
| Neutral Emphasis | --bgColor-neutral-emphasis | #59636e | Neutral badges, counters |
| Header BG | --header-bgColor | #25292e | Global navigation background |
| Emphasis BG | --bgColor-emphasis | #25292e | Tooltips, emphasis surfaces |
| Disabled | --bgColor-disabled | #eff2f5 | Disabled control backgrounds |
| Overlay Backdrop | --overlay-backdrop-bgColor | #c8d1da66 | Modal backdrops |
Typography
| Role | Family | Size | Weight | Line Height | Letter Spacing | Usage | |------|--------|------|--------|-------------|----------------|-------| | Display | -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif | 3rem | 600 | 1.25 | -0.01em | Hero headlines | | Heading | -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif | 1.5rem | 600 | 1.25 | normal | Section titles | | Body | -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif | 1rem | 400 | 1.5 | normal | Paragraph text | | Caption | -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif | 0.75rem | 400 | 1.5 | normal | Labels, metadata | | Mono | 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace | 0.875rem | 400 | 1.5 | normal | Code, data, diffs |
Layout
| Token | Value | Context | |-------|-------|---------| | Spacing XS | 0.25rem | Inline gaps, tight icon spacing | | Spacing SM | 0.5rem | Component padding, small gaps | | Spacing MD | 1rem | Standard component padding | | Spacing LG | 1.5rem | Section internal gaps | | Spacing XL | 2rem | Section separators | | Spacing 2XL | 3rem | Major layout sections | | Border Width | 0.0625rem | All border definitions | | Max Width | 1280px | Content container | | Tab Size | 4 | Code tab rendering (--tab-size-preference: 4) |
Responsive strategy: GitHub uses a fluid content-width approach with fixed navigation header; component-level spacing tokens scale through xs→2xl; no explicit breakpoint variables observed in extracted CSS, but header and overlay components suggest a mobile-first collapsing navigation pattern.
Elevation & Depth
| Level | CSS Value | Usage |
|-------|-----------|-------|
| xsmall | 0 1px 1px 0 #1f23280d | Subtle lift, row hover |
| small | 0 1px 1px 0 #1f23280a, 0 1px 2px 0 #1f232808 | Cards, tooltips |
| medium | 0 1px 1px 0 #25292e1a, 0 3px 6px 0 #25292e1f | Dropdowns, popovers |
| inset | inset 0 1px 0 0 #1f23280a | Button pressed states |
| floating-small | 0 0 0 1px #d1d9e040, 0 6px 12px -3px #25292e0a, 0 6px 18px 0 #25292e1f | Floating panels |
| floating-medium | 0 0 0 1px #d1d9e000, 0 8px 16px -4px #25292e14, 0 4px 32px -4px #25292e14, 0 24px 48px -12px #25292e14, 0 48px 96px -24px #25292e14 | Modals, overlays |
| floating-large | 0 0 0 1px #d1d9e000, 0 40px 80px 0 #25292e3d | Full-screen overlays |
| floating-xlarge | 0 0 0 1px #d1d9e000, 0 56px 112px 0 #25292e52 | Maximum depth modals |
Shapes
| Token | Value | Applied To | |-------|-------|-----------| | none | 0px | Sharp-edged table cells, code blocks | | sm | 0.1875rem | Small badges, inline labels | | md | 0.375rem | Buttons, inputs, cards | | lg | 0.75rem | Panels, dropdowns, larger cards | | xl | 1rem | Modal dialogs, overlays | | full | 9999px | Pill badges, avatar rings, toggle controls |
Components
Buttons: Five variants — primary (green #1f883d bg), default (neutral surface), danger (red), outline (accent-colored border/text), invisible (transparent bg). All buttons use 0.0625rem borders, var(--borderColor-translucent) for primary border, and share a consistent state model: rest → hover → active → disabled. Disabled states use #eff2f5 background with muted text. Shadow on default button rest state: 0 1px 0 0 #1f23280a.
Header: Fixed dark navigation bar (#25292e), with logo in white (#fff), default text at #ffffffb3 (70% white), and a divider at #818b98. Header search uses matching dark background with #818b98 border.
Labels/Tags: Full color palette of named semantic labels (auburn, blue, brown, coral, cyan, gray, green, indigo, lemon, lime, olive, orange, pine, pink, plum, purple, red, teal, yellow). Each has rest/hover/active background and foreground states. Borders are transparent (#fff0) by default in light theme; in high-contrast mode borders match the foreground color.
Avatars: White background (#fff), translucent border (#1f232826), drop shadow ring 0 0 0 2px #fffc. Avatar stacks use fade colors #c8d1da and #dae0e7.
Overlays/Modals: White background, #d1d9e080 border, backdrop #c8d1da66. Floating shadow system provides four depth levels.
Progress Bars: Semantic color bars for accent, attention, danger, done, neutral, severe, sponsors, success. Track background uses --borderColor-default. Track border is transparent.
Skeleton Loaders: #818b981a background (neutral muted at low opacity).
Contribution Graph: Five-level green scale (0: #eff2f5, 1: #aceebb, 2: #4ac26b, 3: #2da44e, 4: #116329). Halloween and winter alternate palettes also defined.
Code/Syntax: Full prettylights and CodeMirror syntax token sets. Keywords in red (#cf222e), constants in blue (#0550ae), strings in navy (#0a3069), variables in orange (#953800), entities in purple (#6639ba).
Focus: 0.125rem solid #0969da — consistent 2px solid blue outline. Applied via --focus-outline token.
Selection: #0969da33 — translucent accent blue selection highlight.
Underline Nav: Active border #fd8c73 (coral/salmon), hover border uses --borderColor-muted, icon color uses --fgColor-muted.
Control Knobs (Toggle): White knob (#fff) on colored track. Rest track: #e6eaef, hover: #e0e6eb, active: #dae0e7. Disabled track matches --fgColor-disabled.
Do's and Don'ts
| Do ✓ | Don't ✗ |
|------|---------|
| Use semantic color tokens (--bgColor-*, --fgColor-*, --borderColor-*) for all color decisions | Hardcode raw hex values that bypass the token layer |
| Apply --fgColor-muted (#59636e) for secondary text, captions, and placeholder text | Use the primary text color for metadata or supporting copy |
| Use --bgColor-accent-emphasis (#0969da) for primary interactive CTAs and focus indicators | Use custom blues or off-brand accent colors for interactive elements |
| Apply the full state model (rest/hover/active/disabled) for all interactive controls | Skip disabled or active states, leaving incomplete interaction feedback |
| Use --bgColor-success-emphasis (#1f883d) for primary action buttons (green = confirm/create) | Use accent blue for primary create/confirm actions — that is reserved for navigation and links |
| Respect the dark/high-contrast theme variants using data-color-mode and data-light-theme/data-dark-theme attributes | Hard-code light-only colors that break dark mode rendering |
| Use monospace font stack (SFMono-Regular, Consolas, Menlo) for all code, diffs, and data display | Use proportional fonts inside code blocks or terminal output |
| Apply tab-size: var(--tab-size-preference) (default 4) for all pre/code elements | Override tab-size without referencing the CSS custom property |
| Use 0.0625rem (1px) borders consistently across all components | Mix border widths arbitrarily across components |
| Leverage the named label color system for issue/PR classification labels | Invent new label colors outside the defined 19-color semantic palette |
Agent Prompt Guide
You are working within the GitHub · Change is constant. GitHub keeps you ahead. · GitHub design system. Key constraints:
- —Colours: background #ffffff, surface #f6f8fa, text primary #1f2328, text secondary #59636e, border #d1d9e0, accent #0969da (blue), primary action #1f883d (green), danger #cf222e
- —Typography: -apple-system/BlinkMacSystemFont/'Segoe UI' sans-serif for UI text; 'SFMono-Regular'/Consolas/Menlo monospace for all code and data
- —Font sizes: caption 0.75rem, body 1rem, heading 1.5rem, display 3rem; code 0.875rem
- —Spacing: use the spacing scale only — xs 0.25rem / sm 0.5rem / md 1rem / lg 1.5rem / xl 2rem / 2xl 3rem
- —Radius: sm 0.1875rem for badges, md 0.375rem for buttons/inputs/cards, full 9999px for pills and avatars
- —Borders: always 0.0625rem width; use --borderColor-default (#d1d9e0) for standard borders
- —Focus: always 0.125rem solid #0969da — never suppress focus outlines
- —Elevation: use shadow-resting-small for cards, shadow-floating-medium for dropdowns, shadow-floating-large for modals
- —Dark mode: all colors must reference semantic tokens that resolve correctly under data-color-mode="dark"
- —Never use colours, fonts, spacing, or radius values outside this design system