This is the full documentation for 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.
---
# Atomus 4.0
> 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.
URL: https://docs.atomus.io/
Figma library
\~140 component sets, 30 responsive website sections and 13 example pages, all on 671 variables with Light/Dark, brand, radius and breakpoint modes.
Design tokens
W3C DTCG JSON, plain CSS, a Tailwind v4 theme and a shadcn/ui theme, generated from the Figma variables, with the same names as Dev Mode.
React components
`@stanvision/atomus-react`: 21 accessible components whose props match the Figma properties one to one, plus the [Agent kit](https://docs.atomus.io/components/ai-conversation/) for AI products.
Built for agents
Guidelines, an agent skill, `AGENTS.md` rules and `llms.txt` teach Claude Code, Cursor, Copilot, Figma Make and the Figma MCP to build with Atomus. See [AI & agents](https://docs.atomus.io/ai/).
## Start here
[Getting started](https://docs.atomus.io/getting-started/) Pick your path: Figma, code, or both.
[Foundations](https://docs.atomus.io/foundations/color/) Colour, type, spacing, radius, icons and theming.
[Components](https://docs.atomus.io/components/) Live React examples, Figma properties and usage rules on one page per component.
[Tokens for code](https://docs.atomus.io/code/tokens/) DTCG, CSS, Tailwind and shadcn/ui.
[AI & agents](https://docs.atomus.io/ai/) Use Atomus with Claude Code, Cursor, Copilot, Figma MCP and llms.txt.
---
# Getting started
> Use Atomus in Figma, in code, or both.
URL: https://docs.atomus.io/getting-started/
Atomus works the same way in Figma and in code: the same tokens, the same component names, the same modes. Start wherever your work starts.
1. **Get the file** from [Gumroad](https://stanvision.gumroad.com/l/atomus-design-system) and duplicate it into your team.
2. **One file per project.** Duplicate Atomus for every client project and rename it. Everything — variables, components, pages — lives in that one file.
3. **Set the brand.** In the **Brand** variable collection, add a mode and point `brand-25 … brand-950` at the client’s ramp. Every brand colour follows.
4. **Pick the shape and type.** Switch the **Radius** mode (Default, Sharp, Round) and edit the font families in **Typography**.
5. **Design.** Use the components and website sections; set Light/Dark and Desktop/Tablet/Mobile modes on the top frame. See [Figma](https://docs.atomus.io/figma/).
1) **Add the tokens.** Copy `css/atomus.css` from the [repo](https://github.com/StanVisionAgency/atomus), or use the [Tailwind v4](https://docs.atomus.io/code/tailwind/) or [shadcn/ui](https://docs.atomus.io/code/shadcn/) theme.
2) **Add the components** (optional): `@stanvision/atomus-react` from the repo’s `react/` folder. See [React](https://docs.atomus.io/react/).
3) **Theme with attributes:** `data-theme="dark"`, `data-brand="violet"`, `data-radius="round"` on any element.
4) **Set up your agents.** Install the Atomus skill (`npx skills add StanVisionAgency/atomus`) and add the Atomus rules to your repo’s `AGENTS.md`. See [AI & agents](https://docs.atomus.io/ai/).
## Principles
1. **Tokens first.** Every fill, stroke, gap, padding, radius and text size is a variable.
2. **Roles, not hues.** Colours are named by job (`text-secondary`, `bg-brand-solid`), so themes and dark mode just work.
3. **8-point grid.** Sizes are multiples of 8; 4 and 2 only for fine detail. Controls share heights: 32, 40, 48.
4. **Slots over detaching.** Open content areas are slots; icons are instance swaps.
5. **Responsive by mode.** Switch Spacing & Layout and Typography to Tablet or Mobile and layouts reflow.
---
# Figma file
> How the Atomus 4.0 Figma file is organised and how to work with it.
URL: https://docs.atomus.io/figma/
The Figma file is the source of truth. Tokens, CSS, React and these docs are all generated from it.
## Pages
| Section | Pages |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| ⬢ Getting started, ⬢ Changelog | How to use the file; what changed in each version |
| ⬢ Foundations | Colors & typography, Atomus Icons |
| ⬢ Components | 28 pages: buttons, inputs, menus, navigation, tables, charts, modals, drawers, notifications, chat, shared assets, app examples |
| ⬢ Website sections | 10 pages: header, footer, hero, features, social proof, pricing, FAQ, CTA, blog, team, contact, careers, legal, auth, and 13 example pages |
| ⬢ Utility | Brand guidelines deck, UX research, persona, social media sizes, wireframes, device frames |
Every component page starts with a doc header and a **Usage** frame (anatomy, properties, do / don’t).
## Variable collections
| Collection | Modes | Switches |
| ---------------- | --------------------------------------- | ---------------------------------------------------- |
| \_Primitives | — | 23 colour ramps (25–950), alpha ramps, size scale |
| Brand | Atomus · Example — Violet · your brands | The brand ramp |
| Color | Light · Dark | Semantic roles: text, background, border, foreground |
| Radius | Default · Sharp · Round | Corner scale |
| Spacing & Layout | Desktop · Tablet · Mobile | Layout gaps, container, section padding |
| Typography | Desktop · Tablet · Mobile | Headline sizes and families |
| Effects | Light · Dark | Elevation shadows |
Every variable has scopes, a description and **code syntax**: Dev Mode shows the same CSS name developers use.
## How we work with it
- Duplicate the file per client project, rename it, set the brand mode and fonts, then design. Atomus stays a single file on purpose — teams run 10–20 projects at once and one file per project is easier than linked libraries.
- Set modes (Light/Dark, Brand, Radius, Desktop/Tablet/Mobile) on the top frame, never on single layers.
- Put custom content in slots instead of detaching instances.
---
# React
> @stanvision/atomus-react — accessible React components whose props match the Figma properties.
URL: https://docs.atomus.io/react/
`@stanvision/atomus-react` is free and open source. Its props mirror the Figma component properties — Hierarchy → `hierarchy`, Size → `size`, Style → `variant` — so a Figma spec reads straight into code.
## Install
The package lives in the [`react/`](https://github.com/StanVisionAgency/atomus/tree/main/react) folder of the repo (npm publishing comes later).
```bash
git clone https://github.com/StanVisionAgency/atomus.git
cd atomus/react && npm install && npm run build
# then in your app
npm install ../atomus/react
```
```tsx
import '@stanvision/atomus-react/atomus.css'; // tokens and themes
import '@stanvision/atomus-react/styles.css'; // component styles
import { Button, Input, Card } from '@stanvision/atomus-react';
```
## Components
| Component | Figma component |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `Button` | Button |
| `Badge`, `Tag` | Badge, Tag |
| `Input`, `Select` | Input, Select |
| `Checkbox`, `Radio`, `Toggle` | Checkbox, Radio, Toggle |
| `Avatar` | Avatar |
| `Alert`, `Toast`, `ToastProvider` | Alert, Toast |
| `Card` | Card |
| `Tabs` | Tabs |
| `DropdownMenu`, `MenuItem` | Dropdown menu, Menu item |
| `Modal` | Modal |
| `Table` | Table header cell, Table cell |
| `DatePicker`, `Calendar` | Date input, Date picker, Calendar day |
| `AppHeader`, `SidebarNavigation`, `NavItem` | App header, Sidebar navigation, Nav item |
| `ProgressBar` | Progress bar |
| `MetricCard` | Metric card |
| `EmptyState` | Empty state |
| `PromptInput`, `Message`, `StreamingText`, `Shimmer`, `Reasoning`, `ToolCall`, `Approval`, `Sources`, `InlineCitation`, `Suggestions`, `ModelSelector`, `Feedback`, `AILabel`, `ContextMeter` | Agent kit (Figma components planned) — see [Conversation](https://docs.atomus.io/components/ai-conversation/) |
## Accessibility
- Every control has a visible label or an `aria-label`, and a focus ring (`border-focus` + `shadow-focus-ring`).
- Select, DropdownMenu, Tabs and the Calendar follow the WAI-ARIA keyboard patterns.
- Modal is the native `