<SYSTEM>This is the AI and agents part of the Atomus documentation: rules for agents, the skill, the Atomus MCP server, lint rules, the shadcn registry, evals, Figma MCP and llms.txt.</SYSTEM>

---

# Atomus is built for humans and agents

> What Atomus gives AI agents today (guidelines, skill, MCP server, lint rules, shadcn registry, Storybook, Agent kit, llms.txt, Figma MCP rules), how it is measured, and what is coming next.

URL: https://docs.atomus.io/ai/

Most design systems are written for people and then scraped by AI tools. Atomus is written for both. Every rule a designer or developer reads on this site is also published in a form agents can follow literally. The props, tokens and rules agents use are **generated from the same sources** as the Figma file and the React package, so they can’t drift.

The result: Claude Code, Cursor, Copilot, Figma Make and the Figma MCP server pick the right component, use only real props, style with semantic tokens and keep one primary action per view. You review the result instead of fixing it.

## Available now

Guidelines for agents

Plain-Markdown guidelines with an entry point (`Guidelines.md`), a component catalogue with decision trees, imperative **Do / Forbidden** rules, and a **React API** section on every component generated from the TypeScript source.

Atomus skill

An [Agent Skill](https://agentskills.io/) with the workflow, references (components, tokens by intent, page patterns, Figma) and a validator that flags raw colours, primitive tokens and invented props. `npx skills add StanVisionAgency/atomus`.

AGENTS.md template

Paste-in rules for product repos that use Atomus, read by Claude Code, Cursor, Copilot and Codex.

llms.txt and Markdown pages

`/llms.txt`, `/llms-full.txt`, `/llms-small.txt`, topic subsets, and every page as Markdown at `…/index.md`.

Figma MCP rules

How an agent reads Atomus designs through the Figma MCP server: modes on the top frame, Code Connect first, variables to tokens, never paste hex.

Code Connect mappings

All 21 React components are mapped to their Figma component sets, ready to publish to Dev Mode.

Atomus MCP server

Components, props, tokens by intent, page patterns, Figma to code, validation, setup files and brand ramps as MCP tools. [Set it up](https://docs.atomus.io/ai/mcp/).

ESLint and Stylelint rules

The Atomus rules as lint rules for editors, CI and agent loops, with SARIF output. [Lint rules](https://docs.atomus.io/ai/lint/).

shadcn registry

Every component, four app screens, an AI chat block and 30 website sections as source, for the shadcn CLI, the shadcn MCP server and v0. [Registry](https://docs.atomus.io/ai/registry/).

Storybook

Stories for every React component with theme, brand and radius switches, a component manifest and an MCP server for agents.

Agent kit

12 components for AI products — prompt input, messages, streaming text, reasoning, tool calls, approvals, citations, suggestions, model selector, feedback, AI label and context meter — on the same tokens and modes. See the [Conversation](https://docs.atomus.io/components/ai-conversation/) demo.

## Coming next

| What                                                                        | Status                                                                                                                                                                                                   |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **npm packages** `@stanvision/atomus-react` and `@stanvision/atomus-tokens` | Publishing soon. Until then, install from the [repo](https://github.com/StanVisionAgency/atomus).                                                                                                        |
| **Figma Make kit**                                                          | After the npm packages publish. See [Figma Make kit](https://docs.atomus.io/ai/figma-make/).                                                                                                             |
| **Evals results**                                                           | The [evals harness](https://docs.atomus.io/ai/evals/) scores agent output against the rules (real imports and props, lint, axe, no raw hex). The first scorecard per agent is coming with the first run. |

## Start here

[Claude Code, Cursor and Copilot](https://docs.atomus.io/ai/coding-agents/) Install the skill, add the AGENTS.md template, validate the output.

[Atomus MCP server](https://docs.atomus.io/ai/mcp/) Components, tokens, patterns and validation as tools, local or remote.

[Figma MCP and Code Connect](https://docs.atomus.io/ai/figma-mcp/) Turn Atomus designs into Atomus code, not div soup.

[llms.txt](https://docs.atomus.io/ai/llms-txt/) Give any LLM the whole documentation as Markdown.

[shadcn registry, MCP and v0](https://docs.atomus.io/ai/registry/) Install Atomus components, screens and sections as source with shadcn add.

[Agent compatibility (evals)](https://docs.atomus.io/ai/evals/) 50 prompts and six deterministic scorers, with and without the skill and MCP server.

[Rules for agents](https://docs.atomus.io/ai/rules/) The core rules and the forbidden list every Atomus agent follows.

---

# Claude Code, Cursor and Copilot

> Set up coding agents to build UI with Atomus — the Atomus skill, the AGENTS.md template, docs for agents and the validator.

URL: https://docs.atomus.io/ai/coding-agents/

Three pieces make a coding agent reliable with Atomus. The **skill** gives it the knowledge, the **AGENTS.md rules** make it follow it in your repo, and the **validator** catches what slips through.

1. **Install the Atomus skill**

   The skill follows the open [Agent Skills](https://agentskills.io/) format, so it works in Claude Code, Cursor, Copilot, Codex and other compatible agents.

   ```bash
   npx skills add StanVisionAgency/atomus
   ```

   Or copy it by hand (Claude Code, all projects):

   ```bash
   git clone --depth 1 https://github.com/StanVisionAgency/atomus.git /tmp/atomus
   mkdir -p ~/.claude/skills && cp -R /tmp/atomus/skills/atomus ~/.claude/skills/
   ```

   For one project, copy it to `.claude/skills/atomus` in the repo and commit it, so the whole team gets it.

2. **Add the Atomus rules to your repo**

   Copy [`templates/consumer/AGENTS.atomus.md`](https://github.com/StanVisionAgency/atomus/blob/main/templates/consumer/AGENTS.atomus.md) into your product repo. Append it to `AGENTS.md`, or save it next to it and link it. Each tool reads it from a different place:

   Claude Code reads `CLAUDE.md`. Point it at the shared file:

   ```md
   See @AGENTS.md and @AGENTS.atomus.md.
   ```

   Cursor reads `AGENTS.md` and `.cursor/rules/*.mdc`. To scope the rules to UI code, add a rule:

   ```md
   ---
   description: Atomus UI rules
   globs: src/**/*.{tsx,jsx,css}
   ---
   Follow AGENTS.atomus.md for every component, style and screen.
   ```

   Copilot reads `.github/copilot-instructions.md` and `AGENTS.md`. Add a line to the instructions:

   ```md
   Build UI with Atomus and follow AGENTS.atomus.md.
   ```

3. **Give the agent the docs**

   Point the agent at [`https://docs.atomus.io/llms.txt`](https://docs.atomus.io/ai/llms-txt/). Every page is also available as Markdown at `…/index.md`, for example `https://docs.atomus.io/components/button/index.md`. In Cursor, add `https://docs.atomus.io/llms-full.txt` under **Docs** and mention it with `@Docs`.

4. **Validate before you merge**

   The skill ships a dependency-free validator. Ask the agent to run it, or add it to CI:

   ```bash
   node ~/.claude/skills/atomus/scripts/validate.mjs src/
   ```

   ```text
   src/Settings.tsx:12:7   error   invalid-value    <Button hierarchy="danger"> — allowed: "primary" | "secondary" | "outline" | "tertiary" | "link"
   src/Settings.tsx:18:22  error   raw-color        raw colour #18181b — same value as var(--color-text-primary) … (pick by intent)
   src/app.css:4:15        error   primitive-token  primitive --color-gray-200 — same value as var(--color-border-secondary) … (pick by intent)
   ```

## What to ask for

Agents do best with the page type and the components named. For example:

> Build a settings page with Atomus: a Page header, a Profile card with name, email and time zone fields and a Save button, and a Notifications card with toggles. Use only props from the Atomus skill and run the validator when you’re done.

The skill’s [page patterns](https://github.com/StanVisionAgency/atomus/blob/main/skills/atomus/references/patterns.md) cover the app shell, dashboard, settings, auth, table view and website sections.

## What the agent follows

- [Rules for agents](https://docs.atomus.io/ai/rules/): the core rules and the forbidden list.
- [Choosing a component](https://docs.atomus.io/components/choosing/): the catalogue, other names (dialog → Modal) and decision trees.
- The **React API** section at the end of every component page. The skill has the same tables.

## Working on Atomus itself

The Atomus repo has its own [`AGENTS.md`](https://github.com/StanVisionAgency/atomus/blob/main/AGENTS.md), with the repo map, build commands, which files are generated, and the AI policy: agents may not add tokens, disable lint rules or change thresholds without human review.

---

# Atomus MCP server

> Give Claude Code, Cursor, VS Code and Codex the Atomus components, props, tokens, patterns and validator as MCP tools — locally with npx or remotely at mcp.atomus.io.

URL: https://docs.atomus.io/ai/mcp/

The Atomus MCP server turns the design system into tools an agent calls while it works: it looks up a component’s real props before writing JSX, asks for the token that matches an intent instead of guessing a hex value, and validates every file before it hands over. It serves the same sources as these docs, bundled at build time, so it can’t drift from the release you use.

`@stanvision/atomus-mcp` publishes to npm together with `@stanvision/atomus-react` and `@stanvision/atomus-tokens`, and the remote server goes live at `mcp.atomus.io` at the same time. Until then, build it from the [repo](https://github.com/StanVisionAgency/atomus/tree/main/packages/mcp) (`cd packages/mcp && npm install && npm run build`) and point your client at `node packages/mcp/dist/stdio.js`.

## Install

The local server runs over stdio with `npx`. It needs Node 18.20 or newer.

### Claude Code

```bash
claude mcp add atomus -- npx -y @stanvision/atomus-mcp
```

Add `--scope project` to write it to `.mcp.json` for the whole team.

### Cursor

`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (all projects):

```json
{
  "mcpServers": {
    "atomus": { "command": "npx", "args": ["-y", "@stanvision/atomus-mcp"] }
  }
}
```

### VS Code (Copilot agent mode)

`.vscode/mcp.json`:

```json
{
  "servers": {
    "atomus": { "type": "stdio", "command": "npx", "args": ["-y", "@stanvision/atomus-mcp"] }
  }
}
```

### Codex

`~/.codex/config.toml`:

```toml
[mcp_servers.atomus]
command = "npx"
args = ["-y", "@stanvision/atomus-mcp"]
```

### Remote server

A read-only server with the same tools runs over Streamable HTTP at:

```text
https://mcp.atomus.io/mcp
```

```bash
claude mcp add --transport http atomus https://mcp.atomus.io/mcp
```

In Cursor and VS Code use `{ "url": "https://mcp.atomus.io/mcp" }` (VS Code: `"type": "http"`). The remote server needs no account and stores nothing. Use the local server when you work offline or want the version pinned in your `package.json`.

## Tools

| Tool                     | When the agent calls it                                                                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `atomus_get_started`     | **First**, before writing or reviewing Atomus UI. Returns the workflow, core rules, forbidden list and setup imports.                                                       |
| `atomus_list_components` | Choosing a component. The catalogue (React export or Figma-only), other names (dialog → Modal, sheet → Drawer) and the decision trees.                                      |
| `atomus_get_component`   | Before writing JSX for a component: every prop with type, values, default and Figma name, native attributes, rules, examples, Code Connect mapping and accessibility notes. |
| `atomus_find_token`      | Instead of any hex, `rgb()` or px: “supporting text” → `--color-text-secondary` with Light and Dark values. Also takes a hex, a px value or a primitive.                    |
| `atomus_get_pattern`     | Laying out a screen: app shell, dashboard, table view, settings, auth, website sections, AI chat.                                                                           |
| `atomus_figma_to_code`   | Reading a Figma instance without a Code Connect snippet: component set and property values → Atomus JSX, validated.                                                         |
| `atomus_validate`        | **Last**, on every changed file. Runs the [Atomus ESLint and Stylelint rules](https://docs.atomus.io/ai/lint/) and returns problems, suggestions and safe fixes.            |
| `atomus_init`            | Setting up a project: content for AGENTS.md, CLAUDE.md, the Cursor rule, Copilot instructions, CSS imports, lint and MCP configs. It writes nothing.                        |
| `atomus_brand`           | A client brand colour: the `[data-brand]` ramp, contrast checks and the steps for code and Figma.                                                                           |

Every tool is read-only, and every link it returns points to docs.atomus.io.

## Example session

> Build a team settings page with Atomus.

1. `atomus_get_started` → rules and workflow.
2. `atomus_get_pattern` `settings` → layout with Vertical tabs as `NavItem`s, Cards and one primary per card.
3. `atomus_get_component` `Toggle`, `Input`, `Select` → real props.
4. `atomus_find_token` “section divider” → `--color-border-secondary`.
5. `atomus_validate` on `Settings.tsx` and `settings.css` → fix, validate again.

## With the skill and AGENTS.md

The server complements the [Atomus skill and AGENTS.md rules](https://docs.atomus.io/ai/coding-agents/): the rules tell the agent to use Atomus and when to call the tools; the tools give exact answers without loading the whole reference into context. `atomus_init` returns the rules files with a short section that points agents at the server.

## Under the hood

- One manifest, `@stanvision/atomus-manifest`, generated from the TypeScript source, the Code Connect files, the guidelines and the token files. The server, the lint rules and the docs read the same data.
- The tool descriptions are imperative (“CALL THIS FIRST”, “REQUIRED FINAL STEP”) so agents call them at the right moment.
- The remote server is a Cloudflare Worker in stateless mode; `atomus_validate` runs the same ESLint rules there, and the CSS checks without Stylelint.

---

# Lint rules (ESLint and Stylelint)

> The Atomus ESLint plugin and Stylelint config catch raw colours, primitive tokens, arbitrary values, invented props, raw controls, unlabelled icon buttons and extra primary buttons — in the editor, in CI and in agent loops.

URL: https://docs.atomus.io/ai/lint/

The Atomus rules are machine-checkable, so check them by machine. Two packages run them where code is written: in the editor, in CI and in the agent’s own loop (the [MCP server’s](https://docs.atomus.io/ai/mcp/) `atomus_validate` runs the same rules). Both read the Atomus manifest, so they know every component, prop, enum value and token of the release you install.

| Package                               | For                                                                               |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| `@stanvision/eslint-plugin-atomus`    | JSX, TSX, JS and CSS-in-JS: tokens, Tailwind classes, Atomus props and components |
| `@stanvision/stylelint-config-atomus` | CSS: tokens for colour, spacing and radius                                        |

The packages publish to npm with `@stanvision/atomus-react`. Until then, use them from [`packages/`](https://github.com/StanVisionAgency/atomus/tree/main/packages) in the repo.

## ESLint

ESLint 9 or newer, flat config.

```bash
npm install -D eslint @stanvision/eslint-plugin-atomus
```

```js
import atomus from '@stanvision/eslint-plugin-atomus';
import tseslint from 'typescript-eslint'; // for .ts and .tsx

export default [
  ...tseslint.configs.recommended,
  atomus.configs.recommended, // or atomus.configs.strict: every rule an error
];
```

### no-raw-color

Hex, `rgb()`, `hsl()` and `oklch()` colours (and named colours in colour properties) in JSX `style`, SVG `fill` and `stroke`, Tailwind arbitrary values such as `bg-[#4057ff]`, and CSS-in-JS (`styled.div`, `css`). Custom-property definitions such as `--color-brand-600: #…` are token definitions and allowed. **Recommended: error.** Suggestions offer the semantic tokens with the same Light value, the ones that fit the property first (`fill` → foreground tokens).

```tsx
<p style={{ color: '#3f3f46' }}>            // ✗
<p style={{ color: 'var(--color-text-secondary)' }}>   // ✓
```

### no-primitive-token

Primitive tokens where a semantic token exists: `var(--color-gray-500)`, `--color-brand-600`, Tailwind `bg-gray-100`. **Recommended: error.** Suggestions: semantic tokens or utilities with the same value (`text-gray-500` → `text-tertiary`).

### no-arbitrary-value

Tailwind arbitrary values for spacing, radius and colour: `p-[16px]`, `gap-x-[24px]`, `rounded-[8px]`, `bg-[red]`, `[padding:10px]`. Values that use a token (`p-[var(--spacing-xl)]`) are fine; raw colours are left to `no-raw-color`. **Recommended: warn.** Autofix when a spacing value equals a spacing token (`p-[16px]` → `p-xl`); a suggestion for radius, because radius tokens follow the Radius mode.

### valid-props

Driven by the manifest: imports that `@stanvision/atomus-react` doesn’t export (Figma-only components such as `Drawer` get a hint on what to use instead), unknown props, values outside a prop’s enum, and missing required props. **Recommended: error.** Autofix for a wrong-case or Figma value (`hierarchy="Primary"` → `"primary"`); suggestions for Figma property names used as props (`Style` → `variant`) and for valid values.

```tsx
<Button hierarchy="danger">     // ✗ allowed: primary | secondary | outline | tertiary | link
<Button variant="ghost">        // ✗ <Button> has no prop "variant"
import { Drawer } from '@stanvision/atomus-react';   // ✗ Figma-only
```

### prefer-atomus-component

In files that import Atomus: raw `<button>`, `<input>` (text, checkbox, radio, date …), `<select>` and `<dialog>`. Use `Button`, `Input`, `Checkbox`, `Radio`, `Toggle`, `DatePicker`, `Select` and `Modal`. File, range, colour and hidden inputs are left alone (their Atomus components are Figma-only). **Recommended: warn.** Option: `{ allow: ['dialog'] }`.

### icon-only-needs-label

`<Button iconOnly>`, or a Button with only an icon, without `aria-label` or `aria-labelledby`. **Recommended: error.**

### one-primary-per-view

More than one `hierarchy="primary"` Button in one component. A `Modal` counts as its own view, and Buttons in the two branches of a conditional count once. **Recommended: warn.**

### Settings

```js
export default [
  atomus.configs.recommended,
  { settings: { atomus: { packages: ['@stanvision/atomus-react', '@acme/ui'] } } },
];
```

`packages` lists the import sources treated as Atomus (for a wrapper package that re-exports it).

## Stylelint

```bash
npm install -D stylelint @stanvision/stylelint-config-atomus
```

```js
export default {
  extends: ['@stanvision/stylelint-config-atomus'],
  ignoreFiles: ['src/styles/tokens.css'], // token files, if you keep any
};
```

### Stylelint: no-raw-color

`atomus/no-raw-color`: hex, `rgb()`, `hsl()`, `oklch()` and named colours anywhere except in token definitions (custom properties named `--color-*`, `--spacing-*` …, such as a `[data-brand="acme"]` block).

### Stylelint: no-primitive-token

`atomus/no-primitive-token`: `var(--color-gray-500)` and other primitives outside token definitions.

### Stylelint: use-tokens

`atomus/use-tokens`: `margin`, `padding`, `gap`, `border-radius` and colour properties must use `var(--…)` tokens, `calc()` with tokens, `0`, `auto` or a CSS keyword. `border-radius: 50%` and CSS system colours inside `@media (forced-colors: active)` are allowed. Autofix when a px value equals a spacing token: `padding: 16px` → `padding: var(--spacing-xl)`.

Both options take regexes: `tokenDefinitions` (custom properties that may hold raw values) and `allow` (extra allowed values).

## In CI, with SARIF

GitHub code scanning shows SARIF results inline on pull requests.

```bash
npm install -D @microsoft/eslint-formatter-sarif
npx eslint src -f @microsoft/eslint-formatter-sarif -o atomus-eslint.sarif
npx stylelint "src/**/*.css" --custom-formatter @stanvision/stylelint-config-atomus/sarif-formatter --output-file atomus-stylelint.sarif
```

```yaml
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: atomus-eslint.sarif
```

## Ignoring a rule

Don’t switch a rule off to make code pass. If a case is legitimate (a third-party embed that needs a raw colour, a forced-colors fallback), disable the one line with a comment that says why, and get it reviewed:

```tsx
// eslint-disable-next-line atomus/no-raw-color -- Stripe Elements needs a literal colour value
```

Disabling or weakening lint rules is one of the changes that always need human review. See the AI policy in `AGENTS.md`.

---

# Figma MCP and Code Connect

> Connect an agent to the Atomus Figma file through the Figma MCP server, and get real Atomus code out of designs with Code Connect.

URL: https://docs.atomus.io/ai/figma-mcp/

The [Figma MCP server](https://help.figma.com/hc/en-us/articles/32132100833559) lets an agent read a Figma frame (layers, variables, screenshots) and write back to the canvas. On its own it returns generic React and Tailwind with raw values. With Atomus, the agent maps that output onto Atomus components and tokens instead.

## Set it up

1. **Connect the Figma MCP server** to your agent. In Claude Code, for the remote server:

   ```bash
   claude mcp add --transport http figma https://mcp.figma.com/mcp
   ```

   Cursor, VS Code and other clients take the same URL in their MCP settings. Figma’s guide covers the desktop server too.

2. **Give the agent the Atomus rules.** Install the [Atomus skill](https://docs.atomus.io/ai/coding-agents/). Its `references/figma.md` contains the [Figma MCP rules](https://docs.atomus.io/ai/figma-mcp-rules/). Without the skill, add [`guidelines/figma-mcp-rules.md`](https://github.com/StanVisionAgency/atomus/blob/main/guidelines/figma-mcp-rules.md) to your agent’s rules.

3. **Share a frame link** from your project’s copy of the Atomus file and ask: _“Build this screen with Atomus.”_

## How the agent should read an Atomus design

- **Modes are on the top frame.** Light/Dark, Brand, Radius and Desktop/Tablet/Mobile are set once on the top frame. In code they become `data-theme`, `data-brand` and `data-radius` on the root; breakpoints are automatic.
- **Instances map to components.** A Button instance with Hierarchy=Primary and Size=md is `<Button hierarchy="primary" size="md">`. State (Hover, Focused) is never a prop.
- **Slots map to children.** Card Content, Modal Content and Dropdown menu Items become `children`, `items`, `actions` or `footer`. Atomus files don’t detach instances, so the structure is reliable.
- **Variables map to tokens.** Every Atomus variable has code syntax, so `get_variable_defs` returns the CSS name (`var(--color-text-secondary)`). The agent never copies hex values.
- **Text styles map to classes.** `Headline/H2` → `.text-headline-h2`.

The full list, including what to flag to a human, is on [Figma MCP rules](https://docs.atomus.io/ai/figma-mcp-rules/).

## Code Connect

Code Connect links each Figma component to its React component. When it is published, Dev Mode and the MCP server’s `get_design_context` return the real snippet for the selected instance:

```tsx
import { Button } from '@stanvision/atomus-react';

<Button hierarchy="primary" size="md" iconLeading={<PlusIcon />}>New project</Button>
```

- The mappings for all 21 React components are in [`react/src/components/*.figma.ts`](https://github.com/StanVisionAgency/atomus/tree/main/react/src/components), covering variant, boolean, text and instance-swap properties.
- Publishing them needs a Dev or Full seat on a **Figma Organization or Enterprise** plan: `FIGMA_ACCESS_TOKEN=… npm run figma:publish` in `react/`.
- Until they are published, the agent maps instances by name using [Choosing a component](https://docs.atomus.io/components/choosing/) and each page’s React API. That is slower but gives the same result.

## Writing to Figma

With `use_figma`, agents can also build screens in your Atomus file. The same rules apply in reverse: search the library first, insert Atomus components, set modes on the top frame, fill slots, and bind everything to variables. The [Figma MCP rules](https://docs.atomus.io/ai/figma-mcp-rules/#writing-to-figma-use_figma) list them.

---

# Figma Make kit

> Using Atomus in Figma Make — the guidelines are ready; the kit with the npm packages comes once they are published.

URL: https://docs.atomus.io/ai/figma-make/

[Figma Make](https://www.figma.com/make/) builds working prototypes from prompts. A **Make kit** gives it a design system: an npm package with the components and styles, plus guidelines that tell Make how to use them.

A Make kit installs the design system from npm. The Atomus kit will ship when `@stanvision/atomus-react` and `@stanvision/atomus-tokens` are on npm, which is coming soon.

## What’s ready

The guidelines already follow Figma’s [guidance for design-system guidelines](https://developers.figma.com/docs/code/write-design-system-guidelines/):

- **`Guidelines.md` is the entry point.** It covers what Atomus is, the reading order, the core rules and the forbidden list.
- **`setup.md`** covers install, CSS imports, theme attributes and fonts, and what Make must not configure.
- **`overview-components.md`** is the catalogue with other names and decision trees, so Make picks the right component.
- **One file per component** with imperative **Do / Forbidden** rules and the generated **React API**, so Make uses only real props.
- Plain Markdown with no JSX, split into small files Make can read on demand.

## Use it today

Until the kit ships, you can attach the guidelines yourself:

1. Download the [`guidelines/`](https://github.com/StanVisionAgency/atomus/tree/main/guidelines) folder.
2. In your Make file, add the files to the guidelines, with `Guidelines.md` at the top.
3. Add the token CSS (`css/atomus.css` from the repo) to the project’s styles, and set `data-theme`, `data-brand` and `data-radius` on the root.

Make then styles with Atomus tokens and follows the rules. It can’t import the React components until they are on npm, so expect it to rebuild simple components from tokens.

## When the kit ships

- The kit will install `@stanvision/atomus-react` and `@stanvision/atomus-tokens` and bundle the guidelines.
- This page will link the kit, and the [Overview](https://docs.atomus.io/ai/) will mark it as available.

---

# llms.txt

> The whole Atomus documentation as plain Markdown for LLMs — llms.txt, llms-full.txt, llms-small.txt, topic subsets and a Markdown twin of every page.

URL: https://docs.atomus.io/ai/llms-txt/

These docs follow the [llms.txt](https://llmstxt.org/) convention. Every file below is plain Markdown served as text, built from the same sources as the pages, so it is always current.

| URL                                                                                                    | What it is                                                                         | Use it when                                                                  |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [`/llms.txt`](https://docs.atomus.io/llms.txt)                                                         | The index: what Atomus is, the core rules for agents, and links to the files below | Giving an agent a starting point                                             |
| [`/llms-full.txt`](https://docs.atomus.io/llms-full.txt)                                               | Every page in full, as one Markdown file                                           | The agent has a large context window, or you add the docs to Cursor **Docs** |
| [`/llms-small.txt`](https://docs.atomus.io/llms-small.txt)                                             | Every page, minus notes, tips and collapsed details                                | The context window is tight                                                  |
| [`/_llms-txt/components.txt`](https://docs.atomus.io/_llms-txt/components.txt)                         | Only the component pages: Figma properties, rules and React API                    | Building UI                                                                  |
| [`/_llms-txt/foundations-and-tokens.txt`](https://docs.atomus.io/_llms-txt/foundations-and-tokens.txt) | Foundations and the code token formats                                             | Styling and theming                                                          |
| [`/_llms-txt/ai-and-agents.txt`](https://docs.atomus.io/_llms-txt/ai-and-agents.txt)                   | This section: rules, skill, Figma MCP                                              | Setting up an agent                                                          |

## A Markdown twin of every page

Every page is also available as Markdown at its URL plus `index.md`:

- `https://docs.atomus.io/components/button/` → [`https://docs.atomus.io/components/button/index.md`](https://docs.atomus.io/components/button/index.md)
- `https://docs.atomus.io/foundations/color/` → [`https://docs.atomus.io/foundations/color/index.md`](https://docs.atomus.io/foundations/color/index.md)

Fetch a twin when the agent needs one page, such as a component’s React API, without the rest of the site.

## Using them

- **Claude Code, Codex, Copilot:** say _“read <https://docs.atomus.io/llms.txt>”_, or put the link in `AGENTS.md`. The [AGENTS.md template](https://docs.atomus.io/ai/coding-agents/) already includes it.
- **Cursor:** add `https://docs.atomus.io/llms-full.txt` under **Settings → Indexing & Docs**, then mention it with `@Docs`.
- **Chat assistants:** paste the URL of `llms-small.txt` or a page’s `index.md`.

For agents that write code in your repo, the [Atomus skill](https://docs.atomus.io/ai/coding-agents/) is better than llms.txt. It loads only what the task needs and ships a validator.

---

# shadcn registry, MCP and v0

> Install Atomus components, the Agent kit, app screens and website sections as source with the shadcn CLI, let agents browse them through the shadcn MCP server, and open them in v0.

URL: https://docs.atomus.io/ai/registry/

Atomus is published as a [shadcn registry](https://ui.shadcn.com/docs/registry) at `https://docs.atomus.io/r/`. The shadcn CLI, the shadcn MCP server and v0 can install any Atomus item **as source you own**: the component code, the CSS it needs and the Atomus tokens. You don’t need the npm package for it.

| What             | Items                                                                                                                                                                                                                                        | Installs to                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| The whole system | `atomus` (base)                                                                                                                                                                                                                              | Tokens, shadcn/ui theme, fonts, base styles, `@stanvision/atomus-react` and `@stanvision/atomus-tokens`  |
| Theme            | `atomus-theme`, `atomus-tokens`                                                                                                                                                                                                              | Your CSS file: Atomus tokens, and the shadcn/ui variables (`--background`, `--primary` …) mapped to them |
| Components       | `button`, `input`, `select`, `checkbox-radio-toggle`, `date-picker`, `table`, `modal`, `toast` … (20)                                                                                                                                        | `components/atomus/<name>.tsx` + CSS in `@layer components`                                              |
| Agent kit        | `ai-prompt-input`, `ai-message`, `ai-streaming-text`, `ai-reasoning`, `ai-tool-call`, `ai-approval`, `ai-sources`, `ai-suggestions`, `ai-model-selector`, `ai-feedback`, `ai-label`, `ai-context-meter` (12, plus the `ai-internal` helpers) | `components/atomus/ai-<name>.tsx` + CSS in `@layer components`                                           |
| App screens      | `dashboard`, `settings`, `auth`, `table-view`, `ai-chat` (and `app-shell`)                                                                                                                                                                   | `components/atomus/blocks/<name>.tsx`                                                                    |
| Website sections | `hero-section`, `pricing-section`, `faq-section`, `footer` … (30)                                                                                                                                                                            | `components/atomus/sections/<name>.tsx`                                                                  |

The index of every item is [`/r/registry.json`](https://docs.atomus.io/r/registry.json). Each item has a description and install notes (`docs`), and pulls in what it depends on, so `button` also brings the tokens, fonts and shared helpers.

Atomus components install into `components/atomus/`, not `components/ui/`, so they never overwrite shadcn/ui’s own `button.tsx` or `card.tsx`. The two can live side by side: the theme makes shadcn/ui components use Atomus colours and radius too.

## Install with the shadcn CLI

You need a project with Tailwind CSS v4 and a `components.json` (run `npx shadcn@latest init` once). Then add the theme and the components you want:

```bash
npx shadcn@latest add https://docs.atomus.io/r/atomus-theme.json
npx shadcn@latest add https://docs.atomus.io/r/button.json https://docs.atomus.io/r/input.json
npx shadcn@latest add https://docs.atomus.io/r/dashboard.json
```

```tsx
import { Button } from '@/components/atomus/button';
import { Dashboard } from '@/components/atomus/blocks/dashboard';
import HeroSection from '@/components/atomus/sections/hero-section';
```

Every component and website-section page on this site has the command for its item, with a copy button and **Open in v0**.

### Use the `@atomus` namespace

Add the registry to `components.json` once, and refer to items by name:

```json
{
  "registries": {
    "@atomus": "https://docs.atomus.io/r/{name}.json"
  }
}
```

```bash
npx shadcn@latest add @atomus/atomus-theme @atomus/button @atomus/hero-section
npx shadcn@latest view @atomus/button
npx shadcn@latest search @atomus -q "date"
```

### Theme, dark mode and brand

The theme writes the Atomus tokens into your CSS file and maps the shadcn/ui variables to them. Switch modes with attributes on `<html>` (or any element), exactly as in Figma:

```html
<html data-theme="dark" data-brand="violet" data-radius="round">
```

`shadcn init` adds `@custom-variant dark (&:is(.dark *));`. To make Tailwind’s `dark:` variant follow `data-theme` as well, replace that line with:

```css
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *, .dark, .dark *));
```

### Source or package?

- **Registry (source)**: you own the code and can change it. Updates are a re-run of `shadcn add` (it asks before it overwrites a file).
- **npm package**: `npm i @stanvision/atomus-react @stanvision/atomus-tokens`, `import "@stanvision/atomus-react/styles.css"` once, and import components from `@stanvision/atomus-react`. Updates are a version bump. The `atomus` base item installs both packages.

Both are generated from the same source (`react/src`), so props and markup are identical. Don’t mix both for the same component in one app.

## Let agents use it: the shadcn MCP server

The [shadcn MCP server](https://ui.shadcn.com/docs/mcp) lets Claude Code, Cursor, VS Code and other MCP clients browse, search and install registry items from a prompt. With the `@atomus` registry in `components.json` (above), set it up once per project:

```bash
npx shadcn@latest mcp init --client claude   # or: cursor, vscode, codex, opencode
```

That writes the client’s MCP config, for example `.mcp.json` for Claude Code:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}
```

Restart the client, then ask in plain language:

- “Show me the components in the @atomus registry.”
- “Add the Atomus dashboard block and the date picker.”
- “Build a pricing page from @atomus/pricing-section and @atomus/faq-section.”

The MCP server reads each item’s description and `docs`, so the agent knows where files land and how to import them. Pair it with the [Atomus skill and rules](https://docs.atomus.io/ai/coding-agents/) so the agent also follows the usage rules: semantic tokens only, one primary button per view, props from the React API.

## Open in v0

**Open in v0** on a component or section page sends that registry item to [v0](https://v0.app) as the starting point of a new chat, with its dependencies, CSS and tokens. You can also build the link yourself:

```text
https://v0.app/chat/api/open?url=https://docs.atomus.io/r/hero-section.json
```

Ask v0 to compose pages from Atomus items (“a landing page with the Atomus hero, features, pricing and FAQ sections”), then install the result in your project with the command v0 gives you.

## Storybook

Every React component also has stories in the [Atomus Storybook](https://docs.atomus.io/storybook/) with light/dark, brand and radius switches. Storybook publishes a component manifest at [`/storybook/manifests/components.json`](https://docs.atomus.io/storybook/manifests/components.json) with the props of every component. When you run Storybook locally (`cd react && npm run storybook`), its MCP server at `http://localhost:6006/mcp` lets agents list the documented components and their stories:

```bash
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

## For maintainers

The registry source is `registry/` in the [Atomus repository](https://github.com/StanVisionAgency/atomus/tree/main/registry):

- `scripts/items.mjs` lists what ships; `atomus/blocks/` holds the app screens. Everything else is generated from the single sources: `npm run generate` copies the components from `react/src` and the website sections from the docs, cuts each component’s CSS out of `react/src/styles.css`, converts `css/atomus.css` and `shadcn/globals.css`, and writes `registry.json` (the committed item index; `npm run check` fails when it is stale) and `.build/registry.json` (the same items with their CSS).
- `npm run build` runs `shadcn build` into `sites/docs/public/r/`; `npm run validate` checks every item against the shadcn schema and checks that dependencies and imports resolve.
- `npm run test:install` installs the theme, every component and every block into a fresh Vite + Tailwind v4 app and builds it.

---

# Agent compatibility (evals)

> How Atomus measures whether coding agents build correct Atomus UI — 50 prompts, six deterministic scorers (imports, props, lint, axe, inline styles and raw colours, expectations), with and without the Atomus skill and MCP server.

URL: https://docs.atomus.io/ai/evals/

Atomus claims that agents with the skill and the [MCP server](https://docs.atomus.io/ai/mcp/) pick the right component, use only real props and tokens, and ship accessible UI. The evals turn that claim into numbers: a fixed set of prompts, deterministic scorers and a scorecard per agent and setup. They live in [`evals/`](https://github.com/StanVisionAgency/atomus/tree/main/evals) in the repo.

## Method

**Prompts.** 50 tasks, each with expectations in `evals/prompts/<id>.yaml`:

| Category      | Prompts | Examples                                                                                                                                                                            |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Components    | 35      | Button, Input, Select, Checkbox, Toggle and Radio, Modal, Table, Tabs, Alert, Badge and Tag, Card (3 each), plus Toast, Dropdown menu, Empty state, Metric card, Sidebar navigation |
| App screens   | 5       | Dashboard, settings, sign-in, users list, billing                                                                                                                                   |
| Website pages | 5       | Landing page, pricing, contact, blog index, newsletter section                                                                                                                      |
| AI chat UIs   | 5       | Basic chat, welcome state, agent with tool calls, approval, cited answer                                                                                                            |

**Setups.** Each agent runs every prompt twice, in a fresh empty workspace:

- **atomus**: the [Atomus skill](https://docs.atomus.io/ai/coding-agents/) and the Atomus MCP server are installed;
- **baseline**: neither. The agent only gets the package names in the instruction.

The instruction is the same for every agent: build the task with `@stanvision/atomus-react` and `@stanvision/atomus-tokens`, and reply with one TSX file (a default-exported component, no required props) and optional CSS.

**Scorers.** Six deterministic checks, no LLM judge. Each gives a score from 0 to 1 and a list of issues; a prompt is **clean** when no scorer reports an error.

| Scorer                        | Checks                                                                                                                                                                                                                  |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Import match                  | Imports come from `@stanvision/atomus-react` (real exports, no deep imports, no Figma-only components) and the tokens package; no other UI kit; the expected components are imported.                                   |
| Props and enums               | Every prop on an Atomus component exists and every enum value is allowed, checked against the [component manifest](https://docs.atomus.io/ai/mcp/) with the `valid-props` [lint rule](https://docs.atomus.io/ai/lint/). |
| Lint                          | The Atomus ESLint rules on the TSX and the Atomus Stylelint config on the CSS: raw colours, primitive tokens, arbitrary values, raw controls, unlabelled icon buttons, extra primary buttons.                           |
| Accessibility                 | The output is server-rendered with React, hydrated in Chromium with the Atomus CSS, and checked with axe-core (WCAG 2.2 A and AA) in Light and Dark. An output that doesn’t build or render scores 0.                   |
| Inline styles and raw colours | `style={…}` attributes and hex, `rgb()` or `hsl()` colours in the code and CSS.                                                                                                                                         |
| Expectations                  | The prompt’s own checks: components rendered, prop values, at most one primary button, raw HTML elements an Atomus component replaces, required text.                                                                   |

The scorers are tested against six hand-written outputs (three good, three bad) in `evals/fixtures/`, so a scorer change that stops catching a known mistake fails CI.

## How to run

```bash
cd evals
npm install && npm run setup
npm test                                                     # scorers against the fixtures
npm run generate -- --agent claude-code --variant atomus     # claude -p with the skill and MCP server
npm run generate -- --agent claude-code --variant baseline   # without them
npm run score -- runs/claude-code-atomus-2026-10-08          # writes scorecard.json + scorecard.md
```

Other CLI agents work through `--agent command --cmd '…{prompt_file}…'`. Cursor and GitHub Copilot have no batch mode: `--agent manual` writes the 50 instructions to paste one by one, and you save each reply as `<prompt-id>.tsx` in the run folder. The [README](https://github.com/StanVisionAgency/atomus/blob/main/evals/README.md) has the details. In CI, the **Evals** workflow runs on demand only.

## Scorecard format

Each run folder gets `scorecard.json` and `scorecard.md`:

- **Totals**: overall score (mean of all prompts), prompts clean, errors and warnings, axe violations, inline styles, raw colours, missing outputs.
- **By scorer** and **by category**: mean scores.
- **Per prompt**: the six scores and every issue with its line, so a low score points at the exact mistake.

The JSON carries the agent, setup, model and date of the run, and a scorecard version; scores from different versions are not compared.

## Results

| Agent          | Setup    | Model | Overall                   | Clean prompts | Date |
| -------------- | -------- | ----- | ------------------------- | ------------- | ---- |
| Claude Code    | atomus   | —     | Coming with the first run | —             | —    |
| Claude Code    | baseline | —     | Coming with the first run | —             | —    |
| Cursor         | atomus   | —     | Coming with the first run | —             | —    |
| GitHub Copilot | atomus   | —     | Coming with the first run | —             | —    |

Results are published here with the run folder in the repo, so anyone can rescore them.

---

# Rules for agents

> The entry point agents read: what Atomus is, the reading order, the core rules and the forbidden list.

URL: https://docs.atomus.io/ai/rules/

This page is [`guidelines/Guidelines.md`](https://github.com/StanVisionAgency/atomus/blob/main/guidelines/Guidelines.md), the entry point for AI agents and Figma Make. The Atomus skill, `AGENTS.md` and the Cursor and Copilot rules all use these rules.

Start here. This folder teaches AI agents (Claude Code, Cursor, Copilot, Figma Make, the Figma MCP server, v0) and people how to build UI with **Atomus 4.0**, and what not to do.

## What Atomus is

Atomus is one design system for **product UI** and **marketing websites**, built by StanVision. It has four layers that share one set of names:

- **Figma file**: about 140 component sets, 30 responsive website sections and 13 example pages, all bound to 671 variables with Light/Dark, Brand, Radius and Desktop/Tablet/Mobile modes. The file is sold separately at <https://stanvision.gumroad.com/l/atomus-design-system>.
- **Design tokens** (`@stanvision/atomus-tokens`): W3C DTCG JSON, plain CSS custom properties, a Tailwind v4 theme and a shadcn/ui theme. Every CSS name matches the code syntax in Figma Dev Mode.
- **React components** (`@stanvision/atomus-react`): 21 accessible components whose props mirror the Figma properties (Hierarchy → `hierarchy`, Size → `size`, Style → `variant`), plus the **Agent kit** for AI products (`components/ai-*.md`: Prompt input, Message, Streaming text, Reasoning, Tool call, Approval, Sources, Suggestions, Model selector, Feedback, AI label, Context meter).
- **These guidelines**: plain Markdown, also published at <https://docs.atomus.io> with an `llms.txt` index.

The code and guidelines are MIT-licensed. If something you need is not in Atomus, compose it from Atomus components and tokens, or ask a human. Never invent a new component API, token or style.

## Reading order

1. **[`Guidelines.md`](https://docs.atomus.io/ai/rules/)** (this file): the core rules and the forbidden list.
2. **[`setup.md`](https://github.com/StanVisionAgency/atomus/blob/main/guidelines/setup.md)**: install, CSS imports, theme attributes and fonts, plus what you must not configure.
3. **[`overview-components.md`](https://docs.atomus.io/components/choosing/)**: every component in one table, alternative names (dialog → Modal) and decision trees (Alert vs Toast vs Banner vs Modal …). Read it before you choose a component.
4. **`foundations/`**: `color.md` (semantic tokens, Light and Dark), `typography.md`, `spacing-layout.md`, `radius-effects.md`, `icons.md`, `theming.md`.
5. **`components/<name>.md`**: read the file of every component you use. Each one has the Figma properties, **Do** / **Forbidden** rules, and a generated **React API** section with every prop, type and default.
6. **[`website-sections.md`](https://docs.atomus.io/website-sections/)**: marketing sections and how to assemble pages.
7. **[`figma-mcp-rules.md`](https://docs.atomus.io/ai/figma-mcp-rules/)**: rules for reading Atomus Figma designs through the Figma MCP server.

Read files when you need them. Don’t load the whole folder at once.

## Core rules

1. **Search before you write.** Before you build anything, look it up in [`overview-components.md`](https://docs.atomus.io/components/choosing/) and read the component’s guideline file. Use the Atomus component when one exists.
2. **Never invent props.** Use only the props, values and defaults listed in a component’s **React API** section. If you need a prop that is not there, compose around the component or ask a human.
3. **Tokens, not values.** Every colour, space, radius, shadow and text size comes from a semantic token: `var(--color-text-primary)`, `var(--spacing-xl)`, `var(--radius-md)`, or Tailwind `text-primary`, `bg-secondary`, `border-primary`. Never raw hex, `rgb()` or a primitive such as `--color-gray-500`.
4. **Roles, not hues.** Pick colours by job: `text-secondary` for supporting copy, `bg-brand-solid` for the main action, `border-secondary` for cards. Dark mode and brands then work automatically.
5. **One primary per view.** A screen, modal or card has at most one `hierarchy="primary"` button: the main action. Put it last in a group, after Cancel.
6. **8-point spacing.** Inside components use `--spacing-*` (2–24px); between blocks and sections use `--layout-*` (24–240px, responsive).
7. **Shared control heights.** Buttons, inputs and selects share sm 32, md 40 and lg 48. Match sizes in one row.
8. **Slots, not detaching.** Put custom content into a component’s slot (`children`, `footer`, `actions`, the Content slot in Figma). Never copy a component’s markup to change it.
9. **Theme with attributes.** Switch `data-theme`, `data-brand` and `data-radius` on an element (code) or the mode on the top frame (Figma). Never on single layers, and never by overriding token values.
10. **Accessible by default.** Every control has a visible label or `aria-label`. Status is never colour alone: alerts and toasts carry an icon and badges keep their word. Keep the focus ring.
11. **Sentence case, verbs on buttons.** Write “Save changes”, not “OK” or “SAVE CHANGES”.
12. **Ask instead of guessing.** If the guidelines don’t cover a case, say so and propose an option built from existing components.

## Forbidden

- Never put two primary buttons in one view.
- Never use raw hex, `rgb()`, `hsl()` or named colours. Use tokens.
- Never use primitive tokens (`--color-gray-500`, `bg-gray-500`, `--color-brand-600`) where a semantic token exists.
- Never invent component props, prop values, tokens or text-style classes.
- Never import a component that is not in the React API. Figma-only components (Drawer, Command menu, Breadcrumb …) have no React export.
- Never restyle Atomus components with `className` or `style` to change colour, size, radius or font. Pick a variant.
- Never nest cards inside cards, or modals on top of modals.
- Never use placeholder text as a label.
- Never detach a Figma instance to change content. Use slots and instance swaps.
- Never set Light/Dark, Brand, Radius or breakpoint modes on individual layers.
- Never add or change tokens, disable lint rules or change thresholds without human review.

## Before you finish

- Run the Atomus validator on the files you touched: `node skills/atomus/scripts/validate.mjs <files>`. It flags raw colours, primitive tokens and unknown props or values.
- Check the view in light and dark (`data-theme="dark"`) and at mobile width (< 768px).
- Count primary buttons per view: at most one.

## Where things live

| Need                           | File                                                                                                                                                                                                                                                        |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Install and theming            | [`setup.md`](https://github.com/StanVisionAgency/atomus/blob/main/guidelines/setup.md)                                                                                                                                                                      |
| Which component?               | [`overview-components.md`](https://docs.atomus.io/components/choosing/)                                                                                                                                                                                     |
| Colour tokens (Light/Dark)     | [`foundations/color.md`](https://docs.atomus.io/foundations/color/)                                                                                                                                                                                         |
| Type, spacing, radius, shadows | [`foundations/typography.md`](https://docs.atomus.io/foundations/typography/), [`foundations/spacing-layout.md`](https://docs.atomus.io/foundations/spacing-layout/), [`foundations/radius-effects.md`](https://docs.atomus.io/foundations/radius-effects/) |
| Brand, Color and Radius modes  | [`foundations/theming.md`](https://docs.atomus.io/foundations/theming/)                                                                                                                                                                                     |
| A component’s props and rules  | `components/<name>.md`                                                                                                                                                                                                                                      |
| Marketing pages                | [`website-sections.md`](https://docs.atomus.io/website-sections/)                                                                                                                                                                                           |
| Reading Figma designs          | [`figma-mcp-rules.md`](https://docs.atomus.io/ai/figma-mcp-rules/)                                                                                                                                                                                          |
| Docs for people                | <https://docs.atomus.io> (index for agents: <https://docs.atomus.io/llms.txt>)                                                                                                                                                                              |

---

# Figma MCP rules

> Rules for agents that read Atomus designs through the Figma MCP server and turn them into code.

URL: https://docs.atomus.io/ai/figma-mcp-rules/

Generated from [`guidelines/figma-mcp-rules.md`](https://github.com/StanVisionAgency/atomus/blob/main/guidelines/figma-mcp-rules.md). Add the file to your agent’s rules, or install the [Atomus skill](https://docs.atomus.io/ai/coding-agents/), which includes it.

Rules for an agent that reads Atomus designs through the Figma MCP server (`get_design_context`, `get_screenshot`, `get_variable_defs`, `get_code_connect_map`, `search_design_system`, `use_figma`) and turns them into code, or writes designs back into Figma. Add this file to your agent’s rules next to [`Guidelines.md`](https://docs.atomus.io/ai/rules/).

The Figma MCP output is a **reference, not final code**. It describes layers in generic React and Tailwind with raw values. Your job is to rebuild the design with Atomus components and tokens.

## Files

- The Atomus library file key is `bC42e82J3PYg2LMkryodIA` (Atomus 4.0). The file is sold separately; teams work in a duplicate per client project, so the key in a link you are given is usually that duplicate. Parse it from the URL: `figma.com/design/<fileKey>/<name>?node-id=<a-b>` → node id `a:b`.
- Code Connect mappings live in `react/src/components/*.figma.ts`. When they are published, `get_design_context` returns the real `@stanvision/atomus-react` snippet for each mapped instance.

## Workflow: Figma to code

1. **Get the context.** Call `get_design_context` for the frame you were given, and `get_screenshot` to see it. If the frame is large, call `get_metadata` first and fetch child frames one at a time.

2. **Read the modes on the top frame.** Light/Dark, Brand, Radius and Desktop/Tablet/Mobile are set on the top frame. Translate them to `data-theme`, `data-brand` and `data-radius` on the root element. Breakpoint modes need no attribute because the CSS handles them.

3. **Map every instance to a component.**

   - The instance has a Code Connect snippet → use it as written.
   - No snippet → match the Figma component name to [`overview-components.md`](https://docs.atomus.io/components/choosing/) and open its guideline file. Use the React export if there is one; otherwise follow the file’s “React API” note for what to compose it from.
   - It is a website section (“Hero section”, “Pricing section”) → build it from [`website-sections.md`](https://docs.atomus.io/website-sections/); keep the section order.

4. **Map properties to props.** Use the guideline’s React API table (it lists the Figma name for each prop):

   - Variant properties become lowercase string props: Hierarchy=Primary → `hierarchy="primary"`, Size=md → `size="md"`, Style=Outlined → `variant="outlined"`.
   - **State is not a prop.** Hover, Focused and Active come from CSS. Disabled → `disabled`, Loading → `loading`, Error → `error="…message"`, Selected/Active → the component’s selection prop (`value`, `active`).
   - Boolean + instance-swap pairs (Leading icon + Leading icon swap) → one prop with an icon node (`iconLeading={<Icon />}`). Off → omit the prop.
   - Text properties (Label, Title, Description) → `children` or the prop with that name.
   - Slot content (Content, Items, Actions) → `children`, `items`, `actions`, `footer`.

5. **Map variables to tokens.** Call `get_variable_defs` and use the variable’s code syntax. It is the CSS name: `Text/text-primary` → `var(--color-text-primary)`, `Background/bg-brand-solid_hover` → `var(--color-bg-brand-solid-hover)`, `Spacing/spacing-xl` → `var(--spacing-xl)`, `Layout/layout-md` → `var(--layout-md)`, `radius-md` → `var(--radius-md)`.

6. **Map text styles to classes.** Figma text style `Headline/H2` → `.text-headline-h2`; `Content/Body` → `.text-content-body`; `Web/Heading lg` → `.text-web-heading-lg`. The full list is in [`foundations/typography.md`](https://docs.atomus.io/foundations/typography/).

7. **Lay out with tokens.** Turn auto layout into flex/grid with `gap` and `padding` from `--spacing-*` (inside components) and `--layout-*` (between blocks). Use the Desktop frame (1440) for structure and check the Tablet (768) and Mobile (375) frames for what changes.

8. **Validate.** Run `node skills/atomus/scripts/validate.mjs <files>` and compare your result with the screenshot in light and dark.

## Always

- Use Atomus components for every instance of an Atomus component, even when the MCP output inlines it as divs.
- Use semantic tokens for every colour, gap, padding, radius, shadow and font size.
- Keep one primary button per view. If the design shows two, flag it.
- Keep icons as icon components from your icon library (Font Awesome names match the Figma icon names). Download image assets only for photos and illustrations.
- Keep labels, `aria-label`s and alt text, even when the design hides the label.

## Never

- Never copy hex values, pixel paddings or font sizes from the MCP output. Map them to tokens. If a value has no token, the layer is probably detached: flag it.
- Never reproduce a component’s internals (its padding, border, radius) with divs and utility classes.
- Never invent props from Figma property names that are not in the React API (for example a `state` prop). Check the guideline file.
- Never use absolute positioning from the frame coordinates for layout.
- Never set themes per element to match a single layer’s mode. Modes belong on the top frame / root.
- Never ship the MCP output’s generated Tailwind classes (`bg-[#4057ff]`, `p-[17px]`) as they are.

## When the design is off-system

Flag these to a human instead of guessing:

- Detached instances, or layers named `Frame 123` that look like components.
- Raw colours or sizes with no matching variable.
- A component or variant that is not in the guidelines.
- Two primary buttons in one view, or text that fails contrast.

## Writing to Figma (`use_figma`)

- Call `search_design_system` first and insert Atomus components from the library. Never draw a component from rectangles and text.
- Set Light/Dark, Brand, Radius and breakpoint modes on the top frame only.
- Fill slots and use instance swaps for icons; never detach.
- Bind every fill, stroke, gap, padding, radius and text style to Atomus variables and styles.
- Build pages from website sections (Desktop 1440, Tablet 768, Mobile 375) and keep one Breakpoint variant per frame.