Agent-native design system
Design system agent demo
Machine-readable contracts, intent benchmarks, and MCP tools so agents reuse @dt/* before inventing markup. Colophon covers the full stack.
MCP & docs
- MCP: /mcp
- 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.
| alert-dismissible | “dismissible warning banner” | AlertBanner (top 1) |
|---|---|---|
| button-primary | “primary action button” | Button, MCPActionButton (in top 3) |
| title-semantic | “semantic page title heading” | Title (top 1) |
| submit-loading | “loading submit button” | Button (in top 3) |
| modal | “modal dialog” | Modal (in top 3) |
| cookie-consent | “cookie consent” | CookieConsent (top 1) |
| text-input | “labeled text input” | TextInput (in top 3) |
| pagination | “pagination controls” | Pagination (top 1) |
| chat-widget | “chat widget send” | ChatWidget, ChatComposer, ChatHeader (in top 3) |
| file-upload | “file upload” | FileUpload (top 1) |
| toast | “toast message” | Toast (top 1) |
| hero | “hero section landing” | HeroSection, Hero, CTASection (in top 3) |
| card-actions | “card with actions” | Card (top 1) |
| select | “dropdown select options” | Select (top 1) |
| checkbox | “checkbox with label” | Checkbox (in top 3) |
| switch | “toggle switch” | Switch (top 1) |
| badge | “status badge” | Badge (top 1) |
| tabs | “tabs navigation” | Tabs (top 1) |
| icon-button | “icon only button” | IconButton (top 1) |
| helper-text | “tooltip help” | HelperText, Label (in top 3) |
Component taxonomy
178 components from the generated docs registry. Expand a group and select a component to see the dense contract line agents retrieve.
Select a component to see the dense contract line agents retrieve.
Agent benchmark (A/B)
The same coding agent, twice per task: WITH the design-system affordances documented in its workspace vs WITHOUT (identical repository access). 90 runs, claude-sonnet-5 maxTurns=30 repairLoop=true, total spend $78.57. Acceptance tests semantics, not implementation — reuse of @dt/* is reported separately. Methodology: docs/AGENT_BENCH_METHODOLOGY.md.
| Arm | First-try pass | Final pass (repair loop) | Mean cost / run | DS reuse (build tasks) |
|---|---|---|---|---|
| WITH | 45/45 | 45/45 | $0.82 ± 0.29 | 14/27 |
| WITHOUT | 42/45 | 45/45 (3 via repair) | $0.93 ± 0.54 | 2/27 |
| Task | WITH | WITHOUT | DS reuse (with / without) |
|---|---|---|---|
| forced-colors | 9/9 | 9/9 | 1/9 / 1/9 |
| migration | 9/9 | 9/9 (3 via repair) | — / — |
| repair | 9/9 | 9/9 | — / — |
| table | 9/9 | 9/9 | 8/9 / 0/9 |
| tree | 9/9 | 9/9 | 5/9 / 1/9 |
- Arms are identical except the workspace guidance file: WITH documents the dt CLI affordances; WITHOUT is generic with the same repository access. The control can discover the affordances on its own, so measured lift under-claims.
- Acceptance is affordance-neutral (semantics, not implementation); design-system reuse is reported separately and never gates a pass.
- The migration category is from a re-run after a task-spec fix (#1406): the original brief enumerated 4 files while acceptance swept wider. The corrected brief demands all consumers and acceptance matches; the confounded original migration results are excluded.
- On the corrected migration task both arms passed 3/3; the affordance effect there is efficiency (WITH mean ~$1.18 and ~25 turns vs WITHOUT ~$1.73 and ~34 turns), with one WITHOUT run needing the repair loop.
- num_turns counts top-level turns only; runs that delegate to subagents can show few turns at normal cost.
- Batch 2 (2026-08-06, 30 runs, $26.87) doubles every cell to n=6 under the identical pinned methodology; cost figures are mean +/- sample sd across both batches.
- Batch 3 (2026-08-08, 30 runs): identical pinned methodology, run against the post-Phase-4 HEAD where the affordance layer includes the seven per-publish evidence artifacts, enriched playground defaults, and the parity-repaired components. First batch with 30/30 passes in both arms.
Raw artifact: /ds-health/agent-bench.json · n=9 per arm per task; cost is mean ± sample sd. Runs are nondeterministic, so treat single deltas as noise and distributions as the signal.
Evidence per publish
Seven artifacts regenerate inside the publish preflight and ship stamped at the published version — currently @digitaltableteur/react@0.1.24. 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.
| Artifact | What it records | Headline | Raw |
|---|---|---|---|
| Bundle cost | Minified+gzip bytes per exported component, in two honest modes: the package's own code (self) and the marginal cost to a consumer that satisfies the peer contract (withDeps). | 143 exports · package self 722.5 kB JS + 46.9 kB CSS gzip | JSON |
| SSR + hydration | renderToString in plain Node (no DOM globals), then hydrateRoot over that HTML with zero recoverable hydration errors. | 90 SSR pass · 90 hydrate clean · 2 provider-required errors | JSON |
| Override precedence | A consumer's single-class className override wins over component base styles in real Chromium (the owner-decided contract), plus the container × child encapsulation matrix on child-pinned properties. | 47 pass · 0 fail · 64 matrix pairs, 0 affected | JSON |
| Interaction cost | Mount/re-render commit cost (flushSync, informational) and DOM render weight per component, plus interaction recipes over the data primitives' documented hot paths. | 90 measured · 4 recipes completed | JSON |
| React peer-range matrix | The declared react range (>=19.0.0) exercised at its endpoints in isolated consumer installs; outcome sets must match across combos. | react 19.0.0 & 19.2.8 · 0 divergent components | JSON |
| Web-component parity | React↔native rendered parity (pixels + geometry across the viewport/theme matrix); enforced components fail the publish on regression. | 20 enforced clean · fleet visual 145/413, geometry 197/413 of 413 | JSON |
| Compatibility manifest | The toolchain combinations ACTUALLY exercised by the gates — resolved versions, never ranges. Absence means untested, not incompatible. | react 19.2.8 · next 16.3.0 · typescript 6.0.3 | JSON |
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