# Atomus

> Atomus 4.0 is a design system for product UI and marketing websites by StanVision, built for humans and agents: a Figma file, design tokens (`@stanvision/atomus-tokens`: CSS, Tailwind v4, shadcn/ui, DTCG JSON) and React components (`@stanvision/atomus-react`) whose props mirror the Figma properties.

Rules for agents building with Atomus:

- Search before you write: pick components with "Choosing a component" and use only the props in each component page's "React API" section. Never invent props or import components that are not listed.
- Use semantic tokens only (`var(--color-text-primary)`, `var(--spacing-xl)`, Tailwind `text-primary`), never raw hex or primitives such as `--color-gray-500`.
- One primary button per view; put custom content in slots instead of copying component markup.
- Theme with `data-theme`, `data-brand` and `data-radius` attributes; never override token values.

Every page is also available as Markdown at its URL plus `index.md` (for example https://docs.atomus.io/components/button/index.md). The source guidelines and the Atomus agent skill (`npx skills add StanVisionAgency/atomus`) are at https://github.com/StanVisionAgency/atomus.

## Documentation sets

- [Full documentation](https://docs.atomus.io/llms-full.txt): every page in one file
- [Abridged documentation](https://docs.atomus.io/llms-small.txt): every page without notes, tips and collapsed details
- [Components](https://docs.atomus.io/_llms-txt/components.txt): every component page: Figma properties, usage rules and React API
- [Foundations and tokens](https://docs.atomus.io/_llms-txt/foundations-and-tokens.txt): colour, type, spacing, radius, icons, theming and the code token formats
- [AI and agents](https://docs.atomus.io/_llms-txt/ai-and-agents.txt): rules for agents, the skill, the Atomus MCP server, lint rules, the shadcn registry, evals, Figma MCP and llms.txt

## Start here

- [Atomus 4.0](https://docs.atomus.io/index.md): One design system for product UI and marketing websites, built for humans and agents — Figma file, design tokens, React components, guidelines and an agent skill.
- [Getting started](https://docs.atomus.io/getting-started/index.md): Use Atomus in Figma, in code, or both.
- [Figma file](https://docs.atomus.io/figma/index.md): How the Atomus 4.0 Figma file is organised and how to work with it.
- [React](https://docs.atomus.io/react/index.md): @stanvision/atomus-react — accessible React components whose props match the Figma properties.
- [Changelog](https://docs.atomus.io/changelog/index.md): What changed in Atomus 4.0.

## Foundations

- [Colour](https://docs.atomus.io/foundations/color/index.md)
- [Typography](https://docs.atomus.io/foundations/typography/index.md)
- [Spacing, layout and breakpoints](https://docs.atomus.io/foundations/spacing-layout/index.md)
- [Radius and effects](https://docs.atomus.io/foundations/radius-effects/index.md)
- [Icons](https://docs.atomus.io/foundations/icons/index.md)
- [Theming](https://docs.atomus.io/foundations/theming/index.md)

## Components

- [Components](https://docs.atomus.io/components/index.md): Every Atomus component: live React demos, the Figma properties and variants, and usage guidance on one page.
- [Choosing a component](https://docs.atomus.io/components/choosing/index.md): Every Atomus component with its purpose and React export, other names, and decision trees.
- [Button](https://docs.atomus.io/components/button/index.md): Triggers an action. Five hierarchies, five sizes from 24 to 56px.
- [Button group](https://docs.atomus.io/components/button-group/index.md): Connected buttons for switching views or filters.
- [Input](https://docs.atomus.io/components/input/index.md): Single-line text field with label, hint and error. Heights match Button.
- [Select](https://docs.atomus.io/components/select/index.md): Pick one value from a list. Keyboard and screen-reader ready.
- [Checkbox, Radio & Toggle](https://docs.atomus.io/components/checkbox-radio-toggle/index.md): Selection controls in two sizes.
- [Date picker](https://docs.atomus.io/components/date-picker/index.md): A date field with a calendar; single dates or ranges.
- [Slider](https://docs.atomus.io/components/slider/index.md): Slider for a single value or a range.
- [File upload](https://docs.atomus.io/components/file-upload/index.md): A drop zone and upload rows with progress, success and error states.
- [Color picker](https://docs.atomus.io/components/color-picker/index.md): Saturation area, hue slider, eyedropper, hex field and presets.
- [Text editor](https://docs.atomus.io/components/text-editor/index.md): Rich text editor shell.
- [Alert](https://docs.atomus.io/components/alert/index.md): Inline messages about a page, section or form.
- [Toast](https://docs.atomus.io/components/toast/index.md): Short floating confirmations with auto-dismiss.
- [Banner](https://docs.atomus.io/components/banner/index.md): Full-width announcement bar.
- [Notifications](https://docs.atomus.io/components/notifications/index.md): Dropdown panel for the bell icon: header, tabs, rows, footer link.
- [Progress bar](https://docs.atomus.io/components/progress-bar/index.md): Progress of a known task or quota.
- [Loading & skeleton](https://docs.atomus.io/components/loading-skeleton/index.md): Spinners for short waits and skeletons that hold the layout while content loads.
- [Empty state](https://docs.atomus.io/components/empty-state/index.md): Fills empty pages and tables, and says what to do next.
- [Navigation](https://docs.atomus.io/components/navigation/index.md): App header, sidebar and nav items.
- [Tabs](https://docs.atomus.io/components/tabs/index.md): Switch between views. Underline, pill or segmented.
- [Breadcrumb](https://docs.atomus.io/components/breadcrumb/index.md): Breadcrumb trail; last segment is Current.
- [Pagination & carousel](https://docs.atomus.io/components/pagination/index.md): Pagination for tables and lists, and carousel controls for marketing galleries.
- [Progress steps](https://docs.atomus.io/components/progress-steps/index.md): Multi-step flow indicator for onboarding, checkout and setup wizards.
- [Table](https://docs.atomus.io/components/table/index.md): Rows of records with sorting and selection.
- [Badge & Tag](https://docs.atomus.io/components/badge-tag/index.md): Status labels and removable chips.
- [Avatar](https://docs.atomus.io/components/avatar/index.md): People and workspaces, 24 to 64px, with initials fallback and status.
- [Metric card](https://docs.atomus.io/components/metric-card/index.md): A single KPI for dashboards.
- [Activity item](https://docs.atomus.io/components/activity-item/index.md): A feed or notification row: who did what, and when.
- [Code snippet](https://docs.atomus.io/components/code-snippet/index.md): Copyable code, Roboto Mono.
- [Tree view](https://docs.atomus.io/components/tree-view/index.md): Nested, expandable lists for files, folders and navigation hierarchies.
- [Messaging](https://docs.atomus.io/components/messaging/index.md): Chat panel: header, Messages slot, composer.
- [Modal](https://docs.atomus.io/components/modal/index.md): A dialog that blocks the page until the person decides.
- [Dropdown menu](https://docs.atomus.io/components/dropdown-menu/index.md): A list of actions that opens from a button.
- [Tooltip & popover](https://docs.atomus.io/components/tooltip-popover/index.md): Dark tooltip; arrow None, Top, Bottom, Left, Right.
- [Drawer & slideout](https://docs.atomus.io/components/drawer/index.md): Panel from right, left or bottom (mobile sheet); content is a slot.
- [Command menu](https://docs.atomus.io/components/command-menu/index.md): ⌘K command palette; results are a slot.
- [Card](https://docs.atomus.io/components/card/index.md): Groups related content and actions. Outlined, elevated or filled.
- [Headers & dividers](https://docs.atomus.io/components/headers-dividers/index.md): Top of an app page: breadcrumb, title, description, actions, divider or tabs.
- [Atomus icons](https://docs.atomus.io/components/atomus-icons/index.md): Icon sets beyond the UI icons: featured icons, brand and payment marks, flags, file types, folders, integrations and star ratings.
- [Shared assets](https://docs.atomus.io/components/shared-assets/index.md): Mockups and annotation kit used across product and marketing files: credit card, video player, email template, status tags and spec annotations.
- [Charts](https://docs.atomus.io/components/charts/index.md): Line, bar, pie, radar and gauge charts for dashboards and reports, with a shared legend item.
- [Conversation](https://docs.atomus.io/components/ai-conversation/index.md): A full AI conversation built from the Agent kit: welcome state, reasoning, a tool call, an approval and a cited answer.
- [Prompt input](https://docs.atomus.io/components/ai-prompt-input/index.md): The composer of an AI chat: auto-growing text, attachments, a toolbar slot, send and stop, and / or @ menus.
- [Message](https://docs.atomus.io/components/ai-message/index.md): One turn in a conversation, with the speaker, status, actions and branches.
- [Streaming text & shimmer](https://docs.atomus.io/components/ai-streaming-text/index.md): Text that renders as it streams, with a caret and calm screen-reader announcements, and a shimmer for status lines.
- [Reasoning](https://docs.atomus.io/components/ai-reasoning/index.md): A collapsible “Thought for 12s” disclosure with the agent’s steps.
- [Tool call](https://docs.atomus.io/components/ai-tool-call/index.md): One function call by the agent: name, status, duration, input and output.
- [Approval](https://docs.atomus.io/components/ai-approval/index.md): Human-in-the-loop confirmation before an agent acts: approve, deny, or edit then approve.
- [Sources & citations](https://docs.atomus.io/components/ai-sources/index.md): Numbered inline citations with preview cards, and the list of sources behind an answer.
- [Suggestions](https://docs.atomus.io/components/ai-suggestions/index.md): Follow-up prompts as chips and prompt starters as cards, to send or insert.
- [Model selector](https://docs.atomus.io/components/ai-model-selector/index.md): A Select for AI models with provider icons, descriptions and capability badges.
- [Feedback](https://docs.atomus.io/components/ai-feedback/index.md): Thumbs up and down on an AI reply, with an optional reason form.
- [AI label](https://docs.atomus.io/components/ai-label/index.md): Marks AI-generated content and opens an explainability popover, with Revert to AI after edits.
- [Context meter](https://docs.atomus.io/components/ai-context-meter/index.md): How much of the model’s context window a conversation uses, and what it cost.

## Website sections

- [Website sections](https://docs.atomus.io/website-sections/index.md): Responsive marketing sections and example pages in the Atomus Figma file, with live previews.

## Code

- [Design tokens](https://docs.atomus.io/code/tokens/index.md): W3C DTCG token files generated from the Figma variables.
- [CSS](https://docs.atomus.io/code/css/index.md): atomus.css — every token as a CSS custom property, with theme, brand, radius and breakpoint switches.
- [Tailwind CSS v4](https://docs.atomus.io/code/tailwind/index.md): The Atomus theme for Tailwind v4 with semantic utilities.
- [shadcn/ui](https://docs.atomus.io/code/shadcn/index.md): Map shadcn/ui's theme variables onto Atomus tokens.

## AI & agents

- [Atomus is built for humans and agents](https://docs.atomus.io/ai/index.md): 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.
- [Claude Code, Cursor and Copilot](https://docs.atomus.io/ai/coding-agents/index.md): Set up coding agents to build UI with Atomus — the Atomus skill, the AGENTS.md template, docs for agents and the validator.
- [Atomus MCP server](https://docs.atomus.io/ai/mcp/index.md): 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.
- [Lint rules (ESLint and Stylelint)](https://docs.atomus.io/ai/lint/index.md): 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.
- [Figma MCP and Code Connect](https://docs.atomus.io/ai/figma-mcp/index.md): Connect an agent to the Atomus Figma file through the Figma MCP server, and get real Atomus code out of designs with Code Connect.
- [Figma Make kit](https://docs.atomus.io/ai/figma-make/index.md): Using Atomus in Figma Make — the guidelines are ready; the kit with the npm packages comes once they are published.
- [llms.txt](https://docs.atomus.io/ai/llms-txt/index.md): 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.
- [shadcn registry, MCP and v0](https://docs.atomus.io/ai/registry/index.md): 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.
- [Agent compatibility (evals)](https://docs.atomus.io/ai/evals/index.md): 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.
- [Rules for agents](https://docs.atomus.io/ai/rules/index.md): The entry point agents read: what Atomus is, the reading order, the core rules and the forbidden list.
- [Figma MCP rules](https://docs.atomus.io/ai/figma-mcp-rules/index.md): Rules for agents that read Atomus designs through the Figma MCP server and turn them into code.

## Optional

- [Guidelines (Markdown source)](https://github.com/StanVisionAgency/atomus/tree/main/guidelines): the plain-Markdown guidelines these docs are built from
- [Atomus agent skill](https://github.com/StanVisionAgency/atomus/tree/main/skills/atomus): install with `npx skills add StanVisionAgency/atomus`