Design system agent demo

MCP & docs

• MCP: /mcp (POST, Streamable HTTP)
• Card: /.well-known/mcp/server-card.json
• Agent card: /.well-known/agent.json
• Case study (repo): docs/AGENTIC_DS_CASE_STUDY.md
• Catalog policy (repo): docs/CATALOG-POLICY.md

Intent golden set

20 queries verified by npm run agent:eval.

Component taxonomy

184 components from the generated docs registry. Expand a group and select a component to see the dense contract line agents retrieve.

Agent benchmark

Coding agents on the same tasks, in 4 arms that differ in one thing only: how the design system is offered to them. 264 published runs across Claude Code and OpenAI Codex CLI. Metered spend on these runs: $66.94; subscription runs report output tokens instead and spend on superseded runs is in the notes. Acceptance tests user-visible semantics and contract conformance, not implementation; reuse of @dt/* is reported separately and never gates a pass. Methodology: docs/AGENT_BENCH_METHODOLOGY.md.

• WITH (dt CLI documented in workspace)
• MCP (design-system MCP attached, generic workspace)
• MCP + POINTER (same server, plus one line in the workspace naming it)
• WITHOUT (generic workspace)

• Two model families, same tasks, same graders, same repository state per task: Claude Code (claude-sonnet-5) and the OpenAI Codex CLI (gpt-5.6-sol, high effort). Four arms each, differing in one thing only. WITH: the workspace instructions document the dt CLI. MCP: generic instructions plus the repository's stdio design-system MCP server attached. MCP + POINTER: the MCP arm plus one line naming the server. WITHOUT: generic instructions. Each runtime reads the arm text from its own instruction file (CLAUDE.md or AGENTS.md).
• Headline, replicated across both families: an MCP server is only as good as the pointer to it. Attached alone, Claude called it in 4 of 33 runs and Codex in 0 of 33, and design-system reuse stayed at the control's level (Claude 10 of 24 vs 12 of 24; Codex 4 of 24 vs 4 of 24). With one line naming the server, Claude called it in 31 of 33 runs and Codex in 33 of 33, and reuse rose to 21 of 24 in both, level with documenting the CLI (Claude 20 of 24, Codex 21 of 24). The clients defer MCP tools behind a tool search, so an agent that is not told the server exists rarely or never looks.
• The pointer line, verbatim: "This repository's design system is available through the `design-system` MCP server; use its tools to find components and validate usage before finishing."
• Pass rates saturated for both families. Eleven tasks, including three multi-component and cross-file tasks added to separate the arms (a tabbed settings panel with shared state, a filterable paginated directory, and a three-page migration off hand-rolled tabs). First-try pass is 31 to 33 of 33 for every Claude arm and 33 of 33 for every Codex arm. Today's differences are in how agents build, not whether they succeed. Tasks whose briefs say to use the design system correctly if used saw high reuse in every arm; compare arms within a task.
• Isolation: Claude runs pass --strict-mcp-config and --setting-sources project,local; Codex runs use a throwaway CODEX_HOME holding only the login. Neither sees the operator's own instructions, skills, plugins or MCP servers.
• Cost: Claude spend $95.13 including $28.19 on superseded runs (see supersededRuns: a stale hardcoded consumer list and a colour scan that flagged var(--color-white), both fixed and guarded in the selftest before re-running). Codex ran on a subscription, so it reports output tokens instead of dollars; token counts are not comparable across families.
• Harness notes: a result-file name collision between parallel arms lost three Codex migration runs; filenames are now unique and the three runs were re-run from the same source commit. n=3 per arm per task per family. Treat per-task differences as anecdotes; the MCP call rates and the reuse gaps are consistent enough to read.

Raw artifact: /ds-health/agent-bench.json. n=3 per arm per task; cost is mean ± sample sd. Runs are nondeterministic, so treat single deltas as noise and distributions as the signal. The earlier two-arm batch (August 2026, 90 runs, different isolation) is archived at /ds-health/agent-bench-2026-08.json.

Evidence per publish

Seven artifacts regenerate inside the publish preflight and ship stamped at the published version — currently @digitaltableteur/react@0.1.26. Numbers below are derived from the committed artifacts, never hand-written; each raw file carries its own provenance (source commit, generator, tree state) and timings live outside the stamped substance because they vary by machine.

Pattern recipes

MCP tool suggest_pattern_for_layout

• @dt/CTASection

  marketing call-to-action band at section end

  Avoid: inline alert or toast feedback

• @dt/HeroSection

  full-bleed marketing hero with alignment and background variants

  Avoid: blog article hero — prefer ArticleHero pattern

• @dt/HomeHero

  production homepage hero with kinetic title and scroll indicator

  Avoid: generic marketing hero without homepage-specific motion

• @dt/SiteHeader

  Next.js app shell sticky header with brand and nav

  Avoid: embedded header inside a card or modal

• @dt/SiteFooter

  site-wide footer with link columns and social links

  Avoid: legacy Footer pattern with different IA

• @dt/NewsBulletin

  homepage news strip with three topical slots above footer

  Avoid: full blog index or article grid

• @dt/ArticleHero

  blog article hero with title metadata and optional image

  Avoid: marketing homepage hero — prefer HeroSection

• @dt/ContactInquiryPanel

  contact page message vs book-a-call tab panel

  Avoid: standalone contact form without tab chrome

• @dt/PricingPageContent

  pricing page with package tiers and agency comparison

  Avoid: single pricing card inline on homepage

Local verification

npm run build:tokens
npm run agent:eval
npm run agentic-ds-audit
npm run ds:mcp