Built for agents

The repo is the interface.

AI coding agents do not need a special endpoint to use Clarity. They open the repository, the same way an engineer does, and read the files. No MCP server stands in between. No documentation mirror lags behind the code. No sync job translates the system into an agent-friendly shape. The agent-friendly shape is the shape the system already has.

What agents read is the same machine-readable surface engineers and tools rely on:

• COMPONENTS.md — the library map at packages/components/COMPONENTS.md. Theme summary plus a for/not-for index of every component. Agents read this first; see Working with AI agents for the workflow and to preview or download the file from the docs site.
• Tokens as W3C DTCG JSON — queryable by name, by category, by reference. The colour, spacing, and typography contracts of the system, in a format that does not require interpretation.
• Component contracts as TypeScript source — props, variants, slots, and types, all expressed in code. The contract is the implementation.
• Usage guidance as COMPONENT.md files colocated with each component. Sixty-two components, sixty-two markdown files, sitting next to the source they describe.
• Executable examples as Storybook stories, also colocated. Runnable proof of how a component is meant to be composed.
• Workspace structure as an Nx project graph, machine-readable, so agents can reason about package boundaries and dependencies.

Because all of this lives in the repo, agents always read the current state. There is no version of the design system that is "true" elsewhere. The truth is the file the engineer just edited.

This is what makes the agentic delivery path real. A designer prompting Claude Code to build a checkout step does not get hallucinated components — the agent reads COMPONENTS.md to pick the right primitives, then button/COMPONENT.md for variants and usage, then the token files as needed. The same is true for any future agent or tool that arrives. The interface is open, file-based, and standard. The repo is the API.

The lesson generalises. A design system that is legible to humans through documentation, and legible to machines through structure, does not need a separate strategy for either audience. It just needs to be honest about being made of files.

What an agent actually reads

Every component ships with a COMPONENT.md colocated next to its source. Here is an abbreviated excerpt from the Button component:

---
name: Button
slug: button
status: stable
---

## Props

| Prop      | Type                                                              | Default   | Description                              |
|-----------|-------------------------------------------------------------------|-----------|------------------------------------------|
| variant   | 'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'link' | 'default' | Visual style                             |
| size      | 'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-xs'                | 'default' | Size variant                             |
| loading   | boolean                                                           | false     | Shows spinner, disables interaction      |
| asChild   | boolean                                                           | false     | Renders as child element via Radix Slot  |

## Usage guidelines

Use Button for synchronous actions: form submission, dialog triggers, immediate in-page operations.
Do not use for navigation — use a link styled as a button via the asChild pattern instead.

## Live component

<StorybookEmbed story="actions-button--default" />

The agent reads this file, knows the available variants and sizes, knows when not to use the component, and can see a live rendered example. No other website surface is needed — the repo files are the interface.

See it live: Button → · Working with AI agents →