Primer React in the index · Correct by Design

1Scores

What the instrument measured.

3Single source · partial139 distinct token(s) across 30 sources; 0% of colour/size references in system source resolve to a token; dark-mode handling is patched.

8Legibility · strong148 of the 223 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.

4Adherence · partial64 of 66 application file(s) gated against the design system's own contract; 0% of style declarations resolve to a token.

5Mean of 3of 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 / cold7 / 7 completeness
2 / 2 legibility
3 / 5 constraint
8 / 8 interaction

2What the instrument read

Measured against a pinned commit.

Repository: primer/react
Revision: dc8387f4fa07, committed 2026-09-04
System directory: packages/react (@primer/react)
Components found: 223, of which 148 carry documentation and 172 have a colocated doc artifact
Agent context: 1 context file, 15 skills
Tokens: 139 distinct, across 30 sources (30 authored); dark mode patched
Adherence surface: 66 files outside the system, graded own-docs-site: the docs site and examples. GitHub.com itself isn't in this repository.

primer/react/

1├── (agent context file) agent context · 1 file, 15 skills · read before the code

2├── .github/skills/ 15 skills

└── packages/react/ measured here

3 ├── src/ 223 components found, 148 documented, 172 with a colocated doc artifact

4 ├── .storybook/

5 ├── (30 CSS sources) 139 tokens; dark mode patched in a separate file from the light values

□ └── docs site & examples 66 files · own-docs-site, not github.com · adherence measured here, 0% of declarations resolve to a token

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 source3

3,551 hardcoded colour and size values in component sourcemajor

The design system's own component source hardcodes colour and size values instead of referencing its own tokens. This happens in 3551 of 3555 total colour/size references in system source (99.9%), so an agent copying that file as a pattern copies the hardcoding along with it.

packages/react/src/legacy-theme/ts/color-schemes.ts:11 rgba(
packages/react/src/theme.ts:9 544px
packages/react/src/Overlay/constants.ts:2 192px

30 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/react/src/PageLayout/PageLayout.module.css css, 23 token(s)
packages/react/src/PageHeader/PageHeader.module.css css, 15 token(s)
packages/react/src/Token/IssueLabelToken.module.css css, 13 token(s)

1 theme maintained by handcritical

Dark mode is patched in a separate file from where the light values are declared, rather than generated from the same source, so the two can drift apart without anything flagging it.

Legibility8

75 undocumented componentsmajor

Some components carry no documentation an agent could find. That is 75 of the 223 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/react/.storybook/src/accessibility-tool.tsx
packages/react/src/utils/types/AriaRole.ts
packages/react/babel-defines.cjs

Adherence4

7,063 hardcoded colour valuesmajor

The application hardcodes colour values instead of using the design system's own tokens, so an agent editing nearby code has no signal that a token exists and will likely repeat the pattern.

packages/styled-react/src/legacy-theme/ts/color-schemes.ts:10 rgba(255,255,255,0)
packages/styled-react/src/legacy-theme/ts/colors/light_high_contrast.ts:2 rgba(255,255,255,0)
packages/styled-react/src/legacy-theme/ts/colors/light_colorblind.ts:2 rgba(255,255,255,0)

4 components that duplicate one the system already shipscritical

The application defines its own component under the same name as one the design system already ships. This happens for 4 of the 242 component names the design system exports, so an agent importing that name by convention can silently get the wrong implementation.

examples/theming/src/app/components/PageHeader/PageHeader.tsx:3 PageHeader
packages/styled-react/src/components/BaseStyles.tsx:70 BaseStyles
packages/styled-react/src/components/FeatureFlaggedTheming.tsx:2 ThemeProvider

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 112 min · 7 files read · completed

5Constraint

2Legibility

7Completeness

8Interaction

Informed arm, draw 115 min · 12 files read · completed

primer-react-informed-r1 at 1280px — 1280px

primer-react-informed-r1 at 390px — 390px

3Constraint

2Legibility

7Completeness

8Interaction

What setting it up found

cosmetic

The README's root-wiring snippet names the wrapper component RootLayout, a Next.js App Router idiom, without stating the framework assumption.

Handling: Mapped to this scaffold's equivalent root wrapper (src/providers.tsx, already mounted around <App /> by main.tsx). A faithful adaptation, not a deviation: the documented structure (BaseStyles wrapping the app) is preserved exactly.

material

The README's documented setup imports the light theme only ('by default we are including the light theme below'), while simultaneously instructing that the <html> element carry data-dark-theme="dark" and data-color-mode="auto". Following the documentation literally therefore yields a project that advertises automatic dark mode via its html attributes but never loads the dark theme stylesheet.

Handling: Followed literally: only the light theme is imported, exactly as documented. Not silently corrected. If a generated screen mis-renders in dark mode, that is a finding attributable to Primer's own documented setup rather than to the agent, and it must be reported as such.

informational

The README links to primer.style for anything beyond installation and does not document composition, layout primitives, or page structure in the package itself.

Handling: No action. Recorded because the informed arm's prompt points the agent at the system's documentation, and what that documentation does and does not contain is precisely what the two-arm design measures.

Screens generated

Arm	Draw	Date	Duration	Files read	Outcome
cold	1	2026-08-14	12 min	7	completed
informed	1	2026-08-14	15 min	12	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

1Constraint in practiceSet by the volume reading. Kinds: 5, violations of one kind (69 hardcoded dimensions). Volume: 1, 69 in total. The worse of the two is the score.

2Legibility in practiceRead the package's components.json and the dist type definitions and source of ToggleSwitch, ProgressBar, Banner and SegmentedControl; never a README or docs page.

7CompletenessTime range and timezone: 4. TextInput type=time and Select; composed from the system, absence never named. Usage meter: 10. Primer's ProgressBar with a Banner past 80%. Anticipated.

8Interaction8 of 10 checklist items observed.

Counted: 0 hardcoded colours, 69 hardcoded dimensions, 0 raw elements where a component exists, 71 uses of the system's components, 0 foreign UI imports, 0 invented names.
Read: 0 documentation reads, 25 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: 2 toggles, 2 time inputs, 1 selects reached, save not reached, focus visible on 100%)
Composition: Six no's: conforms. Bordered cards, inset, a sticky save bar; a demo checkbox below the last card with ground around it.

Informed arm, draw 1 · the working

3Constraint in practiceSet by both readings. Kinds: 3, violations of two kinds (18 hardcoded dimensions, 1 raw elements where a component exists). Volume: 3, eleven to twenty in total. The worse of the two is the score.

2Legibility in practiceAn informed run that never opened the documentation: read the scaffold README, then the dist type definitions and the primitives CSS. Built from types.

7CompletenessTime range and timezone: 4. Native time inputs and Select; composed, silent. Usage meter: 10. ProgressBar with the colour changed past 80%, plus Banner. Anticipated.

8Interaction8 of 10 checklist items observed.

Counted: 0 hardcoded colours, 18 hardcoded dimensions, 1 raw elements where a component exists, 72 uses of the system's components, 0 foreign UI imports, 0 invented names.
Read: 0 documentation reads, 21 reads of the package's source or types.
Checklist: I1 yes · I2 no · I3 yes · I4 yes · I5 yes · I6 yes · I7 yes · I8 yes · I9 yes · I10 noI2: bundling choice is exclusive, not observed (probe: no exclusive control found). I10: every control keyboard reachable, not observed (probe tab walk: 5 toggles, 0 time inputs, 0 selects reached, save not reached, focus visible on 100%)
Composition: Q2: no visible gap between sections. Dense: the four bordered sections sit with only a few pixels between them and the matrix rows are tight (Q2). Segmented control for bundling. Sticky bar.

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.