# GOV.UK Design System

> `govuk@1.0.0`

GOV.UK is the unified service-delivery surface for UK central government, maintained by the Government Digital Service (GDS). The brand is austere by design: GOV.UK Black (#0B0C0C) ink on a white or pale-blue (#F4F8FB) template, GOV.UK Blue (#1D70B8) for links and the brand stripe, and a signature GOV.UK Yellow (#FFDD00) focus indicator that is a non-negotiable accessibility affordance across every form, button, and link on every central government service. Typography on the live GOV.UK estate is GDS Transport (a proprietary GDS-commissioned typeface descended from the Department for Transport's road-signage face); this atom substitutes Inter as the open-source rendering proxy and documents the substitution.


**Tags:** `govuk`, `gds`, `government`, `civic`, `design-system`, `light-first`, `accessibility`

## Atoms

### Palette

**GOV.UK Design System** · `govuk@1.0.0` · MIT (code) / Open Government Licence v3.0 (content)

> The GOV.UK Design System colour palette as published by the Government Digital Service (GDS). The palette is built around GOV.UK Black (#0B0C0C) for ink and GOV.UK Blue (#1D70B8) for the brand link colour, with a yellow focus state (#FFDD00) that is the signature accessibility-driven affordance on every UK central-government service surface. Functional roles (link, link-hover, link-visited, error, success, border, focus, template-background, surface) are published alongside an 11-hue "web palette" (blue, green, teal, purple, magenta, red, orange, yellow, brown, black, white) for chart and illustration use. Light-first; the system targets WCAG 2.1 AA on the GOV.UK template background. 

### Fonts

| Role | Font | License | Classification |
|------|------|---------|----------------|
| `heading` | **Inter** `(inter@1.0.0)` | OFL-1.1 | sans-serif |
| `body` | **Inter** `(inter@1.0.0)` | OFL-1.1 | sans-serif |
| `mono` | **Roboto Mono** `(roboto-mono@1.0.0)` | Apache-2.0 | monospace |

## Swatches

| ID | Name | Value |
|----|------|-------|
| `text` | Text | `#0B0C0C` |
| `secondary-text` | Secondary Text | `#484949` |
| `link` | Link | `#1A65A6` |
| `link-hover` | Link Hover | `#0F385C` |
| `link-visited` | Link Visited | `#54319F` |
| `link-active` | Link Active | `#0B0C0C` |
| `border` | Border | `#CECECE` |
| `input-border` | Input Border | `#0B0C0C` |
| `hover` | Hover | `#CECECE` |
| `focus` | Focus | `#FFDD00` |
| `focus-text` | Focus Text | `#0B0C0C` |
| `error` | Error | `#CA3535` |
| `success` | Success | `#0F7A52` |
| `brand` | Brand | `#1D70B8` |
| `body-background` | Body Background | `#FFFFFF` |
| `template-background` | Template Background | `#F4F8FB` |
| `surface-background` | Surface Background | `#F4F8FB` |
| `surface-text` | Surface Text | `#0B0C0C` |
| `surface-border` | Surface Border | `#8EB8DC` |
| `web-blue` | Web Blue | `#1D70B8` |
| `web-green` | Web Green | `#0F7A52` |
| `web-teal` | Web Teal | `#158187` |
| `web-purple` | Web Purple | `#54319F` |
| `web-magenta` | Web Magenta | `#CA357C` |
| `web-red` | Web Red | `#CA3535` |
| `web-orange` | Web Orange | `#F47738` |
| `web-yellow` | Web Yellow | `#FFDD00` |
| `web-brown` | Web Brown | `#99704A` |
| `web-black` | Web Black | `#0B0C0C` |
| `web-white` | Web White | `#FFFFFF` |

## Mode role mappings

### Light mode

| Role | Swatch | Hex |
|------|--------|-----|
| `background` | `body-background` | `#FFFFFF` |
| `surface` | `template-background` | `#F4F8FB` |
| `surface-elevated` | `body-background` | `#FFFFFF` |
| `text-primary` | `text` | `#0B0C0C` |
| `text-secondary` | `secondary-text` | `#484949` |
| `text-tertiary` | `secondary-text` | `#484949` |
| `primary` | `brand` | `#1D70B8` |
| `primary-hover` | `link-hover` | `#0F385C` |
| `accent` | `focus` | `#FFDD00` |
| `accent-hover` | `focus` | `#FFDD00` |
| `warning` | `web-orange` | `#F47738` |
| `warning-hover` | `web-orange` | `#F47738` |
| `error` | `error` | `#CA3535` |
| `success` | `success` | `#0F7A52` |
| `border` | `border` | `#CECECE` |

### Dark mode

| Role | Swatch | Hex |
|------|--------|-----|
| `background` | `text` | `#0B0C0C` |
| `surface` | `text` | `#0B0C0C` |
| `surface-elevated` | `secondary-text` | `#484949` |
| `text-primary` | `body-background` | `#FFFFFF` |
| `text-secondary` | `border` | `#CECECE` |
| `text-tertiary` | `border` | `#CECECE` |
| `primary` | `web-blue` | `#1D70B8` |
| `primary-hover` | `web-blue` | `#1D70B8` |
| `accent` | `focus` | `#FFDD00` |
| `accent-hover` | `focus` | `#FFDD00` |
| `warning` | `web-orange` | `#F47738` |
| `warning-hover` | `web-orange` | `#F47738` |
| `error` | `error` | `#CA3535` |
| `success` | `success` | `#0F7A52` |
| `border` | `secondary-text` | `#484949` |

## Brand semantic roles

### Colors

| Role | Swatch | Hex |
|------|--------|-----|
| `identity` | `body-background` | `#FFFFFF` |
| `on-identity` | `text` | `#0B0C0C` |
| `primary` | `brand` | `#1D70B8` |
| `primary-hover` | `link-hover` | `#0F385C` |
| `accent` | `focus` | `#FFDD00` |
| `accent-hover` | `focus` | `#FFDD00` |
| `mark` | `text` | `#0B0C0C` |
| `success` | `success` | `#0F7A52` |
| `warning` | `web-orange` | `#F47738` |
| `error` | `error` | `#CA3535` |
| `text-primary-light` | `text` | `#0B0C0C` |
| `text-primary-dark` | `body-background` | `#FFFFFF` |
| `background-light` | `body-background` | `#FFFFFF` |
| `background-dark` | `text` | `#0B0C0C` |
| `surface-light` | `template-background` | `#F4F8FB` |
| `surface-dark` | `text` | `#0B0C0C` |
| `text-secondary-light` | `secondary-text` | `#484949` |
| `text-tertiary-light` | `secondary-text` | `#484949` |
| `border-light` | `border` | `#CECECE` |

### Typography

| Role | Font role key |
|------|---------------|
| `display` | `heading` |
| `prose` | `body` |
| `code` | `mono` |

## Rules

### 🛑 error (7)

#### `colorChoice` → `roles.colors.accent`

- **allowed:** focus
- **forbidden:** brand, error, success, web-orange, web-purple

> GOV.UK Yellow (#FFDD00) is the documented focus indicator across every central government service surface, paired with GOV.UK Black ink and an accompanying focus-bottom border. Substituting the brand blue or any other hue for the focus state breaks visual parity with the rest of GOV.UK and fails the system's keyboard-accessibility contract (WCAG 2.1 Success Criterion 2.4.7). 

#### `colorChoice` → `roles.colors.primary`

- **allowed:** brand, link
- **forbidden:** web-magenta, web-purple, web-orange, web-teal

> GOV.UK Blue (#1D70B8) is the documented link / brand colour. The other "web palette" hues exist for chart, illustration, and category-distinction use and MUST NOT stand in for the primary link role — users navigating GOV.UK rely on blue-means-link recognition built up across thousands of service pages. 

#### `contrastRatio` → `text-primary`

- **against:** `background`
- **minRatio:** `4.5`
- **standard:** `WCAG-AA`

> GOV.UK targets WCAG 2.1 Level AA at minimum across every central-government service, in line with the Public Sector Bodies Accessibility Regulations 2018. GOV.UK Black (#0B0C0C) on white clears AA at ~19:1; on the pale-blue template (#F4F8FB) it clears AA at ~18:1. 

#### `accessibilityRequirement` → `*`

- **standard:** `WCAG-AA`
- **criterion:** `2.4.7`

> WCAG 2.1 Success Criterion 2.4.7 (Focus Visible) — Level AA. The signature GOV.UK Yellow focus state exists specifically to satisfy this criterion. Any GOV.UK-styled consumer that suppresses or substitutes focus indicators fails the regulation that drove the focus state's existence. 

#### `forbiddenTreatment` → `logo`

- **treatments:** stretched, rotated, recolored, drop-shadow, gradient-fill, outlined, tilted, on-busy-photo

> The GOV.UK logotype is Crown copyright and its use is restricted to UK central-government services. The mark MUST render in its supplied form (black wordmark on a white field, or white on the GOV.UK Black header bar) with no decorative treatment. Non-government consumers of this brand atom should substitute their own identifier rather than alter the GOV.UK mark. 

#### `fontPairing` → `typography.display`

- **requires:** `prose`
- **minSizeRatio:** `1.5`

> GOV.UK's published type scale steps from 16px body up through 19px lede, 24px small heading, 36px medium heading, and 48px+ display heading — every step preserving at least a 1.5× ratio against the 16px body anchor. Display-at-body-size collapses the hierarchy that service-page scannability depends on. 

#### `contextRestriction` → `roles.colors.error`

- **forbiddenContexts:** confirmation, completion, data-viz-positive
- **allowedContexts:** error-state, destructive-action, validation-failure

> GOV.UK Red (#CA3535) is reserved for the error-summary and validation patterns. Reusing it for confirmation inverts the semantic contract that users navigating a GOV.UK form rely on — the red border / red link inside an error summary is the documented signal that something needs the user's attention before submission. 

### ⚠️ warning (1)

#### `enumMembership` → `typography.heading.fontWeight`

- **allowed:** 400, 700

> GDS Transport, the live GOV.UK heading face, ships in two weights only (Light/Regular and Bold) and the published GOV.UK type ramp uses Regular and Bold exclusively. Constraining the substitute (Inter) to the same two weights preserves the typographic restraint of the live service surface. 

### 💡 recommendation (1)

#### `compositionConstraint` → `roles.colors.primary`

- **pairsWith:** body-background, template-background, text
- **doesNotPairWith:** web-purple, web-magenta, web-teal, web-orange

> GOV.UK Blue reads cleanly against the white body or pale template background; placing it adjacent to the other web-palette hues at equal weight produces chromatic competition that fights GOV.UK's restrained, hierarchy- first voice. The web-palette colours are for charts and illustrations, where they sit inside a frame and are legibly distinct without competing with brand blue. 

## Provenance

- **Source:** <https://design-system.service.gov.uk/styles/colour/>
- **License:** `MIT (code) / Open Government Licence v3.0 (content)`
- **Attribution:** GOV.UK Design System, maintained by the Government Digital Service (Cabinet Office, Crown copyright). govuk-frontend code MIT-licensed; design-system guidance content under the Open Government Licence v3.0. "GOV.UK," the GOV.UK logotype, and GDS Transport are reserved — GDS Transport in particular is a proprietary GDS-commissioned typeface and is NOT publicly redistributable. Use of the GOV.UK name and logotype is restricted to UK central-government services. 
- **Imported:** `2026-05-19`
- **Notes:** Typography substitution: GDS Transport is proprietary and is not present in this catalogue's fonts/ directory. This brand references inter@1 as the open-source heading/body face and roboto-mono@1 for code. Consumers shipping an actual UK central-government service MUST license and use GDS Transport via govuk-frontend's distribution; this atom serves consumers rendering GOV.UK-styled comparators, mock-ups, or third-party documentation where Transport licensing does not apply. 

---

*Generated by the brand-atoms converter. Source: `govuk@1.0.0` from the encyclopedia.*