Registry + tokens + MCP server · being packaged
Give your agents something real to build on.
Put the token source, component registry and MCP interface in the same codebase. Follow a working integration, diagnose what is missing, and rehearse failures before adapting the setup to your product.
or write to kir.zhukovsky@gmail.com — subject prefilled
A real customization, deliberate failure and rollback. No email or account.
Included in Agent-Ready Starter:
- Token source and eight controls
- MCP and context templates
- Integration diagnostics
- Failure and recovery exercises
- Trace the whole path
- From a semantic token to generated CSS, React components and the source your agent can retrieve.
- Check more than the happy path
- Integration diagnostics, a token rollback and an asynchronous form exercise expose concrete failure states. They do not certify an agent or your production app.
Kiryl Zhukouskimaintainer of the Agent-Ready Index — a dated, source-linked reference for 37 systems.
Agent-Ready Starter
or write to kir.zhukovsky@gmail.com — subject prefilled
Change the token. see what breaks.
Trace a concrete change through the system. This free exercise shows the kind of work the kit helps you carry forward.
Six-digit hex. Try #fbbf24 to expose a contrast failure.
Semantic action token
CSS custom property
Button surface
Pass: 6.29:1 against white text
Required here: 4.5:1:root {
--ds-color-action-solid-bg: #4f46e5;
}This browser preview checks one foreground/background pair. It does not run the package build or test an agent. The downloadable build checks nine declared pairs in light and dark; its walkthrough verifies failure and rollback.
A working build is only one part of the integration.
The adoption companion traces what gets copied, what gets generated and what the MCP server actually returns. Then an asynchronous form exercise makes pending, failure, retry and confirmed success explicit.
The diagnostic runs local checks and reports their limits. Controller tests do not establish your backend's persistence, authorization or a model's execution quality.
Source → installation → behavior
- Compare generated CSS and retrieved component/token content with the files on disk.
- Check copied registry targets, direct CSS imports and declared dependencies. A pass is scoped to the checks performed.
- Rehearse an invalid token, a failed save and a retry. Preserve entered values and distinguish an uncertain response from confirmed persistence.
node diagnose.mjs
node --test diagnose.test.mjs \
examples/async-settings-flow.test.mjsRead the first integration exercise →A guide from the first copy to the first release.
Nine designed pages connect source ownership, token updates, agent instructions, failed saves and release evidence. The editable Markdown and an offline HTML reader come with the PDF.
These previews are exported from the files included in the download. Open either page to inspect the type and layout.
A registry, a token build and an MCP server. twelve registry targets, plus an integration map, diagnostics and worked failure exercises.
- 01
8 components — button through switch
Button, input, field, card, badge, alert, dialog and switch as shadcn-spec registry items. Each item declares its files and dependencies; the full registry has 12 install targets.
- 02
139 tokens — W3C DTCG, three tiers
$value, $type and a $description on every leaf, {dot.path} aliases between the tiers, and 28 dark values carried in $extensions.
- 03
3 tools — a stdio MCP server that runs
list_components, get_component and get_tokens read the actual files. The diagnostic compares returned source and tokens with disk and checks an unknown-component refusal. Implemented MCP revision: 2025-06-18.
- 04
Agent context and an adoption decision
llms.txt and DESIGN.md describe the real kit. ADOPTION-DECISION.md records canonical sources, ownership, persistence rules and test evidence. TODO markers identify decisions your team must make.
- 05
2 mappings — Figma Code Connect
button.figma.tsx is the straightforward case. field.figma.tsx is the one worth reading: one Figma component with toggles, one React wrapper composing an Input, absorbed in the mapping.
- 06
0 dependencies — the build gates itself on contrast
Plain Node turns the DTCG file into tokens.css, checks 9 declared text pairs against 4.5:1 in both themes, and fails below the threshold. A disposable rehearsal proves failure and exact rollback.
- 07
An integration diagnostic with inspectable evidence
Read-only checks cover generated output, registry targets and actual MCP retrieval. Optional consumer checks inspect copied files, declared dependencies, direct CSS imports and a chosen built stylesheet.
- 08
A save flow that makes failure explicit
A React form, dependency-free state controller and seven acceptance cases cover validation, pending, retry, duplicate saves and late responses. Inject your own save adapter; the kit supplies no backend.
The error message is part of the product.
Ask the kit's MCP server for a component that doesn't exist and the refusal is legible: the error names every component that does exist, then tells the model not to invent one. That message is the mechanism — it turns “add a toast” from an improvisation into a decision someone gets to make.
get_component · name='toast'
No registry item named 'toast'.
Available: cn, tokens, button, input, field, card, badge, alert, dialog, switch.
Do not create a new component — pick one of these or ask the user.Verbatim output. The error is written for the model, not for a log file: it names all 10 registry items and asks the agent to resolve the gap explicitly. It cannot force the agent to follow that instruction.
How the lookup changes the task
The two paths below illustrate possible failure modes and the information the kit exposes. They are not recorded model outputs or a measured success comparison.
Add a destructive Delete button that matches our design system.
The contract may be missing from context.
- 01Without a canonical component map in context, an agent may use unrelated documentation or infer the available controls.
- 02A generated button might use raw palette and spacing utilities instead of your token roles. It can render while bypassing the design system.
- 03An assumed variant such as destructive can differ from the kit's danger API. TypeScript may catch it; copied untyped markup may not.
- 04Compilation alone does not prove that the screen uses your intended components or handles failure states. A reviewer needs the contract and interaction evidence.
The source is available to inspect.
- 01list_components returns the registry — 10 items, 8 of them components — with real metadata: button carries dependencies @radix-ui/react-slot and class-variance-authority, and installs to components/ui/button.tsx.
- 02The button entry names the closed variant set in its description: solid, subtle, outline, ghost, danger — the name is in text the agent just fetched.
- 03get_component returns the actual source, where danger resolves to bg-[var(--ds-color-danger-solid-bg)]. There is no hex for the model to choose.
- 04get_tokens with format="flat" gives a name→value map, so if no token fits, that is a visible fact rather than an improvised colour.
Inspect a public registry and the integration workflow.
The site's registry, public HTTP MCP endpoint and Agent-Ready Index are free to inspect. The $99 Starter is a separate downloadable reference with a smaller local stdio server and worked adoption materials; the public service is not the packaged transport.
Browse the live registry- /r — this site's own components, served as a shadcn-spec registry index.
- /api/mcp — this site's MCP server answering on this domain over HTTP.
- /ai-ready/systems — the Agent-Ready Index, 37 public systems scored on the five signals, audited 2026-09-04.
- The kit ships a smaller, generic version of that MCP pattern: 3 tools, 0 dependencies, run from your repo over stdio.
- What the $99 adds: owned source, an installation diagnostic, async save exercise, token rollback and adoption decision record.
Who it's for, and who should skip it.
The 8 components are reference implementations of the pattern — registry entry, token discipline, MCP exposure — meant to be copied, restyled, and owned. What the kit wires is the machine-readable half of the system you already have.
You have the components and none of the wiring
Your Button ships. A canonical token source, queryable component contracts and integration evidence are missing. The kit provides a working pattern to adapt to the system you already own.
You want to own the code
Copy the 12 registry targets and the companions you need. Downloads have a versioned manifest; you review later source changes and maintain your app's locked dependencies.
Tokens alone would earn the hour
tokens.css is 139 plain custom properties. Copy it in, import it in the root layout, and the framework question never comes up.
Your agents keep inventing values
get_tokens and get_component expose the actual token paths and prop APIs. The agent brief asks for those lookups before changes, and for a record of what still needs human review.
- You already ship an MCP server, DTCG tokens, and a registry.
- You want a component library. Eight ship, with no roadmap toward forty.
- You want a hosted dependency with automatic source upgrades. This is code you maintain.
- You need a select, table, or date picker today. The kit names those gaps.
Score your own system first on the Agent-Ready Index — 37 public systems, audited 2026-09-04.
Not on sale yet.
The kit is built and it runs; the checkout isn't wired yet. The button below opens an email. Two emails at most: one when a launch date exists, one when it ships. No card required.
One-time purchase with 8 components, 139 tokens and the adoption companions. Preview the workflow while checkout is being prepared.
or write to kir.zhukovsky@gmail.com — subject prefilled
- 14-day refund, no questions asked.
- Prices are in USD.
- Receipts and invoices come from the payment processor.
- One purchase covers internal use across your team (LICENSE.md ships in the download).
This kit wires the machine-readable half; the Migrate Playbook sequences the componentization work that comes before it.
Everything else, one fold each.
The file tree, path by path
These files are included in the archive. Grouped rows describe their role; they are not public file downloads. Start with ADOPTION.md after unzipping.
- 01
registry.json + registry/Eight reference components — button, input, field, card, badge, alert, dialog, switch — plus the cn() helper and the token theme. TSX with forwardRef, cva variants, and per-item dependency lists so someone who only wants Badge doesn't get Radix Dialog.
- 02
tokens/tokens.dtcg.json$value / $type / $description on every leaf, across three tiers, with {dot.path} aliases and dark-mode values carried in $extensions. The descriptions explain the intended roles and decisions.
- 03
tokens/build.mjsResolves aliases with cycle detection, refuses two tokens under one CSS name, emits the dark block from the token file, and gates the build on contrast. Also runs --check in CI to catch a stale committed tokens.css.
- 04
mcp/server.mjslist_components, get_component, get_tokens over local stdio, implementing the 2025-06-18 handshake revision. Full-response checks cover source retrieval and stdout draining; current-client compatibility still needs a client check.
- 05
smoke-test.mjsRuns the token build and counts the custom properties in the output, performs the MCP handshake over stdio and asserts the three tools, and verifies every file registry.json lists exists. One ok line per check, non-zero exit on the first failure.
- 06
diagnose.mjs + diagnose.test.mjsChecks the real generated files, registry and MCP content. Optional consumer checks inspect selected install paths, dependency declarations and CSS. JSON includes hashes and limits; three tests exercise the baseline, stale output and broken integration paths.
- 07
ADOPTION.md + WALKTHROUGH.mdChoose an adoption boundary, follow source into the app and the agent's context, diagnose mismatches, and retain release evidence. The walkthrough includes an isolated token-change and rollback exercise.
- 08
examples/ + exercises/settings-save.mdIncludes the local settings demo, async React form, dependency-free controller, TypeScript contract and tests. A state map, adapter contract, agent brief and browser checklist connect the code to a real app; no endpoint or persistence is supplied.
- 09
templates/ADOPTION-DECISION.mdRecord canonical sources, copied-code ownership, CSS generation, account switching and retry policy. Mark browser, server and agent checks as performed only when you have their actual evidence.
- 10
templates/llms.txtCanonical URLs, the rules an agent must not break, the component list, and sections for 'Not in this system' and 'Deprecated — do not use'. TODO markers mark every place a decision is yours.
- 11
templates/DESIGN.mdToken architecture, layout and density, the eight component decisions agents reliably get wrong, the five states every data view needs, the accessibility floor, and voice. Written out, with TODOs where your team differs.
- 12
code-connect/button.figma.tsx is the straightforward case. field.figma.tsx is the one worth reading: Figma models a form field as one component with toggles, React models it as a wrapper composing an Input — the comments show how to absorb that in the mapping instead of adding a redundant prop.
- 13
COMPATIBILITY.mdA maintained Node 22 patch is recommended; tests ran on 22.13.0 and ≥18 remains an API floor only. React 19 / Tailwind 4 is exercised; 18 / 3.3+ are untested targets. Dated official sources distinguish implemented MCP 2025-06-18 from current 2026-07-28.
- 14
README.mdIncluding what the kit is not: no npm package, no hosted registry, no select or table or date picker, and Code Connect files that cannot be real until they point at your Figma node.
Token architecture, and the contrast gate on the build
A flat token file hands a model every value as an equally plausible choice. A tiered one narrows the legal set and names each option by intent, so “the background of a primary button” resolves to exactly one token instead of a plausible-looking wrong one. Rebranding becomes one edit to the ramp plus a rebuild — and if a rebrand needs a component file touched, a token is missing.
primitive.color.brand.600 = #4f46e5Raw palette and scale values. Semantic colour roles point here; component colours use those roles so a rebrand can be reviewed in one place.
semantic.color.action.solidBg → {brand.600}28 colour roles that describe intent, not appearance. This is the vocabulary components are allowed to use, and the only tier that flips in dark mode.
component.button.height.md = 40pxPer-component decisions. button.height.md and input.height are equal on purpose, and the token file says why in its $description.
The diagram shows the intended reference direction. The generator rejects unknown aliases and cycles; it does not enforce every architectural convention.
70 colour tokens exist in the set. Only the 28 semantic roles are legal inside a component — the primitives exist for the semantic tier to point at. Counted from tokens.dtcg.json.
node tokens/build.mjs turns the DTCG file into tokens.css, scores 9 text pairs against WCAG 2.1 AA in both themes, and exits non-zero below 4.5:1 — a floor wired into the build rather than an audit someone remembers to run. Zero dependencies: no Style Dictionary, no config file for an agent to guess at.
Source excerpts and commands to run
These source excerpts come from packages/agent-ready-starter as it stands. Where a file was too long for this column it is cut with a … line — those lines are truncation markers added here, not content in the file — and a few JSON entries are line-wrapped for explanation. The install block lists runnable kit commands; use the archive files for complete source.
tokens/tokens.dtcg.jsonjson{
"primitive": {
"color": {
"brand": {
"600": { "$value": "#4f46e5", "$type": "color",
"$description": "Solid action background (light mode)." }
… 41 more primitive colour steps …
}
}
},
"semantic": {
"color": {
"action": {
"solidBg": { "$value": "{primitive.color.brand.600}", "$type": "color",
"$description": "Primary button background.",
"$extensions": {
"one.designsystems.dark": "{primitive.color.brand.500}" } },
"solidFg": { "$value": "{primitive.color.neutral.0}", "$type": "color",
"$description": "Primary button label.",
"$extensions": {
"one.designsystems.dark": "{primitive.color.neutral.950}" } }
… subtleBg, subtleFg, solidBgHover …
}
}
},
"component": {
"button": {
"height": {
"md": { "$value": "40px", "$type": "dimension",
"$description": "Default button height. Matches input height so
they line up in a row." }
}
}
}
}All three tiers in one file. A primitive holds a hex and no meaning; the semantic role points at it with a {dot.path} alias and carries its dark value in $extensions, which is where the 28 dark overrides come from; the component tier records the decisions a role can't justify — including why button and input heights are equal.
registry/ui/badge.tsxtsxconst badgeVariants = cva(
cn(
"inline-flex items-center gap-[var(--ds-space-1)]",
"px-[var(--ds-badge-padding-x)] py-[var(--ds-badge-padding-y)]",
"rounded-[var(--ds-badge-radius)] border",
"text-[length:var(--ds-text-help)] font-medium leading-none whitespace-nowrap",
),
{
variants: {
tone: {
neutral:
"border-[var(--ds-color-border-default)] bg-[var(--ds-color-bg-subtle)] …",
brand:
"border-transparent bg-[var(--ds-color-action-subtle-bg)] …",
danger:
"border-[var(--ds-color-danger-border)] bg-[var(--ds-color-danger-bg)] …",
… success, warning, solid …
},
},
defaultVariants: { tone: "neutral" },
},
)
export function Badge({ className, tone, ...props }: BadgeProps) {
return <span className={cn(badgeVariants({ tone }), className)} {...props} />
}One of the 8 reference components, minus its imports and type declarations, with three of the six tones cut for width. Note what is absent from what remains: no hex, no spacing number, no font size. Its colour, spacing and size choices use var(--ds-*) references so a token edit can reach the component. Review the full source and actual screen when changing a theme.
mcp/server.mjs — tools/listjson-rpc$ printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| node mcp/server.mjs
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"name": "list_components",
"description": "List every component in this design system's registry:
name, type, title, description, npm dependencies, registry
dependencies, and the path each file installs to. Call this FIRST —
before writing any UI — so you use the components that exist instead
of inventing new ones.",
"inputSchema": {
"type": "object",
"properties": {
"type": { "type": "string", "description": "Optional filter on
registry type, e.g. 'registry:ui' …" }
}
}
},
{ "name": "get_component", "inputSchema": { …, "required": ["name"] } },
{ "name": "get_tokens", "inputSchema": { … "format": {
"enum": ["dtcg", "css", "flat"] } } }
]
}
}An abbreviated tools/list response. 3 tools over JSON-RPC 2.0. The kit ships with zero dependencies, and rather than make @modelcontextprotocol/sdk its first one, the stdio loop is written by hand — initialize, ping, tools/list, tools/call. The tool descriptions are written to be read by a model, which is why list_components says “call this FIRST” in its own text.
ADOPTION.md — baseline checksbash# From the unzipped agent-ready-starter directory.
# Use a maintained Node 22 patch release.
node diagnose.mjs > baseline.json
# Three diagnostic and seven async behaviour checks.
node --test diagnose.test.mjs \
examples/async-settings-flow.test.mjs
# Disposable token change, failure and exact rollback.
node examples/rehearse-theme-change.mjsOne catch: until you serve registry.json from your own domain there is no URL for the CLI to fetch. The exercised install path copies the 12 files to the registry targets. ADOPTION.md also documents the generated CSS copy step and the consumer diagnostic.
How it goes in: baseline · screen · recovery · ownership
Use a maintained Node 22 patch release for the exercised runtime family. The token build, diagnostic and local MCP server need no installed packages; the React consumer has its own dependencies. Start with the read-only diagnostic, then retain the consumer, browser and server evidence that it cannot produce.
node diagnose.mjs > baseline.json
# Inspect your chosen consumer paths:
node diagnose.mjs \
--consumer /absolute/path/to/my-app \
--source-dir src \
--stylesheet src/app/globals.cssChecks source agreement and actual local MCP retrieval. Exit zero does not close review or not_checked rows, or establish a compatible agent client.
- 01node tokens/build.mjs — tokens.css and the contrast report, from zero dependencies.
- 02node mcp/server.mjs — initialize, tools/list, and tools/call answered over stdio.
- 03node smoke-test.mjs — the build, the MCP handshake, and a registry integrity check in one command.
- 04node diagnose.mjs — generated-output and actual MCP content checks, with a JSON report and explicit open items.
- 05node --test diagnose.test.mjs examples/async-settings-flow.test.mjs — three diagnostic and seven controller acceptance cases.
- 06tokens.css in any app — plain custom properties, framework optional.
- 01Serving registry.json at your own URL — and re-pointing its bare registryDependencies names at your domain when you do.
- 02The brand ramp. The default palette is a placeholder that passes contrast, not a brand.
- 03The TODO_ markers in llms.txt and DESIGN.md, and the Code Connect node URLs.
- 04Your save adapter, server authorization/validation, persistence confirmation and retry policy. The async example provides the client boundary.
- 05The runtime CSS copy step after token generation, and a compatible agent client's absolute path to the same canonical source.
- 06The dialog's open/close fade — its animate-in classes expect tailwindcss-animate (v3) or tw-animate-css (v4).
- ~1 hour
Tokens only
Copy tokens.css into any app and import it in the root layout.
- ~half a day
Registry into an existing shadcn-style app
Copy 12 files to their targets, install the six packages the items declare, import tokens.css.
- 1–2 days
Full five-signal wiring
Both of the above, plus the MCP entry in your agent config, the template TODOs, and Code Connect pointed at your Figma file.
Planning ranges, counted from the steps each scope involves. The same table ships in the zip as COMPATIBILITY.md.
The gap, and the receipts on this domain
The public sample records five signals across 37 design systems. 19 receive zero points under the current scoring rules; that does not prove those teams have none of the capabilities internally. The highest recorded score is 4 of 5, and exactly one system gets there. Inspect the field evidence and dates before interpreting a score as current implementation coverage.
Signals addressed
Systems scoring zero
Left: the signals the Starter includes foundations for, with configuration still required. Right: systems with zero recorded points in this public sample, including uncertain or absent signals.
These bars describe the recorded public sample. The Starter includes source and templates for the five signals; hosting a registry, completing context documents and publishing your Figma mappings remain your setup work.
Count of systems with confirmed first-party evidence for each signal, audited 2026-09-04. "unknown" and "n/a" are not counted as yes. Source: /ai-ready/systems.
Inspect the related public surfaces and compare their scope with the downloadable reference before deciding whether it fits your project.
- /rThis site serves its own components through a shadcn-spec registry — the same shape registry.json uses.
- /api/mcpA public MCP server runs on this domain. The kit ships a smaller, generic version of the same pattern.
- /ai-ready/systemsThe Agent-Ready Index scores 37 public systems on the five signals the kit ships. Audited 2026-09-04.
Questions before you buy
- Is this a component library I install from npm?
- No. You copy and maintain the source. The registry has 12 file targets across 10 items; the archive also includes diagnostics, exercises and decision materials. Downloads have a versioned manifest, but there is no automatic source-upgrade path. Review later changes and keep your app's dependencies locked.
- How many components are in it, exactly?
- Eight: button, input, field (label + control + description + error, with the aria wiring done), card, badge, alert, dialog, and switch — reference implementations to adapt, not a catalogue to consume. Plus the cn() helper and the generated token theme, which makes ten registry items. There is no select, combobox, table, date picker, toast, or tabs — those are the components where a half-serious implementation is worse than none.
- Does the MCP server actually work, or is it a stub?
- It runs locally over stdio. The diagnostic compares retrieved Field source, semantic tokens and complete CSS with disk, and checks an unknown-component refusal. The implemented handshake revision is 2025-06-18, not the current 2026-07-28 revision. Use a client that supports that older handshake or migrate and test the transport. COMPATIBILITY.md records dated official sources and the checks performed.
- Why not Style Dictionary for the token build?
- This kit needs a bounded DTCG-to-CSS build: alias resolution, duplicate-name checks, dark values, generated-output checks and nine declared contrast pairs. One dependency-free Node script covers those needs. If you need additional platforms or transforms, evaluate a broader build tool and verify its output against your existing token contract.
- What does the contrast gate actually check?
- Nine declared foreground/background text pairs, in both light and dark, against 4.5:1 for normal text. It prints the table and exits non-zero on a failure. The included default palette's lowest checked pair is 4.52:1. Custom screens introduce additional combinations and interaction checks; this is not an accessibility certificate.
- Can I use it without Tailwind?
- The tokens are plain CSS custom properties and need no framework. The components require React and Tailwind, with their files included in Tailwind's source scanning. The isolated consumer check exercises React 19 / Tailwind 4. React 18 / Tailwind v3.3+ are compatibility targets inferred from the source, not tested combinations. The optional v4 bridge adds short names such as bg-surface; the components themselves reference token variables directly.
- What runtime should I use?
- Use a maintained Node 22 patch release. The local checks were exercised on Node 22.13.0; that older patch is an evidence record, not the recommended patch to install today. The declared ≥18 API floor does not mean Node 18 is still maintained. Node 24 is another maintained LTS family but has not been exercised for this kit. COMPATIBILITY.md links the official release table checked on 6 September 2026.
- Does the async form save to my backend?
- It requires your save adapter. The included React composition and tested controller cover pending, validation feedback, failed or unconfirmed saves, retry and late responses. Your service must handle authorization, server validation, persistence and retry safety. The exercise includes a non-persistent adapter for learning and separate browser and backend acceptance checks.
- Where are the adoption materials?
- ADOPTION.md, exercises/settings-save.md, the async example files and templates/ADOPTION-DECISION.md are included in the Starter archive. This product page and the free walkthrough explain the workflow and verification boundaries. Those archive paths are not public download links.
- My design system already has some of this. Should I still buy it?
- Check which gap you actually have. If your component contracts, token build, agent context and integration evidence already work together, you may not need the kit. The public Agent-Ready Index helps inspect external signals; it does not establish what your team already has internally or whether this purchase is worthwhile.

