GOV.UK Design System

---
name: govuk-design-system
description: Apply the GOV.UK Design System visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" GOV.UK Design System, mentions GDS, GOV.UK Frontend, UK government design system, or describes yellow #ffdd00 focus states, near-black #0b0c0c text, underlined blue links — 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
---

# GOV.UK Design System Design System

The UK government's service design system: near-black #0b0c0c text, GDS Transport type, underlined blue links, square corners, unmistakable #ffdd00 yellow focus states, and a green action button. Content-first, WCAG-obsessed, and deliberately unglamorous — built so millions of people can complete tasks like renewing a passport.

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 GOV.UK Design System.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (GDS, GOV.UK Frontend, UK government design system, gov.uk style), or describes its traits: yellow #ffdd00 focus states; near-black #0b0c0c text; underlined blue links; square corners everywhere; green primary action button; content-first single column.

## Design tokens

### Color palette

- body-background — white page background: `#ffffff` (--color-bg)
- template-background / surface-background — blue tint-95: `#f4f8fb` (--color-surface)
- text — black primary (also input-border and link-active): `#0b0c0c` (--color-text)
- secondary-text — black tint-25 (2025 refresh; was #505a5f): `#484949` (--color-text-muted)
- brand — GOV.UK blue primary: `#1d70b8` (--color-accent)
- link — blue shade-10 (2025 refresh; classic link blue was #1d70b8): `#1a65a6` (--color-link)
- link-hover — blue shade-50: `#0f385c` (--color-link-hover)
- link-visited — purple primary: `#54319f` (--color-link-visited)
- focus — yellow, paired with #0b0c0c focus-text: `#ffdd00` (--color-focus)
- border — black tint-80, also hover state on form controls: `#cecece` (--color-border)
- error — red primary (2025 refresh; was #d4351c): `#ca3535` (--color-error)
- success — green primary; also the primary button fill (was #00703c): `#0f7a52` (--color-success)

### Typography

- Display / headings: Arial (fallback: Helvetica Neue, Helvetica, sans-serif) (ideal: GDS Transport, premium — use Arial as the free substitute)
- Body: Arial (fallback: Helvetica Neue, Helvetica, sans-serif) (ideal: GDS Transport, premium — use Arial as the free substitute)
- Type scale: 1.25 ratio, base 19px — computed steps: 19px / 24px / 30px / 37px / 46px / 58px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 700, line-height 1.1, letter-spacing 0
- Body: line-height 1.32, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 5, 10, 15, 20, 25, 30, 40, 50, 60 — The responsive spacing scale runs 5px to 60px in named steps; content pages breathe with 30–50px between components, but forms stay tight so a question fits on one screen.
- Border radius: none 0px — Everything is square: buttons, inputs, panels, notification banners. Rounding is reserved for the crown logo, not the UI.
- Border treatment: 1px solid #cecece — Section breaks use 1px #cecece rules; form inputs use a 2px solid #0b0c0c border; error states thicken to a 4–5px #ca3535 left border on summaries.

### Shadows

- none: `none` — Default — GOV.UK surfaces are completely flat; hierarchy comes from type scale and spacing
- button-edge: `0 2px 0 #0b5c3e` — The green button's hard bottom edge (green shade-25); pressed state removes it and shifts the button down 2px
- focus-underline: `0 -2px #ffdd00, 0 4px #0b0c0c` — Focused links: yellow highlight block behind the text plus a thick black bottom border

### Layout

- Max content width: 960px
- 960px width container with 15/30px gutters; content column capped at two-thirds width for readable line length
- One question per page in transactional flows; single-column always — no sidebars in services
- Black full-width header with crown logotype; blue brand rule beneath
- Error summary box anchored at the top of the page, linked to each failing field

### Effects

- No decorative effects at all: no gradients, no shadows, no animation — clarity is the aesthetic
- Phase banners (alpha/beta tags) and notification banners provide the only colour blocking

### Motion

- Easing: linear; durations 0ms / 0ms / 200ms
- Essentially motionless: no transitions on links, buttons, or focus states — state changes are instant
- Only JavaScript-driven reveals (accordions, details) animate, and abruptly

## CSS variables (drop-in)

```css
:root {
  --color-bg: #ffffff;
  --color-surface: #f4f8fb;
  --color-text: #0b0c0c;
  --color-text-muted: #484949;
  --color-accent: #1d70b8;
  --color-link: #1a65a6;
  --color-link-hover: #0f385c;
  --color-link-visited: #54319f;
  --color-focus: #ffdd00;
  --color-border: #cecece;
  --color-error: #ca3535;
  --color-success: #0f7a52;
  --radius-none: 0px;
  --shadow-button-edge: 0 2px 0 #0b5c3e;
  --shadow-focus-underline: 0 -2px #ffdd00, 0 4px #0b0c0c;
  --border-default: 1px solid #cecece;
  --font-display: Arial, "Helvetica Neue", Helvetica, sans-serif;
  --font-body: Arial, "Helvetica Neue", Helvetica, sans-serif;
  --text-base: 19px;
  --leading-heading: 1.1;
  --leading-body: 1.32;
  --tracking-heading: 0;
  --tracking-body: 0;
  --ease: linear;
  --duration-fast: 0ms;
  --duration-base: 0ms;
  --duration-slow: 200ms;
}
```

All fonts are system fonts — nothing to load.

## Component recipes

- **Nav:** Black #0b0c0c header bar, white GDS Transport logotype with crown, optional service name; a 10px blue #1d70b8 brand rule runs beneath
- **Hero:** No hero: pages open with a govuk-heading-xl (48px bold) directly on white, often preceded by a grey caption line; services lead with a green start button and a right-pointing arrow
- **Card:** GOV.UK avoids cards; related content sits in a #f4f8fb surface panel or behind a 1px #cecece top rule with bold link headings
- **Button (primary):** Green #0f7a52 fill, white bold 19px text, square corners, 2px darker green bottom edge (#0b5c3e); hover darkens, focus swaps to #ffdd00 with black text
- **Button (secondary):** Light grey #f3f3f3 fill with black text and same hard bottom edge; 'warning' variant uses red for destructive actions
- **Form fields:** Bold question label (often as an h1), grey hint text below, then a square white input with 2px #0b0c0c border; 4px #ca3535 left border and red message when in error

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 focus state: any focused link or control gets a #ffdd00 yellow highlight with a thick #0b0c0c black underline/outline — visible from across the room and the same on every GOV.UK service. Spend boldness here; keep everything else quiet.

## Do

- Use the yellow #ffdd00 + black focus style on every interactive element — it is the system's accessibility signature
- Keep links underlined at all times; colour alone never signals interactivity
- Write in plain language and let the type scale (19px base) do the visual work
- Use the one-thing-per-page pattern for forms and transactions

## Don't

- Don't round corners, add drop shadows, or animate — GOV.UK is aggressively flat and still
- Don't use GDS Transport outside gov.uk domains — it is licensed only for government services; use Arial/Helvetica instead
- Don't invent new colours; the 2025 refresh palette (link #1a65a6, error #ca3535) replaces the older #d4351c/#00703c set — avoid mixing eras
- Don't put more than one primary action on a page

## Accessibility notes

- The system is built to WCAG 2.2 AA as a legal requirement (UK Public Sector Bodies Accessibility Regulations 2018); every published component is audited, including for touch-target and focus-appearance criteria
- Focus states must keep a 3:1 contrast change and never rely on colour alone — the yellow/black pair delivers ~16:1 against the focused text
- Text #0b0c0c on white is 20.4:1; link #1a65a6 on white passes AA at 5.4:1; all palette pairings are published with contrast guidance

## Reference sites

- GOV.UK Design System: https://design-system.service.gov.uk
- GOV.UK colour guidance: https://design-system.service.gov.uk/styles/colour/
- GOV.UK Frontend (source of truth for tokens): https://github.com/alphagov/govuk-frontend

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

Install this skill

unzip govuk-design-system.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/govuk-design-system.json

Settings → Capabilities → Skills → Upload skill → govuk-design-system.zip