Making @lawhive/ui agent-ready

This is a research synthesis from deep web research across 2025-26 sources, 3-vote adversarially verified, cross-referenced against an empirical map of the current packages/ui. It answers one question: what does the field actually know about making a design system understandable and usable by AI coding agents, and how much of it is real versus marketing? The short version is that the structural mechanisms are well documented and the efficacy evidence is thin, and the exact thing we care about most, whether any of this raises the design-quality bar, is the biggest gap in the whole space.

The one-line mental model

The field converged in 2025-26 on a single idea: treat the design system as machine-readable infrastructure, a structured contract an agent queries, not as prose docs an agent has to read and interpret. The failure mode everyone is designing against is that "LLMs don't look up your tokens and components; they generate plausible-looking ones". Left to itself an agent collapses to the average of the public internet (generic shadcn/Tailwind), not your encoded decisions. The whole playbook is about closing that gap.

A useful framing from the strongest practitioner source (Into Design Systems): foundations before automation. Naming, tokens, and component descriptions have to be clean first, because MCP servers and skills just expose whatever you have encoded. Garbage in, confidently-wrong UI out.

The gap the whole field is designing against. Without a machine-readable contract, an agent regresses to the public-internet mean. The six mechanisms below are the bridge; they only work if the foundations they expose are clean.

⚠️

Honesty upfront

The structural claims below (what schemas and servers exist and expose) are solidly grounded in primary vendor docs. The efficacy claims are much weaker, mostly first-party marketing or a single non-replicated benchmark. The flags throughout say which is which.

A widely-cited Storybook-MCP benchmark (2.76× faster, 27% fewer tokens) failed verification, so don't repeat it. And critically: almost nobody has measured whether any of this raises the design-quality bar, as opposed to component-selection accuracy and token cost. That is the exact thing we care about, and it is the biggest evidence gap in the whole space.

structural what exists / is exposed. Primary vendor docs, high confidence.

validated a real measured result, but read the caveat.

weak / hype first-party or unmeasured claim. Treat with suspicion.

refuted failed 3-vote verification. Do not cite.

evidence gap plausible but no verified evidence surfaced.

The external playbook: six mechanisms

1. Machine-readable component manifests structural

The highest-leverage move. The emerging standard is a JSON manifest per component describing identity, props, variants, sizes, states, dependencies, and usage, consumed by agents instead of prose. Two reference implementations:

shadcn registry (registry.json / registry-item.json): each item declares name, type, title, description, dependencies, registryDependencies, files (with target paths), cssVars, css, categories, meta. registryDependencies composes across sources, so an item can pull its primitives. This is a reproducible, CLI-installable contract, not just docs. ui.shadcn.com/docs/registry/registry-item-json
Meta's Astryx (open-sourced June 2026): ships a manifest command returning a self-describing JSON payload of every command, arg, flag, and type, framed as "an OpenAPI spec for the CLI." facebook/astryx

The one quantified result that survived verification validated Indeed's design-system team (Diana Wolosin) converted 77 components from MDX prose to JSON metadata, ran 1,056 prompts across 8 MCP configs, and found JSON beat Markdown on both accuracy and cost: roughly 80% fewer tokens, about $1,500 to $300 a year. Caveat: single team, internal, non-replicated, and the sharpest comparison was JSON-vs-hybrid. Treat as a validated case study, not a law.

"JSON for MCP, Markdown for LLM." Structured API data (props, variants, sizes) belongs in JSON; conceptual guidance ("when to use this") stays in prose.

2. MCP servers, the delivery channel structural ROI unproven

MCP is how the manifest, token, and story surface reaches the agent at authoring time. Four shipping servers:

shadcn MCP: natural language to registry commands ("add a login form"), works with any compatible registry by reading its index. ui.shadcn.com/docs/mcp
Figma Dev Mode MCP: exposes code representations (React/Tailwind), screenshots, and variable/token definitions with code-syntax metadata; works in Cursor, Copilot, Claude Code. figma.com/blog/introducing-figma-mcp-server
Storybook MCP (React-only, experimental): exposes stories, API, and docs so agents reuse existing components instead of inventing, and, notably, lets the agent run component and a11y tests and fix its own output. storybook.js.org/blog/storybook-mcp-for-react
Astryx MCP over JSON-RPC 2.0.

Everything here is either beta or experimental. Real capability, unproven ROI.

3. LLM-facing docs & context layers structural

llms.txt / llms-full.txt: Nuxt UI ships a ~5K-token llms.txt index (fits any context window) plus a comprehensive llms-full.txt. Serving docs as markdown rather than HTML cuts token use ~90%. ui.nuxt.com/docs/getting-started/ai/llms-txt
shadcn Skills: an installable context layer that auto-activates when it detects components.json, and on every interaction runs shadcn info --json to inject live project config (framework, Tailwind version, aliases, installed components, resolved paths). This is the pattern that keeps the agent grounded in this repo's reality rather than generic defaults. ui.shadcn.com/docs/skills
AGENTS.md: note that the specific claim that AGENTS.md acts as an agent "orchestration file" with trust levels was refuted. Its role is real but more modest: repo-level rules and pointers, not a magic control plane.

4. API design toward the "pit of success" structural

Constrain choices so the agent lands on the right primitive by default. shadcn Skills steer agents to FieldGroup for forms, ToggleGroup for option sets, semantic colors over raw palette. Important caveat verifiers flagged: this is soft guidance / context injection, not hard enforcement. The durable point: fewer degrees of freedom plus discoverable, intention-revealing names equals better agent output. (Our existing Button vs InlineButton doc-comment is exactly this instinct.)

5. Design tokens as the source of truth structural efficacy unmeasured

The consensus failure mode: agents fabricate plausible token values. The fix is a closed, named token set the model picks from. Figma's own claim: passing the variable name via MCP reduces token usage and improves precision (first-party, unmeasured). This is the area where we are already ahead of the field (see below). On W3C DTCG and Tailwind v4 @theme enumerability specifically, honestly, no verified evidence surfaced on those helping agents. It is an evidence gap, not a validated practice.

6. Guardrails & verification thinnest evidence

This is where the research came up short, and it happens to be our strength. The only confirmed verification instance was Storybook's self-run test loop (agent runs tests, applies its own fixes). Deterministic drift-catching (custom lint plugins, codemods, evals tied to a quality gate) is widely advocated but barely documented with evidence. So our instinct to enforce via CI is correct, and under-served by the public playbook.

Mapped onto `@lawhive/ui`: where we stand

We are further along than most on the two hardest foundations, and behind on the packaging and exposure layer. The two panels below are the honest self-assessment; the table after is the gap list in priority order.

Already strong (keep, lean into)

Tokens are our best asset. tokens.css to a generated, committed TokenName union plus a tokens:check CI drift-guard is exactly the "closed, named, enumerable token contract" the field says prevents fabrication. Most teams don't have this. We have the machine-readable source of truth for tokens; we just haven't pointed an agent at it yet.
Foundations are clean. Consistent data-slot, compound/dot-notation, cva-dominant variants, react-docgen-typescript already extracting prop tables, CSF3 plus autodocs. The "foundations before automation" prerequisite, done.
A verification culture exists. Three Vitest tiers, Biome custom GritQL plugins (no-use-effect and others), Chromatic, a dedicated frontend-reviewer agent plus /frontend-review skill. We have the guardrail muscle the public playbook lacks evidence for.

The "JSON for MCP, Markdown for LLM" split maps cleanly

The generated token contract is the JSON side already.
docs/agent/react-and-frontend.md plus component doc-comments are the Markdown side.
The missing piece is the JSON side for components, and we already own the exact codegen pattern to build it (scripts/generate-*.mjs).
That single asymmetry, rich token JSON but no component JSON, is the load-bearing gap in the table below.

The gaps that actually matter (priority order)

Gap	What the field does	Effort / leverage
No `packages/ui/AGENTS.md`Guidance lives only in repo-wide `docs/agent/*`	A package-scoped rules file: which primitive when, `Button` vs `InlineButton`, "use semantic tokens not palette", anti-examples.	Low effort, high leverage — do first
No machine-readable component manifest	shadcn `registry.json` / Indeed's JSON-per-component. We already generate a token manifest — extend the same `scripts/generate-*.mjs` pattern to emit component metadata from cva variants plus docgen.	Medium effort, highest leverage
No agent context layer / MCP	shadcn Skills' `info --json` live-config injection; a small MCP or a generated `llms.txt` over the barrel plus manifest.	Medium
Semantic-tokens-over-palette is doc-only	Turn it into a Biome GritQL plugin (we have the plugin infra plus the `TokenName` union to validate against). Single biggest drift risk and we're one plugin away from closing it.	Medium effort, high leverage
No component scaffolding generator	plop / turbo generator so agents (and humans) produce conformant components. We have a package generator already — extend the pattern.	Low / medium
Two authoring conventions + stale `./guards` export	Agents pattern-match on inconsistency. Normalise flat-vs-folder, kill the dead `tv` outlier and the `./guards` export pointing at a non-existent dir.	Low

Recommended sequence

Foundations, then exposure, then enforcement. The order is the point.

Write packages/ui/AGENTS.md. The cheapest win, immediately useful to every agent in the repo. Include a "which primitive when" decision list and explicit anti-examples ("don't use raw bg-blue-500, use semantic tokens").
Ship the semantic-tokens-over-palette GritQL plugin. Converts our best-articulated convention into a hard guardrail, validated against the TokenName union we already generate. Closes the number-one drift risk.
Generate a component manifest. Extend generate-design-tokens.mjs's approach to emit per-component JSON (name, variants from cva, prop types from docgen, "when to use" from doc-comments). This is the load-bearing agent contract and the highest-ROI structural change.
Then, and only then, decide on exposure. llms.txt first (cheap), MCP later (higher effort, unproven ROI, beta and moving fast; worth a spike, not a bet).

Rationale for the order: the research is unambiguous that exposure mechanisms (MCP, skills) only amplify encoded foundations, and the ROI evidence for MCP specifically is weak or beta. Our leverage is in encoding (steps 1 to 3), which we are unusually well-positioned to do because the token codegen already exists.

Honest caveats & open questions

ⓘ

Caveats that shape how much to trust this

The quality-bar question is unanswered by the literature. Everything measured is retrieval accuracy and token cost. Whether any of this makes agent-built surfaces beautiful and correct is unmeasured. We would have to build our own eval, which, given the Chromatic plus component-test plus frontend-reviewer stack, we are better placed to do than most.
Everything is 2025-26 and moving fast. Storybook MCP is React-only and experimental, Astryx is beta, shadcn Skills and CLI are actively churning. Don't hard-couple to any one vendor's schema yet.
shadcn's "open code / registry" vs Meta Astryx's "compiled + self-describing CLI" may be a genuine architectural fork, but the research found convergence and little documented dissent, so treat the "one true way" framing skeptically.

🚫

Refuted during verification — do not cite

refuted 1-2 Storybook-MCP efficacy benchmark (Reshaped: 12.8% code usage / 2.76× faster / 27% fewer tokens).
refuted 0-3 AGENTS.md as an "orchestration file" with foundation rules plus MCP pointer plus trust levels.

Open questions worth a targeted follow-up

Does exposing the DS via MCP/JSON measurably raise the design-quality bar, not just retrieval accuracy and cost?
What's the validated guardrail/eval stack for catching agent drift (custom lint, codemods, deterministic checks, visual regression tied to a quality gate)? Almost no confirmed evidence.
How do W3C DTCG and Tailwind v4 @theme enumerability specifically help agents map intent to tokens? No claim survived verification.

Key sources

Start here — highest signal

Into Design Systems — Agentic Design Systems: The Complete Guide (best single synthesis; source of "foundations before automation" and the Indeed benchmark)
Hardik Pandya — Expose your design system to LLMs (concrete llms.txt / rules-file patterns)

Vendor primary docs — structural, high-confidence

Supporting practitioner / secondary

Tokens — asked-about but thin evidence, read critically

Discussion

Comment inline (hover any paragraph, or select text to start a thread), react, and sign at the foot of the page. Particularly interested in: whether the packages/ui/AGENTS.md plus GritQL plugin plus component-manifest sequence is the right first three steps, and whether anyone wants to own the quality-bar eval that the whole field is missing.