IBM Carbon in the index · Correct by Design

1Scores

What the instrument measured.

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

10Legibility · systematic344 of the 350 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.

5Adherence · substantial1054 of 1187 application file(s) gated against the design system's own contract; 4.3% of style declarations resolve to a token.

6Mean 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 / cold9 / 4 completeness
8 / 2 legibility
3 / 5 constraint
7 / 8 interaction

2What the instrument read

Measured against a pinned commit.

Repository: carbon-design-system/carbon
Revision: 474482a993df, committed 2026-09-08
System directory: packages/react (@carbon/react)
Components found: 350, of which 344 carry documentation and 226 have a colocated doc artifact
Agent context: 2 context files, 0 skills
Tokens: 268 distinct, across 70 sources (70 authored); dark mode unobservable
Adherence surface: 1,187 files outside the system, graded own-docs-site: the docs site, examples and Storybook.

carbon-design-system/carbon/

1├── AGENTS.md agent context · 2 files, 0 skills · read before the code

├── docs/ 290 doc artifacts in the repository

├── (70 Sass sources across the monorepo) 268 tokens; dark mode unobservable

└── packages/react/ measured here

1 ├── AGENTS.md

2 ├── src/components/ 350 found, 344 documented, 226 with a colocated doc artifact

3 ├── (Storybook, 2 configs)

□ └── docs site, examples & Storybook 1,187 files · adherence measured here, 4.3% of declarations resolve to a token

skills/ · none 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 source3

412 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 412 of 412 total colour/size references in system source (100%), so an agent copying that file as a pattern copies the hardcoding along with it.

packages/react/src/components/FullPageError/assets/ErrorGenericSVG.tsx:26 #F3F3F3
packages/react/src/components/FullPageError/assets/Error403SVG.tsx:26 #F3F3F3
packages/react/src/components/FullPageError/assets/Error404SVG.tsx:24 #F3F3F3

70 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/type/scss/_styles.scss sass, 59 token(s)
packages/styles/scss/components/tag/_tokens.scss sass, 41 token(s)
packages/styles/scss/theme/_theme.scss sass, 17 token(s)

Legibility10

6 undocumented componentsmajor

Some components carry no documentation an agent could find. That is 6 of the 350 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/examples/custom-data-table-state-manager-vite/src/App.jsx
packages/react/.storybook-v12/manager-head.html
packages/react/examples/custom-data-table-state-manager-vite/src/misc/index.js

Adherence5

402 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/colors/src/colors.ts:8 #000000
packages/colors/examples/colors-explorer/src/pages/index.js:239 #e0e0e0
packages/themes/examples/theme-tokens-dtcg/src/pages/index.js:109 rgba(

10 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 10 of the 437 component names the design system exports, so an agent importing that name by convention can silently get the wrong implementation.

examples/class-prefix/src/App.jsx:13 App
examples/light-dark-mode/src/app/page.js:23 Home
packages/feature-flags/src/index.ts:29 FeatureFlags

38 raw HTML elements used where a system component existsmajor

Some screens render a raw HTML element in place of the system component built for it. This happens in 38 of 110 total uses of a replaceable element (34.5%), so its styling and behaviour can drift independently of the system.

packages/themes/examples/theme-tokens-dtcg/src/pages/index.js:569 <select>
packages/colors/examples/colors-explorer/src/pages/index.js:414 <select>
packages/motion/examples/motion-tokens-dtcg/src/pages/index.js:333 <select>

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 18 min · 1 file read · completed

5Constraint

2Legibility

4Completeness

8Interaction

Informed arm, draw 117 min · 8 files read · completed

3Constraint

8Legibility

9Completeness

7Interaction

What setting it up found

informational

The README states Dart Sass is required but gives no install command for it, delegating to eight external per-bundler guides.

Handling: Followed the linked 'Vite with Sass' path, which is this scaffold's bundler: installed the `sass` package as a dev dependency. Recorded because a setup that requires leaving the package's own documentation to become installable is a legibility finding, and legibility is a scored dimension.

informational

The README requires "skipLibCheck": true because not all components are typed, and links to an open TypeScript-adoption project.

Handling: Applied as documented. Recorded because it means the system cannot be consumed under strict library type-checking, which bears on the constraint dimension when the deep audit reaches it.

cosmetic

The README's Sass configuration note points at ../styles/docs/sass.md, a monorepo-relative path that does not resolve from the installed package.

Handling: No action needed; the default configuration worked without touching includePaths. Recorded as a broken documentation reference in the published package.

Screens generated

Arm	Draw	Date	Duration	Files read	Outcome
cold	1	2026-08-14	8 min	1	completed
informed	1	2026-08-14	17 min	8	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 (41 hardcoded dimensions). Volume: 1, 41 in total. The worse of the two is the score.

2Legibility in practiceRead the scaffold README and listed the package's exports with `require`; never Carbon's README or docs. Used Toggle, RadioTile, Select, InlineLoading, ToastNotification and Tag from the listing.

4CompletenessTime range and timezone: 4. Start, end and timezone as three Carbon Selects. Carbon ships TimePicker; the cold agent did not find it and did not say a time control was missing. Usage meter: 4. A custom role=meter bar with an inline width, styled with Carbon tokens. Never said Carbon lacks a meter (it does; the informed run found the same).

8Interaction8 of 10 checklist items observed.

Counted: 0 hardcoded colours, 41 hardcoded dimensions, 0 raw elements where a component exists, 51 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: 14 toggles, 0 time inputs, 3 selects reached, save not reached, focus visible on 100%)
Composition: Q1: content touches a viewport edge; Q2: no visible gap between sections; Q3: a unit sits on no surface; Q4: a label floats from its control. The most broken render in the field: toggle labels overprint each other across the channel matrix (Q4), the four settings areas share one bordered container with no gap between them (Q2, Q3), and the demo checkbox row ends within 19px of the page bottom (Q1).

Informed arm, draw 1 · the working

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

8Legibility in practiceRead the package README head, the SCSS breakpoint mixins and the TimePicker types, then built with Toggle, RadioButtonGroup, TimePicker, Select, ProgressBar, InlineLoading and ToastNotification. Follows the documentation in the main.

9CompletenessTime range and timezone: 10. Carbon's TimePicker and Select; the system anticipated the gap. Usage meter: 8. Acknowledged explicitly: 'the correct accessible primitive for a gauge is role=meter, which Carbon doesn't ship', after finding ProgressBar announced 'Loading' to screen readers. Composed a meter from Carbon tokens instead.

7Interaction7 of 10 checklist items observed.

Counted: 1 hardcoded colours, 23 hardcoded dimensions, 0 raw elements where a component exists, 48 uses of the system's components, 0 foreign UI imports, 0 invented names.
Read: 1 documentation reads, 24 reads of the package's source or types.
Checklist: I1 yes · I2 yes · I3 yes · I4 no · I5 no · I6 yes · I7 yes · I8 yes · I9 yes · I10 noI4: usage meter reads the numbers, distinct past 80%, not observed (The mock loads at 1,240 of 5,000 (25%). The over-80% presentation exists in the source (warning, then error at 100%) but is not observable on the render, and the checklist scores what is observable.). I5: unsaved changes indicated, not observed (probe: changed a control; unsaved wording did not appear). I10: every control keyboard reachable, not observed (probe tab walk: 13 toggles, 0 time inputs, 1 selects reached, save not reached, focus visible on 100%)
Composition: Six no's: conforms. Clean stacked tiles on the Carbon layer surface, sticky save bar, page inset. The mock usage is 25%, so the over-limit presentation is not on the render.

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.