GOV.UK Frontend in the index · Correct by Design

1Scores

What the instrument measured.

5Single source · substantial100 distinct token(s) across 23 sources; dark-mode handling is none.

9Legibility · systematic38 of the 39 components found in system source carry documentation in some form (a head comment, a colocated doc artifact, or a docs/ entry). Scored from what is in the repository. Documentation held outside it (e.g. Confluence, Notion, Figma) cannot be detected and is neither credited nor penalised.

not measuredAdherencefound 201 application source files (15 readable), but none import the design system, use one of its components, or carry a style declaration this instrument can read. Adherence is not scored rather than scored as clean: there is nothing here to adhere to or drift from.

7Mean of 2of measured

—Constraintnot computed by this instrument: scoring it requires parsing component APIs per framework, which is done in the deep audit of a single system rather than across a field

—Fidelitynot computed by this instrument: scoring it requires parsing component APIs per framework, which is done in the deep audit of a single system rather than across a field

—Completenessrequires a live agent run: a gap only exists relative to something someone tried to build

Trial · informed / cold4 / 4 completeness
10 / 2 legibility
4 / 3 constraint
10 / 8 interaction

2What the instrument read

Measured against a pinned commit.

Repository: alphagov/govuk-frontend
Revision: 6b7063b9cbf9, committed 2026-09-07
System directory: packages/govuk-frontend/src/govuk/components
Components found: 39, of which 38 carry documentation and 38 have a colocated doc artifact
Agent context: 0 context files, 0 skills
Tokens: 100 distinct, across 23 sources (22 authored); dark mode none
Adherence surface: 201 files outside the system, graded first-party: GDS's own review app. The public site, alphagov/frontend, is a separate repository and isn't scanned.

alphagov/govuk-frontend/

1├── (22 authored Sass sources, settings/ and components/) 100 tokens across 23 sources; dark mode none

2├── packages/govuk-frontend/src/govuk/components/ measured here

3 └── (39 component directories) 38 documented, 38 with a colocated doc artifact; HTML copied from the GOV.UK Design System website, no code component layer

└── packages/govuk-frontend-review/ GDS's own review app, built with Nunjucks; not readable by this instrument

no context file found

no skills found

3Findings

What the counts point at.

Each finding carries its count, its severity and up to three file references. A finding on a property that was not banded is still a finding; it is reported without a score.

Single source5

22 separate places tokens are declaredmajor

Design tokens are declared in more than one place in this repository's own authored source, so a value changed in one must be kept in agreement with the others by hand.

packages/govuk-frontend/src/govuk/settings/_colours-legacy-functional.scss sass, 17 token(s)
packages/govuk-frontend/src/govuk/settings/_measurements.scss sass, 11 token(s)
packages/govuk-frontend/src/govuk/settings/_typography-font.scss sass, 5 token(s)

Legibility9

1 undocumented componentmajor

Some components carry no documentation an agent could find. That is 1 of the 39 components found in system source, with no head comment on their own source, no colocated doc artifact matching their name, and no docs/ entry, so an agent must reverse-engineer their contract from implementation alone.

packages/govuk-frontend/src/govuk/components/password-input/macro.njk

1 agent context filemajor

There is no agent-facing context file (a CLAUDE.md, AGENTS.md, or similar) at the project root or inside the design system, so an agent starting cold has no map of how this system wants to be used.

4The trial

Built twice: cold, then informed.

Set up from its own documentation, in full, with every step that could not be followed recorded. Draw 1 of 3, judged; draws 2 and 3 pending.

Cold arm, draw 113 min · 9 files read · completed

govuk-frontend-cold-r1 at 1280px — 1280px

3Constraint

2Legibility

4Completeness

8Interaction

Informed arm, draw 18 min · 6 files read · completed

govuk-frontend-informed-r1 at 1280px — 1280px

govuk-frontend-informed-r1 at 390px — 390px

4Constraint

10Legibility

4Completeness

10Interaction

What setting it up found

structural

The README documents no component layer in code. Components exist as HTML markup on the GOV.UK Design System website, to be copied into a project, plus optional Nunjucks macros. Nothing is importable as a component from the installed package.

Handling: No action. This is the defining property of a framework-agnostic system rather than a defect, but it bears directly on the trial: the agent cannot import a Card or a Switch, so every structural decision is markup it writes itself. Recorded because it will shape how this system's screens compare with the React systems' screens.

informational

The README requires a Sass compiler to consume the styles but names no package and gives no bundler configuration, linking out to the Design System website for details.

Handling: Used Dart Sass, the compiler the wider ecosystem and GOV.UK's own tooling assume. Recorded as a legibility observation.

cosmetic

The README's JavaScript instructions describe copying govuk-frontend.min.js into the application and referencing it by path, which suits a server-rendered app with a static assets directory rather than a bundled ES-module build.

Handling: Used the documented module import form (`import { initAll } from 'govuk-frontend'`), which the same section documents immediately afterwards and which is the correct path for a bundler. No documented step was skipped.

Screens generated

Arm	Draw	Date	Duration	Files read	Outcome
cold	1	2026-08-14	13 min	9	completed
informed	1	2026-08-14	8 min	6	completed

Model: claude-opus-4-8. Generated under GitHub Actions isolation, the agent's own environment, with the frozen task text and no interaction. Files read is the number of repository files the agent opened, from its own transcript.

Cold arm, draw 1 · the working

2Constraint in practiceSet by the volume reading. Kinds: 3, violations of two kinds (4 hardcoded colours, 18 hardcoded dimensions). Volume: 2, twenty one to forty in total. The worse of the two is the score.

2Legibility in practiceRead package.json for the version and then spent its reads on headless-browser tooling; never the README or a component's documentation. Still used govuk- classes 97 times, from prior knowledge rather than from anything it opened.

4CompletenessTime range and timezone: 4. Native time inputs and a select in govuk- form markup; absence never named. Usage meter: 4. A custom role=progressbar with an inline width, a govuk-tag and warning-text. Composed, silent.

8Interaction8 of 10 checklist items observed.

Counted: 4 hardcoded colours, 18 hardcoded dimensions, 0 raw elements where a component exists, 97 uses of the system's components, 0 foreign UI imports, 0 invented names.
Read: 0 documentation reads, 3 reads of the package's source or types; went looking for documentation unprompted: no.
Checklist: I1 yes · I2 yes · I3 yes · I4 yes · I5 no · I6 yes · I7 yes · I8 yes · I9 yes · I10 noI5: unsaved changes indicated, not observed (probe: changed a control; unsaved wording did not appear). I10: every control keyboard reachable, not observed (probe tab walk: 12 toggles, 2 time inputs, 1 selects reached, save not reached, focus visible on 100%)
Composition: Q3: a unit sits on no surface. Two-column layout with a sticky usage card; groups separated by rules, no surfaces (Q3 as the contract states it; that is GOV.UK's own idiom). Checkbox and radio labels render in a serif fallback, so the system's type is not applied to them.

Informed arm, draw 1 · the working

4Constraint in practiceSet by both readings. Kinds: 4, violations of two kinds (1 hardcoded colours, 8 hardcoded dimensions). Volume: 4, six to ten in total. The worse of the two is the score.

10Legibility in practiceRead the package README in full and the component directories (checkboxes, radios, notification banner, button, tag, error summary). The output follows them closely.

4CompletenessTime range and timezone: 4. Native time inputs and a select in a govuk fieldset; absence never named, though the agent noticed and fixed the inputs clipping AM/PM. Usage meter: 4. A custom role=progressbar with an inline width plus govuk-tag and warning-text. Composed, silent.

10Interaction10 of 10 checklist items observed.

Counted: 1 hardcoded colours, 8 hardcoded dimensions, 0 raw elements where a component exists, 122 uses of the system's components, 0 foreign UI imports, 0 invented names.
Read: 1 documentation reads, 8 reads of the package's source or types.
Checklist: I1 yes · I2 yes · I3 yes · I4 yes · I5 yes · I6 yes · I7 yes · I8 yes · I9 yes · I10 yesEvery item observed.
Composition: Q3: a unit sits on no surface. A recognisable GOV.UK page: header, beta banner, single column, groups separated by rules with no surfaces (Q3 per the contract; GOV.UK's idiom), save button at the end. The most idiomatic screen in the field.

Judged 2026-09-09 by an agent under authorisation; a second read is pending. Constraint from the counts, banded twice, on how many kinds of the system's rules the output broke and on how many times it broke them, with the worse of the two published (deviation of 2026-09-10). Legibility and completeness from the transcript and the source, interaction from the ten-item checklist, composition from the six contract questions. Hover a checklist item for its observation.

5Reproduce it

Clone the repository at the revision above, point the instrument at the system directory, and the same numbers come out. The field manifest, the run script and the full payload this page was built from are committed beside it. Methods.