{
  "lede": "A field survey of 19 actively maintained open-source design systems and component libraries, plus the five platforms around them. For each one: what it ships so coding agents can build with it (MCP servers, agent skills, llms.txt, editor rules, registries) and the tricks that keep a model using real components and tokens instead of making up its own. Every snippet links to its source.",
  "insights_lede": "Nineteen records read together: what nearly every team now ships, and what the leading systems do that the rest haven’t started.",
  "methodology_lede": "How the set was picked and what counted as an affordance or a technique. Every number on this site is computed from the records, not typed in.",
  "techniques_lede": "Every team here is solving the same problem: a model will happily write plausible code against a component API that doesn’t exist. The 148 techniques catalogued below are the industry’s answers, grouped into 11 categories, from blunt prohibition (“never invent components”) to setups where hallucination stops being possible because the agent has to fetch source it can’t fabricate.",
  "platforms_lede": "Figma is the deepest AI surface in the study, a remote MCP server that gets sharper the more Code Connect mappings you feed it. Storybook turned the component workshop into an agent-readable API. Supernova, Knapsack and zeroheight all run remote MCP servers over the design-system content they host, and none of them can point to much published adoption yet.",
  "findings": [
    {
      "title": "The machine interface is table stakes: 16 of 19 ship an official MCP server",
      "body": "Only Cloudscape, Nord and USWDS lack one, and Cloudscape makes up for it with the most engineered docs pipeline in the study. Nobody is still arguing about whether to ship a machine interface. The arguments now are about how the context gets sliced, how generation gets gated, and how the whole thing is kept from rotting."
    },
    {
      "title": "2026 is the year of the agent skill",
      "body": "Seventeen of nineteen ship official agent skills (Cloudscape has none; USWDS has an open issue). Distribution has settled on `npx skills add`, and Nord, React Spectrum, Nuxt UI and Atlassian serve skills from well-known discovery endpoints, a pattern that didn’t exist a year ago. PatternFly ships 32 consumer skills across 8 plugins. daisyUI sells paid Dashboard and Charts skills next to its free one."
    },
    {
      "title": "The frontier: portable design context and published evals",
      "body": "Atlassian ships DESIGN.md, an 80KB token-first manifest (RFC 2119 rules over roughly a thousand lines of YAML tokens) for generating on-brand UI anywhere, and routes production work to the MCP server instead. It also published head-to-head evals of its own affordances: MCP vs skill vs DESIGN.md vs no context, with token, time and turn counts. shadcn regression-tests its skill’s rules with an evals.json. Agent-facing artifacts are becoming measured, versioned software."
    },
    {
      "title": "Tool-gating beats prohibition",
      "body": "The strongest systems restructure the task so hallucination can’t happen, rather than asking nicely. Shopify’s Polaris skill tells the model “you cannot trust your trained knowledge” and gates every answer behind a docs search plus a validator run. Primer writes “CRITICAL: CALL THIS FIRST” into its MCP tool descriptions, and “you cannot complete a task involving CSS without a successful run of this tool”. shadcn’s skill bans fetching raw files outright: “NEVER fetch raw files from GitHub manually — always use the CLI.”"
    },
    {
      "title": "The best context files are compiled, not written",
      "body": "Mantine regenerates llms.txt, a 4.2MB llms-full.txt and mcp/index.json from the same MDX and docgen data as the human docs, on every release. Cloudscape mirrors every docs page as markdown, exposes typed JSON API definitions per component and regenerates llms.txt daily. HeroUI refreshes its MCP server from docs deploys via repository_dispatch. Hand-written agent docs rot. These can’t."
    },
    {
      "title": "Consumer-side and builder-side investment barely track each other",
      "body": "Fluent UI has the deepest builder-side agent stack in the study (nine executable skills, never-violate rules, lint auto-fix loops, visual verification) and almost nothing for consumers. React Spectrum, shadcn, Polaris and SLDS are the mirror image: heavy consumer investment, no public agent files for contributors. Carbon, HeroUI, Ant Design and Chakra are the few investing seriously on both sides."
    },
    {
      "title": "A walled-garden pattern is emerging alongside the open one",
      "body": "Polaris blocks GPTBot, ClaudeBot and friends in robots.txt and puts `noai` meta tags on every docs page, while funneling all AI consumption through Shopify’s own tightly gated toolkit. Nuxt UI bets the other way: RFC 9727 api-catalog, Link headers, markdown content negotiation, maximum discoverability for any agent. Both are deliberate. They can’t both be the future."
    },
    {
      "title": "Validation loops turn guidelines into gates",
      "body": "SLDS ships a dedicated validate skill plus slds-linter. Fluent’s skills wrap lint auto-fix loops with Storybook and Playwright visual checks. shadcn exposes an audit checklist as an MCP tool. Polaris bundles a validate.mjs the agent must run. None of them trust generation. They check it mechanically and make the agent fix what fails."
    },
    {
      "title": "The public sector is sitting this out, so far",
      "body": "USWDS ships zero consumer-facing AI affordances: no llms.txt, no MCP, no AI docs. Three weeks before this study it merged a single deliberately vendor-neutral AGENTS.md for contributors, on 2026-07-06. That is the entire federal contribution to date. The AI-affordance race is a private-sector phenomenon for now."
    }
  ],
  "convergence": [
    {
      "title": "llms.txt plus markdown twins of every docs page",
      "body": "The near-universal baseline: 14 of 19 systems publish llms.txt. The refinement war is over context budgets. Chakra slices llms.txt six ways by concern, HeroUI four ways by platform, Atlassian six ways by topic, Nuxt UI serves section-scoped variants, and Cloudscape regenerates daily with typed JSON API definitions per component."
    },
    {
      "title": "Official MCP servers, converging on read-only retrieval",
      "body": "Sixteen of nineteen systems have an official MCP channel, and nearly all expose the same core shape: search docs, get component docs and examples, list tokens. The variance is in delivery. Bundled in the CLI (shadcn), npm stdio (MUI, Chakra, Mantine, HeroUI, Spectrum, Primer, PatternFly, daisyUI), hosted remote with auth (Carbon, Nuxt UI, Atlassian), or owned by the platform org rather than the DS team (SLDS via @salesforce/mcp, Polaris via Shopify’s dev MCP)."
    },
    {
      "title": "Agent skills with progressive disclosure",
      "body": "The dominant skill architecture is a compact SKILL.md router plus lazy-loaded reference files. Carbon: a 24KB SKILL.md with 12 reference files. Nuxt UI: a routing table with 15. Chakra: a decision tree over its ~114 components. Everyone landed on the same trick independently: keep the always-loaded surface small and gate the detail behind explicit reads."
    },
    {
      "title": "Prohibition language that names the hallucination",
      "body": "The most effective negative rules name the exact failure. Ant Design’s allow-list exists to stop models hallucinating `Box`/`Stack`/`Container`. shadcn bans raw divs with `space-y-*` and manual `dark:` overrides. Carbon and SLDS both enumerate the components that exist, so anything else is provably invented."
    },
    {
      "title": "Design-to-code grounding via Figma Code Connect",
      "body": "248 public repos carry @figma/code-connect in package.json. For the systems that invest (Carbon, Primer, Fluent and Spectrum among them), it is the only mechanism in the stack that grounds design-to-code generation in real component imports rather than pixel reconstruction."
    }
  ],
  "divergence": [
    {
      "title": "Open discovery vs. walled garden",
      "body": "Nuxt UI publishes an RFC 9727 api-catalog, Link headers and markdown content negotiation so any agent can find everything. Polaris blocks AI crawlers outright and routes all consumption through Shopify’s own toolkit, where it enforces the strictest ruleset in the study. The industry hasn’t decided whether the machine interface is a public good or a controlled channel."
    },
    {
      "title": "Where the affordances live",
      "body": "In the DS repo itself, with skills and MCP developed in-tree (shadcn, HeroUI, Chakra). In the platform tooling layer, invisible from the DS repo (SLDS inside @salesforce/mcp, Polaris inside shopify-ai-toolkit). Or in the docs-site infrastructure (Cloudscape, Nord). Where it lives predicts who maintains it and how fast it ships."
    },
    {
      "title": "Vendor-neutral vs. harness-specific",
      "body": "USWDS wrote one deliberately vendor-neutral AGENTS.md. Primer went all-in on GitHub-native formats: copilot-instructions.md plus path-scoped *.instructions.md. HeroUI ships system prompts tuned per vendor (v0.dev, bolt.new, universal). Most hedge by shipping the same content through every channel at once."
    },
    {
      "title": "Builder-side philosophy: rulebook vs. router",
      "body": "Fluent UI’s contributor stack is a rulebook: numbered never-violate rules and nine operational skills. Carbon and Cloudscape bet on routers, keeping AGENTS.md deliberately tiny (Carbon’s opens by telling maintainers to keep it short; Cloudscape’s ~20 lines point into a 12-file docs index) and trusting retrieval over resident context."
    },
    {
      "title": "Paid AI surfaces are appearing inside open systems",
      "body": "MUI’s MCP includes generateReactCode, a paid service that can ground generation in a Figma frame. Chakra’s MCP unlocks Pro templates with an API key. daisyUI sells Dashboard and Charts skills. The open-source design system with a commercial AI tier is now a live business model, and it changes the incentives around how good the free machine interface is allowed to be."
    }
  ],
  "essay": [
    "Two years ago the question was whether design systems should care about AI consumption at all. That debate is over: of the nineteen systems here, all but one ship official machine-facing affordances, and thirteen treat AI consumption as a core design goal. What’s still contested, and what this study set out to map, is how you make a probabilistic text generator reliably use *your* components and *your* tokens rather than a statistically plausible imitation of them.",
    "The answers cluster into three generations. The first is documentation reshaped for machines: llms.txt, markdown twins of docs pages, condensed component indexes. Nearly everyone does this now, and the state of the art is no longer writing these files but compiling them from the same sources as the human docs so they can’t drift. The second is instruction: rules files and skills that tell the model what to do and, mostly, what never to do. The best instruction writing reads like policy rather than documentation: numbered never-violate rules, allow-lists of exported components written to stop models hallucinating `Box`/`Stack`/`Container` (Ant Design), Incorrect/Correct exemplar pairs (shadcn).",
    "The third generation, and the clearest line between the leaders and the pack, is structural coercion: redesigning the task so the model can’t go off-system even if it wants to. Tool-gating makes the agent call an MCP tool or CLI to get component source; Primer writes “CRITICAL: CALL THIS FIRST” straight into its tool descriptions. Scaffolding has the CLI generate canonical code while the agent merely orchestrates (shadcn). Registries resolve real artifacts instead of imagined ones. Validation loops make the agent run linters and audits until they pass (SLDS, Fluent, Polaris). Instruction hopes the model complies. Structure checks.",
    "The design-system team’s own repo is a different battlefield from the consumer’s repo, and investment on the two sides barely correlates. Some of the most consumer-invested systems (React Spectrum, shadcn, SLDS) show no public builder-side agent files at all, while Fluent UI runs the deepest contributor stack in the study behind a thin consumer surface. A quieter trend connects the leaders: they have started treating agent files as versioned, evaluated software. shadcn ships evals for its skill. Mantine version-locks its MCP server to each release. Atlassian published benchmark numbers. Carbon’s AGENTS.md opens by telling maintainers to keep it short because it’s loaded into every agent’s context. Give the machine interface the care you already give the component API. That is the part of this worth copying."
  ],
  "methodology": [
    "Research agents (Claude Opus 5) gathered the data on 26–27 July 2026, coordinated by a lead model (Claude Fable 5). Scouts mapped the territory, then one researcher per system catalogued affordances and coercion techniques against a fixed schema, quoting files verbatim and linking every claim to its source. Every claim was checked against its primary source before publication.",
    "Inclusion criteria: open source, active within the last six months, and enough public surface to study. The set spans AI-native leaders, large corporate systems and one deliberate public-sector contrast case. Where monorepos are private (Atlassian, Nord, SLDS internals), records rely on published packages and docs, and say so.",
    "AI maturity is a four-step editorial rating applied with one rubric across all systems: **none** (no AI affordances found), **emerging** (llms.txt or an AI docs page, little more), **invested** (official MCP, skills or rules with real engineering behind them), **ai-native** (AI consumption is a core design goal).",
    "The full dataset ships alongside this report as JSON records and a relational SQLite database: systems, affordances, techniques, platform capabilities and sources."
  ],
  "caveats": [
    "A snapshot taken 26–27 July 2026. The systems described here ship weekly, so expect drift within weeks.",
    "Snippets are excerpts, capped at 40 lines and sometimes abridged mid-list. Follow the source link before quoting further.",
    "Builder-side findings cover public evidence only. Private monorepos may hold agent tooling this study can’t see; “no public agent files” is not “no AI usage”.",
    "Community tools were checked for existence, not audited for quality or maintenance.",
    "Maturity ratings are our judgment against one rubric, not vendor self-reports."
  ]
}