CorrectByDesign
A standard for agent-ready design systems Text and diagrams CC BY 4.0
← The Index
System 1 of 10
Ghost Foundation (non-profit; HQ jurisdiction unverified) · React, inside the product
Pinned 2026-09-09

Ghost (Shade + Admin X Design System).

Ghost's own token layer is the strongest measured here: colour and size values overwhelmingly resolve to a token, and dark mode is generated rather than hand-maintained. That discipline carries into the apps that consume it, helped by a skill that routes an agent to the right page template rather than leaving it to invent one. It was not trialled, because the package it ships was never published to npm. Measured at apps/shade.

1Scores

What the instrument measured.

10Single source · systematic693 distinct token(s) across 33 sources; 91% of colour/size references in system source resolve to a token; dark-mode handling is generated.
9Legibility · systematic91 of the 108 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.
9Adherence · systematic4026 of 4279 application file(s) gated against the design system's own contract; 87.5% of style declarations resolve to a token.
9.3Mean 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
TrialNot trialled
2What the instrument read

Measured against a pinned commit.

Repository
TryGhost/Ghost
Revision
6a11b45a82d9, committed 2026-09-08
System directory
apps/shade (@tryghost/shade)
Components found
108, of which 91 carry documentation and 82 have a colocated doc artifact
Agent context
2 context files, 19 skills
Tokens
693 distinct, across 33 sources (33 authored); dark mode generated
Adherence surface
4,279 files outside the system, graded first-party: apps/admin and apps/activitypub.
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 source10
175 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 175 of 1890 total colour/size references in system source (9.3%), so an agent copying that file as a pattern copies the hardcoding along with it.

  • apps/shade/src/components/patterns/color-picker.tsx:138 hsl(
  • apps/shade/src/components/ui/loading-indicator.tsx:22 16px
  • apps/shade/.storybook/shade-theme.tsx:14 #30CF43
33 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.

  • apps/shade/tailwind.theme.css css, 305 token(s)
  • apps/ember-admin/app/styles/patterns/global.css css, 141 token(s)
  • apps/shade/theme-variables.css css, 101 token(s)
Legibility9
17 undocumented componentsmajor

Some components carry no documentation an agent could find. That is 17 of the 108 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.

  • apps/shade/src/app.ts
  • apps/shade/src/docs/showcase/breakpoint-table.tsx
  • apps/shade/src/components/ui/code-editor-view.tsx
Adherence9
920 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.

  • apps/admin/src/settings/site/theme/theme-code-editor-modal.tsx:280 #c8ccd3
  • apps/portal/src/components/pages/gift-page.styles.js:4 #15212A
  • apps/activitypub/src/views/preferences/components/profile.tsx:50 rgba(
13 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 13 of the 363 component names the design system exports, so an agent importing that name by convention can silently get the wrong implementation.

  • apps/admin-toolbar/src/icons.js:54 Icon
  • apps/admin-x-framework/src/api/config.ts DEFAULT
  • apps/admin/src/settings/providers/dialog-portal.tsx:19 DialogPortal
255 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 255 of 906 total uses of a replaceable element (28.1%), so its styling and behaviour can drift independently of the system.

  • apps/admin/src/settings/growth/offers/offers-index.tsx:110 <button>
  • koenig/kg-default-nodes/src/nodes/audio/audio-renderer.ts:86 createElement("button")
  • apps/comments-ui/src/components/content/context-menus/admin-context-menu.tsx:67 <button>
4The trial

Not trialled.

The trial requires a system that can be installed from its own documentation into a clean scaffold. This one cannot be, because @tryghost/shade was never published to npm. The system is consumable only inside the Ghost repository, so it cannot be installed from its own documentation into the trial scaffold. It keeps its row in the static index with that reason stated, per the standing rule.

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.