Free integration walkthrough
Trace the source. rehearse the failure. know what a pass means.
A working token build is a starting point. This walkthrough follows the path into an application, shows a recorded failure and rollback, and explains how the async save exercise separates client feedback from real persistence.
The commands below run from the unzipped Starter archive. This page is free to read; the diagnostic, source exercises and full adoption documents are included in that archive.
Keep three boundaries visible
Tokens and component contracts
The DTCG file generates CSS. The local MCP server reads the kit's actual source. Keep both pointed at the canonical version.
Installed controls and behaviour
Your app imports runtime CSS, compiles the utilities and renders the form. Type checks and browser evidence belong here.
The confirmed save
Your server owns authorization, validation and persistence. The form receives an explicit result through your adapter.
Use a maintained Node 22 patch release. The recorded local runtime is 22.13.0, with React 19 and Tailwind 4 for the exercised consumer. The package's ≥18 declaration is an API floor; it does not mean Node 18 remains maintained. Official Node release table, checked 6 September 2026.
Diagnose what the files actually provide
node diagnose.mjs > baseline.json
node --test diagnose.test.mjs \
examples/async-settings-flow.test.mjsThe diagnostic is read-only: it checks generated output, registry targets and actual MCP retrieval against the files on disk. It does not install dependencies, access a network or run consumer scripts. The test command executes three diagnostic checks and seven async controller acceptance cases.
- pass
- The named check passed within its stated scope. A dependency declaration check, for example, does not prove packages are installed.
- review
- A human decision remains. Stock context-template TODOs and intentionally customized consumer files can appear here.
- not_checked
- No evidence was gathered for that boundary. Without a selected consumer, the kit cannot establish installation.
- fail
- A checked requirement failed. The command exits nonzero and reports the concrete problem.
Exit zero does not close review or not_checked rows. Keep the report's hashes, runtime, time and limits beside your application evidence.
Install one screen before widening the scope
styles/tokens.css from your app's global CSS.The generator later writes tokens/tokens.css; copy that generated output back to the imported path after changes.settings-form.tsx example.Submit an empty email, correct it and inspect focus, error association and success feedback. This original example never sends or saves anything.# Example: your app keeps components and styles under src/.
node diagnose.mjs \
--consumer /absolute/path/to/my-app \
--source-dir src \
--stylesheet src/app/globals.cssPaths after --consumer are relative to the app. Omit --source-dir when the targets live at its root. The stylesheet check expects a direct token import; if your framework imports through JavaScript or an intermediate stylesheet, record that path manually. The full integration map in ADOPTION.md explains the alternatives.
MCP runtime and client scope
The kit implements local stdio with the 2025-06-18 handshake revision. The current official specification is 2026-07-28; those newer protocol mechanisms are not implemented here. Use a client that supports the older handshake, or migrate and test the transport. The diagnostic checks local content retrieval, not every agent client. COMPATIBILITY.md links the dated sources and exact coverage. Official MCP versioning, checked 6 September 2026.
Change a token. prove you can undo it.
node examples/rehearse-theme-change.mjsThe rehearsal changes semantic.color.action.solidBg to reference primitive.color.brand.800. It requires generated CSS to change and the declared contrast pairs to pass. Then it inserts a missing alias and requires the build to fail. Finally, it restores the source and compares CSS byte for byte.
It edits an OS temporary copy and removes it afterwards. Review the source and generated diff before applying a change to your own app. The browser contrast preview checks one pair; this rehearsal runs the package build.
Recorded rollback result
Run 2026-09-05 · Starter 1.0.0 · Node v22.13.0. This receipt covers the token rehearsal only, not the later async form or a model benchmark.
- originalBuildpassed
- changedCsspassed
- declaredContrastPairsPassedpassed
- brokenAliasRejectedpassed
- rollbackExactpassed
Inspect the reproducibility receipt
{
"schemaVersion": 1,
"ranAt": "2026-09-05T13:10:52.151Z",
"node": "v22.13.0",
"kitVersion": "1.0.0",
"tokenSourceSha256": "162b2dba4554c1390c249dfe46cdf90004e24fd08200b9ac799ce81661a8913b",
"change": "semantic.color.action.solidBg → primitive.color.brand.800",
"checks": {
"originalBuild": true,
"changedCss": true,
"declaredContrastPairsPassed": true,
"brokenAliasRejected": true,
"rollbackExact": true
},
"limits": [
"Runs on a disposable copy; no application files are changed",
"Not a full accessibility audit",
"Not an agent execution benchmark",
"Review and apply any real migration yourself"
]
}An uncertain response is not a confirmed save
The async companion composes the actual Field, Input, Button and Alert with a dependency-free controller. Supply a save adapter from a client parent. A known validation rejection returns to field correction; an unavailable service or malformed response leaves the save unconfirmed.
- 01
Invalid
Keep the entry, show the associated field error and focus the input. Invalid local input never reaches the adapter.
- 02
Pending
Keep the field readable but read-only and disable submission. Duplicate calls are ignored so the displayed address matches the submitted one.
- 03
Unconfirmed → retry
Retain the address, show a useful error and allow an explicit retry. Your server must make retries safe when an earlier write may have succeeded.
- 04
Confirmed
Only an explicit ok: true result confirms success. Editing clears that feedback. Cancelled older requests cannot overwrite a newer attempt's result.
node --test examples/async-settings-flow.test.mjsSeven tests exercise the controller's validation, pending/duplicate handling, failure/retry, explicit success contract, server validation, stale-result protection and disposal. They do not mount React or contact a backend.
The included exercise adds a controlled non-persistent adapter, an agent brief and a browser walkthrough. Complete the keyboard, focus, announcements, both-theme and account-switch checks in your own app. Then verify server authorization, validation and persistence separately. Aborting a request cannot undo a write the server already accepted.
Where to continue inside the archive
These are package paths, not public downloads. Open them after unzipping the Starter.
- ADOPTION.md
- Integration map, diagnostic interpretation, CSS copy boundary, release gates and troubleshooting.
- exercises/settings-save.md
- State map, save adapter contract, automatic and browser acceptance cases, plus a concrete agent task brief.
- examples/async-settings-form.tsx
- The React composition. Keep async-settings-flow.mjs and its .d.mts declaration beside it when copying.
- templates/ADOPTION-DECISION.md
- A worked architecture decision and open evidence record for your application's actual owners and results.
- COMPATIBILITY.md
- Declared floors, exercised versions, protocol limitations and dated official references.
What the evidence establishes
The isolated consumer path type-checks all eight components and the local and async forms with the repository's locked React 19 dependencies, then compiles token/focus utilities with Tailwind 4. The local diagnostic checks source agreement, and the deterministic controller suite checks its seven behaviour cases. The dated receipt above establishes token change, failure and exact rollback.
Those are separate checks with separate limits. They do not establish React 18 or Tailwind 3 compatibility, remote installation, every MCP client, production persistence, full accessibility conformance or model performance. Keep your own browser, backend and adoption decisions beside the code.