This is the abridged documentation for Atomus (notes, tips and collapsed details removed). 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 `

`: focus is trapped, Esc closes, the page behind is inert. - Status is never colour alone: alerts and toasts carry an icon, badges keep their word. ## Code Connect `react/src/components/*.figma.ts` (Code Connect template files) map the components to the Figma file. Publishing it to Dev Mode needs a Figma Organization plan; until then the mapping files document the prop names. --- # Changelog > What changed in Atomus 4.0. URL: https://docs.atomus.io/changelog/ | Version | Date | Highlights | | ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 4.0 | October 2026 | Rebuilt on 671 variables with Light/Dark, Brand, Radius and Desktop/Tablet/Mobile modes; \~140 component sets; 30 website sections and 13 example pages; app examples; Usage frames on every page; DTCG tokens, CSS, Tailwind v4 and shadcn/ui themes; AI guidelines; React package with 21 components; docs at docs.atomus.io; dark-mode contrast fixes | | 3.6 | 2024 | Previous version | --- # Colour URL: https://docs.atomus.io/foundations/color/ Use **semantic tokens** only. Each has a Light and Dark value and follows the Brand collection. Names below are the CSS variables (Figma names in brackets). ## Text Text colour. `primary` for headings and body, `secondary` for supporting copy, `tertiary` for hints and meta, `placeholder` in inputs, `brand` for links/highlights, `on-brand` on brand fills. | Token | Light | Dark | | ------------------------------------------------------- | --------------- | --------------- | | `--color-text-primary` Figma: Text/text-primary | `#18181b` | `#fafafa` | | `--color-text-secondary` Figma: Text/text-secondary | `#3f3f46` | `#d4d4d8` | | `--color-text-white` Figma: Text/text-white | `#ffffff` | `#ffffff` | | `--color-text-opacity` Figma: Text/text-opacity | `#00000099` 60% | `#ffffff99` 60% | | `--color-text-link` Figma: Text/text-link | `#4057ff` | `#6e96ff` | | `--color-text-tertiary` Figma: Text/text-tertiary | `#71717a` | `#a1a1aa` | | `--color-text-placeholder` Figma: Text/text-placeholder | `#71717a` | `#a1a1aa` | | `--color-text-disabled` Figma: Text/text-disabled | `#d4d4d8` | `#52525b` | | `--color-text-brand` Figma: Text/text-brand | `#4057ff` | `#6e96ff` | | `--color-text-on-brand` Figma: Text/text-on-brand | `#ffffff` | `#ffffff` | | `--color-text-error` Figma: Text/text-error | `#be123c` | `#fda4af` | | `--color-text-warning` Figma: Text/text-warning | `#b45309` | `#fbbf24` | | `--color-text-success` Figma: Text/text-success | `#15803d` | `#49de80` | | `--color-text-brand-hover` Figma: Text/text-brand_hover | `#2335d6` | `#97bdff` | | `--color-text-inverse` Figma: Text/text-inverse | `#ffffff` | `#18181b` | | `--color-text-on-warning` Figma: Text/text-on-warning | `#18181b` | `#18181b` | ## Background Surface fills. `primary` page and cards, `secondary` sections and table headers, `tertiary` subtle fills and image placeholders, `brand-solid` primary buttons, `brand-subtle` selected/tinted areas, `overlay` behind modals. | Token | Light | Dark | | --------------------------------------------------------------------- | --------------- | --------------- | | `--color-bg-primary` Figma: Background/bg-primary | `#ffffff` | `#18181b` | | `--color-bg-primary-hover` Figma: Background/bg-primary_hover | `#fafafa` | `#27272a` | | `--color-bg-secondary` Figma: Background/bg-secondary | `#fafafa` | `#27272a` | | `--color-bg-tertiary` Figma: Background/bg-tertiary | `#f4f4f5` | `#3f3f46` | | `--color-bg-inverse` Figma: Background/bg-inverse | `#18181b` | `#ffffff` | | `--color-bg-disabled` Figma: Background/bg-disabled | `#f4f4f5` | `#27272a` | | `--color-bg-brand-solid` Figma: Background/bg-brand-solid | `#4057ff` | `#4057ff` | | `--color-bg-brand-solid-hover` Figma: Background/bg-brand-solid_hover | `#2335d6` | `#2335d6` | | `--color-bg-brand-subtle` Figma: Background/bg-brand-subtle | `#ebf5ff` | `#121f8c` | | `--color-bg-error-solid` Figma: Background/bg-error-solid | `#e11d48` | `#e11d48` | | `--color-bg-error-subtle` Figma: Background/bg-error-subtle | `#fff1f2` | `#881337` | | `--color-bg-warning-subtle` Figma: Background/bg-warning-subtle | `#fffbeb` | `#78350f` | | `--color-bg-success-subtle` Figma: Background/bg-success-subtle | `#f0fdf4` | `#14532d` | | `--color-bg-tertiary-hover` Figma: Background/bg-tertiary_hover | `#e4e4e7` | `#52525b` | | `--color-bg-warning-solid` Figma: Background/bg-warning-solid | `#f59e0b` | `#f59e0b` | | `--color-bg-success-solid` Figma: Background/bg-success-solid | `#15803d` | `#15803d` | | `--color-bg-overlay` Figma: Background/bg-overlay | `#18181bb2` 70% | `#000000b2` 70% | | `--color-bg-quaternary` Figma: Background/bg-quaternary | `#e4e4e7` | `#3f3f46` | | `--color-bg-quaternary-hover` Figma: Background/bg-quaternary_hover | `#d4d4d8` | `#52525b` | ## Border Strokes. `secondary` for cards and dividers, `primary` for inputs and outlined controls, `brand` / `focus` for selected and focused states. | Token | Light | Dark | | --------------------------------------------------------- | --------- | --------- | | `--color-border-primary` Figma: Border/border-primary | `#d4d4d8` | `#3f3f46` | | `--color-border-secondary` Figma: Border/border-secondary | `#e4e4e7` | `#27272a` | | `--color-border-disabled` Figma: Border/border-disabled | `#e4e4e7` | `#3f3f46` | | `--color-border-brand` Figma: Border/border-brand | `#4057ff` | `#6e96ff` | | `--color-border-focus` Figma: Border/border-focus | `#4c70ff` | `#6e96ff` | | `--color-border-error` Figma: Border/border-error | `#e11d48` | `#fb7185` | | `--color-border-warning` Figma: Border/border-warning | `#f59e0b` | `#fbbf24` | | `--color-border-success` Figma: Border/border-success | `#16a34a` | `#49de80` | ## Foreground Icons and graphics. Same roles as Text. | Token | Light | Dark | | ------------------------------------------------------------------- | --------- | --------- | | `--color-fg-primary` Figma: Foreground/fg-primary | `#18181b` | `#ffffff` | | `--color-fg-secondary` Figma: Foreground/fg-secondary | `#52525b` | `#d4d4d8` | | `--color-fg-tertiary` Figma: Foreground/fg-tertiary | `#71717a` | `#a1a1aa` | | `--color-fg-disabled` Figma: Foreground/fg-disabled | `#d4d4d8` | `#52525b` | | `--color-fg-brand` Figma: Foreground/fg-brand | `#4057ff` | `#6e96ff` | | `--color-fg-on-brand` Figma: Foreground/fg-on-brand | `#ffffff` | `#ffffff` | | `--color-fg-error` Figma: Foreground/fg-error | `#e11d48` | `#fb7185` | | `--color-fg-warning` Figma: Foreground/fg-warning | `#d97706` | `#fbbf24` | | `--color-fg-success` Figma: Foreground/fg-success | `#16a34a` | `#49de80` | | `--color-fg-inverse` Figma: Foreground/fg-inverse | `#ffffff` | `#18181b` | | `--color-fg-on-warning` Figma: Foreground/fg-on-warning | `#18181b` | `#18181b` | | `--color-fg-contrast` Figma: Foreground/fg-contrast | `#000000` | `#ffffff` | | `--color-fg-contrast-inverse` Figma: Foreground/fg-contrast-inverse | `#ffffff` | `#000000` | `fg-contrast` is the maximum-contrast foreground (pure black in Light, pure white in Dark) for marks that must read on any surface, such as the Stop button of the Prompt input; put `fg-contrast-inverse` on top of it. ## AI The Agent kit’s layer for AI content (see `components/ai-label.md`). Each value is the brand ramp blended with purple, so AI reads as related to the brand but distinct from it, and follows the Brand mode. Hex values below are for the Atomus brand. `bg-ai-subtle` tints AI surfaces (AI label, assistant avatar, reasoning, active citations), `border-ai` is their hairline, `text-ai` their label and accent text. `--gradient-ai` (brand-500 → purple → pink-400 at 135°; 400/300 stops in Dark) fills the AI mark, the streaming caret and the focused Prompt input border. | Token | Light | Dark | | ----------------------------------------------------- | --------- | --------------- | | `--color-bg-ai-subtle` Figma: Background/bg-ai-subtle | `#f2f5ff` | `#938efe1f` 12% | | `--color-border-ai` Figma: Border/border-ai | `#b4b9ff` | `#938efe66` 40% | | `--color-text-ai` Figma: Text/text-ai | `#4c2cd2` | `#b4b9ff` | Use the AI layer only to identify AI content. Never decorate other UI with it, and never let it be the only signal: pair it with the AI label. ## Primitives Raw ramps (`--color-gray-25 … 950`, `--color-red-*`, … `--color-alpha-black-5 … 90`) exist only to be aliased. The brand ramp is `--color-brand-25 … 950` and changes with the Brand mode. ### Brand Atomus Violet `brand` 1. 25 `#f5faff` 2. 50 `#ebf5ff` 3. 100 `#dbeaff` 4. 200 `#bed9ff` 5. 300 `#97bdff` 6. 400 `#6e96ff` 7. 500 `#4c70ff` 8. 600 `#4057ff` 9. 700 `#2335d6` 10. 800 `#1d2fb6` 11. 900 `#121f8c` 12. 950 `#0b1354` `--color-brand-25 … 950` point at `atomus-blue` by default and at `violet` under `data-brand="violet"`. ### Neutrals `gray` 1. 25 `#fdfdfd` 2. 50 `#fafafa` 3. 100 `#f4f4f5` 4. 200 `#e4e4e7` 5. 300 `#d4d4d8` 6. 400 `#a1a1aa` 7. 500 `#71717a` 8. 600 `#52525b` 9. 700 `#3f3f46` 10. 800 `#27272a` 11. 900 `#18181b` 12. 950 `#0e0e10` `blue-gray` 1. 25 `#fbfdfd` 2. 50 `#f8fafc` 3. 100 `#f1f5f9` 4. 200 `#e2e8f0` 5. 300 `#cbd5e1` 6. 400 `#94a3b8` 7. 500 `#64748b` 8. 600 `#475569` 9. 700 `#334155` 10. 800 `#1e293c` 11. 900 `#0f172a` 12. 950 `#090e19` `cool-gray` 1. 25 `#fcfdfd` 2. 50 `#f9fafb` 3. 100 `#f3f4f6` 4. 200 `#e5e7eb` 5. 300 `#d1d5db` 6. 400 `#9ca3af` 7. 500 `#6b7280` 8. 600 `#4b5563` 9. 700 `#374151` 10. 800 `#1f2937` 11. 900 `#111827` 12. 950 `#0a0e17` `true-gray` 1. 25 `#fdfdfd` 2. 50 `#fafafa` 3. 100 `#f5f5f5` 4. 200 `#e5e5e5` 5. 300 `#d4d4d4` 6. 400 `#a3a3a3` 7. 500 `#737373` 8. 600 `#525252` 9. 700 `#404040` 10. 800 `#262626` 11. 900 `#171717` 12. 950 `#0e0e0e` `warm-gray` 1. 25 `#fdfdfc` 2. 50 `#fafaf9` 3. 100 `#f5f5f4` 4. 200 `#e7e5e4` 5. 300 `#d6d3d1` 6. 400 `#a8a29e` 7. 500 `#78716c` 8. 600 `#57534e` 9. 700 `#44403c` 10. 800 `#292524` 11. 900 `#1c1917` 12. 950 `#110f0e` ### Hues `red` 1. 25 `#fff9f9` 2. 50 `#fef2f2` 3. 100 `#fee2e2` 4. 200 `#fecaca` 5. 300 `#fca5a5` 6. 400 `#f87171` 7. 500 `#ef4444` 8. 600 `#dc2626` 9. 700 `#b91c1c` 10. 800 `#991b1b` 11. 900 `#7f1d1d` 12. 950 `#4c1111` `rose` 1. 25 `#fff8f9` 2. 50 `#fff1f2` 3. 100 `#ffe4e6` 4. 200 `#fecdd3` 5. 300 `#fda4af` 6. 400 `#fb7185` 7. 500 `#f43f5e` 8. 600 `#e11d48` 9. 700 `#be123c` 10. 800 `#9f1239` 11. 900 `#881337` 12. 950 `#520b21` `pink` 1. 25 `#fef9fb` 2. 50 `#fdf2f8` 3. 100 `#fce7f3` 4. 200 `#fbcfe8` 5. 300 `#f9a8d4` 6. 400 `#f472b6` 7. 500 `#ec4899` 8. 600 `#db2777` 9. 700 `#be185d` 10. 800 `#9d174d` 11. 900 `#831843` 12. 950 `#4f0e28` `fuschia` 1. 25 `#fef9ff` 2. 50 `#fdf4ff` 3. 100 `#fae8ff` 4. 200 `#f5d0fe` 5. 300 `#f0abfc` 6. 400 `#e879f9` 7. 500 `#d946ef` 8. 600 `#c026d3` 9. 700 `#a21caf` 10. 800 `#86198f` 11. 900 `#701a75` 12. 950 `#431046` `purple` 1. 25 `#fdfaff` 2. 50 `#faf5ff` 3. 100 `#f3e8ff` 4. 200 `#e9d5ff` 5. 300 `#d8b4fe` 6. 400 `#c084fc` 7. 500 `#a855f7` 8. 600 `#9333ea` 9. 700 `#7e22ce` 10. 800 `#6b21a8` 11. 900 `#581c87` 12. 950 `#351151` `violet` 1. 25 `#faf9ff` 2. 50 `#f5f3ff` 3. 100 `#ede9fe` 4. 200 `#ddd6fe` 5. 300 `#c4b5fd` 6. 400 `#a78bfa` 7. 500 `#8b5cf6` 8. 600 `#7c3aed` 9. 700 `#6d28d9` 10. 800 `#5b21b6` 11. 900 `#4c1d95` 12. 950 `#2e1159` `indigo` 1. 25 `#f7f9ff` 2. 50 `#eef2ff` 3. 100 `#e0e7ff` 4. 200 `#c7d2fe` 5. 300 `#a5b4fc` 6. 400 `#818cf8` 7. 500 `#6366f1` 8. 600 `#4f46e5` 9. 700 `#4338ca` 10. 800 `#3730a3` 11. 900 `#312e81` 12. 950 `#1d1c4d` `blue` 1. 25 `#f7fbff` 2. 50 `#eff6ff` 3. 100 `#dbeafe` 4. 200 `#bfdbfe` 5. 300 `#93c5fd` 6. 400 `#60a5fa` 7. 500 `#3b82f6` 8. 600 `#2563eb` 9. 700 `#1d4ed8` 10. 800 `#1e40af` 11. 900 `#1e3a8a` 12. 950 `#122353` `light-blue` 1. 25 `#f7fcff` 2. 50 `#f0f9ff` 3. 100 `#e0f2fe` 4. 200 `#bae6fd` 5. 300 `#7dd3fc` 6. 400 `#38bdf8` 7. 500 `#0ea5e9` 8. 600 `#0284c7` 9. 700 `#0369a1` 10. 800 `#075985` 11. 900 `#0c4a6e` 12. 950 `#072c42` `cyan` 1. 25 `#f5ffff` 2. 50 `#ecfeff` 3. 100 `#cffafe` 4. 200 `#a5f3fc` 5. 300 `#67e8f9` 6. 400 `#22d3ee` 7. 500 `#06b6d4` 8. 600 `#0891b2` 9. 700 `#0e7490` 10. 800 `#155e75` 11. 900 `#164e63` 12. 950 `#0d2f3b` `teal` 1. 25 `#f7fefd` 2. 50 `#f0fdfa` 3. 100 `#ccfbf1` 4. 200 `#99f6e4` 5. 300 `#5eead4` 6. 400 `#2dd4bf` 7. 500 `#14b8a6` 8. 600 `#0d9488` 9. 700 `#0f766e` 10. 800 `#115e59` 11. 900 `#134e4a` 12. 950 `#0b2f2c` `emerald` 1. 25 `#f5fefa` 2. 50 `#ecfdf5` 3. 100 `#d1fae5` 4. 200 `#a7f3d0` 5. 300 `#6ee7b7` 6. 400 `#34d399` 7. 500 `#10b981` 8. 600 `#059669` 9. 700 `#047857` 10. 800 `#065f46` 11. 900 `#064e3b` 12. 950 `#042f23` `green` 1. 25 `#f7fef9` 2. 50 `#f0fdf4` 3. 100 `#dcfce7` 4. 200 `#baf7d0` 5. 300 `#85efab` 6. 400 `#49de80` 7. 500 `#22c55d` 8. 600 `#16a34a` 9. 700 `#15803d` 10. 800 `#166534` 11. 900 `#14532d` 12. 950 `#0c321b` `lime` 1. 25 `#fbfff3` 2. 50 `#f7fee7` 3. 100 `#ecfccb` 4. 200 `#d9f99d` 5. 300 `#bef264` 6. 400 `#a3e635` 7. 500 `#84cc16` 8. 600 `#65a30d` 9. 700 `#4d7c0f` 10. 800 `#3f6212` 11. 900 `#365314` 12. 950 `#20320c` `yellow` 1. 25 `#fffdf3` 2. 50 `#fefce8` 3. 100 `#fef9c3` 4. 200 `#fef08a` 5. 300 `#fde047` 6. 400 `#facc15` 7. 500 `#eab308` 8. 600 `#ca8a04` 9. 700 `#a16207` 10. 800 `#854d0e` 11. 900 `#713f12` 12. 950 `#44260b` `amber` 1. 25 `#fffdf5` 2. 50 `#fffbeb` 3. 100 `#fef3c7` 4. 200 `#fde68a` 5. 300 `#fcd34d` 6. 400 `#fbbf24` 7. 500 `#f59e0b` 8. 600 `#d97706` 9. 700 `#b45309` 10. 800 `#92400e` 11. 900 `#78350f` 12. 950 `#482009` `orange` 1. 25 `#fffbf6` 2. 50 `#fff7ed` 3. 100 `#ffedd5` 4. 200 `#fed7aa` 5. 300 `#fdba74` 6. 400 `#fb923c` 7. 500 `#f97316` 8. 600 `#ea580c` 9. 700 `#c2410c` 10. 800 `#9a3412` 11. 900 `#7c2d12` 12. 950 `#4a1b0b` ### Alpha `alpha-black` 1. 5 `#0000000d` 2. 10 `#0000001a` 3. 20 `#00000033` 4. 30 `#0000004d` 5. 40 `#00000066` 6. 50 `#00000080` 7. 60 `#00000099` 8. 70 `#000000b2` 9. 80 `#000000cc` 10. 90 `#000000e5` `alpha-white` 1. 5 `#ffffff0d` 2. 10 `#ffffff1a` 3. 20 `#ffffff33` 4. 30 `#ffffff4d` 5. 40 `#ffffff66` 6. 50 `#ffffff80` 7. 60 `#ffffff99` 8. 70 `#ffffffb2` 9. 80 `#ffffffcc` 10. 90 `#ffffffe5` --- # Typography URL: https://docs.atomus.io/foundations/typography/ Families: **Inter Display** (headlines), **Inter** (body and UI), **Roboto Mono** (code). Sizes and line heights are variables with Desktop / Tablet / Mobile values; the text styles below use them. ## Font families ### Inter Display Headlines · `--font-family-title` ABCDEFGHIJKLMNOPQRSTUVWXYZ\ abcdefghijklmnopqrstuvwxyz\ 0123456789 &@$%?! - Medium `500` - Semi Bold `600` - Bold `700` ### Inter Body and UI · `--font-family-body` ABCDEFGHIJKLMNOPQRSTUVWXYZ\ abcdefghijklmnopqrstuvwxyz\ 0123456789 &@$%?! - Light `300` - Regular `400` - Medium `500` - Semi Bold `600` - Bold `700` ### Roboto Mono Code and tokens · `.text-components-code` ABCDEFGHIJKLMNOPQRSTUVWXYZ\ abcdefghijklmnopqrstuvwxyz\ 0123456789 &@$%?! - Regular `400` - Medium `500` ## Type scale Every style below is rendered with its CSS class, so sizes switch at the tablet and mobile breakpoints like they do in product. ### Headline **Headline/Huge** `.text-headline-huge` - Desktop 120/140 - Tablet 88/100 - Mobile 56/64 - Weight SemiBold Build faster **Headline/H1** `.text-headline-h1` - Desktop 64/72 - Tablet 52/60 - Mobile 40/52 - Weight SemiBold Build faster **Headline/H2** `.text-headline-h2` - Desktop 56/64 - Tablet 44/52 - Mobile 36/48 - Weight Medium One system **Headline/H3** `.text-headline-h3` - Desktop 40/44 - Tablet 36/44 - Mobile 32/40 - Weight Medium Design that scales **Headline/H4** `.text-headline-h4` - Desktop 32/40 - Tablet 30/40 - Mobile 28/36 - Weight Medium Design that scales **Headline/H5** `.text-headline-h5` - Desktop 24/32 - Weight Medium The quick brown fox jumps over the lazy dog **Headline/H6** `.text-headline-h6` - Desktop 20/28 - Weight Medium The quick brown fox jumps over the lazy dog **Headline/Subtitle** `.text-headline-subtitle` - Desktop 12/20 - Weight Medium Design system **Headline/Overline** `.text-headline-overline` - Desktop 14/20 - Weight Bold Design system ### Content **Content/Body leading** `.text-content-body-leading` - Desktop 18/28 - Weight Medium Atomus keeps product UI and marketing websites in one design language. **Content/Body leading bold** `.text-content-body-leading-bold` - Desktop 18/28 - Weight Bold Atomus keeps product UI and marketing websites in one design language. **Content/Body** `.text-content-body` - Desktop 16/24 - Weight Regular App body copy Atomus keeps product UI and marketing websites in one design language. **Content/Body bold** `.text-content-body-bold` - Desktop 16/24 - Weight Semi Bold Atomus keeps product UI and marketing websites in one design language. **Content/Small** `.text-content-small` - Desktop 14/20 - Weight Regular Most UI text, table cells Atomus keeps product UI and marketing websites in one design language. **Content/Small Bold** `.text-content-small-bold` - Desktop 14/20 - Weight Semi Bold Atomus keeps product UI and marketing websites in one design language. **Content/Tiny** `.text-content-tiny` - Desktop 12/16 - Weight Regular Meta, captions Atomus keeps product UI and marketing websites in one design language. **Content/Tiny bold** `.text-content-tiny-bold` - Desktop 12/16 - Weight Medium Atomus keeps product UI and marketing websites in one design language. **Content/Micro** `.text-content-micro` - Desktop 10/12 - Weight Regular Atomus keeps product UI and marketing websites in one design language. **Content/Micro Bold** `.text-content-micro-bold` - Desktop 10/12 - Weight Semi Bold Atomus keeps product UI and marketing websites in one design language. ### Components **Components/Button xSmall** `.text-components-button-xsmall` - Desktop 10/12 - Weight Semi Bold Save changes **Components/Button Small** `.text-components-button-small` - Desktop 12/16 - Weight Semi Bold Save changes **Components/Button Medium** `.text-components-button-medium` - Desktop 14/16 - Weight Semi Bold Save changes **Components/Button Large** `.text-components-button-large` - Desktop 16/20 - Weight Semi Bold Save changes **Components/Button xLarge** `.text-components-button-xlarge` - Desktop 18/20 - Weight Semi Bold Save changes **Components/Input xSmall** `.text-components-input-xsmall` - Desktop 12/12 - Weight Regular you\@company.com **Components/Input Small** `.text-components-input-small` - Desktop 14/16 - Weight Regular you\@company.com **Components/Input Medium** `.text-components-input-medium` - Desktop 15/16 - Weight Regular you\@company.com **Components/Input Large** `.text-components-input-large` - Desktop 18/20 - Weight Regular you\@company.com **Components/Caption xSmall** `.text-components-caption-xsmall` - Desktop 10/12 - Weight Semi Bold Caption text **Components/Caption Small** `.text-components-caption-small` - Desktop 12/12 - Weight Medium Caption text **Components/Caption Medium** `.text-components-caption-medium` - Desktop 14/16 - Weight Semi Bold Caption text **Components/Caption Large** `.text-components-caption-large` - Desktop 16/16 - Weight Semi Bold Caption text **Components/Metric value** `.text-components-metric-value` - Desktop 36/44 - Weight Semi Bold $48.2k **Components/Code** `.text-components-code` - Desktop 14/20 - Weight Regular const theme = "dark"; ### Template **Template/Title** `.text-template-title` - Desktop 48/56 - Weight Semi Bold One system **Template/Heading** `.text-template-heading` - Desktop 24/32 - Weight Semi Bold Page/drawer titles in app The quick brown fox jumps over the lazy dog **Template/Eyebrow** `.text-template-eyebrow` - Desktop 14/20 - Weight Semi Bold Design system ### Web **Web/Display** `.text-web-display` - Desktop 64/72 - Tablet 52/60 - Mobile 40/52 - Weight Semi Bold Hero headlines Build faster **Web/Heading xl** `.text-web-heading-xl` - Desktop 56/64 - Tablet 44/52 - Mobile 36/48 - Weight Semi Bold Section titles One system **Web/Heading lg** `.text-web-heading-lg` - Desktop 40/44 - Tablet 36/44 - Mobile 32/40 - Weight Semi Bold Large card / split headings Design that scales **Web/Heading md** `.text-web-heading-md` - Desktop 32/40 - Tablet 30/40 - Mobile 28/36 - Weight Semi Bold Sub-section titles Design that scales **Web/Heading sm** `.text-web-heading-sm` - Desktop 24/32 - Weight Semi Bold Card titles, article H2 The quick brown fox jumps over the lazy dog **Web/Heading xs** `.text-web-heading-xs` - Desktop 20/28 - Weight Semi Bold Small titles, quotes The quick brown fox jumps over the lazy dog **Web/Body lg** `.text-web-body-lg` - Desktop 18/28 - Weight Regular Lead paragraphs Atomus keeps product UI and marketing websites in one design language. **Web/Body** `.text-web-body` - Desktop 16/24 - Weight Regular Website body copy Atomus keeps product UI and marketing websites in one design language. **Web/Eyebrow** `.text-web-eyebrow` - Desktop 14/20 - Weight Semi Bold Labels above headings Design system **Web/Quote** `.text-web-quote` - Desktop 20/28 - Weight Italic Atomus keeps product UI and marketing websites in one design language. --- # Spacing, layout and breakpoints URL: https://docs.atomus.io/foundations/spacing-layout/ Breakpoints: **Desktop ≥ 1024px**, **Tablet 768–1023px**, **Mobile < 768px** (Figma frames 1440 / 768 / 375). ### Inside components (padding, gaps) | Token | Desktop | Tablet | Mobile | Preview | | ---------------- | ------- | ------ | ------ | ------- | | `--spacing-none` | 0 | 0 | 0 | | | `--spacing-xxs` | 2 | 2 | 2 | | | `--spacing-xs` | 4 | 4 | 4 | | | `--spacing-sm` | 6 | 6 | 6 | | | `--spacing-md` | 8 | 8 | 8 | | | `--spacing-lg` | 12 | 12 | 12 | | | `--spacing-xl` | 16 | 16 | 16 | | | `--spacing-2xl` | 20 | 20 | 20 | | | `--spacing-3xl` | 24 | 24 | 24 | | ### Between blocks and sections | Token | Desktop | Tablet | Mobile | Preview | | -------------- | ------- | ------ | ------ | ------- | | `--layout-xs` | 32 | 32 | 24 | | | `--layout-sm` | 40 | 32 | 24 | | | `--layout-md` | 48 | 40 | 32 | | | `--layout-lg` | 56 | 48 | 32 | | | `--layout-xl` | 64 | 48 | 40 | | | `--layout-2xl` | 72 | 56 | 40 | | | `--layout-3xl` | 80 | 64 | 40 | | | `--layout-4xl` | 96 | 72 | 56 | | | `--layout-5xl` | 120 | 80 | 56 | | | `--layout-6xl` | 160 | 120 | 80 | | | `--layout-7xl` | 200 | 160 | 80 | | | `--layout-8xl` | 240 | 160 | 80 | | ### Icon size | Token | Desktop | Tablet | Mobile | Preview | | ----------- | ------- | ------ | ------ | ------- | | `--icon-xs` | 12 | 12 | 12 | | | `--icon-sm` | 16 | 16 | 16 | | | `--icon-md` | 20 | 20 | 20 | | | `--icon-lg` | 24 | 24 | 24 | | | `--icon-xl` | 32 | 32 | 32 | | ### Control height (sm 32, md 40, lg 48) | Token | Desktop | Tablet | Mobile | Preview | | ------------ | ------- | ------ | ------ | ------- | | `--size-xs` | 24 | 24 | 24 | | | `--size-sm` | 32 | 32 | 32 | | | `--size-md` | 40 | 40 | 40 | | | `--size-lg` | 48 | 48 | 48 | | | `--size-xl` | 56 | 56 | 56 | | | `--size-2xl` | 64 | 64 | 64 | | ### Page container | Token | Desktop | Tablet | Mobile | Preview | | ----------------------- | ------- | ------ | ------ | ------- | | `--container-padding` | 80 | 32 | 16 | | | `--container-max-width` | 1280 | 704 | 343 | | | `--section-padding` | 96 | 72 | 56 | | Grid styles in Figma: Desktop 12 col (gutter 32, margin 80), Tablet 8 col (24 / 32), Mobile 4 col (16 / 16), plus 8px and 4px baseline grids. --- # Radius and effects URL: https://docs.atomus.io/foundations/radius-effects/ ## Radius (modes: Default · Sharp · Round) Default **0** Sharp **0** Round **0** `--radius-none` Default **2** Sharp **0** Round **4** `--radius-xxs` Default **4** Sharp **2** Round **6** `--radius-xs` Default **6** Sharp **2** Round **8** `--radius-sm` Default **8** Sharp **4** Round **12** `--radius-md` Default **10** Sharp **4** Round **16** `--radius-lg` Default **12** Sharp **6** Round **20** `--radius-xl` Default **16** Sharp **8** Round **24** `--radius-2xl` Default **20** Sharp **10** Round **32** `--radius-3xl` Default **24** Sharp **12** Round **40** `--radius-4xl` Default **full** Sharp **full** Round **full** `--radius-full` Default **32** Sharp **16** Round **48** `--radius-5xl` Default **40** Sharp **20** Round **64** `--radius-6xl` Controls (buttons, inputs) use `radius-md`; cards `radius-xl`/`2xl`; badges and avatars `radius-full`. ## Shadows (Effects: Light · Dark) `--shadow-elevation-1 … 24`. Use 1–2 for cards, 3–4 for dropdowns and popovers, 6–8 for drawers and modals, 9+ for marketing visuals. Dark mode uses stronger, neutral shadows. 1 Cards `--shadow-elevation-1` 2 Cards `--shadow-elevation-2` 3 Dropdowns, popovers `--shadow-elevation-3` 4 Dropdowns, popovers `--shadow-elevation-4` 6 Drawers, modals `--shadow-elevation-6` 8 Drawers, modals `--shadow-elevation-8` 9 Marketing visuals `--shadow-elevation-9` 12 Marketing visuals `--shadow-elevation-12` 16 Marketing visuals `--shadow-elevation-16` 24 Marketing visuals `--shadow-elevation-24` ## Focus Focused controls get a 4px ring in `bg-brand-subtle` (`--shadow-focus-ring`) and a `border-brand` stroke; errors use `bg-error-subtle` / `border-error`. Focused input `--shadow-focus-ring` + `--color-border-brand` Invalid input `--shadow-focus-ring-error` + `--color-border-error` ## Blur Effect styles `Blur/Backdrop sm 8 · md 16 · lg 24 · xl 40` for glass overlays. 8px Effect style `Blur/Backdrop sm` `backdrop-filter: blur(8px)` 16px Effect style `Blur/Backdrop md` `backdrop-filter: blur(16px)` 24px Effect style `Blur/Backdrop lg` `backdrop-filter: blur(24px)` 40px Effect style `Blur/Backdrop xl` `backdrop-filter: blur(40px)` ## Motion Streaming motion for the Agent kit: `--motion-stream-caret-blink` (1s) is the blink period of the Streaming text caret, and `--motion-stream-shimmer-duration` (1.8s) is one sweep of the Shimmer on status text. Under `prefers-reduced-motion: reduce` both become `0s` and the components switch the animation off: the caret stays solid and the shimmer shows static text. --- # Icons URL: https://docs.atomus.io/foundations/icons/ - **UI icons**: 88 components named `icon/` (e.g. `icon/arrow-right`, `icon/magnifying-glass`). 24px frame; colour from Foreground tokens. Swap via the icon property of Button, Input, Badge, Menu item… - Because names match Font Awesome, a file can switch to Font Awesome Pro with **Swap library**. - Sizes: `icon-xs 12 · sm 16 · md 20 · lg 24 · xl 32`. - Other sets: Icon brand (44 logos), Icon payment (24), Icon flag (18), Icon file type (12 types × 2 sizes), Icon folder, Icon integration (16 app tiles), Star rating, Featured icon. - Never mix icon families; never use an icon without a label or tooltip for actions. ## Sizes `--icon-xs` 12px `--icon-sm` 16px `--icon-md` 20px `--icon-lg` 24px `--icon-xl` 32px ## Glyphs in the React package The React components ship a small set of internal glyphs (``) for checks, close buttons, status and navigation. Product icons come from the 88 `icon/*` components in Figma or Font Awesome. - `check` - `minus` - `x` - `plus` - `info` - `alert` - `success` - `search` - `folder` - `user` - `home` - `settings` - `bell` - `menu` - `more` - `calendar` - `sort` - `arrowUp` - `arrowDown` - `chevronDown` - `chevronUp` - `chevronLeft` - `chevronRight` --- # Theming URL: https://docs.atomus.io/foundations/theming/ Three collections re-theme everything without touching components. Set the mode on the top frame (Figma) or an attribute on an element (code): | Collection | Modes | Code | | ---------------------------- | ----------------------------------------- | ------------------------- | | Brand | Atomus · Example — Violet · (your brands) | `data-brand="violet"` | | Color | Light · Dark | `data-theme="dark"` | | Radius | Default · Sharp · Round | `data-radius="sharp"` | | Spacing & Layout, Typography | Desktop · Tablet · Mobile | media queries (automatic) | **Add a client brand:** add a mode to Brand, point `brand-25 … brand-950` at the client ramp (add the ramp to \_Primitives first). In CSS, copy the `[data-brand="violet"]` block. --- # Components > Every Atomus component: live React demos, the Figma properties and variants, and usage guidance on one page. URL: https://docs.atomus.io/components/ Each page shows the component live, then its Figma properties and variants, then how to use it in code, with the full React API at the end. 31 components ship in React; the rest are Figma-only for now. Not sure which one you need? See [Choosing a component](https://docs.atomus.io/components/choosing/). ## Actions [Button Triggers an action. Five hierarchies, five sizes from 24 to 56px. React + Figma](https://docs.atomus.io/components/button/) [Button group Connected buttons for switching views or filters. Figma only](https://docs.atomus.io/components/button-group/) ## Forms & inputs [Input Single-line text field with label, hint and error. Heights match Button. React + Figma](https://docs.atomus.io/components/input/) [Select Pick one value from a list. Keyboard and screen-reader ready. React + Figma](https://docs.atomus.io/components/select/) [Checkbox, Radio & Toggle Selection controls in two sizes. React + Figma](https://docs.atomus.io/components/checkbox-radio-toggle/) [Date picker A date field with a calendar; single dates or ranges. React + Figma](https://docs.atomus.io/components/date-picker/) [Slider Slider for a single value or a range. Figma only](https://docs.atomus.io/components/slider/) [File upload A drop zone and upload rows with progress, success and error states. Figma only](https://docs.atomus.io/components/file-upload/) [Color picker Saturation area, hue slider, eyedropper, hex field and presets. Figma only](https://docs.atomus.io/components/color-picker/) [Text editor Rich text editor shell. Figma only](https://docs.atomus.io/components/text-editor/) ## Feedback [Alert Inline messages about a page, section or form. React + Figma](https://docs.atomus.io/components/alert/) [Toast Short floating confirmations with auto-dismiss. React + Figma](https://docs.atomus.io/components/toast/) [Banner Full-width announcement bar. Figma only](https://docs.atomus.io/components/banner/) [Notifications Dropdown panel for the bell icon: header, tabs, rows, footer link. Figma only](https://docs.atomus.io/components/notifications/) [Progress bar Progress of a known task or quota. React + Figma](https://docs.atomus.io/components/progress-bar/) [Loading & skeleton Spinners for short waits and skeletons that hold the layout while content loads. Figma only](https://docs.atomus.io/components/loading-skeleton/) [Empty state Fills empty pages and tables, and says what to do next. React + Figma](https://docs.atomus.io/components/empty-state/) ## Navigation [Navigation App header, sidebar and nav items. React + Figma](https://docs.atomus.io/components/navigation/) [Tabs Switch between views. Underline, pill or segmented. React + Figma](https://docs.atomus.io/components/tabs/) [Breadcrumb Breadcrumb trail; last segment is Current. Figma only](https://docs.atomus.io/components/breadcrumb/) [Pagination & carousel Pagination for tables and lists, and carousel controls for marketing galleries. Figma only](https://docs.atomus.io/components/pagination/) [Progress steps Multi-step flow indicator for onboarding, checkout and setup wizards. Figma only](https://docs.atomus.io/components/progress-steps/) ## Data display [Table Rows of records with sorting and selection. React + Figma](https://docs.atomus.io/components/table/) [Badge & Tag Status labels and removable chips. React + Figma](https://docs.atomus.io/components/badge-tag/) [Avatar People and workspaces, 24 to 64px, with initials fallback and status. React + Figma](https://docs.atomus.io/components/avatar/) [Metric card A single KPI for dashboards. React + Figma](https://docs.atomus.io/components/metric-card/) [Activity item A feed or notification row: who did what, and when. Figma only](https://docs.atomus.io/components/activity-item/) [Code snippet Copyable code, Roboto Mono. Figma only](https://docs.atomus.io/components/code-snippet/) [Tree view Nested, expandable lists for files, folders and navigation hierarchies. Figma only](https://docs.atomus.io/components/tree-view/) [Messaging Chat panel: header, Messages slot, composer. Figma only](https://docs.atomus.io/components/messaging/) ## Overlays [Modal A dialog that blocks the page until the person decides. React + Figma](https://docs.atomus.io/components/modal/) [Dropdown menu A list of actions that opens from a button. React + Figma](https://docs.atomus.io/components/dropdown-menu/) [Tooltip & popover Dark tooltip; arrow None, Top, Bottom, Left, Right. Figma only](https://docs.atomus.io/components/tooltip-popover/) [Drawer & slideout Panel from right, left or bottom (mobile sheet); content is a slot. Figma only](https://docs.atomus.io/components/drawer/) [Command menu ⌘K command palette; results are a slot. Figma only](https://docs.atomus.io/components/command-menu/) ## Layout & content [Card Groups related content and actions. Outlined, elevated or filled. React + Figma](https://docs.atomus.io/components/card/) [Headers & dividers Top of an app page: breadcrumb, title, description, actions, divider or tabs. Figma only](https://docs.atomus.io/components/headers-dividers/) ## Media & assets [Atomus icons Icon sets beyond the UI icons: featured icons, brand and payment marks, flags, file types, folders, integrations and star ratings. Figma only](https://docs.atomus.io/components/atomus-icons/) [Shared assets Mockups and annotation kit used across product and marketing files: credit card, video player, email template, status tags and spec annotations. Figma only](https://docs.atomus.io/components/shared-assets/) ## Charts [Charts Line, bar, pie, radar and gauge charts for dashboards and reports, with a shared legend item. Figma only](https://docs.atomus.io/components/charts/) ## AI [Conversation A full AI conversation built from the Agent kit: welcome state, reasoning, a tool call, an approval and a cited answer. React + Figma](https://docs.atomus.io/components/ai-conversation/) [Prompt input The composer of an AI chat: auto-growing text, attachments, a toolbar slot, send and stop, and / or @ menus. React + Figma](https://docs.atomus.io/components/ai-prompt-input/) [Message One turn in a conversation, with the speaker, status, actions and branches. React + Figma](https://docs.atomus.io/components/ai-message/) [Streaming text & shimmer Text that renders as it streams, with a caret and calm screen-reader announcements, and a shimmer for status lines. React + Figma](https://docs.atomus.io/components/ai-streaming-text/) [Reasoning A collapsible “Thought for 12s” disclosure with the agent’s steps. React + Figma](https://docs.atomus.io/components/ai-reasoning/) [Tool call One function call by the agent: name, status, duration, input and output. React + Figma](https://docs.atomus.io/components/ai-tool-call/) [Approval Human-in-the-loop confirmation before an agent acts: approve, deny, or edit then approve. React + Figma](https://docs.atomus.io/components/ai-approval/) [Sources & citations Numbered inline citations with preview cards, and the list of sources behind an answer. React + Figma](https://docs.atomus.io/components/ai-sources/) [Suggestions Follow-up prompts as chips and prompt starters as cards, to send or insert. React + Figma](https://docs.atomus.io/components/ai-suggestions/) [Model selector A Select for AI models with provider icons, descriptions and capability badges. React + Figma](https://docs.atomus.io/components/ai-model-selector/) [Feedback Thumbs up and down on an AI reply, with an optional reason form. React + Figma](https://docs.atomus.io/components/ai-feedback/) [AI label Marks AI-generated content and opens an explainability popover, with Revert to AI after edits. React + Figma](https://docs.atomus.io/components/ai-label/) [Context meter How much of the model’s context window a conversation uses, and what it cost. React + Figma](https://docs.atomus.io/components/ai-context-meter/) --- # Choosing a component > Every Atomus component with its purpose and React export, other names, and decision trees. URL: https://docs.atomus.io/components/choosing/ Generated from [`guidelines/overview-components.md`](https://github.com/StanVisionAgency/atomus/blob/main/guidelines/overview-components.md). Agents read the same file before they pick a component. Use this file to pick the right component before you write code or design. For props and rules, open the component’s file in `components/`. Its **React API** section lists every prop, value and default. **React** names the export from `@stanvision/atomus-react`. “—” means the component is **Figma only**. Don’t import it in code. Compose it from tokens and the React components named in its guideline file. ## Catalogue ### Actions | Component | Use it for | React | Guideline | | ------------ | --------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------- | | Button | Triggering an action. Hierarchies primary · secondary · outline · tertiary · link; sizes xs–xl (24–56px). | `Button` | [`components/button.md`](https://docs.atomus.io/components/button/) | | Button icon | Icon-only action in toolbars and rows. Always has an `aria-label`. | `Button iconOnly` | [`components/button.md`](https://docs.atomus.io/components/button/) | | Button group | 2–5 joined, mutually exclusive options (view or filter switch). | — (use `Tabs variant="segmented"`) | [`components/button-group.md`](https://docs.atomus.io/components/button-group/) | ### Forms and inputs | Component | Use it for | React | Guideline | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------- | | Input | Single-line text, email, number, search. Sizes sm · md · lg (32 · 40 · 48). | `Input` | [`components/input-select.md`](https://docs.atomus.io/components/input/) | | Textarea | Multi-line text. | — | [`components/input-select.md`](https://docs.atomus.io/components/input/) | | Number input, Phone input, Payment input, Verification code input, Tags input | Formatted text entry. | — | [`components/input-select.md`](https://docs.atomus.io/components/input/) | | Select | One value from a list (6+ options, or when space is tight). | `Select` | [`components/input-select.md`](https://docs.atomus.io/components/input/) | | Multi-select | Several values from a list, shown as tags. | — | [`components/input-select.md`](https://docs.atomus.io/components/input/) | | Slider | A value or range on a continuous scale. | — | [`components/input-select.md`](https://docs.atomus.io/components/input/) | | Checkbox | Independent yes/no choices; several can be on. | `Checkbox` | [`components/checkbox-radio.md`](https://docs.atomus.io/components/checkbox-radio-toggle/) | | Radio | One choice from 2–5 visible options. | `Radio` | [`components/checkbox-radio.md`](https://docs.atomus.io/components/checkbox-radio-toggle/) | | Toggle | A setting that applies immediately. | `Toggle` | [`components/toggle.md`](https://docs.atomus.io/components/checkbox-radio-toggle/) | | Date input, Date picker, Calendar day | Picking a date or a range. | `DatePicker`, `Calendar` | [`components/date-time-pickers.md`](https://docs.atomus.io/components/date-picker/) | | File upload, File upload item | Drop zone and per-file progress. | — | [`components/empty-state-file-upload.md`](https://docs.atomus.io/components/file-upload/) | | Color picker, Color swatch | Picking a colour. | — | [`components/tree-editor-color-picker.md`](https://docs.atomus.io/components/color-picker/) | | Text editor, Editor toolbar button | Rich-text editing. | — | [`components/tree-editor-color-picker.md`](https://docs.atomus.io/components/color-picker/) | ### Feedback | Component | Use it for | React | Guideline | | -------------------------------------- | --------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------- | | Alert | A persistent message about a page, section or form. | `Alert` | [`components/message-alert.md`](https://docs.atomus.io/components/alert/) | | Toast | A short, temporary confirmation of something the user just did. | `Toast`, `ToastProvider`, `useToast` | [`components/message-alert.md`](https://docs.atomus.io/components/alert/) | | Banner | One product- or account-wide announcement across the top of the page. | — | [`components/metrics-feeds.md`](https://docs.atomus.io/components/banner/) | | Notifications panel, Notification item | The bell-icon inbox. | — | [`components/message-alert.md`](https://docs.atomus.io/components/alert/) | | Progress bar, Progress circle | Progress of a task with a known percentage. | `ProgressBar` (bar only) | [`components/progress-loading.md`](https://docs.atomus.io/components/progress-bar/) | | Loading indicator | A spinner for short waits of unknown length. | — (`Button loading` for buttons) | [`components/progress-loading.md`](https://docs.atomus.io/components/progress-bar/) | | Skeleton | A placeholder that holds the layout while content loads. | — | [`components/progress-loading.md`](https://docs.atomus.io/components/progress-bar/) | | Empty state | An empty page, table or panel, with an icon, explanation and action. | `EmptyState` | [`components/empty-state-file-upload.md`](https://docs.atomus.io/components/file-upload/) | ### Navigation | Component | Use it for | React | Guideline | | ---------------------------- | --------------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------- | | Sidebar navigation, Nav item | The main app navigation (280px, or a 72px rail). | `SidebarNavigation`, `NavItem` | [`components/navigation.md`](https://docs.atomus.io/components/navigation/) | | App header | Top bar of an app: brand, links, search, notifications, account. | `AppHeader` | [`components/navigation.md`](https://docs.atomus.io/components/navigation/) | | Tabs, Tab | Switching between views of the same content (underline · pill · segmented). | `Tabs` | [`components/tabs.md`](https://docs.atomus.io/components/tabs/) | | Vertical tabs | Settings sub-navigation. | — (list of `NavItem`) | [`components/tabs.md`](https://docs.atomus.io/components/tabs/) | | Breadcrumb | The path to the current page in deep hierarchies. | — | [`components/breadcrumb.md`](https://docs.atomus.io/components/breadcrumb/) | | Pagination, Carousel | Paging tables and lists; stepping through galleries. | — | [`components/pagination.md`](https://docs.atomus.io/components/pagination/) | | Progress steps, Step | A multi-step flow (onboarding, checkout, setup). | — | [`components/progress-loading.md`](https://docs.atomus.io/components/progress-bar/) | | Header navigation, Footer | Website header and footer. | — | [`website-sections.md`](https://docs.atomus.io/website-sections/) | ### Data display | Component | Use it for | React | Guideline | | ---------------------------------------- | --------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | | Table (header cell, cell) | Rows of records you compare, sort and select. | `Table` | [`components/table.md`](https://docs.atomus.io/components/table/) | | Filter bar | Search, filters and actions above a table. | — | [`components/table.md`](https://docs.atomus.io/components/table/) | | Badge | A short status or count label. | `Badge` | [`components/badge.md`](https://docs.atomus.io/components/badge-tag/) | | Tag | A removable value: filter, skill, recipient. | `Tag` | [`components/badge.md`](https://docs.atomus.io/components/badge-tag/) | | Avatar, Avatar group, Avatar label group | A person or workspace. | `Avatar` | [`components/avatar.md`](https://docs.atomus.io/components/avatar/) | | Metric card | A KPI: number, change and period. | `MetricCard` | [`components/metrics-feeds.md`](https://docs.atomus.io/components/banner/) | | Activity item | A feed row: who did what, when. | — | [`components/metrics-feeds.md`](https://docs.atomus.io/components/banner/) | | Code snippet | Copyable code. | — | [`components/metrics-feeds.md`](https://docs.atomus.io/components/banner/) | | Tree view, Tree item | Nested, expandable hierarchies (files, categories). | — | [`components/tree-editor-color-picker.md`](https://docs.atomus.io/components/color-picker/) | | Chat, Message bubble, Message input | Messaging. | — | [`components/messaging.md`](https://docs.atomus.io/components/messaging/) | | Charts | Line, bar, pie, radar, activity gauge, legend item. | — | [`components/charts.md`](https://docs.atomus.io/components/charts/) | ### Overlays | Component | Use it for | React | Guideline | | ------------------------ | ------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------- | | Modal | A focused task or decision that blocks the page. Sizes 400 · 544 · 720px. | `Modal` | [`components/modal.md`](https://docs.atomus.io/components/modal/) | | Dropdown menu, Menu item | A short list of actions from a trigger. | `DropdownMenu`, `MenuItem` | [`components/menu.md`](https://docs.atomus.io/components/dropdown-menu/) | | Context menu | Right-click actions. | `DropdownMenu` | [`components/menu.md`](https://docs.atomus.io/components/dropdown-menu/) | | Tooltip | A one-sentence hint on hover or focus. | — | [`components/tooltip-popover.md`](https://docs.atomus.io/components/tooltip-popover/) | | Drawer, Slideout menu | A side panel for details or secondary forms. | — | [`components/slideout-command-menu.md`](https://docs.atomus.io/components/drawer/) | | Command menu | ⌘K search and actions. | — | [`components/slideout-command-menu.md`](https://docs.atomus.io/components/drawer/) | ### Layout and content | Component | Use it for | React | Guideline | | ---------------------------------- | ------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- | | Card (Card header, Section footer) | A bounded group of related content with optional header and footer. | `Card` | [`components/card.md`](https://docs.atomus.io/components/card/) | | Inline CTA | A call to action inside app pages or articles. | — | [`components/card.md`](https://docs.atomus.io/components/card/) | | Page header | Top of an app page: breadcrumb, title, description, actions, tabs. | — | [`components/headers-dividers.md`](https://docs.atomus.io/components/headers-dividers/) | | Section header | A heading for a section inside a page. | — | [`components/headers-dividers.md`](https://docs.atomus.io/components/headers-dividers/) | | Divider | A rule between groups, optionally with a label. | — | [`components/headers-dividers.md`](https://docs.atomus.io/components/headers-dividers/) | | Website sections | Hero, features, pricing, FAQ, CTA … 30 responsive sections. | — | [`website-sections.md`](https://docs.atomus.io/website-sections/) | ### Media and assets | Component | Use it for | React | Guideline | | ------------- | -------------------------------------------------------------------------------- | ----- | --------------------------------------------------------------------------------- | | Featured icon | An icon in a tinted circle or square for empty states, modals and feature lists. | — | [`components/atomus-icons.md`](https://docs.atomus.io/components/atomus-icons/) | | Icon sets | Brand, payment, flag, file-type, folder and integration icons; star rating. | — | [`components/atomus-icons.md`](https://docs.atomus.io/components/atomus-icons/) | | Shared assets | Mockups and annotation kit (design files only). | — | [`components/shared-assets.md`](https://docs.atomus.io/components/shared-assets/) | ### AI (Agent kit) Components for AI products: chat, copilots and agents. They mark AI content with the AI layer (`--color-bg-ai-subtle`, `--color-border-ai`, `--color-text-ai`, `--gradient-ai`) and take plain props, so they work with any AI SDK. | Component | Use it for | React | Guideline | | ------------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- | | Conversation | The pattern: header, `role="log"` thread of Messages, welcome state with starters, docked Prompt input. | — (compose the parts) | [`components/ai-message.md`](https://docs.atomus.io/components/ai-conversation/) | | Prompt input | The chat composer: auto-growing text, attachments, toolbar slot, Send ↔ Stop, `/` and `@` menus. | `PromptInput` | [`components/ai-prompt-input.md`](https://docs.atomus.io/components/ai-prompt-input/) | | Message | One turn: user, assistant, system or tool; streaming, error and stopped states; copy, regenerate, edit, branches. | `Message` | [`components/ai-message.md`](https://docs.atomus.io/components/ai-conversation/) | | Streaming text, Shimmer | A reply that renders as it streams, with a caret and batched announcements; a shimmer for status lines. | `StreamingText`, `Shimmer` | [`components/ai-streaming-text.md`](https://docs.atomus.io/components/ai-streaming-text/) | | Reasoning | A collapsible “Thought for 12s” disclosure with the agent’s steps. | `Reasoning` | [`components/ai-reasoning.md`](https://docs.atomus.io/components/ai-reasoning/) | | Tool call | One function call: name, status, duration, input and output. | `ToolCall` | [`components/ai-tool-call.md`](https://docs.atomus.io/components/ai-tool-call/) | | Approval | Human-in-the-loop confirmation before an agent acts; risk level, edit then approve, always allow. | `Approval` | [`components/ai-approval.md`](https://docs.atomus.io/components/ai-approval/) | | Sources, Inline citation | Numbered citations with preview cards and the list of sources behind an answer. | `Sources`, `InlineCitation` | [`components/ai-sources.md`](https://docs.atomus.io/components/ai-sources/) | | Suggestions | Follow-up chips and prompt-starter cards that send or insert a prompt. | `Suggestions` | [`components/ai-suggestions.md`](https://docs.atomus.io/components/ai-suggestions/) | | Model selector | Choosing the AI model, with provider icons and capability badges. | `ModelSelector` | [`components/ai-model-selector.md`](https://docs.atomus.io/components/ai-model-selector/) | | Feedback | Thumbs up / down on a reply, with a reason form. | `Feedback` | [`components/ai-feedback.md`](https://docs.atomus.io/components/ai-feedback/) | | AI label | Marks AI-generated content; explainability popover; “Revert to AI” after edits. | `AILabel` | [`components/ai-label.md`](https://docs.atomus.io/components/ai-label/) | | Context meter | Context-window usage and cost of a conversation. | `ContextMeter` | [`components/ai-context-meter.md`](https://docs.atomus.io/components/ai-context-meter/) | ## Also called If a request uses one of these names, use the Atomus component on the right. | You may hear | Atomus component | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | | dialog, popup, lightbox, confirm dialog | Modal | | sheet, side sheet, side panel, off-canvas, flyout | Drawer | | snackbar, notification (temporary), flash message | Toast | | callout, inline message, notice | Alert | | announcement bar, top bar message | Banner | | chip, pill, token (removable) | Tag | | pill, label, status, lozenge (read-only) | Badge | | switch | Toggle | | dropdown (picks a value), picker | Select | | dropdown (runs actions), kebab menu, overflow menu, action menu | Dropdown menu | | right-click menu | Context menu | | combobox, autocomplete, typeahead | Select. A searchable combobox is not in Atomus yet (see the decision tree below). | | segmented control, toggle group | Tabs `variant="segmented"` (code) / Button group (Figma) | | stepper, wizard | Progress steps | | spinner, loader | Loading indicator (`Button loading` inside buttons) | | placeholder, shimmer | Skeleton | | zero state, blank slate, no results | Empty state | | dropzone, uploader | File upload | | data grid, data table, list view | Table | | KPI, stat, scorecard | Metric card | | navbar, top nav (app) | App header | | navbar, site header (website) | Header navigation | | side nav, rail | Sidebar navigation | | panel, tile, box, container | Card | | separator, hr, rule | Divider | | page title, page heading | Page header | | command palette, ⌘K, spotlight | Command menu | | hint, info bubble | Tooltip | | accordion | FAQ item (website) | | range slider | Slider | | image slider, gallery | Carousel | | user picture, profile image | Avatar | | rating | Star rating | | rich text editor, WYSIWYG | Text editor | | chatbot, assistant panel, copilot, chat UI, AI chat | Conversation (Message + Prompt input) | | composer, chat input, prompt box, prompt bar | Prompt input | | chat bubble, AI response, turn | Message | | typing indicator, thinking indicator, “Thinking…” | Shimmer (or Reasoning with `status="thinking"`) | | chain of thought, thoughts, plan | Reasoning | | function call, tool use, tool invocation, MCP tool | Tool call | | confirmation (agent), human-in-the-loop, permission prompt | Approval | | citations, references, footnotes (AI) | Sources, Inline citation | | quick replies, follow-ups, prompt starters, conversation starters | Suggestions | | model picker, model switcher, LLM dropdown | Model selector | | thumbs up / down, rate response | Feedback | | AI badge, sparkle badge, “AI generated” tag | AI label | | token counter, usage meter, context window | Context meter | ## Decision trees ### Which button hierarchy? 1. Is it **the** main action of this view (screen, modal, card, form)? → `primary`. There is only one per view. 2. Is it an alternative to the main action (“Cancel”, “Save draft”, “Export”)? → `outline` on white surfaces, `secondary` on grey or in dense groups. 3. Is it in a toolbar, table row, card header or another dense spot? → `tertiary` (often `iconOnly` with an `aria-label`). 4. Does it sit inside a sentence or look like a link (“Learn more”, “Edit”)? → `link`. 5. Is it destructive? → In a confirmation Modal (`type="destructive"`) the confirm button is the `primary`. Elsewhere use `outline` and confirm first. Never use `link` for destructive actions. 6. Does it go to another page? → Use a link (``, or `NavItem` in navigation), not a Button. Sizes: `md` in product UI, `sm`/`xs` in tables and toolbars, `lg`/`xl` on marketing pages. Match the inputs on the same row. ### Input, Textarea, Select, Multi-select, Combobox, Radio, Checkbox or Toggle? 1. Is the answer free text? - One line → **Input** (`type="email"`, `"number"`, `"search"` …). - Several lines → **Textarea** (Figma only; in code a native `` styled with tokens). 2. Is it a choice from known options? - **One** value: - 2–5 options and there is room to show them all → **Radio** group. Use **Tabs `variant="segmented"`** when the choice switches a view. - 6 or more options, or no room → **Select**. - Very long or searchable list (countries, users) → a **combobox**. It is not in Atomus yet: use **Select** up to about 15 options, and for longer lists flag it to a human instead of building your own. - **Several** values: - Few options, all visible → **Checkbox** group. - Many options → **Multi-select** (Figma only; in code compose Select-like UI with `Tag`s, or flag it). 3. Is it a single on/off? - It applies **immediately** (a setting) → **Toggle**. - It is submitted with a form (“I agree”, “Remember me”) → **Checkbox**. 4. Is it a date? → **DatePicker** (`type="range"` for ranges). Birth dates and far dates → a typed date **Input**. ### Alert, Toast, Banner, Modal, field error or Empty state? 1. Is the message about **one form field**? → the field’s `error` prop (Input, Select, DatePicker). Not an Alert. 2. Must the user **decide or confirm** before continuing (delete, discard changes)? → **Modal**. 3. Does it confirm something the user **just did**, and is it fine if it disappears (“Saved”, “Invite sent”)? → **Toast** (`useToast().show`). Errors stay until closed. 4. Is it about **this page, section or form** and should it stay visible until resolved (“Your trial ends in 3 days”, “3 rows failed to import”)? → **Alert**. Use `variant="solid"` only for blocking issues. 5. Is it **product- or account-wide** and shown across the top of every page (“Scheduled maintenance Sunday”)? → **Banner** (one at a time). 6. Is there **no content yet** (first use, no results, cleared inbox)? → **Empty state** in place of the content. 7. Is it a history of events the user checks later? → **Notifications panel**. ### Which AI component? 1. Does the person **type to the AI**? → **Prompt input**, docked at the bottom of the thread. Put the model choice in its `toolbar` (**Model selector**) and usage in its `actions` (**Context meter**). 2. Is it **one turn** of the conversation? → **Message** with `role` user, assistant, system or tool. Inside an assistant Message, in the order things happened: - The model is **thinking or planning** → **Reasoning** (`status="thinking"`, then `done` with a duration). For a one-line status (“Searching…”) → **Shimmer**. - The agent **called a function** (search, API, MCP tool) → **Tool call**. - The agent wants to **write, send, spend, delete or share** → **Approval** first; run the tool only after Approve. Read-only actions the person asked for need no Approval. - The **answer text** → **Streaming text** while it arrives, plain text afterwards. - The answer **relies on documents or pages** → **Inline citation** after each claim and **Sources** under the answer. 3. Should the person **rate** the answer? → **Feedback** in the Message `actions` slot. 4. Should the person **continue** with one tap? → **Suggestions** under the latest answer (`mode="insert"` when they must add details); on an empty thread → `variant="cards"` prompt starters. 5. Is AI-generated content shown **outside a chat** (a summary, a prefilled field, a table cell)? → **AI label** next to it, with an `explanation`; after the person edits it, `edited` and `onRevert`. 6. Is it a **person-to-person** chat without AI? → the Messaging guidelines, not the Agent kit. 7. Never use the AI layer (`--gradient-ai`, `bg-ai-subtle`, `border-ai`, `text-ai`) on content that is not AI. ### Card or Section? 1. Is it a **bounded, self-contained group** (a settings group, a chart, a form, one record) that sits next to similar groups on a page? → **Card** (`title`, `footer`, Content slot). 2. Is it a **band of a page** that spans the content width (a settings area with several groups, or a marketing section)? → a **section**: a `<section>` with a **Section header** and `--layout-*` spacing. Use a website section on marketing pages. Don’t wrap a whole page section in a Card. 3. Is it one item in a **list or grid** of similar items (projects, pricing plans, blog posts)? → **Card** per item (marketing: Pricing card, Blog card). 4. Is it a single **call to action** inside content? → **Inline CTA**. 5. Would the card sit **inside another card**? → Don’t. Use a Divider, a Section header or a filled area (`--color-bg-secondary`) instead. Card style: `outlined` on white backgrounds, `filled` on grey, `elevated` only when it floats above content. ### Tabs, segmented control, Button group, Vertical tabs, Sidebar or Progress steps? 1. Do the options show **different views of the same content** on one page? → **Tabs** (`underline` under a Page header, `pill` inside cards). 2. Is it a **compact switch** of 2–5 options, like a view mode or a time range? → **Tabs `variant="segmented"`** (Figma: Button group or Segmented tab). 3. Is it **sub-navigation for settings** with many sections? → **Vertical tabs** (code: a list of `NavItem`s). 4. Is it **app-wide navigation** between areas? → **Sidebar navigation** (or **App header** links for apps with few areas). 5. Are the options **sequential steps**? → **Progress steps**. Never tabs. ### Modal, Drawer, Dropdown menu, Tooltip or Command menu? 1. A decision or short focused task that must block the page → **Modal**. 2. Details of a record, or a secondary form, while keeping the page in view → **Drawer** (Bottom position on mobile). 3. A list of actions or options from a trigger → **Dropdown menu** (up to about 10 items). 4. A one-sentence hint about an icon or truncated text → **Tooltip**. No links or buttons inside. 5. Searching everything and running commands with the keyboard → **Command menu**. 6. A long form or multi-step flow → a **page**, not an overlay. ### Badge, Tag or Status tag? - A read-only **status or count** (“Active”, “Overdue”, “3”) → **Badge**. Pick the colour by meaning. - A **value the user added and can remove** (filter, skill, recipient) → **Tag** with `onRemove`. - A **design-file annotation** (Ready, In progress) → **Status tag** (shared assets, Figma only). ### Progress bar, Loading indicator, Skeleton or Button loading? 1. Is the percentage known (upload, storage used)? → **Progress bar**. 2. Is a button’s action running? → `<Button loading>`. 3. Is content loading and the layout known? → **Skeleton**. 4. Is it a short wait with unknown layout? → **Loading indicator**. 5. Is it a multi-step flow? → **Progress steps**. ### Table, cards, metric cards or a chart? - **Records with the same fields** that people compare, sort or select → **Table**, with Filter bar above and Pagination below over about 25 rows. - **A few items with visuals or mixed content** (projects, integrations) → a grid of **Card**s. - **Headline numbers** (up to four in a row) → **Metric card**s. - **A trend or a comparison over time** → a **chart** (line for time, bar for categories). --- # Button > Triggers an action. Five hierarchies, five sizes from 24 to 56px. URL: https://docs.atomus.io/components/button/ Triggers an action. Five hierarchies, five sizes from 24 to 56px. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/button.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fbutton.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/button.md` · Open in Figma: [Button](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25416-2898) Properties, variants and anatomy of the Figma components. React props use the same names. ### Button Hierarchy: Primary (main action, one per view), Secondary, Outline, Tertiary (low emphasis), Link. Sizes xs–xl (24–56px). Icons via instance swap. Loading shows a spinner. Variants: 125 | Property | Type / options | | ------------------ | ----------------------------------------------- | | Label | text | | Leading icon | boolean (off) | | Leading icon swap | instance swap (icon) | | Trailing icon | boolean (off) | | Trailing icon swap | instance swap (icon) | | Hierarchy | Primary · Secondary · Outline · Tertiary · Link | | Size | xs · sm · md · lg · xl | | State | Default · Hover · Focused · Disabled · Loading | ### Button icon Icon-only button. Same hierarchies, sizes and states as Button; square 24–56px. Always give it a tooltip or aria-label in code. Variants: 100 | Property | Type / options | | --------- | ---------------------------------------------- | | Icon | instance swap (icon) | | Hierarchy | Primary · Secondary · Outline · Tertiary | | Size | xs · sm · md · lg · xl | | State | Default · Hover · Focused · Disabled · Loading | ## Usage ```tsx import { Button } from '@stanvision/atomus-react'; <Button hierarchy="primary" size="md" iconLeading={<PlusIcon />}> New project </Button> ``` Triggers an action. One **primary** per view for the main action; **secondary** or **outline** for the rest; **tertiary** in toolbars and dense rows; **link** for inline, low-emphasis actions. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `children` — the label: a verb in sentence case (“Save changes”). - `hierarchy` — `primary` · `secondary` · `outline` · `tertiary` · `link` (Figma: Hierarchy; default `secondary`). - `size` — `xs` 24 · `sm` 32 · `md` 40 · `lg` 48 · `xl` 56 (Figma: Size). Match the inputs on the same row. - `iconLeading` / `iconTrailing` — an icon element (Figma: Leading/Trailing icon swap). `iconOnly` + `aria-label` for icon buttons. - `loading` — spinner, disabled while busy (Figma: State=Loading). **Do** - Use `lg`/`xl` on marketing pages, `md` in product UI, `sm`/`xs` in tables and toolbars. ### Design guidance From the Figma guidelines. #### Button **Do** - Use one primary button per view, for the main action. - Label with a verb in sentence case: “Save changes”, not “OK”. - Match sizes in a row — buttons and inputs share the 32 / 40 / 48 heights. - Put the primary action last in a group, after Cancel. **Forbidden** - Never put two primary buttons in one view. - Never use the Link style for destructive actions. - Never detach to change an icon — use Leading / Trailing icon swap. - Never use a button to navigate to another page — use a link. #### Button icon **Do** - Always give it an accessible name (`aria-label`) and a tooltip. - Use Tertiary in toolbars, cards and table rows. **Forbidden** - Never use an icon-only button for the main action of a view. - Never use an icon whose meaning is not widely understood without a label. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/button.md`. Use only these props; anything else is not part of the API. ### `Button` `import { Button } from '@stanvision/atomus-react';` — source: `react/src/components/Button.tsx` | Prop | Type | Default | Description | | -------------- | --------------------------------------------------------------- | ------------- | ------------------------------------------------------------------ | | `hierarchy` | `'primary' \| 'secondary' \| 'outline' \| 'tertiary' \| 'link'` | `'secondary'` | Figma: Hierarchy | | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Figma: Size — xs 24 · sm 32 · md 40 · lg 48 · xl 56 | | `iconLeading` | `ReactNode` | — | Figma: Leading icon + Leading icon swap | | `iconTrailing` | `ReactNode` | — | Figma: Trailing icon + Trailing icon swap | | `loading` | `boolean` | — | Figma: State=Loading | | `iconOnly` | `boolean` | — | Square icon-only button (Figma: Button icon). Requires aria-label. | | `fullWidth` | `boolean` | — | Stretches to the width of its container. | Also accepts every native `<button>` attribute (`onClick`, `type`, `disabled`, `form` …), and `ref` (forwarded to the `<button>`). --- # Button group > Connected buttons for switching views or filters. URL: https://docs.atomus.io/components/button-group/ Connected buttons for switching views or filters. ## In Figma From `guidelines/components/button-group.md` Properties, variants and anatomy of the Figma components. ### Button group Variants: 2 | Property | Type / options | | -------- | -------------- | | Size | sm · md | ### Button group item Segment inside a Button group. Selected = toggled on. Variants: 10 | Property | Type / options | | ----------------- | ----------------------------------------------- | | Label | text | | Leading icon | boolean (off) | | Leading icon swap | instance swap (icon) | | Size | sm · md | | State | Default · Hover · Selected · Focused · Disabled | ## Usage #### Button group **Do** - Use for 2–5 related, mutually exclusive options. - Keep labels short and parallel. - Show the current option with the Selected state. **Forbidden** - Never group unrelated actions. - Never mix icon-only and text items. - Never wrap a button group to a second row. --- # Input > Single-line text field with label, hint and error. Heights match Button. URL: https://docs.atomus.io/components/input/ Single-line text field with label, hint and error. Heights match Button. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/input.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Finput.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/input-select.md` · Open in Figma: [Input](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25418-1714) Properties, variants and anatomy of the Figma components. React props use the same names. ### Input Text input. Label position Outside, Inside (floating) or Notched. Sizes 32/40/48 match Buttons. Variants: 42 | Property | Type / options | | -------------- | ----------------------------------------------------- | | Label | text | | Show label | boolean (on) | | Hint | text | | Show hint | boolean (on) | | Label position | Outside · Inside · Notched | | Size | sm · md · lg | | State | Default · Hover · Focused · Filled · Disabled · Error | ### Textarea Multi-line text input. Variants: 5 | Property | Type / options | | --------- | --------------------------------------------- | | Label | text | | Value | text | | Show hint | boolean (on) | | State | Default · Focused · Filled · Disabled · Error | ### Number input Number counter with decrease/increase buttons. Variants: 9 | Property | Type / options | | ---------- | ---------------------------- | | Show label | boolean (on) | | Value | text | | Show hint | boolean (on) | | Size | sm · md · lg | | State | Default · Focused · Disabled | ### Verification code input One-time code (OTP) input, 4 or 6 digits. Variants: 24 | Property | Type / options | | ---------- | ---------------------------------- | | Show label | boolean (on) | | Show hint | boolean (on) | | Digits | 4 · 6 | | Size | sm · md · lg | | State | Default · Filled · Focused · Error | ### Tags input Input that turns entries into removable tags. Variants: 6 | Property | Type / options | | ---------- | ----------------- | | Show label | boolean (on) | | Show hint | boolean (on) | | Size | sm · md · lg | | State | Default · Focused | ### Phone input Phone number with country selector (flag + dial code). Variants: 9 | Property | Type / options | | ---------- | ------------------------- | | Show label | boolean (on) | | Show hint | boolean (on) | | Size | sm · md · lg | | State | Default · Focused · Error | ### Payment input Card number, expiry and CVC in one field with the card brand mark. Variants: 9 | Property | Type / options | | ---------- | ------------------------- | | Show label | boolean (on) | | Show hint | boolean (on) | | Size | sm · md · lg | | State | Default · Focused · Error | ## Usage ```tsx import { Input } from '@stanvision/atomus-react'; <Input label="Email" placeholder="you@company.com" hint="We never share it." /> <Input label="URL" error="This URL is taken." /> ``` Single-line text field with label, hint and error. Heights match Button: `sm` 32 · `md` 40 · `lg` 48. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `label` — always (Figma: Label); use `aria-label` when the design hides it. - `placeholder` — an example value, never the label. - `hint` (Figma: Hint); `error` replaces it and turns the border `border-error` (Figma: State=Error). - `size`, `iconLeading`, `iconTrailing` and any native input attribute. **Do** - Write errors that say how to fix it: “Enter a date after today”. **Don’t** - Don’t rely on the red border alone — the error text is required. ### Design guidance From the Figma guidelines. #### Input **Do** - Always show a label; use Inside or Notched when space is tight. - Use the hint for format help and Error for validation. - Match the size to the buttons in the same form. **Forbidden** - Never use placeholder text as the label. - Never show an error before the user has typed. - Never clear the user’s value after an error. #### Textarea **Do** - Use for multi-line text; show a character count when there is a limit. **Forbidden** - Never use Textarea for single-line values — use Input. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/input-select.md`. Use only these props; anything else is not part of the API. ### `Input` `import { Input } from '@stanvision/atomus-react';` — source: `react/src/components/Input.tsx` | Prop | Type | Default | Description | | -------------- | ---------------------- | ------- | ------------------------------------------------------------------------------- | | `label` | `string` | — | Figma: Label (+ Show label). Always give one; use aria-label when it is hidden. | | `hint` | `string` | — | Figma: Hint (+ Show hint) | | `error` | `string` | — | Figma: State=Error — replaces the hint and turns the border red | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Figma: Size — sm 32 · md 40 · lg 48, matching Button | | `iconLeading` | `ReactNode` | — | Icon before the text. | | `iconTrailing` | `ReactNode` | — | Icon after the text. | Also accepts every native `<input>` attribute (`name`, `value`, `checked`, `onChange`, `required` …), except `size`, which is replaced above, and `ref` (forwarded to the `<input>`). --- # Select > Pick one value from a list. Keyboard and screen-reader ready. URL: https://docs.atomus.io/components/select/ Pick one value from a list. Keyboard and screen-reader ready. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/select.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fselect.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/input-select.md` · Open in Figma: [Select](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25419-14452) Properties, variants and anatomy of the Figma components. React props use the same names. ### Select Select trigger; pair with Dropdown menu for the open list. Variants: 15 | Property | Type / options | | ---------- | --------------------------------------------- | | Label | text | | Show label | boolean (on) | | Show hint | boolean (on) | | Size | sm · md · lg | | State | Default · Focused · Filled · Disabled · Error | ### Multi-select Select with several values as tags; open state shows a searchable checkbox list. Variants: 6 | Property | Type / options | | ---------- | -------------- | | Show label | boolean (on) | | Show hint | boolean (on) | | Size | sm · md · lg | | State | Closed · Open | ## Usage ```tsx import { Select } from '@stanvision/atomus-react'; const [team, setTeam] = useState('design'); <Select label="Team" value={team} onChange={setTeam} options={[ { value: 'design', label: 'Design' }, { value: 'product', label: 'Product' }, ]} /> ``` Pick one value from a list of 5–15 options. Uses the Input heights (`sm` 32 · `md` 40 · `lg` 48) and the Menu item rows for the list. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `options` — `[{ value, label, icon?, disabled? }]`; `value` + `onChange` or `defaultValue`. - `label` (always), `placeholder`, `hint`, `error`, `size`, `disabled`, `name` for forms. - Keyboard: ↑ ↓ Home End to move, Enter to pick, Esc to close, letters jump to a match. **Don’t** - Don’t use for more than \~15 options — add search (Combobox, coming next). ### Design guidance From the Figma guidelines. #### Select **Do** - Use for one choice from six or more options, or when space is tight. - Write a placeholder that says what to pick (“Select a country”). **Forbidden** - Never use Select for two to four options — use Radio or a segmented Tabs. - Never put actions in the option list — use Dropdown menu. #### Multi-select **Do** - Show the selected values as tags in the field. - Add search when there are more than about ten options. **Forbidden** - Never use Multi-select when only one value is allowed — use Select. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/input-select.md`. Use only these props; anything else is not part of the API. ### `Select` Figma: Select (trigger) + Dropdown menu (list). A WAI-ARIA select-only combobox. `import { Select } from '@stanvision/atomus-react';` — source: `react/src/components/Select.tsx` | Prop | Type | Default | Description | | -------------- | ------------------------- | -------------------- | ------------------------------------------------------------------------------- | | `options` | `SelectOption[]` | **required** | The options. | | `value` | `string` | — | Controlled value. | | `defaultValue` | `string` | — | Initial value when uncontrolled. | | `onChange` | `(value: string) => void` | — | Called with the new value. | | `label` | `string` | — | Figma: Label (+ Show label) | | `hint` | `string` | — | Figma: Show hint | | `error` | `string` | — | Figma: State=Error | | `placeholder` | `string` | `'Select an option'` | Placeholder text — never a replacement for the label. | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Figma: Size — sm 32 · md 40 · lg 48 | | `disabled` | `boolean` | — | Disables the control. | | `name` | `string` | — | Form field name; a hidden input carries the value | | `id` | `string` | — | Element id; generated when omitted (wires label and hint). | | `defaultOpen` | `boolean` | — | Start open (docs and tests) | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `SelectOption`: | Field | Type | Description | | ----------- | ----------- | ----------- | | `value` | `string` | | | `label` | `string` | | | `icon?` | `ReactNode` | | | `disabled?` | `boolean` | | --- # Checkbox, Radio & Toggle > Selection controls in two sizes. URL: https://docs.atomus.io/components/checkbox-radio-toggle/ Selection controls in two sizes. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/checkbox-radio-toggle.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fcheckbox-radio-toggle.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/checkbox-radio.md`, `guidelines/components/toggle.md` · Open in Figma: [Checkbox](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25419-14605) · [Radio](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25419-14694) · [Toggle](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25420-988) Properties, variants and anatomy of the Figma components. React props use the same names. ### Checkbox Checkbox with optional label and description. Variants: 24 | Property | Type / options | | ---------------- | ------------------------------------ | | Label | text | | Show label | boolean (on) | | Description | text | | Show description | boolean (off) | | Size | sm · md | | Checked | False · True · Indeterminate | | State | Default · Hover · Focused · Disabled | ### Radio Radio button for groups of mutually exclusive options. Variants: 16 | Property | Type / options | | ---------------- | ------------------------------------ | | Label | text | | Show label | boolean (on) | | Description | text | | Show description | boolean (off) | | Size | sm · md | | Checked | False · True | | State | Default · Hover · Focused · Disabled | ### Toggle On/off switch for settings that apply immediately. Variants: 32 | Property | Type / options | | ---------------- | ------------------------------------ | | Label | text | | Show label | boolean (on) | | Description | text | | Show description | boolean (off) | | Shape | Pill · Square | | Size | sm · md | | Checked | False · True | | State | Default · Hover · Focused · Disabled | ## Usage ```tsx import { Checkbox, Radio, Toggle } from '@stanvision/atomus-react'; <Checkbox label="Email me updates" defaultChecked /> <Radio name="plan" label="Pro" description="Unlimited projects" /> <Toggle label="Dark mode" size="md" /> ``` ### Checkbox Pick any number of options, or confirm one setting that applies on submit. #### Props - `label`, `description` (Figma: Label, Description), `size` `sm` (16 box) · `md` (20 box). - `checked`/`defaultChecked`, `onChange`; `indeterminate` for a partial “select all”. ### Radio Pick exactly one of 2–5 options. Wrap the group in `role="radiogroup"` with a label. #### Props - The same `name` on each radio, a `label`, optional `description`, `size` `sm` · `md`. ### Toggle A switch for a setting that takes effect immediately. #### Props - `label`, `description`, `checked`/`onChange`. - `size` `sm` (36×20) · `md` (44×24); `shape` `pill` · `square` (Figma: Shape). ### Design guidance From the Figma guidelines. #### Checkbox **Do** - Use for multiple independent choices. - Use Indeterminate for a partially selected group. - Turn on Description only when the label needs explaining. **Forbidden** - Never use a checkbox for a setting that applies instantly — use Toggle. - Never write negative labels (“Don’t send emails”). - Never nest checkboxes more than one level. #### Radio **Do** - Use for one choice from 2–5 visible options. - Preselect a sensible default when there is one. **Forbidden** - Never use a single radio on its own — use Checkbox. - Never use radios for more than about five options — use Select. #### Toggle **Do** - Use for settings that apply immediately. - Write the label as the setting (“Email notifications”). - Use one shape across the product. **Forbidden** - Never use a toggle in a form that needs Save — use Checkbox. - Never use a toggle for more than two states. - Never hide the label. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/checkbox-radio.md`, `guidelines/components/toggle.md`. Use only these props; anything else is not part of the API. ### `Checkbox` `import { Checkbox } from '@stanvision/atomus-react';` — source: `react/src/components/Choice.tsx` | Prop | Type | Default | Description | | --------------- | -------------- | ------- | ----------------------------------------------------------------------- | | `label` | `string` | — | Figma: Label (+ Show label) | | `description` | `string` | — | Figma: Description (+ Show description) | | `size` | `'sm' \| 'md'` | `'sm'` | Figma: Size — sm (16 control, 14px label) · md (20 control, 16px label) | | `indeterminate` | `boolean` | — | Figma: Checked=Indeterminate | Also accepts every native `<input>` attribute (`name`, `value`, `checked`, `onChange`, `required` …), except `size`, `type`, which are replaced above, and `ref` (forwarded to the `<input>`). ### `Radio` `import { Radio } from '@stanvision/atomus-react';` — source: `react/src/components/Choice.tsx` | Prop | Type | Default | Description | | ------------- | -------------- | ------- | ----------------------------------------------------------------------- | | `label` | `string` | — | Figma: Label (+ Show label) | | `description` | `string` | — | Figma: Description (+ Show description) | | `size` | `'sm' \| 'md'` | `'sm'` | Figma: Size — sm (16 control, 14px label) · md (20 control, 16px label) | Also accepts every native `<input>` attribute (`name`, `value`, `checked`, `onChange`, `required` …), except `size`, `type`, which are replaced above, and `ref` (forwarded to the `<input>`). ### `Toggle` `import { Toggle } from '@stanvision/atomus-react';` — source: `react/src/components/Choice.tsx` | Prop | Type | Default | Description | | ------------- | -------------------- | -------- | ----------------------------------------------------------------------- | | `label` | `string` | — | Figma: Label (+ Show label) | | `description` | `string` | — | Figma: Description (+ Show description) | | `size` | `'sm' \| 'md'` | `'sm'` | Figma: Size — sm (16 control, 14px label) · md (20 control, 16px label) | | `shape` | `'pill' \| 'square'` | `'pill'` | Figma: Shape | Also accepts every native `<input>` attribute (`name`, `value`, `checked`, `onChange`, `required` …), except `size`, `type`, which are replaced above, and `ref` (forwarded to the `<input>`). --- # Date picker > A date field with a calendar; single dates or ranges. URL: https://docs.atomus.io/components/date-picker/ A date field with a calendar; single dates or ranges. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/date-picker.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fdate-picker.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/date-time-pickers.md` · Open in Figma: [DatePicker](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25430-2256) · [Calendar](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25430-2200) Properties, variants and anatomy of the Figma components. React props use the same names. ### Date picker Calendar dropdown: single date or range. Variants: 2 | Property | Type / options | | -------- | -------------- | | Type | Single · Range | ### Date input Date field that opens the Date picker. Variants: 5 | Property | Type / options | | -------- | --------------------------------------------- | | Label | text | | State | Default · Focused · Filled · Disabled · Error | ### Calendar day Day cell for calendars and date pickers. Variants: 7 | Property | Type / options | | -------- | ------------------------------------------------------------------ | | Day | text | | State | Default · Hover · Today · Selected · In range · Outside · Disabled | ## Usage ```tsx import { DatePicker, Calendar } from '@stanvision/atomus-react'; <DatePicker label="Due date" value={date} onChange={setDate} /> <Calendar type="range" range={range} onRangeChange={setRange} /> ``` A date field that opens a calendar. `Calendar` is exported on its own for inline use. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `type` `single` (with `value` / `onChange`) or `range` (with `range` / `onRangeChange`); dates are ISO strings like `2026-10-14`. - `label`, `hint`, `error`, `placeholder`, `min`, `max`, `weekStartsOn` (Monday by default), `locale`. - Keyboard: arrow keys move by day and week, PageUp / PageDown by month, Enter picks, Esc closes. ### Design guidance From the Figma guidelines. **Do** - Show today and the selected range clearly. - Let people type the date in Date input. - Offer presets for common ranges. **Forbidden** - Never hide the year when a range crosses years. - Never disable past dates unless the task requires it. - Never make people click through a calendar for birth dates — use Date input. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/date-time-pickers.md`. Use only these props; anything else is not part of the API. ### `DatePicker` Figma: Date input + Date picker. A field that opens the calendar in a popover. `import { DatePicker } from '@stanvision/atomus-react';` — source: `react/src/components/DatePicker.tsx` | Prop | Type | Default | Description | | --------------- | ---------------------------- | ---------- | ------------------------------------------------------------------------------- | | `type` | `'single' \| 'range'` | `'single'` | Figma: Date picker Type | | `value` | `ISODate \| null` | — | Controlled value. | | `range` | `DateRange` | — | Selected range (type=“range”). | | `onChange` | `(value: ISODate) => void` | — | Called with the new value. | | `onRangeChange` | `(range: DateRange) => void` | — | Called with the new range (type=“range”). | | `min` | `ISODate` | — | Earliest selectable date. | | `max` | `ISODate` | — | Latest selectable date. | | `weekStartsOn` | `0 \| 1` | `1` | Monday-first by default | | `locale` | `string` | — | BCP 47 locale for month and weekday names. | | `label` | `string` | — | Figma: Date input — Label | | `hint` | `string` | — | Help text under the field. | | `error` | `string` | — | Error message; replaces the hint and marks the field invalid. | | `placeholder` | `string` | — | Placeholder text — never a replacement for the label. | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size. | | `disabled` | `boolean` | — | Disables the control. | | `id` | `string` | — | Element id; generated when omitted (wires label and hint). | | `defaultOpen` | `boolean` | — | Start open (docs and tests) | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `ISODate` — Dates are ISO strings ‘YYYY-MM-DD’ (no time zones): ```ts type ISODate = string; ``` `DateRange`: | Field | Type | Description | | ------- | ----------------- | ----------- | | `start` | `ISODate \| null` | | | `end` | `ISODate \| null` | | ### `Calendar` Figma: Date picker body with Calendar day cells (Default, Today, Selected, In range, Outside, Disabled). Arrow keys move days, PageUp/PageDown move months. `import { Calendar } from '@stanvision/atomus-react';` — source: `react/src/components/DatePicker.tsx` | Prop | Type | Default | Description | | --------------- | ---------------------------- | ---------- | ------------------------------------------------------------------------------- | | `type` | `'single' \| 'range'` | `'single'` | Figma: Date picker Type | | `value` | `ISODate \| null` | — | Controlled value. | | `range` | `DateRange` | — | Selected range (type=“range”). | | `onChange` | `(value: ISODate) => void` | — | Called with the new value. | | `onRangeChange` | `(range: DateRange) => void` | — | Called with the new range (type=“range”). | | `min` | `ISODate` | — | Earliest selectable date. | | `max` | `ISODate` | — | Latest selectable date. | | `weekStartsOn` | `0 \| 1` | `1` | Monday-first by default | | `locale` | `string` | — | BCP 47 locale for month and weekday names. | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `ISODate` — Dates are ISO strings ‘YYYY-MM-DD’ (no time zones): ```ts type ISODate = string; ``` `DateRange`: | Field | Type | Description | | ------- | ----------------- | ----------- | | `start` | `ISODate \| null` | | | `end` | `ISODate \| null` | | --- # Slider > Slider for a single value or a range. URL: https://docs.atomus.io/components/slider/ Slider for a single value or a range. ## In Figma From `guidelines/components/input-select.md` Properties, variants and anatomy of the Figma components. ### Slider Variants: 6 | Property | Type / options | | -------- | ------------------------ | | Type | Single · Range | | Label | None · Bottom · Floating | ## Usage Follow the descriptions above; there are no extra rules for this component yet. --- # File upload > A drop zone and upload rows with progress, success and error states. URL: https://docs.atomus.io/components/file-upload/ A drop zone and upload rows with progress, success and error states. ## In Figma From `guidelines/components/empty-state-file-upload.md` Properties, variants and anatomy of the Figma components. ### File upload Drop zone. Hover = dragging a file over it. Variants: 3 | Property | Type / options | | -------- | -------------------------- | | Hint | text | | State | Default · Hover · Disabled | ### File upload item Uploaded file row with progress. Variants: 3 | Property | Type / options | | --------- | ---------------------------- | | File name | text | | State | Uploading · Complete · Error | ## Usage #### File upload **Do** - State the accepted file types and the size limit. - Show progress and a clear error per file (File upload item). **Forbidden** - Never upload silently without showing the file list. --- # Color picker > Saturation area, hue slider, eyedropper, hex field and presets. URL: https://docs.atomus.io/components/color-picker/ Saturation area, hue slider, eyedropper, hex field and presets. ## In Figma From `guidelines/components/tree-editor-color-picker.md` Properties, variants and anatomy of the Figma components. ### Color picker Variants: 1 ### Color swatch Preset colour dot. Variants: 2 | Property | Type / options | | -------- | ------------------ | | State | Default · Selected | ## Usage Follow the descriptions above; there are no extra rules for this component yet. --- # Text editor > Rich text editor shell. URL: https://docs.atomus.io/components/text-editor/ Rich text editor shell. ## In Figma From `guidelines/components/tree-editor-color-picker.md` Properties, variants and anatomy of the Figma components. ### Text editor Variants: 1 | Property | Type / options | | -------- | -------------- | | Value | text | ### Editor toolbar button Formatting button for the text editor. Variants: 3 | Property | Type / options | | --------- | ------------------------ | | Icon swap | instance swap (icon) | | State | Default · Hover · Active | ## Usage Follow the descriptions above; there are no extra rules for this component yet. --- # Alert > Inline messages about a page, section or form. URL: https://docs.atomus.io/components/alert/ Inline messages about a page, section or form: a tinted fill, a hairline border and a coloured title and icon, so the tone reads at a glance. ### Subtle (default) Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/alert.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Falert.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ### Outline — on tinted or grey surfaces ### Solid — blocking issues only ### Small and flush ## In Figma From `guidelines/components/message-alert.md` · Open in Figma: [Alert](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25427-447) Properties, variants and anatomy of the Figma components. React props use the same names. ### Alert Inline alert about a page, section or form. Tinted fill, hairline border, coloured title and icon. Colours: Brand, Gray, Error, Warning, Success. Variants: 10 | Property | Type / options | | ---------------- | ---------------------------------------- | | Title | text | | Description | text | | Show description | boolean (on) | | Actions | boolean (on) | | Close | boolean (on) | | Style | Subtle · Outline · Solid | | Color | Brand · Gray · Error · Warning · Success | Code adds one option that is not a Figma variant yet: Size **sm · md** (`size="sm"`, default md). Colours come from the `--color-alert-<color>-bg · border · title · icon` component tokens. **Style** - **Subtle** (default) — tinted background, hairline border. Use it almost everywhere. - **Outline** — white surface, coloured border and a soft shadow. Use it on tinted or grey surfaces (bg-secondary, filled cards) where a tint would disappear. - **Solid** — full-colour fill. Only for blocking, page-level issues (account suspended, payment failed, data loss). **Size** - **md** (default) for pages and cards; **sm** for dense UI, forms, table toolbars and side panels. ## Usage ```tsx import { Alert } from '@stanvision/atomus-react'; <Alert color="warning" title="Trial ends in 3 days" onClose={dismiss}> Add a payment method to keep your projects. </Alert> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `color` — `brand` · `gray` · `error` · `warning` · `success` (aliases: `info` → brand, `neutral` → gray, `danger` → error). - `variant` — `subtle` (default, tinted) · `outline` (white, for tinted or grey surfaces) · `solid` (blocking issues only). Figma: Style. - `size` — `md` (default) or `sm` for dense UI; `flush` removes the radius and side borders for full-bleed placement. - `title` and `children` (Figma: Title, Description); `actions` — up to two small buttons; `onClose` (Figma: Close). - Each colour has its own icon, so meaning never depends on colour alone. Colours come from the `--color-alert-*` component tokens. **Don’t** - Don’t stack more than two alerts; use toasts for transient confirmations. - Don’t use `solid` for routine messages. ### Design guidance From the Figma guidelines. **Do** - Pick the colour by meaning: Brand = info, Gray = neutral, Error, Warning, Success. - Lead with a short title; put detail in the description. - Give a clear next step: one link or up to two small buttons. **Forbidden** - Never stack several alerts. - Never use alerts for marketing. - Never use Solid for routine messages — it shouts. - Never auto-dismiss an alert — use Toast for transient messages. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/message-alert.md`. Use only these props; anything else is not part of the API. ### `Alert` `import { Alert } from '@stanvision/atomus-react';` — source: `react/src/components/Alert.tsx` | Prop | Type | Default | Description | | ---------- | ------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | `ReactNode` | — | Figma: Title | | `children` | `ReactNode` | — | Figma: Description (+ Show description) | | `color` | `'brand' \| 'gray' \| 'error' \| 'warning' \| 'success' \| 'info' \| 'neutral' \| 'danger'` | `'brand'` | Figma: Color. Aliases: `info` = brand, `neutral` = gray, `danger` = error. | | `variant` | `'subtle' \| 'outline' \| 'solid'` | `'subtle'` | Figma: Style. `subtle` (default) — tinted fill and hairline border. `outline` — white surface with a coloured border; use on tinted or grey surfaces. `solid` — full-colour fill; only for blocking, page-level issues. | | `size` | `'sm' \| 'md'` | `'md'` | Figma: Size — `md` (default) or the compact `sm` for dense UI, forms and side panels. | | `flush` | `boolean` | `false` | Removes the radius and side borders so the alert can span the full width of a card or page edge. | | `actions` | `ReactNode` | — | Figma: Actions — up to two small buttons | | `onClose` | `() => void` | — | Figma: Close | | `icon` | `ReactNode` | — | Replaces the default status icon | Also accepts every native `<div>` attribute (`id`, `role`, `onClick` …), except `title`, `color`, which are replaced above. --- # Toast > Short floating confirmations with auto-dismiss. URL: https://docs.atomus.io/components/toast/ Short floating confirmations with auto-dismiss. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/toast.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ftoast.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/message-alert.md` · Open in Figma: [Toast](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25427-513) Properties, variants and anatomy of the Figma components. React props use the same names. ### Toast Floating notification; auto-dismiss in code. Variants: 5 | Property | Type / options | | ----------- | ---------------------------------------- | | Title | text | | Description | text | | Close | boolean (on) | | Color | Brand · Gray · Error · Warning · Success | ## Usage ```tsx import { Toast, ToastProvider, useToast } from '@stanvision/atomus-react'; // once, at the app root <ToastProvider>{app}</ToastProvider> // anywhere inside const toast = useToast(); toast.show({ color: 'success', title: 'Changes saved' }); ``` A short, floating confirmation. Wrap the app in `ToastProvider` and call `useToast().show({...})`. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `title`, `description`, `color` (`brand` · `gray` · `error` · `warning` · `success`), an optional `action`. - `duration` in ms (default 5000; errors stay until closed). Hover or focus pauses the timer. - `ToastProvider position` — `bottom-right` (default), `top-right`, `bottom-center`; at most 4 at once. ### Design guidance From the Figma guidelines. **Do** - Use for short confirmations of something the user just did (“Changes saved”). - Keep it to a title, an optional one-line description and at most one action. - Keep error toasts open until the user closes them. **Forbidden** - Never put critical information or a required decision in a toast — use Alert or Modal. - Never show more than one toast for one event. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/message-alert.md`. Use only these props; anything else is not part of the API. ### `Toast` Figma: Toast — a single floating notification. Use ToastProvider + useToast to show them. `import { Toast } from '@stanvision/atomus-react';` — source: `react/src/components/Toast.tsx` | Prop | Type | Default | Description | | ------------- | -------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------- | | `title` | `ReactNode` | **required** | Figma: Title | | `description` | `ReactNode` | — | Figma: Description | | `color` | `'brand' \| 'gray' \| 'error' \| 'warning' \| 'success'` | `'gray'` | Figma: Color | | `onClose` | `() => void` | — | Figma: Close | | `action` | `ReactNode` | — | Action element, e.g. a link-style Button. | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. ### `ToastProvider` Hosts toasts. Pauses auto-dismiss on hover and focus. `import { ToastProvider } from '@stanvision/atomus-react';` — source: `react/src/components/Toast.tsx` | Prop | Type | Default | Description | | ---------- | -------------------------------------------------- | ---------------- | -------------------- | | `children` | `ReactNode` | **required** | Content. | | `position` | `'top-right' \| 'bottom-right' \| 'bottom-center'` | `'bottom-right'` | Where toasts appear. | Accepts only the props above. ### `useToast` `import { useToast } from '@stanvision/atomus-react';` — source: `react/src/components/Toast.tsx` Hook. Returns `{ show: (t: ToastOptions) => string; dismiss: (id: string) => void }`. Call it inside `<ToastProvider>`: `const { show, dismiss } = useToast(); show({ title: 'Saved', color: 'success' })`. `show` takes `ToastOptions` (the `Toast` props plus `duration` in ms; 0 keeps it open) and returns the toast id. --- # Banner > Full-width announcement bar. URL: https://docs.atomus.io/components/banner/ Full-width announcement bar. ## In Figma From `guidelines/components/metrics-feeds.md` Properties, variants and anatomy of the Figma components. ### Banner Variants: 2 | Property | Type / options | | -------- | --------------- | | Title | text | | Message | text | | Action | boolean (on) | | Color | Default · Brand | ## Usage #### Banner **Do** - Use for one product- or account-wide message at the top of the page, and let people dismiss it. **Forbidden** - Never show more than one banner at a time. - Never use a banner for form or section errors — use Alert. --- # Notifications > Dropdown panel for the bell icon: header, tabs, rows, footer link. URL: https://docs.atomus.io/components/notifications/ Dropdown panel for the bell icon: header, tabs, rows, footer link. ## In Figma From `guidelines/components/message-alert.md` Properties, variants and anatomy of the Figma components. ### Notifications panel Variants: 1 ### Notification item Row for notification panels and inboxes; unread rows get a tint and dot. Variants: 2 | Property | Type / options | | -------- | ---------------- | | Name | text | | Message | text | | Actions | boolean (off) | | Type | Default · Unread | ## Usage #### Notifications panel **Do** - Mark unread rows with the Unread type and link to the full inbox in the footer. **Forbidden** - Never use the panel for messages about the current page — use Alert. --- # Progress bar > Progress of a known task or quota. URL: https://docs.atomus.io/components/progress-bar/ Progress of a known task or quota. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/progress-bar.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fprogress-bar.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/progress-loading.md` · Open in Figma: [ProgressBar](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25429-686) Properties, variants and anatomy of the Figma components. React props use the same names. ### Progress bar Linear progress. Variants: 3 | Property | Type / options | | -------- | --------------------- | | Label | None · Right · Bottom | ### Progress circle Circular progress. Variants: 3 | Property | Type / options | | -------- | -------------- | | Size | sm · md · lg | ## Usage ```tsx import { ProgressBar } from '@stanvision/atomus-react'; <ProgressBar value={64} label="Storage used" labelPosition="right" /> ``` Shows progress of a known task or quota. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `value` 0–100; `label` — the accessible name; `labelPosition` `none` · `right` · `bottom` (Figma: Label). ### Design guidance From the Figma guidelines. **Do** - Show the percentage when progress is known. - Use Loading indicator when it is not. - Label what is progressing. **Forbidden** - Never use a progress bar for steps — use Progress steps. - Never animate backwards. - Never show several bars for one task. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/progress-loading.md`. Use only these props; anything else is not part of the API. ### `ProgressBar` `import { ProgressBar } from '@stanvision/atomus-react';` — source: `react/src/components/ProgressBar.tsx` | Prop | Type | Default | Description | | --------------- | ------------------------------- | ------------ | ---------------------------------------- | | `value` | `number` | **required** | 0–100 | | `labelPosition` | `'none' \| 'right' \| 'bottom'` | `'right'` | Figma: Label — where the percentage sits | | `label` | `string` | `'Progress'` | Accessible name, e.g. “Storage used” | Also accepts every native `<div>` attribute (`id`, `role`, `onClick` …). --- # Loading & skeleton > Spinners for short waits and skeletons that hold the layout while content loads. URL: https://docs.atomus.io/components/loading-skeleton/ Spinners for short waits and skeletons that hold the layout while content loads. ## In Figma From `guidelines/components/progress-loading.md` Properties, variants and anatomy of the Figma components. ### Loading indicator Spinner for page or section loading. Variants: 2 | Property | Type / options | | ---------- | -------------- | | Show label | boolean (on) | | Size | sm · md | ### Skeleton Loading placeholders. Variants: 3 | Property | Type / options | | -------- | --------------------------- | | Type | Text · Avatar + text · Card | ## Usage #### Loading indicator **Do** - Use for short waits where the layout is unknown. **Forbidden** - Never block a whole page with a spinner when a skeleton fits. #### Skeleton **Do** - Match the skeleton to the layout that will load. **Forbidden** - Never leave a skeleton for more than a few seconds without a message. --- # Empty state > Fills empty pages and tables, and says what to do next. URL: https://docs.atomus.io/components/empty-state/ Fills empty pages and tables, and says what to do next. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/empty-state.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fempty-state.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/empty-state-file-upload.md` · Open in Figma: [EmptyState](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25433-71) Properties, variants and anatomy of the Figma components. React props use the same names. ### Empty state Empty / no-results state for tables, lists and pages. Variants: 2 | Property | Type / options | | ----------- | -------------- | | Title | text | | Description | text | | Actions | boolean (on) | | Size | sm · md | ## Usage ```tsx import { EmptyState } from '@stanvision/atomus-react'; <EmptyState title="No projects yet" description="Create your first project to start designing with Atomus." actions={<Button hierarchy="primary">New project</Button>} /> ``` Fills an empty page, table or panel and says what to do next. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `title` (what’s missing), `description` (one sentence), `actions`, `icon`, `size` `sm` (panels) · `md` (pages). ### Design guidance From the Figma guidelines. **Do** - Explain what will appear here and how to start. - Offer one primary action. - Use md in pages and cards, sm in narrow panels. **Forbidden** - Never leave a screen blank. - Never blame the user. - Never show more than two actions. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/empty-state-file-upload.md`. Use only these props; anything else is not part of the API. ### `EmptyState` `import { EmptyState } from '@stanvision/atomus-react';` — source: `react/src/components/EmptyState.tsx` | Prop | Type | Default | Description | | ------------- | -------------- | ------------ | -------------------------------------------------- | | `title` | `ReactNode` | **required** | Figma: Title | | `description` | `ReactNode` | — | Figma: Description | | `icon` | `ReactNode` | — | Featured icon glyph | | `actions` | `ReactNode` | — | Figma: Actions — usually Outline + Primary buttons | | `size` | `'sm' \| 'md'` | `'md'` | Figma: Size — sm (panels) · md (pages) | Also accepts every native `<div>` attribute (`id`, `role`, `onClick` …), except `title`, which is replaced above. --- # Navigation > App header, sidebar and nav items. URL: https://docs.atomus.io/components/navigation/ App header, sidebar and nav items. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/navigation.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fnavigation.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/navigation.md` · Open in Figma: [AppHeader](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25431-196) · [SidebarNavigation](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25431-195) · [NavItem](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25431-67) Properties, variants and anatomy of the Figma components. React props use the same names. ### App header Top navigation bar for apps. Variants: 1 ### Sidebar navigation App sidebar 280px or 72px rail. Variants: 2 | Property | Type / options | | --------- | -------------- | | Collapsed | False · True | ### Nav item Sidebar navigation row; collapsed = icon only. Variants: 6 | Property | Type / options | | --------- | ------------------------ | | Label | text | | Icon swap | instance swap (icon) | | Badge | boolean (off) | | Chevron | boolean (off) | | Collapsed | False · True | | State | Default · Hover · Active | ## Usage ```tsx import { AppHeader, SidebarNavigation, NavItem } from '@stanvision/atomus-react'; <SidebarNavigation header={<Logo />} footer={<NavItem label="Settings" href="/settings" />}> <NavItem label="Home" href="/" icon={<HomeIcon />} active /> <NavItem label="Projects" href="/projects" badge={12} /> </SidebarNavigation> ``` `AppHeader` (top bar), `SidebarNavigation` (280px, or a 72px rail) and `NavItem` rows. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `NavItem` — `label`, `href`, `icon`, `badge`, `chevron`, `active` (sets `aria-current="page"`), `collapsed` (icon only, label as tooltip and accessible name). - `SidebarNavigation` — `header`, `children` (NavItems), `footer`, `collapsed`. - `AppHeader` — `brand`, `nav`, `actions`; the nav hides below 768px, so pair it with a menu button. **Don’t** - Don’t mix a sidebar and a header nav with the same links. ### Design guidance From the Figma guidelines. #### App header **Do** - Use for apps without a sidebar, or for global search, notifications and the account menu. **Forbidden** - Never put page-level actions in the app header — use Page header. #### Sidebar navigation **Do** - Keep 5–8 top-level items. - Highlight the current page. - Use Collapsed on small screens. **Forbidden** - Never nest navigation more than two levels. - Never mix icon styles. - Never put primary actions in the navigation. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/navigation.md`. Use only these props; anything else is not part of the API. ### `AppHeader` Figma: App header — top navigation bar for apps. `import { AppHeader } from '@stanvision/atomus-react';` — source: `react/src/components/Navigation.tsx` | Prop | Type | Default | Description | | --------- | ----------- | ------- | ----------------------------------------- | | `brand` | `ReactNode` | — | Logo or product name | | `nav` | `ReactNode` | — | Primary links (NavItem or anchors) | | `actions` | `ReactNode` | — | Right side: search, notifications, avatar | Also accepts every native HTML attribute (`id`, `role` …). ### `SidebarNavigation` Figma: Sidebar navigation (280px, or a 72px rail when collapsed). `import { SidebarNavigation } from '@stanvision/atomus-react';` — source: `react/src/components/Navigation.tsx` | Prop | Type | Default | Description | | ------------ | ----------- | ------------ | ------------------------------------------------ | | `header` | `ReactNode` | — | Logo or workspace switcher at the top | | `children` | `ReactNode` | **required** | NavItems | | `footer` | `ReactNode` | — | Pinned at the bottom: secondary links, user card | | `collapsed` | `boolean` | — | Figma: Collapsed — 280px or a 72px rail | | `aria-label` | `string` | — | Accessible name. | Also accepts every native HTML attribute (`id`, `role` …). ### `NavItem` Figma: Nav item. Renders a link; pass href (or onClick). `import { NavItem } from '@stanvision/atomus-react';` — source: `react/src/components/Navigation.tsx` | Prop | Type | Default | Description | | ----------- | ----------- | ------------ | --------------------------------------------------------------------------- | | `label` | `string` | **required** | Figma: Label | | `icon` | `ReactNode` | — | Figma: Icon swap | | `badge` | `ReactNode` | — | Figma: Badge — a count or short label after the text | | `chevron` | `boolean` | — | Figma: Chevron — marks an item with children | | `active` | `boolean` | — | Figma: State=Active | | `collapsed` | `boolean` | — | Figma: Collapsed — icon only, label becomes the tooltip and accessible name | Also accepts every native `<a>` attribute (`href`, `target`, `onClick` …). --- # Tabs > Switch between views. Underline, pill or segmented. URL: https://docs.atomus.io/components/tabs/ Switch between views. Underline, pill or segmented. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/tabs.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ftabs.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/tabs.md` · Open in Figma: [Tabs](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25423-513) Properties, variants and anatomy of the Figma components. React props use the same names. ### Tabs Tab bar built from Tab. Variants: 3 | Property | Type / options | | -------- | ---------------------------- | | Style | Underline · Pill · Segmented | ### Tab Single tab: Underline, Pill or Segmented. Variants: 30 | Property | Type / options | | ------------ | --------------------------------------------- | | Label | text | | Icon | boolean (off) | | Icon swap | instance swap (icon) | | Count | boolean (off) | | Count number | text | | Style | Underline · Pill · Segmented | | Size | sm · md | | State | Default · Hover · Active · Focused · Disabled | ### Vertical tabs Side navigation for settings and long forms. Variants: 2 | Property | Type / options | | -------- | -------------- | | Style | Line · Pill | ## Usage ```tsx import { Tabs } from '@stanvision/atomus-react'; <Tabs aria-label="Project sections" variant="underline" items={[{ value: 'overview', label: 'Overview' }, { value: 'activity', label: 'Activity', count: 12 }]} /> ``` Switch between views of the same object. Arrow, Home and End keys move between tabs. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `items` — `[{ value, label, count?, disabled? }]`, two to six; `aria-label`. - `variant` — `underline` (page sections) · `pill` (sub-navigation) · `segmented` (filters, chart ranges). - `value` + `onChange` (controlled) or `defaultValue`. ### Design guidance From the Figma guidelines. **Do** - Use for views of the same content. - Keep labels short; add counts when they help. - Use Vertical tabs for settings. **Forbidden** - Never use tabs for sequential steps — use Progress steps. - Never exceed seven tabs. - Never mix tab styles on one page. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/tabs.md`. Use only these props; anything else is not part of the API. ### `Tabs` `import { Tabs } from '@stanvision/atomus-react';` — source: `react/src/components/Tabs.tsx` | Prop | Type | Default | Description | | -------------- | -------------------------------------- | ------------- | ------------------------------------------------------------------------------- | | `items` | `TabItem[]` | **required** | The items. | | `variant` | `'underline' \| 'pill' \| 'segmented'` | `'underline'` | Figma: Style | | `value` | `string` | — | Controlled value. | | `defaultValue` | `string` | — | Initial value when uncontrolled. | | `onChange` | `(value: string) => void` | — | Called with the new value. | | `aria-label` | `string` | — | Accessible name for the tab list | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `TabItem`: | Field | Type | Description | | ----------- | ----------- | --------------------------------- | | `value` | `string` | | | `label` | `ReactNode` | | | `count?` | `number` | Small count badge after the label | | `disabled?` | `boolean` | | --- # Breadcrumb > Breadcrumb trail; last segment is Current. URL: https://docs.atomus.io/components/breadcrumb/ Breadcrumb trail; last segment is Current. ## In Figma From `guidelines/components/breadcrumb.md` Properties, variants and anatomy of the Figma components. ### Breadcrumb Variants: 2 | Property | Type / options | | --------- | --------------- | | Separator | Chevron · Slash | ### Breadcrumb item Breadcrumb segment: Home (icon), Link, Current. Variants: 5 | Property | Type / options | | -------- | --------------------- | | Label | text | | Type | Home · Link · Current | | State | Default · Hover | ## Usage #### Breadcrumb **Do** - Show the full path from the top level. - Make every item except the last a link; the last item is the current page. - Collapse middle items into “…” when the path is long. **Forbidden** - Never use breadcrumbs in single-level apps. - Never repeat the page title in the same row. - Never let a breadcrumb wrap to two lines. --- # Pagination & carousel > Pagination for tables and lists, and carousel controls for marketing galleries. URL: https://docs.atomus.io/components/pagination/ Pagination for tables and lists, and carousel controls for marketing galleries. ## In Figma From `guidelines/components/pagination.md` Properties, variants and anatomy of the Figma components. ### Pagination Pagination bar for tables and lists. Variants: 2 | Property | Type / options | | -------- | ---------------------- | | Type | Page numbers · Minimal | ### Pagination number Page number cell. Variants: 3 | Property | Type / options | | -------- | ------------------------ | | Number | text | | State | Default · Hover · Active | ### Carousel Image carousel with arrows and dots. Variants: 4 | Property | Type / options | | ---------- | ---------------------------- | | Type | Arrows inside · Arrows below | | Breakpoint | Desktop · Mobile | ### Carousel dots Slide indicator. Variants: 2 | Property | Type / options | | -------- | --------------- | | Style | Default · Brand | ## Usage #### Pagination **Do** - Show the current page and the total. - Keep Previous and Next visible. - Use for tables over about 25 rows. **Forbidden** - Never paginate feeds — load more instead. - Never show more than seven page numbers. - Never reset the page when sorting. --- # Progress steps > Multi-step flow indicator for onboarding, checkout and setup wizards. URL: https://docs.atomus.io/components/progress-steps/ Multi-step flow indicator for onboarding, checkout and setup wizards. ## In Figma From `guidelines/components/progress-loading.md` Properties, variants and anatomy of the Figma components. ### Progress steps Multi-step flow indicator. Variants: 2 | Property | Type / options | | ----------- | --------------------- | | Orientation | Horizontal · Vertical | ### Step Single step for Progress steps. Variants: 6 | Property | Type / options | | --------------- | ----------------------------- | | Title | text | | Supporting text | text | | Show supporting | boolean (on) | | Orientation | Horizontal · Vertical | | Status | Complete · Current · Upcoming | ## Usage #### Progress steps **Do** - Use for flows of 3–7 steps and show completed, current and upcoming states. **Forbidden** - Never use steps to move between unrelated pages — use Tabs. --- # Table > Rows of records with sorting and selection. URL: https://docs.atomus.io/components/table/ Rows of records with sorting and selection. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/table.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ftable.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/table.md` · Open in Figma: [Table](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25426-503) Properties, variants and anatomy of the Figma components. React props use the same names. ### Table header cell Column header with optional select-all checkbox and sort. Variants: 1 | Property | Type / options | | -------- | -------------- | | Label | text | | Checkbox | boolean (off) | | Sortable | boolean (off) | ### Table cell Body cell: Text, Text + supporting, Avatar, Badge, Checkbox, Actions. Sizes sm (52) / md (72). Variants: 12 | Property | Type / options | | -------- | -------------------------------------------------------------- | | Text | text | | Size | sm · md | | Type | Text · Text + supporting · Avatar · Badge · Checkbox · Actions | ### Filter bar Search, filters, sort and active-filter tags. Variants: 2 | Property | Type / options | | ---------- | ---------------- | | Breakpoint | Desktop · Mobile | ## Usage ```tsx import { Table } from '@stanvision/atomus-react'; <Table caption="Team members" selectable rowKey={(r) => r.id} rows={members} columns={[ { key: 'name', header: 'Name', sortable: true }, { key: 'projects', header: 'Projects', sortable: true, align: 'end' }, ]} /> ``` Rows of records with sortable columns and optional row selection. Pair with Filter bar above and Pagination below. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `columns` — `{ key, header, sortable?, render?, supporting?, align?, width? }`; `rows`; `rowKey`. - `size` `sm` (52px rows) · `md` (72px rows); `selectable` + `selected` / `onSelectedChange`; `caption`; `empty` (e.g. an EmptyState). - Use Avatar, Badge and tertiary Buttons inside `render` for the Figma cell types. **Don’t** - Don’t put more than one primary action per row; group the rest in a DropdownMenu. ### Design guidance From the Figma guidelines. **Do** - Build rows from Table cell types. - Right-align numbers. - Put Filter bar above the table and Pagination below. **Forbidden** - Never exceed 7–8 columns on desktop. - Never wrap long text — truncate it and show the full text in a tooltip. - Never combine zebra stripes and row borders. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/table.md`. Use only these props; anything else is not part of the API. ### `Table` Figma: Table header cell + Table cell. Sorting is built in; filtering and pagination stay with the page (Filter bar, Pagination). `import { Table } from '@stanvision/atomus-react';` — source: `react/src/components/Table.tsx` | Prop | Type | Default | Description | | ------------------ | -------------------------- | ------------ | ------------------------------------------------------------------------------- | | `columns` | `TableColumn<Row>[]` | **required** | Column definitions. | | `rows` | `Row[]` | **required** | Row data. | | `rowKey` | `(row: Row) => string` | **required** | Returns a stable key for a row. | | `size` | `'sm' \| 'md'` | `'sm'` | Figma: Table cell Size — sm 52 · md 72 | | `selectable` | `boolean` | — | Figma: Table header cell — Checkbox; adds a select-all column | | `selected` | `string[]` | — | Keys of the selected rows (controlled). | | `onSelectedChange` | `(keys: string[]) => void` | — | Called with the selected row keys. | | `caption` | `string` | — | Accessible table caption | | `empty` | `ReactNode` | — | Rendered when rows is empty, e.g. an EmptyState | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `TableColumn`: | Field | Type | Description | | ------------- | -------------------------------- | ------------------------------------------------------------------------------------------- | | `key` | `string` | | | `header` | `ReactNode` | Figma: Table header cell — Label | | `sortable?` | `boolean` | Figma: Table header cell — Sortable | | `sortValue?` | `(row: Row) => string \| number` | Value used for sorting; defaults to row\[key] | | `render?` | `(row: Row) => ReactNode` | Cell content; defaults to row\[key]. Use Avatar, Badge or Buttons for the Figma cell types. | | `supporting?` | `(row: Row) => ReactNode` | Supporting text under the main text (Figma: Type=Text + supporting) | | `align?` | `'start' \| 'end'` | | | `width?` | `number \| string` | | --- # Badge & Tag > Status labels and removable chips. URL: https://docs.atomus.io/components/badge-tag/ Status labels and removable chips. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/badge.json https://docs.atomus.io/r/tag.json` Copy command [Open Badge in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fbadge.json) [Open Tag in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ftag.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/badge.md` · Open in Figma: [Badge](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25421-1073) · [Tag](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25421-1092) Properties, variants and anatomy of the Figma components. React props use the same names. ### Badge Status label. Light for tables and lists, Solid for emphasis. Optional dot, icon or close. Variants: 30 | Property | Type / options | | ----------------- | ---------------------------------------- | | Label | text | | Dot | boolean (off) | | Leading icon | boolean (off) | | Leading icon swap | instance swap (icon) | | Close | boolean (off) | | Size | sm · md · lg | | Style | Light · Solid | | Color | Gray · Brand · Error · Warning · Success | ### Tag Removable filter / selection chip. Variants: 3 | Property | Type / options | | ----------------- | -------------------- | | Label | text | | Leading icon | boolean (off) | | Leading icon swap | instance swap (icon) | | Close | boolean (on) | | Size | sm · md · lg | ## Usage ```tsx import { Badge, Tag } from '@stanvision/atomus-react'; <Badge color="success" dot>Active</Badge> <Badge color="brand" variant="solid">New</Badge> <Tag onRemove={() => remove(id)}>Figma</Tag> ``` ### Badge Labels a status or count next to content. #### Props - `children` — one or two words (Figma: Label). - `color` — `gray` · `brand` · `error` · `warning` · `success`; `variant` — `light` (tinted) or `solid` (Figma: Style). - `size` — `sm` 20 · `md` 24 · `lg` 28; `dot`, `icon`, `onClose` (Figma: Dot, Leading icon, Close). - Always keep the word: colour alone never carries the status. **Don’t** - Don’t use solid **warning** with small text — white on amber is 2.2:1. Prefer the light warning badge. - Don’t use badges as buttons; for removable values use Tag. ### Tag A compact, removable chip for filters, keywords and selected values (Tags input, Multi-select). #### Props - `children` (Figma: Label), `size` `sm` 24 · `md` 28 · `lg` 32, optional `icon`. - `onRemove` shows the × button (Figma: Close); its label reads “Remove \<value>”. **Don’t** - Don’t use tags for status — use Badge. ### Design guidance From the Figma guidelines. #### Badge **Do** - Pick the colour by meaning: Success, Warning, Error, Brand (info), Gray (neutral). - Keep labels to one or two words. - Use Tag, not Badge, for values the user can remove. **Forbidden** - Never use a badge as a button or link. - Never rely on colour alone — the word carries the meaning. - Never place more than three badges together. #### Tag **Do** - Use for user-entered or filterable values: filters, skills, recipients. - Give removable tags a close button (`onRemove` in code). **Forbidden** - Never use Tag for status — use Badge. - Never colour tags by status. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/badge.md`. Use only these props; anything else is not part of the API. ### `Badge` `import { Badge } from '@stanvision/atomus-react';` — source: `react/src/components/Badge.tsx` | Prop | Type | Default | Description | | ---------- | -------------------------------------------------------- | ------------ | --------------------------------------- | | `children` | `ReactNode` | **required** | Figma: Label | | `color` | `'gray' \| 'brand' \| 'error' \| 'warning' \| 'success'` | `'gray'` | Figma: Color | | `variant` | `'light' \| 'solid'` | `'light'` | Figma: Style — light (tinted) or solid | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Figma: Size — sm 20 · md 24 · lg 28 | | `dot` | `boolean` | — | Figma: Dot | | `icon` | `ReactNode` | — | Figma: Leading icon + Leading icon swap | | `onClose` | `() => void` | — | Figma: Close — shows a remove button | Also accepts every native `<span>` attribute (`id`, `title` …). ### `Tag` `import { Tag } from '@stanvision/atomus-react';` — source: `react/src/components/Tag.tsx` | Prop | Type | Default | Description | | ---------- | ---------------------- | ------------ | --------------------------------------- | | `children` | `ReactNode` | **required** | Figma: Label | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Figma: Size — sm 24 · md 28 · lg 32 | | `icon` | `ReactNode` | — | Figma: Leading icon + Leading icon swap | | `onRemove` | `() => void` | — | Figma: Close — shows the × button | Also accepts every native `<span>` attribute (`id`, `title` …). --- # Avatar > People and workspaces, 24 to 64px, with initials fallback and status. URL: https://docs.atomus.io/components/avatar/ People and workspaces, 24 to 64px, with initials fallback and status. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/avatar.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Favatar.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/avatar.md` · Open in Figma: [Avatar](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25422-267) Properties, variants and anatomy of the Figma components. React props use the same names. ### Avatar Avatar 24–64px. Shape: Circle or Rounded. Type: Image (pick a face via the Photo property), Initials, Icon. Optional status dot. Variants: 36 | Property | Type / options | | --------- | ---------------------------- | | Status | boolean (off) | | Initials | text | | Icon swap | instance swap (icon) | | Size | xs · sm · md · lg · xl · 2xl | | Type | Image · Initials · Icon | | Shape | Circle · Rounded | ### Avatar photo Stock avatar photos. Pick one via the Photo property on Avatar, or drop your own image into an instance. Variants: 22 | Property | Type / options | | -------- | ----------------- | | Face | M01–M12 · F01–F10 | ### Avatar group Stacked avatars with overflow count. Variants: 3 | Property | Type / options | | -------- | -------------- | | Size | xs · sm · md | ### Avatar label group Avatar with name and email — for tables, nav and comments. Variants: 2 | Property | Type / options | | --------------- | -------------- | | Name | text | | Supporting text | text | | Size | sm · md | ## Usage ```tsx import { Avatar } from '@stanvision/atomus-react'; <Avatar name="Kristina Stan" src={photo} size="md" status="online" /> ``` Shows a person or workspace. Falls back to initials, then to a user icon. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `name` — used for initials, tooltip and accessible name. - `src` (Figma: Type=Image), `initials` (Figma: Initials), `icon` (Figma: Icon swap). - `size` `xs` 24 · `sm` 32 · `md` 40 · `lg` 48 · `xl` 56 · `2xl` 64; `shape` `circle` · `rounded`; `status` `online` · `away` · `offline`. **Don’t** - Don’t use stock faces as placeholders — use initials. ### Design guidance From the Figma guidelines. **Do** - Use a photo when you have one; fall back to initials, then an icon. - Always pass the person’s name so the avatar has an accessible name and tooltip. - Show the status dot only for live presence (online, away, offline). **Forbidden** - Never stretch or crop photos by hand — size comes from the Size variant. - Never mix Circle and Rounded shapes in one list. - Never use an avatar as decoration without a name nearby. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/avatar.md`. Use only these props; anything else is not part of the API. ### `Avatar` `import { Avatar } from '@stanvision/atomus-react';` — source: `react/src/components/Avatar.tsx` | Prop | Type | Default | Description | | ---------- | ----------------------------------------------- | ---------- | ------------------------------------------------------------------------- | | `name` | `string` | — | Person or workspace name — used for initials, tooltip and accessible name | | `src` | `string` | — | Figma: Type=Image | | `initials` | `string` | — | Figma: Initials — overrides the initials derived from name | | `icon` | `ReactNode` | — | Figma: Type=Icon + Icon swap | | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | `'md'` | Figma: Size — xs 24 · sm 32 · md 40 · lg 48 · xl 56 · 2xl 64 | | `shape` | `'circle' \| 'rounded'` | `'circle'` | Figma: Shape | | `status` | `'online' \| 'away' \| 'offline'` | — | Figma: Status | Also accepts every native `<span>` attribute (`id`, `title` …). --- # Metric card > A single KPI for dashboards. URL: https://docs.atomus.io/components/metric-card/ A single KPI for dashboards. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/metric-card.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fmetric-card.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/metrics-feeds.md` · Open in Figma: [MetricCard](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25435-72) Properties, variants and anatomy of the Figma components. React props use the same names. ### Metric card KPI / stat card for dashboards and marketing. Variants: 3 | Property | Type / options | | -------- | ---------------------- | | Label | text | | Value | text | | Type | Simple · Trend · Chart | ## Usage ```tsx import { MetricCard } from '@stanvision/atomus-react'; <MetricCard label="Monthly revenue" value="$48.2k" change="12%" caption="vs last month" /> ``` A single KPI for dashboards. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `label`, `value` (pre-formatted), `type` `simple` · `trend` · `chart` (Figma: Type). - `change`, `caption` (“vs last month”), `trend` (inferred from a leading “-”), `data` for the chart sparkline, `action`. ### Design guidance From the Figma guidelines. **Do** - Lead with the number. - Use Trend to show change against a stated period. - Keep units in the value (“$48.2k”, “12%”). **Forbidden** - Never show more than four metric cards in a row. - Never mix time periods in one row. - Never colour-code a change without the arrow. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/metrics-feeds.md`. Use only these props; anything else is not part of the API. ### `MetricCard` `import { MetricCard } from '@stanvision/atomus-react';` — source: `react/src/components/MetricCard.tsx` | Prop | Type | Default | Description | | --------- | -------------------------------- | ------------ | ------------------------------------------------------ | | `label` | `ReactNode` | **required** | Figma: Label | | `value` | `ReactNode` | **required** | Figma: Value — pre-formatted (“$48.2k”) | | `type` | `'simple' \| 'trend' \| 'chart'` | `'trend'` | Figma: Type — simple · trend · chart | | `change` | `string` | — | Change vs the comparison period, e.g. “12%” or “-0.4%” | | `trend` | `'up' \| 'down'` | — | Inferred from a leading “-” in change when omitted | | `caption` | `ReactNode` | — | Comparison period, e.g. “vs last month” | | `data` | `number[]` | — | Sparkline values for type=“chart” | | `action` | `ReactNode` | — | Header action, e.g. a tertiary icon button | Also accepts every native `<div>` attribute (`id`, `role`, `onClick` …). --- # Activity item > A feed or notification row: who did what, and when. URL: https://docs.atomus.io/components/activity-item/ A feed or notification row: who did what, and when. ## In Figma From `guidelines/components/metrics-feeds.md` Properties, variants and anatomy of the Figma components. ### Activity item Feed / notification row. Variants: 2 | Property | Type / options | | -------- | -------------- | | Name | text | | Time | text | | Message | text | | Unread | False · True | ## Usage Follow the descriptions above; there are no extra rules for this component yet. --- # Code snippet > Copyable code, Roboto Mono. URL: https://docs.atomus.io/components/code-snippet/ Copyable code, Roboto Mono. ## In Figma From `guidelines/components/metrics-feeds.md` Properties, variants and anatomy of the Figma components. ### Code snippet Variants: 2 | Property | Type / options | | -------- | -------------- | | Type | Inline · Block | ## Usage Follow the descriptions above; there are no extra rules for this component yet. --- # Tree view > Nested, expandable lists for files, folders and navigation hierarchies. URL: https://docs.atomus.io/components/tree-view/ Nested, expandable lists for files, folders and navigation hierarchies. ## In Figma From `guidelines/components/tree-editor-color-picker.md` Properties, variants and anatomy of the Figma components. ### Tree view Example tree built from Tree items. Variants: 1 ### Tree item Row in a tree; levels 0–2. Variants: 18 | Property | Type / options | | --------- | -------------------------- | | Label | text | | Icon swap | instance swap (icon) | | Type | Folder · File | | Level | 0 · 1 · 2 | | State | Default · Hover · Selected | ## Usage #### Tree view **Do** - Use for files and categories. - Show expand and collapse chevrons. - Highlight the selected item. **Forbidden** - Never nest deeper than four levels. - Never use a tree for flat lists. - Never load a huge tree at once — load children on expand. --- # Messaging > Chat panel: header, Messages slot, composer. URL: https://docs.atomus.io/components/messaging/ Chat panel: header, Messages slot, composer. ## In Figma From `guidelines/components/messaging.md` Properties, variants and anatomy of the Figma components. ### Chat Variants: 1 | Property | Type / options | | -------- | ------------------ | | Messages | slot (any content) | ### Message bubble Chat message: Received or Sent; text or file. Variants: 4 | Property | Type / options | | --------- | --------------- | | Name | text | | Time | text | | Message | text | | Direction | Received · Sent | | Type | Text · File | ### Message input Composer for chat and comments. Variants: 1 | Property | Type / options | | ----------- | -------------- | | Placeholder | text | ## Usage #### Message bubble **Do** - Show sender, time and read state. - Group consecutive messages from one sender. - Use the brand bubble for the current user. **Forbidden** - Never put long documents in a bubble — attach a file. - Never mix alignments for one sender. - Never remove timestamps. --- # Modal > A dialog that blocks the page until the person decides. URL: https://docs.atomus.io/components/modal/ A dialog that blocks the page until the person decides. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/modal.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fmodal.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/modal.md` · Open in Figma: [Modal](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25424-453) Properties, variants and anatomy of the Figma components. React props use the same names. ### Modal Dialog with header, Content slot and actions. Sizes 400 / 544 / 720px. Variants: 6 | Property | Type / options | | ------------- | --------------------- | | Content | slot (any content) | | Title | text | | Description | text | | Featured icon | boolean (on) | | Close button | boolean (on) | | Actions | boolean (on) | | Size | sm · md · lg | | Type | Default · Destructive | ## Usage ```tsx import { Modal } from '@stanvision/atomus-react'; <Modal open={open} onClose={() => setOpen(false)} type="destructive" featuredIcon title="Delete project?" description="You can’t undo this." actions={<><Button hierarchy="outline">Cancel</Button><Button hierarchy="primary">Delete</Button></>} /> ``` A dialog that blocks the page until the person decides. Built on the native `<dialog>`: focus moves in, Esc and the backdrop close it, the page behind is inert. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `open` + `onClose`; `title` and `description`; `children` for the Content slot. - `actions` — buttons, the primary last; `featuredIcon` (`true` or an icon); `closeButton` (default on). - `size` `sm` 400 · `md` 544 · `lg` 720; `type` `destructive` tints the icon red. ### Design guidance From the Figma guidelines. **Do** - Use for focused tasks that need a decision. - Put content into the Content slot. - Put the primary action on the right, after Cancel. - Use Type = Destructive for irreversible actions. **Forbidden** - Never open a modal on top of a modal. - Never use a modal for long forms — use a page or Drawer. - Never hide the close button. - Never open a modal the user did not ask for. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/modal.md`. Use only these props; anything else is not part of the API. ### `Modal` Figma: Modal. Uses the native dialog element: focus trap, Esc to close and inert background come built in. `import { Modal } from '@stanvision/atomus-react';` — source: `react/src/components/Modal.tsx` | Prop | Type | Default | Description | | -------------- | ---------------------------- | ------------ | ------------------------------------------------------------------------------- | | `open` | `boolean` | **required** | Whether it is shown (controlled). | | `onClose` | `() => void` | **required** | Called when the user closes it. | | `title` | `ReactNode` | **required** | Figma: Title | | `description` | `ReactNode` | — | Figma: Description | | `children` | `ReactNode` | — | Figma: Content slot | | `actions` | `ReactNode` | — | Figma: Actions — buttons, primary last | | `featuredIcon` | `boolean \| ReactNode` | — | Figma: Featured icon — true for the default glyph, or pass an icon | | `closeButton` | `boolean` | `true` | Figma: Close button | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Figma: Size — sm 400 · md 544 · lg 720 | | `type` | `'default' \| 'destructive'` | `'default'` | Figma: Type — destructive tints the featured icon red | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. --- # Dropdown menu > A list of actions that opens from a button. URL: https://docs.atomus.io/components/dropdown-menu/ A list of actions that opens from a button. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/dropdown-menu.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fdropdown-menu.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/menu.md` · Open in Figma: [DropdownMenu](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25419-934) · [MenuItem](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25419-933) Properties, variants and anatomy of the Figma components. React props use the same names. ### Dropdown menu Floating menu; items live in a slot. Variants: 1 | Property | Type / options | | -------- | ------------------ | | Items | slot (any content) | ### Menu item Row for dropdowns, selects, context and command menus. Variants: 8 | Property | Type / options | | ----------------- | ------------------------------------- | | Label | text | | Leading icon | boolean (on) | | Leading icon swap | instance swap (icon) | | Shortcut | boolean (off) | | Shortcut text | text | | Size | sm · md | | State | Default · Hover · Selected · Disabled | ### Context menu Right-click menu with shortcuts, separators, destructive item and submenus. Variants: 2 | Property | Type / options | | -------- | ---------------------- | | Type | Default · Submenu open | ## Usage ```tsx import { DropdownMenu, MenuItem } from '@stanvision/atomus-react'; <DropdownMenu label="Project actions" trigger={<Button hierarchy="outline">Actions</Button>} items={[ { label: 'Rename', shortcut: '⌘R', onSelect: rename }, { type: 'separator' }, { label: 'Delete', destructive: true, onSelect: remove }, ]} /> ``` A list of actions that opens from a button. `MenuItem` is exported for custom lists. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `trigger` — the button that opens it (it gets `aria-haspopup`, `aria-expanded` and arrow-key opening). - `items` — `{ label, icon?, shortcut?, disabled?, destructive?, onSelect }`, `{ type: 'separator' }` or `{ type: 'heading', label }`. - `align` `start` · `end`; `size` `sm` 36 · `md` 40; `label` names the menu. **Do** - Put destructive actions last, after a separator. **Don’t** - Don’t use it to pick a value — that’s Select. ### Design guidance From the Figma guidelines. #### Dropdown menu **Do** - Drop Menu items into the Items slot. - Group related items with separators and headings. - Show keyboard shortcuts for power users. **Forbidden** - Never exceed about ten items — use Command menu. - Never put forms inside menus. - Never run a destructive item without a confirmation. #### Context menu **Do** - Mirror actions that also exist elsewhere in the UI; put destructive items last, in red. **Forbidden** - Never hide an action only in a context menu. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/menu.md`. Use only these props; anything else is not part of the API. ### `DropdownMenu` Figma: Dropdown menu / Context menu — keyboard: ↑ ↓ Home End Enter Esc. `import { DropdownMenu } from '@stanvision/atomus-react';` — source: `react/src/components/Menu.tsx` | Prop | Type | Default | Description | | ------------- | ------------------ | ------------ | ------------------------------------------------------------------------------- | | `trigger` | `ReactElement` | **required** | The element that opens the menu, usually a Button | | `items` | `DropdownItem[]` | **required** | Figma: Items slot | | `align` | `'start' \| 'end'` | `'start'` | Alignment. | | `size` | `'sm' \| 'md'` | `'sm'` | Size. | | `label` | `string` | — | Accessible name for the menu | | `defaultOpen` | `boolean` | — | Start open (docs and tests) | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `DropdownItem`: ```ts type DropdownItem = | { type?: 'item'; label: ReactNode; icon?: ReactNode; shortcut?: string; disabled?: boolean; destructive?: boolean; onSelect?: () => void } | { type: 'separator' } | { type: 'heading'; label: ReactNode }; ``` ### `MenuItem` Figma: Menu item — row for dropdowns, selects, context and command menus. `import { MenuItem } from '@stanvision/atomus-react';` — source: `react/src/components/Menu.tsx` | Prop | Type | Default | Description | | ------------- | ---------------------------------------------- | ------------ | ---------------------------------------------------------- | | `label` | `ReactNode` | **required** | Figma: Label | | `icon` | `ReactNode` | — | Figma: Leading icon + Leading icon swap | | `shortcut` | `string` | — | Figma: Shortcut + Shortcut text | | `size` | `'sm' \| 'md'` | `'sm'` | Figma: Size — sm 32 · md 40 | | `selected` | `boolean` | — | Figma: State=Selected — shows a check | | `disabled` | `boolean` | — | Disables the control. | | `destructive` | `boolean` | — | Red label for destructive actions (Context menu) | | `onSelect` | `() => void` | — | Called when the item is chosen. | | `role` | `'menuitem' \| 'option' \| 'menuitemcheckbox'` | `'menuitem'` | ARIA role. | | `id` | `string` | — | Element id; generated when omitted (wires label and hint). | | `active` | `boolean` | — | Highlighted by keyboard navigation. | Accepts only the props above. --- # Tooltip & popover > Dark tooltip; arrow None, Top, Bottom, Left, Right. URL: https://docs.atomus.io/components/tooltip-popover/ Dark tooltip; arrow None, Top, Bottom, Left, Right. ## In Figma From `guidelines/components/tooltip-popover.md` Properties, variants and anatomy of the Figma components. ### Tooltip Variants: 10 | Property | Type / options | | --------------- | ---------------------------------- | | Text | text | | Supporting text | False · True | | Arrow | None · Top · Bottom · Left · Right | ## Usage #### Tooltip **Do** - Use for short hints on icon buttons and truncated text. - Keep it to one sentence. - Point the arrow at the trigger. **Forbidden** - Never put links or actions in a tooltip. - Never explain a disabled button only with a tooltip. - Never repeat the visible label. --- # Drawer & slideout > Panel from right, left or bottom (mobile sheet); content is a slot. URL: https://docs.atomus.io/components/drawer/ Panel from right, left or bottom (mobile sheet); content is a slot. ## In Figma From `guidelines/components/slideout-command-menu.md` Properties, variants and anatomy of the Figma components. ### Drawer Variants: 3 | Property | Type / options | | -------- | --------------------- | | Title | text | | Content | slot (any content) | | Position | Right · Left · Bottom | ### Slideout menu Side drawer (400px); content is a slot. Variants: 1 | Property | Type / options | | --------------- | ------------------ | | Content | slot (any content) | | Title | text | | Supporting text | text | | Actions | boolean (on) | ## Usage #### Drawer **Do** - Use for detail views and secondary forms. - Use the Bottom position on mobile. - Put content into the Content slot. **Forbidden** - Never use a drawer for critical confirmations — use Modal. - Never stack drawers. - Never make a drawer wider than half the screen. --- # Command menu > ⌘K command palette; results are a slot. URL: https://docs.atomus.io/components/command-menu/ ⌘K command palette; results are a slot. ## In Figma From `guidelines/components/slideout-command-menu.md` Properties, variants and anatomy of the Figma components. ### Command menu Variants: 1 | Property | Type / options | | -------- | ------------------ | | Results | slot (any content) | ## Usage #### Command menu **Do** - Open it with ⌘K / Ctrl K; group results and show shortcuts. **Forbidden** - Never make the command menu the only way to reach a feature. --- # Card > Groups related content and actions. Outlined, elevated or filled. URL: https://docs.atomus.io/components/card/ Groups related content and actions. Outlined, elevated or filled. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/card.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fcard.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/card.md` · Open in Figma: [Card](https://www.figma.com/design/bC42e82J3PYg2LMkryodIA/Atomus-4.0?node-id=25425-172) Properties, variants and anatomy of the Figma components. React props use the same names. ### Card Container for product and marketing layouts. Content is a slot. Styles: Outlined, Elevated, Filled. Padding md (16) / lg (24). Variants: 6 | Property | Type / options | | --------------- | ---------------------------- | | Content | slot (any content) | | Title | text | | Supporting text | text | | Header | boolean (on) | | Header action | boolean (on) | | Footer | boolean (off) | | Style | Outlined · Elevated · Filled | | Padding | md · lg | ### Card header Header for cards, tables and settings sections: title, badge, supporting text and actions. Variants: 3 | Property | Type / options | | -------- | ----------------------- | | Title | text | | Badge | boolean (on) | | Actions | boolean (on) | | Type | Default · Avatar · Icon | ### Section footer Footer row for cards, tables and settings sections: actions, pagination or a link. Variants: 3 | Property | Type / options | | -------- | --------------------------- | | Type | Actions · Pagination · Link | ### Inline CTA Call-to-action block inside app pages or articles. Variants: 3 | Property | Type / options | | -------- | ------------------------ | | Title | text | | Text | text | | Style | Subtle · Brand · Outline | ## Usage ```tsx import { Card } from '@stanvision/atomus-react'; <Card title="Team members" supportingText="Invite people and manage roles." headerAction={<Button hierarchy="outline" size="sm">Invite</Button>} footer={<Button hierarchy="primary" size="sm">Save</Button>} > …content </Card> ``` A container that groups related content and actions. ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `title`, `supportingText`, `headerAction` (Figma: Title, Supporting text, Header action). - `children` — the Content slot; `footer` — buttons aligned right. - `variant` — `outlined` · `elevated` · `filled`; `padding` — `md` 16 · `lg` 24. **Don’t** - Don’t nest cards; use dividers or a filled card instead. - Don’t add a coloured left border to signal status — use Alert or Badge. ### Design guidance From the Figma guidelines. **Do** - Put any content into the Content slot. - Use the Header and Footer booleans instead of building your own. - Use Outlined on white backgrounds and Filled on grey ones. **Forbidden** - Never nest cards inside cards. - Never add shadows by hand — pick the Elevated style. - Never detach to change padding — use the Padding variant. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/card.md`. Use only these props; anything else is not part of the API. ### `Card` `import { Card } from '@stanvision/atomus-react';` — source: `react/src/components/Card.tsx` | Prop | Type | Default | Description | | ---------------- | -------------------------------------- | ------------ | -------------------------------------------------------------- | | `title` | `ReactNode` | — | Figma: Title (Header on) | | `supportingText` | `ReactNode` | — | Figma: Supporting text | | `headerAction` | `ReactNode` | — | Figma: Header action — e.g. a Button or icon button, top right | | `children` | `ReactNode` | — | Figma: Content slot | | `footer` | `ReactNode` | — | Figma: Footer — buttons aligned right | | `variant` | `'outlined' \| 'elevated' \| 'filled'` | `'outlined'` | Figma: Style | | `padding` | `'md' \| 'lg'` | `'md'` | Figma: Padding — md 16 · lg 24 | Also accepts every native HTML attribute (`id`, `role` …), except `title`, which is replaced above. --- # Headers & dividers > Top of an app page: breadcrumb, title, description, actions, divider or tabs. URL: https://docs.atomus.io/components/headers-dividers/ Top of an app page: breadcrumb, title, description, actions, divider or tabs. ## In Figma From `guidelines/components/headers-dividers.md` Properties, variants and anatomy of the Figma components. ### Page header Variants: 3 | Property | Type / options | | --------------- | ----------------------- | | Title | text | | Supporting text | text | | Breadcrumb | boolean (on) | | Show supporting | boolean (on) | | Type | Simple · Actions · Tabs | ### Section header Heading for a section inside a page. Variants: 2 | Property | Type / options | | --------------- | ----------------- | | Title | text | | Supporting text | text | | Type | Default · Actions | ### Divider Horizontal rule, optionally with text or a button. Variants: 3 | Property | Type / options | | -------- | -------------------- | | Type | Line · Text · Button | ## Usage #### Page header **Do** - Use one page header per screen. - Keep supporting text to one sentence. - Use the Tabs variant for sub-views. **Forbidden** - Never put more than two buttons in the actions. - Never repeat the sidebar label as the breadcrumb. - Never use a page header inside a card — use Card header. --- # Atomus icons > Icon sets beyond the UI icons: featured icons, brand and payment marks, flags, file types, folders, integrations and star ratings. URL: https://docs.atomus.io/components/atomus-icons/ Icon sets beyond the UI icons: featured icons, brand and payment marks, flags, file types, folders, integrations and star ratings. ## In Figma From `guidelines/components/atomus-icons.md` Properties, variants and anatomy of the Figma components. ### Featured icon Icon in a tinted circle — for modals, alerts, empty states and feature lists. Variants: 15 | Property | Type / options | | --------- | ---------------------------------------- | | Icon swap | instance swap (icon) | | Size | sm · md · lg | | Color | Brand · Gray · Error · Warning · Success | ### Icon brand Brand & social logos, 24px. Style=Dark/Light. Use in social buttons, footers and integrations. Variants: 132 | Property | Type / options | | -------- | ------------------------ | | Name | 44 brands (Apple … Zoom) | | Style | Color · Dark · Light | ### Icon payment Payment method marks, 48×32. Use in checkout, pricing and footers. Variants: 24 | Property | Type / options | | -------- | ---------------------------- | | Name | 24 methods (Apple Pay … Zip) | ### Icon flag Country flags, 48×32. Use in phone input, language and currency selectors. Variants: 18 | Property | Type / options | | -------- | ---------------------- | | Flag | 18 countries (BG … US) | ### Icon file type File-type icons for uploads, attachments and file lists. Sizes sm (32×40) and md (40×48). Variants: 24 | Property | Type / options | | -------- | ---------------------------------------------------------------------- | | Type | PDF · DOC · XLS · PPT · CSV · TXT · ZIP · IMG · MP4 · MP3 · FIG · CODE | | Size | sm · md | ### Icon folder Folder icons, 48×40, closed and open, six colours. Brand follows the Brand collection. Variants: 12 | Property | Type / options | | -------- | --------------------------------------------- | | Color | Brand · Gray · Blue · Green · Orange · Purple | | State | Closed · Open | ### Icon integration App tiles for integrations sections and settings: 56×56 tile with the brand logo at 32px. Variants: 16 | Property | Type / options | | -------- | --------------------------- | | App | 16 apps (Slack … Microsoft) | ### Star rating Star with partial fill for ratings in reviews and testimonials. Variants: 5 | Property | Type / options | | -------- | --------------------------- | | Value | Empty · ¼ · Half · ¾ · Full | ## Usage #### Featured icon **Do** - Use in empty states, modals and feature lists; pick the colour by meaning. **Forbidden** - Never use a featured icon as a button. --- # Shared assets > Mockups and annotation kit used across product and marketing files: credit card, video player, email template, status tags and spec annotations. URL: https://docs.atomus.io/components/shared-assets/ Mockups and annotation kit used across product and marketing files: credit card, video player, email template, status tags and spec annotations. ## In Figma From `guidelines/components/shared-assets.md` Properties, variants and anatomy of the Figma components. ### Credit card Payment card mockup 320×200. Variants: 4 | Property | Type / options | | ----------- | ------------------------------- | | Card holder | text | | Card number | text | | Style | Brand · Dark · Light · Gradient | ### Video player 16:9 player with play button and controls. Variants: 4 | Property | Type / options | | ---------- | ---------------- | | Breakpoint | Desktop · Mobile | | State | Paused · Playing | ### Email template 600px email layouts. Variants: 4 | Property | Type / options | | -------- | ----------------------------------------------- | | Type | Welcome · Password reset · Receipt · Newsletter | ### Status tag Hand-off status on frames. Variants: 4 | Property | Type / options | | -------- | ------------------------------------------------------- | | Status | Ready for dev · In progress · Needs review · Deprecated | ### Annotation marker Numbered marker for annotations. Variants: 5 | Property | Type / options | | -------- | ---------------------------------------- | | Number | text | | Color | Brand · Error · Warning · Success · Gray | ### Annotation note Hand-off callout. Variants: 4 | Property | Type / options | | -------- | ------------------------------ | | Title | text | | Body | text | | Type | Note · Spec · Question · Issue | ### Spec line Red-line measurement. Variants: 2 | Property | Type / options | | --------- | --------------------- | | Value | text | | Direction | Horizontal · Vertical | ### A11y annotation Focus order, heading level, alt text, landmark, 48px touch target. Variants: 5 | Property | Type / options | | -------- | ---------------------------------------------------------- | | Order | text | | Label | text | | Role | text | | Type | Focus order · Heading · Alt text · Landmark · Touch target | ## Usage Follow the descriptions above; there are no extra rules for this component yet. --- # Charts > Line, bar, pie, radar and gauge charts for dashboards and reports, with a shared legend item. URL: https://docs.atomus.io/components/charts/ Line, bar, pie, radar and gauge charts for dashboards and reports, with a shared legend item. ## In Figma From `guidelines/components/charts.md` Properties, variants and anatomy of the Figma components. ### Line chart Line chart (12 months, 2 series). Variants: 1 ### Bar chart Grouped bar chart (12 months, 2 series). Variants: 1 ### Pie chart Pie and donut chart, sizes 160/200/240. Segment colours follow the Brand collection. Variants: 6 | Property | Type / options | | -------- | -------------- | | Type | Pie · Donut | | Size | sm · md · lg | ### Radar chart Radar chart with 6 axes and two series. Variants: 1 ### Activity gauge Concentric progress rings for up to three metrics. Variants: 3 | Property | Type / options | | -------- | -------------- | | Size | sm · md · lg | ### Chart legend item Legend entry; series colours from tokens. Variants: 3 | Property | Type / options | | -------- | -------------- | | Label | text | | Series | 1 · 2 · 3 | ## Usage #### Line chart **Do** - Use for trends over continuous time. - Label axes with units. **Forbidden** - Never draw categories as a line — use a bar chart. #### Bar chart **Do** - Start the value axis at zero. - Use the brand series for the key metric and grey for comparison. - Add a legend when there is more than one series. **Forbidden** - Never use more than four series. - Never use 3D or gradients. - Never hide axis labels. #### Pie chart **Do** - Use for parts of a whole, with five slices or fewer. **Forbidden** - Never compare values across several pies — use a bar chart. --- # Conversation > A full AI conversation built from the Agent kit: welcome state, reasoning, a tool call, an approval and a cited answer. URL: https://docs.atomus.io/components/ai-conversation/ The Agent kit is a set of composable components for AI products: chat, copilots and agents. They use the same tokens, Brand, Color and Radius modes as the rest of Atomus, plus a small AI layer (`--color-bg-ai-subtle`, `--color-border-ai`, `--color-text-ai`, `--gradient-ai`) that marks AI content without decorating anything else. Nothing depends on an AI SDK: each component takes plain props such as a growing string and a status, so it works with the Vercel AI SDK, LangChain, your own backend or an MCP host. Pick a prompt starter below. The demo streams a simulated reply: the agent reasons, runs a tool, asks for your approval, then answers with citations. Try Deny, Edit, or the Stop button while it writes. Add the AI chat screen (this pattern as a block) to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-chat.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-chat.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Finished thread ## In Figma From `guidelines/components/ai-message.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Conversation The pattern that puts the Agent kit together: a header with the assistant’s name, AI label and Context meter; a scrolling thread of Messages; and a Prompt input docked at the bottom. An empty thread shows a welcome state with prompt starters (Suggestions, `variant="cards"`). There is no Conversation component: compose it from the parts. **Anatomy** 1. Header: assistant name, AI label with an explanation, Context meter, New chat. 2. Thread: `role="log"` region, max width about 720px, `spacing-3xl` between messages. 3. Welcome state: AI mark, one-line title, one sentence on what the assistant can do, 2–4 prompt starters. 4. Composer: Prompt input with the Model selector, and a disclaimer. 5. Follow-up Suggestions under the latest answer. **Accessibility** - Give the thread `role="log"` and an accessible name. Turn its own live announcements off (`aria-live="off"`) when Streaming text announces replies, so nothing is read twice. - Make the scrolling thread focusable (`tabIndex={0}`) so keyboard users can scroll it. - Keep focus in the Prompt input after sending; never move it to the new reply. - Scroll new content into view inside the thread, not the whole page. ## Usage There is no `Conversation` component — compose the parts. A minimal thread with any streaming backend: ```tsx import { Message, Reasoning, ToolCall, StreamingText, Sources, PromptInput, Suggestions } from '@stanvision/atomus-react'; <div role="log" aria-label="Conversation" aria-live="off" tabIndex={0} className="thread"> {messages.length === 0 ? ( <Suggestions variant="cards" suggestions={starters} onSelect={send} /> ) : messages.map((m) => ( <Message key={m.id} role={m.role} name={m.role === 'user' ? 'You' : 'Atomus Assistant'} status={m.status} copyText={m.text} onRegenerate={m.role === 'assistant' ? () => regenerate(m.id) : undefined}> {m.reasoning ? <Reasoning status={m.thinking ? 'thinking' : 'done'} duration={m.thoughtFor} steps={m.steps} /> : null} {m.tools.map((t) => <ToolCall key={t.id} name={t.name} status={t.status} input={t.input} output={t.output} />)} <StreamingText text={m.text} streaming={m.status === 'streaming'} /> {m.sources ? <Sources sources={m.sources} /> : null} </Message> ))} </div> <PromptInput status={busy ? 'streaming' : 'ready'} onSubmit={send} onStop={stop} /> ``` ### Adapting an AI SDK - Map the SDK’s message parts to components: text → `StreamingText`, reasoning → `Reasoning`, tool calls → `ToolCall`, tool calls that need approval → `Approval`, source parts → `Sources` and `InlineCitation`. - Map its status to `PromptInput status` (`submitted`, `streaming`, `ready`, `error`) and its stop function to `onStop`. - Adapters for popular SDKs may ship later as optional packages; the components will not change. ### Design guidance From the Figma guidelines. **Do** - Say what the assistant can and can’t do in the welcome state. - Ask before acting: route every write or send through an Approval. - Keep one primary button per view: Send, or Approve while an approval is pending. **Forbidden** - Never start a conversation with a wall of starters — four at most. - Never auto-scroll while the person is reading earlier messages. - Never stream into a region that also announces every token. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-message.md`. Use only these props; anything else is not part of the API. ### `Message` Figma: Message — one turn in a conversation. Every message is an `<article>` named by its speaker, so screen-reader users always know who said what (Primer: speaker clarity). `import { Message } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Message.tsx` | Prop | Type | Default | Description | | ------------------- | ----------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `role` | `'user' \| 'assistant' \| 'system' \| 'tool'` | `'assistant'` | Figma: Role — who is speaking. Sets layout, label and default name. | | `status` | `'streaming' \| 'done' \| 'error' \| 'stopped'` | `'done'` | Figma: Status — `streaming` keeps the message busy; `error` and `stopped` show an inline notice. | | `name` | `string` | — | Figma: Name — the speaker (“You”, “Atomus AI”, “Research agent”). Always announced to screen readers. | | `avatar` | `ReactNode` | — | Figma: Avatar — an Avatar or logo; assistants default to the AI mark. | | `showName` | `boolean` | — | Figma: Show name — show the speaker name visually (screen readers always get it). Defaults to true except for user messages. | | `aiLabel` | `boolean` | `true` | Figma: AI label — shows the AI label next to an assistant’s name. | | `time` | `string` | — | Figma: Timestamp — display text (“2:41 PM”) | | `dateTime` | `string` | — | Machine-readable time (ISO 8601) for the `<time>` element | | `children` | `ReactNode` | — | Figma: Content | | `copyText` | `string` | — | Plain text of the message for the Copy action; Copy is hidden without it. | | `onRegenerate` | `() => void` | — | Figma: Regenerate — assistant messages; also the retry action for `status="error"`. | | `onEdit` | `() => void` | — | Figma: Edit — user messages | | `branch` | `MessageBranch` | — | Figma: Branch — ‹ 1/3 › switcher between regenerated or edited versions | | `actions` | `ReactNode` | — | Extra actions after the built-in ones (e.g. Feedback) | | `actionsVisibility` | `'always' \| 'hover'` | `'always'` | Figma: Actions visibility — `always`, or on `hover` and keyboard focus (always shown on touch screens) | | `errorMessage` | `ReactNode` | `'Something went wrong while generating this response.'` | Error text for `status="error"` | Also accepts every native HTML attribute (`id`, `role` …), except `role`, which is replaced above. `MessageBranch`: | Field | Type | Description | | ------------- | ------------ | ----------------------------------- | | `index` | `number` | 1-based number of the version shown | | `count` | `number` | How many versions exist | | `onPrevious?` | `() => void` | Shows the previous version | | `onNext?` | `() => void` | Shows the next version | --- # Prompt input > The composer of an AI chat: auto-growing text, attachments, a toolbar slot, send and stop, and / or @ menus. URL: https://docs.atomus.io/components/ai-prompt-input/ The composer of an AI chat or agent panel. It grows with the text, shows attachment chips, hosts the Model selector and Context meter in its slots, and turns Send into Stop while the agent works. Focus draws the AI gradient around it. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-prompt-input.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-prompt-input.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## States ## In Figma From `guidelines/components/ai-prompt-input.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Prompt input The composer of an AI chat or agent panel: an auto-growing text area, attachment chips, a toolbar slot for the Model selector and tool toggles, and one button that switches between Send and Stop. Typing `/` or `@` opens a command or mention menu. Part of the Agent kit. Figma: component set `Prompt input` on the 🤖 Agent kit page of Atomus 4.0 (node `25553:1955`), connected to React with Code Connect. Attachment chips: `Prompt attachment` (node `25553:1183`). React props use the same names as the Figma properties below. | Property | Type / options | | ------------- | ------------------------------------------------ | | Text | text | | Placeholder | text | | Size | md · lg | | State | Ready · Submitted · Streaming · Error · Disabled | | Attachments | slot (attachment chips) | | Attach button | boolean (on) | | Toolbar slot | slot (Model selector, toggles) | | Actions slot | slot (Context meter, voice) | | Command menu | boolean (off) | | Disclaimer | text | **Anatomy** 1. Container: `bg-primary`, `border-primary`, radius 2xl (3xl at lg). When focused, the border becomes `--gradient-ai` with a `bg-ai-subtle` glow. 2. Attachment chips: file icon or thumbnail, name, size or upload state, remove button. 3. Text area: grows from `minRows` (1) to `maxRows` (8), then scrolls. 4. Bottom bar: Attach button and Toolbar slot on the left; Actions slot and Send / Stop on the right. 5. Send / Stop: brand-solid arrow while ready; `fg-contrast` square while the agent works. 6. Command menu: a listbox above the input, filtered by what follows `/` or `@`. 7. Disclaimer: one centred line under the input. **Use for** - The main input of a chat, copilot side panel or agent workspace. - Follow-up questions under an AI answer inside a card or drawer. **Not for** - Search fields: use Input with a search icon. - Long-form writing without an AI reply: use a textarea. - Forms with several fields: use Input, Select and the other form components. **Keyboard** - Enter sends; Shift+Enter adds a line. Enter never sends while the agent is working, and never during IME composition. - In the command menu: ↑ ↓ move, Enter or Tab inserts, Esc closes. - The Stop button is a normal button: Tab to it and press Enter or Space. **Accessibility** - The text area has a visually hidden label (`label`, default “Message”); the placeholder is only a hint. - Send and Stop have accessible names (`submitLabel`, `stopLabel`) and change name with the state. - The command menu uses `aria-activedescendant`, so focus stays in the text area; a polite live region says how many suggestions there are. - “Generating response” is announced when the state turns busy. - The disclaimer is linked with `aria-describedby`. ## Usage ```tsx import { PromptInput, ModelSelector, ContextMeter } from '@stanvision/atomus-react'; <PromptInput status={status} // 'ready' | 'submitted' | 'streaming' | 'error' onSubmit={(text, files) => send(text, files)} onStop={stop} attachments={files} onAttach={openFilePicker} onRemoveAttachment={removeFile} toolbar={<ModelSelector models={models} value={model} onChange={setModel} />} actions={<ContextMeter used={usage.tokens} limit={200000} />} triggers={[{ char: '/', items: commands }, { char: '@', label: 'People', items: people }]} disclaimer="AI can make mistakes. Check important information." /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `status` — `submitted` and `streaming` show Stop and block Enter; the text area stays editable. - `value` / `defaultValue` / `onChange` — controlled or uncontrolled text; `onSubmit` gets the trimmed text and the attachments. - `attachments`, `onAttach`, `onRemoveAttachment` — chips with an upload state; an uploading file blocks Send. - `toolbar` and `actions` — slots on the left and right of the bottom bar. - `triggers` — `/` and `@` menus with keyboard support (↑ ↓, Enter or Tab, Esc). - `size` — `md` for panels, `lg` for full-page chat. `minRows` / `maxRows` set the growth. ### Design guidance From the Figma guidelines. **Do** - Keep one Prompt input per conversation, docked at the bottom of the thread. - Put the Model selector in the Toolbar slot and the Context meter in the Actions slot. - Show Stop while the agent works and keep the text area editable, so people can draft the next message. - Block Send while a file is still uploading; show the upload state on its chip. - Add a one-line disclaimer when answers can be wrong. **Forbidden** - Never disable the text area while streaming — only Send is blocked. - Never use the placeholder as the only label. - Never put more than one primary action in the bar: Send is the primary action. - Never move focus out of the text area when the reply arrives. - Never send on Enter while a command menu is open — Enter inserts the highlighted item. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-prompt-input.md`. Use only these props; anything else is not part of the API. ### `PromptInput` Figma: Prompt input — the composer of an AI chat: auto-growing text, attachments, a toolbar slot, send ↔ stop, and “/” or “@” menus. Enter sends, Shift+Enter adds a line, Esc closes a menu. `import { PromptInput } from '@stanvision/atomus-react';` — source: `react/src/components/ai/PromptInput.tsx` | Prop | Type | Default | Description | | -------------------- | --------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------- | | `value` | `string` | — | Figma: Text (controlled) | | `defaultValue` | `string` | `''` | Initial text when uncontrolled | | `onChange` | `(value: string) => void` | — | Called with the new value. | | `onSubmit` | `(text: string, attachments: PromptAttachment[]) => void` | — | Called with the trimmed text and the attachments on Enter or the send button | | `onStop` | `() => void` | — | Called by the stop button while `status` is `submitted` or `streaming` | | `status` | `'ready' \| 'submitted' \| 'streaming' \| 'error'` | `'ready'` | Figma: State — `submitted` and `streaming` turn Send into Stop and block new submits. | | `placeholder` | `string` | `'Ask anything…'` | Figma: Placeholder — a hint, never the label | | `label` | `string` | `'Message'` | Accessible name of the text area (visually hidden) | | `attachments` | `PromptAttachment[]` | `[]` | Figma: Attachments — chips above the text | | `onAttach` | `() => void` | — | Figma: Attach button — shows the paperclip button; open your file picker here | | `onRemoveAttachment` | `(id: string) => void` | — | Called by a chip’s remove button | | `toolbar` | `ReactNode` | — | Figma: Toolbar slot — left of the bottom bar (ModelSelector, tool toggles) | | `actions` | `ReactNode` | — | Figma: Actions slot — right of the bottom bar, before Send (ContextMeter, voice) | | `triggers` | `PromptTrigger[]` | `[]` | Figma: Command menu — “/” and “@” menus that open while typing | | `disclaimer` | `ReactNode` | — | Figma: Disclaimer — one line under the input (“AI can make mistakes. Check important info.”) | | `minRows` | `number` | `1` | Rows shown when empty | | `maxRows` | `number` | `8` | Rows before the text area scrolls | | `size` | `'md' \| 'lg'` | `'md'` | Figma: Size — md for side panels, lg for a full-page chat | | `disabled` | `boolean` | — | Disables the control. | | `autoFocus` | `boolean` | — | Focuses the text area on mount — only on pages whose main task is the chat | | `submitLabel` | `string` | `'Send message'` | Accessible name of the send button | | `stopLabel` | `string` | `'Stop generating'` | Accessible name of the stop button | | `clearOnSubmit` | `boolean` | `true` | Clears the text after submit (uncontrolled only) | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `PromptAttachment`: | Field | Type | Description | | ------------- | ----------------------------------- | --------------------------------------------------- | | `id` | `string` | Stable key | | `name` | `string` | File name shown on the chip | | `kind?` | `'file' \| 'image'` | `image` shows `previewUrl` as a thumbnail | | `size?` | `string` | Human-readable size (“2.4 MB”) | | `previewUrl?` | `string` | Thumbnail for images | | `status?` | `'uploading' \| 'ready' \| 'error'` | `uploading` shows a spinner; `error` marks the chip | `PromptTrigger`: | Field | Type | Description | | ----------- | ------------------------------- | --------------------------------------------------------------------- | | `char` | `string` | The character that opens the menu: “/” for commands, “@” for mentions | | `label?` | `string` | Accessible name of the menu (“Commands”, “People”) | | `items` | `PromptCommand[]` | The menu items, filtered by what is typed after the character | | `onSelect?` | `(item: PromptCommand) => void` | Called when an item is chosen (after its text is inserted) | `PromptCommand`: | Field | Type | Description | | -------------- | ----------- | ------------------------------------------------------------------ | | `value` | `string` | Inserted after the trigger character (“summarize” → “/summarize “) | | `label` | `string` | Text in the menu | | `description?` | `string` | One line under the label | | `icon?` | `ReactNode` | Leading icon (16px) | | `insert?` | `string` | Exact text to insert instead of trigger + value | --- # Message > One turn in a conversation, with the speaker, status, actions and branches. URL: https://docs.atomus.io/components/ai-message/ One turn in a conversation. User messages are bubbles; assistant and tool messages flow full-width next to their avatar, with the AI label beside the name. Every message is an article named by its speaker. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-message.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-message.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Status ## In Figma From `guidelines/components/ai-message.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Message One turn in a conversation. The role sets the layout: user messages are right-aligned bubbles on `bg-tertiary`; assistant and tool messages flow full-width next to an avatar; system messages are a centred line between hairlines. Every message is an `<article>` named by its speaker, so it is always clear who said what. Part of the Agent kit. Figma: component set `Message` on the 🤖 Agent kit page of Atomus 4.0 (node `25552:1473`), connected to React with Code Connect. Default avatars: `Message avatar` (node `25552:989`). React props use the same names as the Figma properties below. | Property | Type / options | | ------------------ | ---------------------------------------------------- | | Role | User · Assistant · System · Tool | | Status | Streaming · Done · Error · Stopped | | Name | text | | Show name | boolean (on, off for User) | | AI label | boolean (on) | | Avatar | instance swap (Avatar) | | Timestamp | text | | Content | slot (text, Reasoning, Tool call, Approval, Sources) | | Actions | Copy · Regenerate · Edit · Branch · slot (Feedback) | | Actions visibility | Always · Hover | **Anatomy** 1. Avatar: the AI mark on `bg-ai-subtle` for assistants, a wrench for tools, an Avatar for people. 2. Header: speaker name, AI label (assistants), timestamp. 3. Content slot: text, then any Reasoning, Tool call, Approval, Streaming text and Sources, in the order they happened. 4. Status notice: “You stopped this response.” or an error with Retry. 5. Actions: branch switcher ‹ 1/3 ›, Copy, Edit (user), Regenerate (assistant), then the slot (Feedback). **Use for** - Chat threads, copilot panels and agent logs. - Showing several agents in one thread: give each a distinct `name` and avatar. **Not for** - Person-to-person chat without AI: see the Messaging guidelines. - Notifications and activity feeds: use the Activity item. **Accessibility** - Speaker clarity: the name is always in the accessible name of the article, even when hidden visually for user messages. - Assistant messages carry the AI label, so AI content is never identified by colour or position alone. - `status="streaming"` sets `aria-busy` on the article; the Streaming text inside announces the reply. - Errors use `role="alert"`; Copy confirms “Copied to clipboard” in a status region. - Icon-only actions have names (“Copy”, “Regenerate response”, “Edit message”, “Previous version”). ## Usage ```tsx import { Message, StreamingText, Feedback } from '@stanvision/atomus-react'; <Message role="user" name="Kristina" copyText={prompt} onEdit={edit}> <p>{prompt}</p> </Message> <Message role="assistant" name="Atomus Assistant" status={status} // 'streaming' | 'done' | 'error' | 'stopped' copyText={answer} onRegenerate={regenerate} branch={{ index: 2, count: 3, onPrevious, onNext }} actions={<Feedback onSubmit={sendFeedback} />} > <StreamingText text={answer} streaming={status === 'streaming'} /> </Message> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `role` — `user` · `assistant` · `system` · `tool`; `name` is always announced (Primer: speaker clarity). - `status` — `streaming` hides the actions and sets `aria-busy`; `error` shows the message with Retry (`onRegenerate`); `stopped` notes that the person stopped it. - Actions: `copyText` (Copy), `onRegenerate`, `onEdit`, `branch`, and the `actions` slot. `actionsVisibility="hover"` for dense threads. - `avatar`, `showName`, `aiLabel`, `time` and `dateTime` for the header. ### Design guidance From the Figma guidelines. **Do** - Name every speaker; use the product’s assistant name rather than “AI”. - Keep the order of what happened: reasoning, then tools, then approvals, then the answer. - Show actions on hover only in dense threads; they stay visible on touch screens and on focus. - Keep the latest assistant message’s actions visible. **Forbidden** - Never style assistant text as a bubble that looks like a person’s message. - Never remove the speaker name from the accessible name. - Never show Regenerate on a user message or Edit on an assistant message. - Never hide an error behind a toast — keep it in the message with a Retry. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-message.md`. Use only these props; anything else is not part of the API. ### `Message` Figma: Message — one turn in a conversation. Every message is an `<article>` named by its speaker, so screen-reader users always know who said what (Primer: speaker clarity). `import { Message } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Message.tsx` | Prop | Type | Default | Description | | ------------------- | ----------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `role` | `'user' \| 'assistant' \| 'system' \| 'tool'` | `'assistant'` | Figma: Role — who is speaking. Sets layout, label and default name. | | `status` | `'streaming' \| 'done' \| 'error' \| 'stopped'` | `'done'` | Figma: Status — `streaming` keeps the message busy; `error` and `stopped` show an inline notice. | | `name` | `string` | — | Figma: Name — the speaker (“You”, “Atomus AI”, “Research agent”). Always announced to screen readers. | | `avatar` | `ReactNode` | — | Figma: Avatar — an Avatar or logo; assistants default to the AI mark. | | `showName` | `boolean` | — | Figma: Show name — show the speaker name visually (screen readers always get it). Defaults to true except for user messages. | | `aiLabel` | `boolean` | `true` | Figma: AI label — shows the AI label next to an assistant’s name. | | `time` | `string` | — | Figma: Timestamp — display text (“2:41 PM”) | | `dateTime` | `string` | — | Machine-readable time (ISO 8601) for the `<time>` element | | `children` | `ReactNode` | — | Figma: Content | | `copyText` | `string` | — | Plain text of the message for the Copy action; Copy is hidden without it. | | `onRegenerate` | `() => void` | — | Figma: Regenerate — assistant messages; also the retry action for `status="error"`. | | `onEdit` | `() => void` | — | Figma: Edit — user messages | | `branch` | `MessageBranch` | — | Figma: Branch — ‹ 1/3 › switcher between regenerated or edited versions | | `actions` | `ReactNode` | — | Extra actions after the built-in ones (e.g. Feedback) | | `actionsVisibility` | `'always' \| 'hover'` | `'always'` | Figma: Actions visibility — `always`, or on `hover` and keyboard focus (always shown on touch screens) | | `errorMessage` | `ReactNode` | `'Something went wrong while generating this response.'` | Error text for `status="error"` | Also accepts every native HTML attribute (`id`, `role` …), except `role`, which is replaced above. `MessageBranch`: | Field | Type | Description | | ------------- | ------------ | ----------------------------------- | | `index` | `number` | 1-based number of the version shown | | `count` | `number` | How many versions exist | | `onPrevious?` | `() => void` | Shows the previous version | | `onNext?` | `() => void` | Shows the next version | --- # Streaming text & shimmer > Text that renders as it streams, with a caret and calm screen-reader announcements, and a shimmer for status lines. URL: https://docs.atomus.io/components/ai-streaming-text/ `StreamingText` renders a reply as it arrives, with a gradient caret, and tells screen readers about finished sentences in batches instead of every token. `Shimmer` sweeps a soft light across short status lines. Both stop moving when the person prefers reduced motion. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-streaming-text.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-streaming-text.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Shimmer ## In Figma From `guidelines/components/ai-streaming-text.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Streaming text Renders an AI reply as it arrives: the text grows, a caret filled with `--gradient-ai` blinks at the end, and screen readers hear finished sentences in calm batches instead of every token. It takes any growing string, so it works with every AI SDK or backend. Part of the Agent kit. Figma: component set `Streaming text` on the 🤖 Agent kit page of Atomus 4.0 (node `25544:55`), connected to React with Code Connect. Status text: `Shimmer` (node `25544:34`). React props use the same names as the Figma properties below. | Property | Type / options | | -------- | ------------------ | | Text | text | | State | Streaming · Done | | Caret | boolean (on) | | Announce | Polite · End · Off | The caret blinks at `--motion-stream-caret-blink` (1s). Under `prefers-reduced-motion: reduce` it stays solid. **Use for** - The text of an assistant Message while it streams. - Live summaries or drafts that an agent writes into a panel. **Not for** - Status lines such as “Thinking…”: use Shimmer. - Text that arrives all at once: render it directly. **Accessibility** - `announce="polite"` (default) puts finished sentences into a polite live region at most every `announceInterval` ms (1500), then the rest when the stream ends, then clears the region. - `announce="end"` only says `doneMessage` (“Response complete”); use it for long code or tables. - `announce="off"` when an outer region already announces. - The visible text has `aria-busy` while streaming, so assistive tech doesn’t read half words. ### Shimmer A light sweep across short status text while the agent works (“Thinking…”, “Searching 12 sources…”). The sweep runs through `text-ai` over `text-tertiary` every `--motion-stream-shimmer-duration` (1.8s); reduced motion shows static `text-tertiary` text. | Property | Type / options | | -------- | -------------- | | Label | text | | Animated | boolean (on) | ## Usage ```tsx import { StreamingText, Shimmer } from '@stanvision/atomus-react'; // Pass the whole string received so far on every chunk. <StreamingText text={text} streaming={!done} render={(t) => <Markdown>{t}</Markdown>} /> // Long code or tables: only say when it's done. <StreamingText text={code} streaming={!done} announce="end" doneMessage="Code ready" /> <Shimmer>Searching 12 sources…</Shimmer> ``` ### Motion tokens - `--motion-stream-caret-blink` (1s) and `--motion-stream-shimmer-duration` (1.8s). Both become `0s` under `prefers-reduced-motion: reduce`, and the components switch their animation off. ### Design guidance From the Figma guidelines. #### Streaming text **Do** - Pass the whole string received so far on every chunk. - Use `render` for Markdown or to turn citation markers into InlineCitation. - Use `announce="end"` for code, tables and very long answers. **Forbidden** - Never announce every token or chunk to screen readers. - Never animate the caret when the person prefers reduced motion. - Never move focus to the streaming text. #### Shimmer **Do** - Keep the label short, in sentence case, ending with an ellipsis. - Swap the shimmer for a static result as soon as the step ends (“Thought for 12s”). **Forbidden** - Never shimmer body text, buttons or links. - Never use Shimmer as the only signal of progress for a long task — show steps or a Progress bar. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-streaming-text.md`. Use only these props; anything else is not part of the API. ### `StreamingText` Figma: Streaming text — renders an AI reply as it arrives, with a caret and batched, polite screen-reader announcements. Framework-agnostic: feed it any growing string. `import { StreamingText } from '@stanvision/atomus-react';` — source: `react/src/components/ai/StreamingText.tsx` | Prop | Type | Default | Description | | ------------------ | ----------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `text` | `string` | **required** | The text received so far. Pass the growing string on every chunk; the component only appends. | | `streaming` | `boolean` | `false` | Figma: State=Streaming — shows the caret and keeps the region busy for screen readers. | | `caret` | `boolean` | `true` | Figma: Caret — blinking caret at the end while streaming (static under reduced motion). | | `announce` | `'polite' \| 'end' \| 'off'` | `'polite'` | How screen readers hear the stream (Primer: announce progress, not every token). `polite` (default) — finished sentences in batches, at most every `announceInterval` ms. `end` — only `doneMessage` once the stream ends. `off` — nothing; use when an outer live region already announces the reply. | | `announceInterval` | `number` | `1500` | Minimum time between announcements in ms | | `doneMessage` | `string` | `'Response complete'` | Announced when the stream ends with `announce="end"` | | `render` | `(text: string) => ReactNode` | — | Renders the text (e.g. Markdown). Defaults to plain text with preserved line breaks. | Also accepts every native `<div>` attribute (`id`, `role`, `onClick` …), except `children`, which is replaced above. ### `Shimmer` Figma: Shimmer — a light sweep across status text while the agent works. The sweep uses –gradient-ai and –motion-stream-shimmer-duration; reduced motion shows static text. `import { Shimmer } from '@stanvision/atomus-react';` — source: `react/src/components/ai/StreamingText.tsx` | Prop | Type | Default | Description | | ---------- | ----------- | ------------ | ------------------------------------------------------------------------------- | | `children` | `ReactNode` | **required** | Figma: Label — short status text such as “Thinking…” or “Searching the web…” | | `active` | `boolean` | `true` | Figma: Animated — when false the text renders static (as under reduced motion). | Also accepts every native `<span>` attribute (`id`, `title` …). --- # Reasoning > A collapsible “Thought for 12s” disclosure with the agent’s steps. URL: https://docs.atomus.io/components/ai-reasoning/ Shows the model’s working apart from its answer: “Thinking…” with a shimmer while it reasons, then “Thought for 12s”. It opens while thinking and collapses when done. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-reasoning.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-reasoning.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/ai-reasoning.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Reasoning A collapsible disclosure for the model’s working: “Thinking…” with a shimmer while it reasons, then “Thought for 12s”. Inside, a short step list and optional free text, on a left rule in `border-ai`. It keeps the model’s working apart from its answer. Part of the Agent kit. Figma: component set `Reasoning` on the 🤖 Agent kit page of Atomus 4.0 (node `25548:978`), connected to React with Code Connect. Steps: `Reasoning step` (node `25548:901`). React props use the same names as the Figma properties below. | Property | Type / options | | -------- | ----------------------------------------------------- | | State | Thinking · Done | | Duration | number (seconds) | | Steps | list (label, detail, status: Pending · Active · Done) | | Expanded | boolean | | Label | text | **Anatomy** 1. Trigger: lightbulb in `text-ai`, label (“Thinking…” shimmer or “Thought for 12s”), chevron. 2. Body: steps with status dots (gradient for active, `text-ai` for done, outline for pending), then free text. **Use for** - Showing what a reasoning model or agent did before answering. - Multi-step plans the agent is working through. **Not for** - Function calls with inputs and outputs: use Tool call. - The answer itself: put it in the Message content. **Accessibility** - The trigger is a button with `aria-expanded` and `aria-controls`. - The finished label (“Thought for 12s”) is announced once in a status region. - Step status is also given as text (“in progress”, “pending”), not only by the dot. ## Usage ```tsx import { Reasoning } from '@stanvision/atomus-react'; <Reasoning status={thinking ? 'thinking' : 'done'} duration={seconds} steps={[ { label: 'Load the page', status: 'done' }, { label: 'Run axe-core', detail: '68 rules', status: 'active' }, { label: 'Draft fixes', status: 'pending' }, ]} > <p>{summary}</p> </Reasoning> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `status` — `thinking` or `done`; `duration` in seconds for “Thought for 12s”. - `steps` — `label`, `detail` and `status` (`pending` · `active` · `done`); `children` for free text. - `open` / `defaultOpen` / `onOpenChange`; `autoCollapse` closes it when thinking ends. ### Design guidance From the Figma guidelines. **Do** - Open it while thinking and collapse it when done (`autoCollapse`, the default). - Write steps as short past-tense or present-tense lines a person can scan. - Summarise long raw thoughts; show the full text only on request. **Forbidden** - Never put the answer or required decisions inside Reasoning — people may never open it. - Never show a duration for a step that is still running. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-reasoning.md`. Use only these props; anything else is not part of the API. ### `Reasoning` Figma: Reasoning — a collapsible “Thought for 12s” disclosure with the agent’s steps. Separates the model’s working from its answer (Primer: speaker clarity). `import { Reasoning } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Reasoning.tsx` | Prop | Type | Default | Description | | -------------- | ------------------------- | -------- | ------------------------------------------------------------------------------- | | `status` | `'thinking' \| 'done'` | `'done'` | Figma: State — `thinking` while the model reasons, `done` afterwards. | | `duration` | `number` | — | Figma: Duration — seconds spent thinking; the trigger reads “Thought for 12s”. | | `steps` | `ReasoningStep[]` | — | Figma: Steps — a short list of what the agent did. | | `children` | `ReactNode` | — | Free-form reasoning text (summary or raw thoughts) under the steps. | | `label` | `string` | — | Figma: Label — overrides “Thinking…” / “Thought for 12s”. | | `open` | `boolean` | — | Expanded (controlled) | | `defaultOpen` | `boolean` | — | Initial expanded state when uncontrolled. Defaults to open while thinking. | | `onOpenChange` | `(open: boolean) => void` | — | Called when the person expands or collapses it | | `autoCollapse` | `boolean` | `true` | Collapse automatically when `status` turns `done` (uncontrolled only). | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `ReasoningStep`: | Field | Type | Description | | --------- | --------------------------------- | --------------------------------------------------------------- | | `id?` | `string` | Stable key; defaults to the index | | `label` | `ReactNode` | What the agent did or concluded, in one line | | `detail?` | `ReactNode` | Optional supporting detail under the label | | `status?` | `'pending' \| 'active' \| 'done'` | `done` (default) · `active` (in progress) · `pending` (planned) | --- # Tool call > One function call by the agent: name, status, duration, input and output. URL: https://docs.atomus.io/components/ai-tool-call/ One function call by the agent, from MCP tools to API calls: what it did in plain words, the function name, a status pill, the run time, and the input and output on demand. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-tool-call.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-tool-call.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/ai-tool-call.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Tool call One function call by the agent: a plain-language title, the function name in monospace, a status pill, the run time, and a disclosure with the input and output as formatted code. Part of the Agent kit. Figma: component set `Tool call` on the 🤖 Agent kit page of Atomus 4.0 (node `25548:1134`), connected to React with Code Connect. React props use the same names as the Figma properties below. | Property | Type / options | | --------- | ----------------------------------- | | Title | text | | Tool name | text | | Status | Pending · Running · Success · Error | | Duration | number (ms) | | Input | code | | Output | code | | Expanded | boolean | | Icon | instance swap (integration logo) | **Status** - **Pending** — queued or waiting; clock icon, gray pill. - **Running** — spinner, `bg-ai-subtle` pill, the icon tile tints. - **Success** — check, success pill (“Done”), duration. - **Error** — alert icon, error pill (“Failed”), error border; the error message replaces the output. **Use for** - Showing what an agent did with your systems: searches, API calls, file reads, MCP tools. - Debug views where people need the exact input and output. **Not for** - Actions that need permission first: use Approval, then show the Tool call. - The model’s thinking: use Reasoning. **Accessibility** - The header is a button with `aria-expanded`; status pill text changes are announced politely. - Status is a word plus an icon, never colour alone. - Code blocks are focusable and named (“search_docs input”) so keyboard users can scroll them. ## Usage ```tsx import { ToolCall } from '@stanvision/atomus-react'; <ToolCall name="search_docs" title="Searched the docs" status="success" // 'pending' | 'running' | 'success' | 'error' duration={420} input={{ query: 'card border token' }} output={{ results: 3 }} /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `name` (monospace) and `title` (plain language); `icon` for the integration’s logo. - `status` with an icon and a word; `duration` in ms. - `input` and `output` — strings or objects (formatted as JSON); `error` replaces the output. - `open` / `defaultOpen` / `onOpenChange` for the disclosure. ### Design guidance From the Figma guidelines. **Do** - Write the title as what happened (“Searched the docs”), and keep the function name as a secondary label. - Collapse calls by default; open the one that failed. - Give an error a cause and a next step (“Reconnect Linear and try again”). **Forbidden** - Never show secrets, tokens or personal data in the input or output — redact them first. - Never hide a failed tool call; keep it in the thread. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-tool-call.md`. Use only these props; anything else is not part of the API. ### `ToolCall` Figma: Tool call — one function call by the agent: name, status, duration, and a disclosure with the input and output. Status changes are announced politely. `import { ToolCall } from '@stanvision/atomus-react';` — source: `react/src/components/ai/ToolCall.tsx` | Prop | Type | Default | Description | | -------------- | ------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------- | | `name` | `string` | **required** | Figma: Tool name — the function the agent called, shown in monospace (`search_docs`). | | `title` | `ReactNode` | — | Figma: Title — what the call does in plain language (“Searched the docs”). Defaults to `name`. | | `status` | `'pending' \| 'running' \| 'success' \| 'error'` | `'success'` | Figma: Status | | `input` | `unknown` | — | Figma: Input — the arguments. Objects are shown as formatted JSON. | | `output` | `unknown` | — | Figma: Output — the result. Objects are shown as formatted JSON. | | `error` | `ReactNode` | — | Error message for `status="error"`; shown in place of the output. | | `duration` | `number` | — | Figma: Duration — run time in milliseconds | | `icon` | `ReactNode` | — | Replaces the wrench icon (e.g. the integration’s logo) | | `open` | `boolean` | — | Expanded (controlled) | | `defaultOpen` | `boolean` | `false` | Initial expanded state when uncontrolled | | `onOpenChange` | `(open: boolean) => void` | — | Called when the person expands or collapses it | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. --- # Approval > Human-in-the-loop confirmation before an agent acts: approve, deny, or edit then approve. URL: https://docs.atomus.io/components/ai-approval/ Asks before the agent acts. It names the action as a question, shows the risk with a word and an icon, previews what will be sent, and lets the person edit it first. The outcome stays in the thread. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-approval.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-approval.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Risk levels ## In Figma From `guidelines/components/ai-approval.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Approval Human-in-the-loop confirmation before an agent acts: the action as a question, a short summary, the risk level, a preview of what will be sent or changed, and Approve / Deny. People can edit the content before approving and can allow the action for the rest of the chat. After they decide, the card stays in the thread with the outcome. Part of the Agent kit. Figma: component set `Approval` on the 🤖 Agent kit page of Atomus 4.0 (node `25550:1196`), connected to React with Code Connect. React props use the same names as the Figma properties below. | Property | Type / options | | -------------------------- | --------------------------- | | Title | text | | Summary | text | | Risk | Low · Medium · High | | Tool name | text | | Details | slot (preview) | | Editable | boolean (off) | | Always allow | boolean (off) + label | | State | Pending · Approved · Denied | | Approve label · Deny label | text | **Risk** - **Low** — read-only or easy to undo; shield icon, success accent. - **Medium** (default) — sends, posts or changes something people can fix; warning accent. - **High** — deletes, pays, publishes or can’t be undone; error accent and border. Name the action on the button (“Delete variables”). **Anatomy** 1. Accent bar on the left in the risk colour, and a risk icon tile. 2. Eyebrow: risk word (“High risk”) and tool name. 3. Title (the question) and summary. 4. Details or editable preview. 5. Footer: “Always allow” checkbox; Deny, Edit, Approve. 6. Outcome after the decision: “Approved”, “Approved with your edits” or “Denied”. **Use for** - Any agent action that writes, sends, spends, deletes or shares. - Steps the person may want to adjust before they happen (an email, a message, a list of issues). **Not for** - Read-only actions the person already asked for: just run them and show a Tool call. - Confirming a person’s own action in a form: use Modal. **Accessibility** - The card is a labelled region (`aria-labelledby` the title, described by the summary). - Risk is a word and an icon, never colour alone. - Focus is not moved to the card when it appears (Primer: keep focus stable); it is reachable in reading order and the buttons are standard buttons. - The outcome is announced in a status region. ## Usage ```tsx import { Approval } from '@stanvision/atomus-react'; <Approval title="Send this summary to #design-system?" risk="medium" toolName="slack.post_message" editableText={draft} alwaysAllowLabel="Always allow posting to #design-system" status={decision} // 'pending' | 'approved' | 'denied' onApprove={({ alwaysAllow, editedText }) => run(editedText ?? draft, alwaysAllow)} onDeny={cancel} > The assistant will post one message as you. </Approval> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `title` (the question), `children` (summary), `risk` (`low` · `medium` · `high`), `toolName`. - `details` for a read-only preview, or `editableText` for edit-then-approve; `onApprove` receives `{ alwaysAllow, editedText }`. - `alwaysAllowLabel` shows the checkbox — never for high risk. - `status` keeps the outcome visible after the decision; `approveLabel` names the action (“Delete variables”). ### Design guidance From the Figma guidelines. **Do** - Phrase the title as a yes/no question with the scope: “File 3 issues in Linear?”. - Show exactly what will be sent or changed, and let people edit it when it is text. - Keep the card in the thread after the decision so the record stays visible. - Offer “Always allow” only for low- and medium-risk actions, scoped to this chat. **Forbidden** - Never run the action before the person approves. - Never pre-tick “Always allow”. - Never offer “Always allow” for high-risk actions. - Never use a vague label such as “OK” or “Continue” — say what Approve does. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-approval.md`. Use only these props; anything else is not part of the API. ### `Approval` Figma: Approval — human-in-the-loop confirmation before an agent acts. Approve, deny, or edit then approve. The person stays the decision-maker; the outcome stays visible after they decide. `import { Approval } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Approval.tsx` | Prop | Type | Default | Description | | ------------------ | -------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- | | `title` | `ReactNode` | **required** | Figma: Title — the action as a question: “Send this email to 12 people?” | | `children` | `ReactNode` | — | Figma: Summary — what will happen and what it affects, in one or two sentences. | | `risk` | `'low' \| 'medium' \| 'high'` | `'medium'` | Figma: Risk — low · medium · high; shown with an icon and a word, never colour alone. | | `toolName` | `string` | — | Figma: Tool name — the function that will run (`send_email`). | | `details` | `ReactNode` | — | Figma: Details — a preview of what will be sent or changed (read-only). | | `editableText` | `string` | — | Figma: Editable — plain text the person may edit before approving (“edit then approve”). | | `editLabel` | `string` | `'Edit before approving'` | Label of the editable field | | `alwaysAllowLabel` | `string` | — | Figma: Always allow — shows the checkbox with this label (“Always allow send_email in this chat”). | | `status` | `'pending' \| 'approved' \| 'denied'` | `'pending'` | Figma: State — `pending` asks; `approved` and `denied` show the outcome in place of the buttons. | | `approveLabel` | `string` | `'Approve'` | Figma: Approve label — name the action for high risk (“Delete variables”) | | `denyLabel` | `string` | `'Deny'` | Figma: Deny label | | `onApprove` | `(decision: ApprovalDecision) => void` | — | Called with the decision when the person approves (after any edits) | | `onDeny` | `() => void` | — | Called when the person denies; keep the card and set `status="denied"` | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `ApprovalDecision`: | Field | Type | Description | | ------------- | --------- | ----------------------------------------------------------- | | `alwaysAllow` | `boolean` | The “always allow” checkbox was ticked | | `editedText?` | `string` | The edited text, when the person used Edit before approving | --- # Sources & citations > Numbered inline citations with preview cards, and the list of sources behind an answer. URL: https://docs.atomus.io/components/ai-sources/ Inline citations are numbered chips after a claim; hover or focus shows a preview card. Sources lists the same numbers under the answer, with the passage each source contributed. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-sources.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-sources.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## List style ## In Figma From `guidelines/components/ai-sources.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Sources The numbered list of sources behind an AI answer: a “3 sources” disclosure with stacked site icons, opening to cards with the number, title, site and the passage the answer used. Numbers match the Inline citations in the text. Part of the Agent kit. Figma: component set `Sources` on the 🤖 Agent kit page of Atomus 4.0 (node `25547:925`), connected to React with Code Connect. Rows: `Source item` (node `25547:794`); citation chip: `Inline citation` (node `25547:946`). React props use the same names as the Figma properties below. | Property | Type / options | | -------- | ---------------------------------------- | | Sources | list (title, url, domain, snippet, icon) | | Label | text (“N sources”) | | Style | Collapsible · List | | Expanded | boolean | **Use for** - Under every answer that relies on retrieved documents, web pages or files. - A side panel listing everything a research agent read (`variant="list"`). **Not for** - Links the person should act on: put them in the answer as normal links. **Accessibility** - The disclosure is a button with `aria-expanded`; the list is an ordered list, so numbers are announced. - Each link says “(source 2, opens in a new tab)” to screen readers. ### Inline citation A small numbered chip right after a claim. Hover or focus shows a preview card (site, title, passage); the chip links to the source. The chip tints with `bg-ai-subtle` and `border-ai` on hover and focus. | Property | Type / options | | -------- | -------------- | | Number | number | | Source | Source item | **Accessibility** - The chip is a link named “Source 2: Title (opens in a new tab)”, described by the preview card (`role="tooltip"`). - The preview opens on focus as well as hover; Esc hides it. ## Usage ```tsx import { Sources, InlineCitation } from '@stanvision/atomus-react'; <p>Body text needs a contrast of at least 4.5:1 <InlineCitation index={1} source={sources[0]} />.</p> <Sources sources={sources} /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `SourceItem` — `id`, `title`, `url`, `domain` (derived from `url`), `snippet`, `icon`. - `Sources` — `variant` `collapsible` (default) or `list`; `label` overrides “N sources”. - `InlineCitation` — `index` matches the position in `sources`. ### Design guidance From the Figma guidelines. #### Sources **Do** - Keep the order of first citation: source 1 is \[1] in the text. - Show the passage the answer used, not the page’s meta description. **Forbidden** - Never list sources the answer didn’t use. - Never invent or guess a URL — leave `url` empty when there is no link. #### Inline citation **Do** - Place the chip right after the sentence or clause it supports, before the full stop of the next one. - Use one chip per source; repeat the number when a source supports several claims. **Forbidden** - Never put interactive content in the preview card. - Never cite with colour or superscript alone — always show the number. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-sources.md`. Use only these props; anything else is not part of the API. ### `Sources` Figma: Sources — the numbered list of sources behind an AI answer. Numbers match InlineCitation. `import { Sources } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Sources.tsx` | Prop | Type | Default | Description | | -------------- | ------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `sources` | `SourceItem[]` | **required** | Figma: Sources — in citation order; item 1 is citation \[1]. | | `label` | `string` | — | Figma: Label — the disclosure text; defaults to “N sources”. | | `variant` | `'collapsible' \| 'list'` | `'collapsible'` | Figma: Style. `collapsible` (default) — a “N sources” disclosure under the answer. `list` — always expanded, for side panels. | | `open` | `boolean` | — | Expanded (controlled, `collapsible` only) | | `defaultOpen` | `boolean` | `false` | Initial expanded state when uncontrolled | | `onOpenChange` | `(open: boolean) => void` | — | Called when the person expands or collapses it | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `SourceItem`: | Field | Type | Description | | ---------- | ----------- | ----------------------------------------------------------- | | `id` | `string` | Stable key | | `title` | `string` | Page or document title | | `url?` | `string` | Link to the source | | `domain?` | `string` | Site shown under the title; derived from `url` when omitted | | `snippet?` | `string` | The passage the answer relied on | | `icon?` | `ReactNode` | Site icon or file-type icon (16px) | ### `InlineCitation` Figma: Inline citation — a numbered chip after a claim. Hover or focus shows a preview card; the chip links to the source. Esc hides the preview. `import { InlineCitation } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Sources.tsx` | Prop | Type | Default | Description | | ----------- | ------------ | ------------ | ------------------------------------------------------------------------------- | | `index` | `number` | **required** | Figma: Number — the citation number, matching the source’s position in Sources | | `source` | `SourceItem` | **required** | The cited source; its title, site and snippet fill the preview card | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `SourceItem`: | Field | Type | Description | | ---------- | ----------- | ----------------------------------------------------------- | | `id` | `string` | Stable key | | `title` | `string` | Page or document title | | `url?` | `string` | Link to the source | | `domain?` | `string` | Site shown under the title; derived from `url` when omitted | | `snippet?` | `string` | The passage the answer relied on | | `icon?` | `ReactNode` | Site icon or file-type icon (16px) | --- # Suggestions > Follow-up prompts as chips and prompt starters as cards, to send or insert. URL: https://docs.atomus.io/components/ai-suggestions/ Follow-ups after an answer, in one row that scrolls sideways, or prompt starters as cards in a welcome state. A chip either sends its prompt or inserts it into the input for editing. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-suggestions.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-suggestions.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Prompt starters ## In Figma From `guidelines/components/ai-suggestions.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Suggestions Follow-up prompts and prompt starters. Chips sit in one row that scrolls sideways with soft faded edges; cards make a grid of starters for an empty conversation. Each chip either sends its prompt or inserts it into the Prompt input for editing. Part of the Agent kit. Figma: component set `Suggestions` on the 🤖 Agent kit page of Atomus 4.0 (node `25545:453`), connected to React with Code Connect. Items: `Suggestion` (node `25545:252`). React props use the same names as the Figma properties below. | Property | Type / options | | -------- | --------------------------------------- | | Items | list (label, prompt, description, icon) | | Action | Send · Insert | | Style | Chips · Cards | | Wrap | boolean (off) | **Action** - **Send** (default) — sends the prompt right away; trailing arrow. - **Insert** — puts the prompt into the input so the person can finish it; trailing plus. **Use for** - 2–5 follow-ups under the latest answer. - 2–4 prompt starters in a welcome state (`variant="cards"`). **Not for** - Navigation or filters: use Tabs, Tag or Button. - Commands with parameters: use the Prompt input’s `/` menu. **Accessibility** - The chips are buttons in a named group (“Suggested prompts”); Insert chips add “(add to message)” for screen readers. - The scrolling row keeps every chip reachable with Tab. ## Usage ```tsx import { Suggestions } from '@stanvision/atomus-react'; <Suggestions suggestions={['Fix the contrast issue', 'Show the axe report']} onSelect={send} /> <Suggestions mode="insert" suggestions={['Make it shorter']} onSelect={(p) => setDraft(p)} /> <Suggestions variant="cards" suggestions={starters} onSelect={send} /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `suggestions` — strings or `{ label, prompt, description, icon }`. - `mode` — `send` (arrow) or `insert` (plus); `onSelect(prompt, item)`. - `variant` — `chips` or `cards`; `wrap` lets chips wrap instead of scroll. ### Design guidance From the Figma guidelines. **Do** - Write chips as the person would type them, in their voice: “Fix the contrast issue”. - Use Insert when the prompt needs a detail the person must add. - Replace follow-ups after every answer; remove them when the person starts typing. **Forbidden** - Never show more than five chips or four cards at once. - Never use Suggestions for actions that change data without a message — use Button. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-suggestions.md`. Use only these props; anything else is not part of the API. ### `Suggestions` Figma: Suggestions — follow-up prompts and prompt starters as chips or cards. `import { Suggestions } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Suggestions.tsx` | Prop | Type | Default | Description | | ------------- | ------------------------------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `suggestions` | `Array<string \| SuggestionItem>` | **required** | Figma: Items — strings or items with a separate prompt, description and icon. | | `onSelect` | `(prompt: string, item: SuggestionItem) => void` | — | Called with the chosen prompt and the item. | | `mode` | `'send' \| 'insert'` | `'send'` | Figma: Action. `send` (default) — choosing a chip sends the prompt right away. `insert` — puts the prompt into the input so the person can edit it first. | | `variant` | `'chips' \| 'cards'` | `'chips'` | Figma: Style. `chips` (default) — one row of pills that scrolls sideways (wraps with `wrap`). `cards` — a grid of prompt starters for a welcome state. | | `wrap` | `boolean` | `false` | Chips wrap onto several lines instead of scrolling | | `label` | `string` | `'Suggested prompts'` | Accessible name of the group | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `SuggestionItem`: | Field | Type | Description | | -------------- | ----------- | --------------------------------------------- | | `id?` | `string` | Stable key; defaults to the label | | `label` | `string` | Text on the chip | | `prompt?` | `string` | Prompt to send or insert; defaults to `label` | | `description?` | `string` | One line under the label (`cards` variant) | | `icon?` | `ReactNode` | Leading icon | --- # Model selector > A Select for AI models with provider icons, descriptions and capability badges. URL: https://docs.atomus.io/components/ai-model-selector/ A Select for AI models. The ghost style sits in the Prompt input toolbar; the outline style suits settings. Options show the provider, when to pick the model and its capabilities. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-model-selector.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-model-selector.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/ai-model-selector.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Model selector Select for AI models: the trigger shows the provider icon and model name; each option shows the name, a “New” badge, provider and one line on when to pick it, and capability badges (Reasoning, Tools, Vision, Fast). It uses the same select-only combobox pattern as Select. Part of the Agent kit. Figma: component set `Model selector` on the 🤖 Agent kit page of Atomus 4.0 (node `25546:1208`), connected to React with Code Connect. List rows: `Model option` (node `25546:397`). React props use the same names as the Figma properties below. | Property | Type / options | | ---------- | --------------------------------------------------------------------------------- | | Models | list (label, provider, provider icon, description, capabilities, badge, disabled) | | Style | Ghost · Outline | | Size | sm · md | | Placement | Up · Down | | Show label | boolean (off) | **Style** - **Ghost** (default) — borderless, for the Prompt input toolbar; opens upwards by default. - **Outline** — bordered like Select, for settings pages; use with `showLabel`. **Use for** - Letting people choose the model for a conversation or a feature. **Not for** - Any other list of options: use Select. **Accessibility** - Combobox with a listbox: ↑ ↓ Home End move, Enter or Space picks, Esc closes, typing jumps to a model. - The trigger has a name (`label`, default “Model”) even when the label is hidden. - Capabilities are text badges, not icons alone. ## Usage ```tsx import { ModelSelector } from '@stanvision/atomus-react'; <ModelSelector models={[ { value: 'pro', label: 'Atomus Pro', provider: 'StanVision', icon: <Logo />, description: 'Best for long, careful work', capabilities: ['Reasoning', 'Tools', 'Vision'], badge: 'New' }, { value: 'fast', label: 'Atomus Fast', provider: 'StanVision', capabilities: ['Fast'] }, ]} value={model} onChange={setModel} /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `models` — `value`, `label`, `provider`, `icon`, `description`, `capabilities`, `badge`, `disabled`. - `variant` — `ghost` (toolbar) or `outline` (settings); `size` `sm` or `md`; `placement` `up` (default) or `down`. - `label` names the combobox; `showLabel` shows it above the trigger. ### Design guidance From the Figma guidelines. **Do** - Describe models by what they are good at, not by version numbers alone. - Keep the list short (up to about six) and put the recommended model first. - Disable models the plan or region doesn’t allow, and say why elsewhere. **Forbidden** - Never switch the model silently in the middle of a conversation. - Never show capability badges the model doesn’t support. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-model-selector.md`. Use only these props; anything else is not part of the API. ### `ModelSelector` Figma: Model selector — Select for AI models with provider icon, description and capability badges. The same select-only combobox pattern as Select: ↑ ↓ Home End Enter Esc and type-ahead. `import { ModelSelector } from '@stanvision/atomus-react';` — source: `react/src/components/ai/ModelSelector.tsx` | Prop | Type | Default | Description | | -------------- | ------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `models` | `ModelOption[]` | **required** | Figma: Models | | `value` | `string` | — | Controlled value. | | `defaultValue` | `string` | — | Initial value when uncontrolled. | | `onChange` | `(value: string) => void` | — | Called with the new value. | | `label` | `string` | `'Model'` | Accessible name; shown only when `showLabel` is set | | `showLabel` | `boolean` | `false` | Shows `label` above the trigger (forms and settings) | | `variant` | `'ghost' \| 'outline'` | `'ghost'` | Figma: Style. `ghost` (default) — borderless trigger for a prompt toolbar. `outline` — bordered like Select, for settings pages. | | `size` | `'sm' \| 'md'` | `'sm'` | Figma: Size — sm 32 · md 40 | | `placement` | `'down' \| 'up'` | `'up'` | Which way the list opens; `up` suits a prompt input at the bottom of the screen | | `disabled` | `boolean` | — | Disables the control. | | `defaultOpen` | `boolean` | — | Start open (docs and tests) | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `ModelOption`: | Field | Type | Description | | --------------- | ----------- | --------------------------------------------------------------------------------- | | `value` | `string` | Model id sent to your backend | | `label` | `string` | Display name (“Claude Sonnet 4.5”) | | `provider?` | `string` | Provider name (“Anthropic”), shown under the label | | `icon?` | `ReactNode` | Figma: Provider icon — the provider’s logo (16–20px) | | `description?` | `string` | One line about when to pick it | | `capabilities?` | `string[]` | Figma: Capabilities — short badges such as “Vision”, “Tools”, “Reasoning”, “Fast” | | `badge?` | `string` | Badge after the name (“New”, “Beta”) | | `disabled?` | `boolean` | Not selectable (plan, region or availability) | --- # Feedback > Thumbs up and down on an AI reply, with an optional reason form. URL: https://docs.atomus.io/components/ai-feedback/ Thumbs up and down on a reply. A thumbs down opens a short form in place with reason chips and an optional comment. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-feedback.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-feedback.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/ai-feedback.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Feedback Thumbs up / down on an AI reply. A thumbs down (and, optionally, a thumbs up) opens a short form in place: reason chips, an optional comment and Send feedback. After sending, a quiet “Thanks for your feedback” replaces the form. Part of the Agent kit. Figma: component set `Feedback` on the 🤖 Agent kit page of Atomus 4.0 (node `25545:219`), connected to React with Code Connect. React props use the same names as the Figma properties below. | Property | Type / options | | -------- | ------------------------------ | | Rating | None · Up · Down | | Reasons | list (text) | | Size | xs · sm | | Form | boolean (opens after a rating) | **Use for** - The actions row of an assistant Message. - Rating a generated draft, summary or image. **Not for** - Product surveys or NPS: use a form or Modal. **Accessibility** - Thumbs are toggle buttons (`aria-pressed`) named “Good response” and “Bad response”. - The form opens because the person asked for it, so focus moves to its first reason; Esc closes it. - Reason chips are toggle buttons; the confirmation is announced in a status region. ## Usage ```tsx import { Feedback } from '@stanvision/atomus-react'; <Feedback onChange={(rating) => track('rating', rating)} onSubmit={({ rating, reasons, comment }) => sendFeedback(messageId, rating, reasons, comment)} /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `value` / `defaultValue` / `onChange` — `'up'`, `'down'` or `null`. - `reasons` for a thumbs down (defaults provided); `positiveReasons` opens a form for a thumbs up too. - `onSubmit` receives `{ rating, reasons, comment }`. ### Design guidance From the Figma guidelines. **Do** - Keep reasons short and specific: “Not accurate”, “Too long”, “Didn’t follow instructions”. - Make the comment optional and send the rating even when the form is closed. **Forbidden** - Never require a reason or a comment. - Never open the form for a thumbs up unless you offer positive reasons. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-feedback.md`. Use only these props; anything else is not part of the API. ### `Feedback` Figma: Feedback — thumbs up / down on an AI reply, with an optional reason form. Thumbs are toggle buttons (aria-pressed); the form opens in place and takes focus. `import { Feedback } from '@stanvision/atomus-react';` — source: `react/src/components/ai/Feedback.tsx` | Prop | Type | Default | Description | | ----------------- | ------------------------------------------ | ----------------- | ------------------------------------------------------------------------------- | | `value` | `'up' \| 'down' \| null` | — | Figma: Rating (controlled); null clears it | | `defaultValue` | `'up' \| 'down' \| null` | `null` | Initial rating when uncontrolled | | `onChange` | `(rating: 'up' \| 'down' \| null) => void` | — | Called on every thumb press | | `onSubmit` | `(feedback: FeedbackSubmission) => void` | — | Called when the reason form is sent | | `reasons` | `string[]` | `DEFAULT_REASONS` | Figma: Reasons — chips offered after a thumbs down | | `positiveReasons` | `string[]` | `[]` | Reasons offered after a thumbs up; no form opens for a thumbs up when empty | | `size` | `'xs' \| 'sm'` | `'xs'` | Figma: Size — xs 24 · sm 32 | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `FeedbackSubmission`: | Field | Type | Description | | --------- | ---------------- | ---------------------------------- | | `rating` | `'up' \| 'down'` | The thumb that was pressed | | `reasons` | `string[]` | The reason chips the person picked | | `comment` | `string` | Free text, may be empty | --- # AI label > Marks AI-generated content and opens an explainability popover, with Revert to AI after edits. URL: https://docs.atomus.io/components/ai-label/ Marks anything an AI wrote or changed. With an explanation it opens a popover that says why the person sees this and which model made it. Once the person edits the content, it reads “Edited” and offers “Revert to AI”. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-label.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-label.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Edited and revert to AI ## In Figma From `guidelines/components/ai-label.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### AI label Marks AI-generated content and is the entry point to explainability: a pill with the gradient AI mark and a short word (“AI”, “AI generated”). With an explanation it becomes a button that opens a popover: why the person sees this, which model made it, and — once they edited the content — “Revert to AI”. Part of the Agent kit. Figma: component set `AI label` on the 🤖 Agent kit page of Atomus 4.0 (node `25543:123`), connected to React with Code Connect. The explainability popover is the separate component `AI label popover` (node `25543:124`). React props use the same names as the Figma properties below. | Property | Type / options | | ---------------------- | ------------------------ | | Label | text (“AI”) | | Size | xs 20 · sm 24 · md 28 | | Style | Chip · Inline · Icon | | Explainability popover | boolean + content | | Model | text | | Edited | boolean (off) | | Revert to AI | boolean (on when Edited) | **Anatomy** 1. AI mark: a sparkle filled with `--gradient-ai`. 2. Label in `text-ai` on `bg-ai-subtle` with a `border-ai` hairline. 3. Chevron when it opens a popover. 4. Popover: gradient top edge, title, explanation, footer with the model and “Revert to AI”. **Edited** When a person changes AI content, the label reads “Edited”, loses the AI tint and shows a pencil. The popover keeps the explanation and offers “Revert to AI”, which restores the generated content. **Use for** - Next to anything an AI wrote or changed: messages, summaries, generated fields, table cells, images. - Field labels of inputs that an AI prefilled. **Not for** - Marketing badges (“New”, “Pro”): use Badge. - Decoration — the AI tint and gradient only identify AI content. **Accessibility** - The `icon` style keeps the label as visually hidden text. - With a popover, the label is a button with `aria-expanded`; the popover is a non-modal dialog named by its title. Esc and an outside click close it and return focus. - AI content is never marked by colour or gradient alone — the word stays. ## Usage ```tsx import { AILabel } from '@stanvision/atomus-react'; <AILabel label="AI generated" explanation={<p>Written from the 14 comments on this pull request.</p>} model="Atomus Pro" edited={text !== generated} onRevert={() => setText(generated)} /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `label`, `size` (`xs` · `sm` · `md`), `variant` (`chip` · `inline` · `icon`). - `explanation`, `explanationTitle` and `model` fill the popover. - `edited` switches to “Edited”; `onRevert` adds “Revert to AI”. ### Design guidance From the Figma guidelines. **Do** - Label every piece of AI-generated content in the same way across the product. - Say in the explanation where the content came from and what to check. - Offer “Revert to AI” whenever people can edit generated content. **Forbidden** - Never use `--gradient-ai`, `bg-ai-subtle` or `border-ai` on content that is not AI. - Never hide the label once the person has edited the content — switch it to Edited. - Never put actions other than Revert to AI and links to settings in the popover. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-label.md`. Use only these props; anything else is not part of the API. ### `AILabel` Figma: AI label — marks AI-generated content and is the entry point to explainability. With `explanation` it is a button with a non-modal popover (Esc and outside click close it). `import { AILabel } from '@stanvision/atomus-react';` — source: `react/src/components/ai/AILabel.tsx` | Prop | Type | Default | Description | | ------------------ | ------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | `string` | `'AI'` | Figma: Label — the visible word. Keep it short: “AI”, “AI generated”, “Draft by AI”. | | `size` | `'xs' \| 'sm' \| 'md'` | `'sm'` | Figma: Size — xs 20 · sm 24 · md 28 | | `variant` | `'chip' \| 'inline' \| 'icon'` | `'chip'` | Figma: Style. `chip` (default) — tinted pill with the gradient mark. `inline` — mark and text, no fill; for message headers and table cells. `icon` — the mark only; the label stays available to screen readers. | | `explanation` | `ReactNode` | — | Figma: Explainability popover. Short, plain-language answer to “why am I seeing this?”. When set, the label becomes a button that opens the popover. | | `explanationTitle` | `string` | `'About this AI content'` | Figma: Popover title — defaults to “About this AI content”. | | `model` | `string` | — | Model or agent that produced the content, shown in the popover footer. | | `edited` | `boolean` | `false` | Figma: Edited — the person changed the AI content; the label reads “Edited” and loses the AI fill. | | `onRevert` | `() => void` | — | Figma: Revert to AI — shows a “Revert to AI” action in the popover (only while `edited`). | | `align` | `'start' \| 'end'` | `'start'` | Which edge of the label the popover lines up with; use `end` near the right edge of a layout | | `defaultOpen` | `boolean` | — | Start with the popover open (docs and tests) | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. --- # Context meter > How much of the model’s context window a conversation uses, and what it cost. URL: https://docs.atomus.io/components/ai-context-meter/ Shows how full the model’s context window is and what the conversation cost. The compact ring sits in the Prompt input; click it for the breakdown. It turns warning at 80% and error at 95%, with a sentence that says what happens next. Add the source to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/ai-context-meter.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fai-context-meter.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## In Figma From `guidelines/components/ai-context-meter.md` Properties, variants and anatomy of the Figma components. React props use the same names. ### Context meter How much of the model’s context window a conversation uses, and what it has cost. The compact style is a ring and percentage for the Prompt input; it opens a card with the bar, a breakdown (input, output, tools) and the cost. The bar style shows the same details inline. Part of the Agent kit. Figma: component set `Context meter` on the 🤖 Agent kit page of Atomus 4.0 (node `25546:320`), connected to React with Code Connect. React props use the same names as the Figma properties below. | Property | Type / options | | --------- | ------------------------------------- | | Used | number (tokens) | | Limit | number (tokens) | | Cost | number + currency | | Breakdown | list (label, tokens) | | Style | Compact · Bar | | State | Default · Warning (80%) · Error (95%) | **State** - Below `warnAt` (80%) the fill uses `--gradient-ai`. - From 80% it turns `fg-warning` with “Getting full: start a new chat for a new topic.” - From 95% it turns `fg-error` with “Almost full: older messages will be summarised or dropped.” **Use for** - Power-user and developer tools where people manage long conversations or pay per token. **Not for** - Consumer chat where tokens mean nothing to people — explain limits in words instead. - Upload or task progress: use Progress bar. **Accessibility** - The bar is a WAI-ARIA `meter` with a text value: “24% used, 48.2K of 200K tokens”. - The compact trigger is a button named with the same text; its card closes with Esc. - Warning and error states add a sentence, not only a colour. ## Usage ```tsx import { ContextMeter } from '@stanvision/atomus-react'; <ContextMeter used={usage.totalTokens} limit={200000} cost={usage.costUsd} breakdown={[{ label: 'Input', tokens: usage.input }, { label: 'Output', tokens: usage.output }]} /> ``` ### Props at a glance Full types and defaults are in [React API](#react-api) at the end of the page. - `used`, `limit` (tokens), `cost` and `currency`, `breakdown`. - `variant` — `compact` (ring + %, details on click) or `bar`. - `warnAt` (80) sets the warning threshold; error is fixed at 95%. `locale` formats numbers. ### Design guidance From the Figma guidelines. **Do** - Format large numbers compactly (48.2K) and show cost in the person’s currency. - Explain what happens when the window is full. **Forbidden** - Never block sending when the meter is full without saying why and what to do. ## React API Generated from `react/src/components` by `scripts/gen-react-api.mjs` — the same tables agents read in `guidelines/components/ai-context-meter.md`. Use only these props; anything else is not part of the API. ### `ContextMeter` Figma: Context meter — how much of the model’s context window a conversation uses, and what it cost. A WAI-ARIA meter; the compact variant is a button that opens the details. `import { ContextMeter } from '@stanvision/atomus-react';` — source: `react/src/components/ai/ContextMeter.tsx` | Prop | Type | Default | Description | | ------------- | -------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `used` | `number` | **required** | Figma: Used — tokens in the context window now | | `limit` | `number` | **required** | Figma: Limit — the model’s context window in tokens | | `cost` | `number` | — | Figma: Cost — spend for this conversation, in `currency` | | `currency` | `string` | `'USD'` | ISO 4217 currency of `cost` | | `breakdown` | `ContextUsagePart[]` | — | Optional split of `used` (input, output, cached …) shown in the details | | `label` | `string` | `'Context window'` | Name of the meter | | `variant` | `'compact' \| 'bar'` | `'compact'` | Figma: Style. `compact` (default) — a ring and percentage for a prompt toolbar; details open on click. `bar` — label, bar and numbers inline, for side panels and settings. | | `warnAt` | `number` | `80` | Percentage at which the meter turns warning; error from 95% | | `locale` | `string` | — | BCP 47 locale for numbers | | `placement` | `'up' \| 'down'` | `'up'` | Which way the compact details open; `up` suits a prompt input at the bottom of the screen | | `defaultOpen` | `boolean` | — | Start with the compact details open (docs and tests) | | `className` | `string` | — | Extra class on the root element (layout only — never restyle colours or sizes). | Accepts only the props above. `ContextUsagePart`: | Field | Type | Description | | -------- | -------- | -------------------------------------- | | `label` | `string` | “Input”, “Output”, “Cached”, “Tools” … | | `tokens` | `number` | Tokens in this part | --- # Website sections > Responsive marketing sections and example pages in the Atomus Figma file, with live previews. URL: https://docs.atomus.io/website-sections/ All sections have Breakpoint variants Desktop (1440), Tablet (768) and Mobile (375); spacing and type follow the variable modes. 30 sections, each previewed live with Atomus CSS and React components. Switch a preview between Desktop (1280), Tablet (768) and Mobile (375) — layout, type and spacing follow the same breakpoints as the Figma variants. ## Header navigation Website header; Tablet/Mobile collapse to a menu button. Figma variants: `Type:Default,Mobile menu open` `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/header-navigation.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fheader-navigation.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Footer Footer with brand, 4 link columns and bottom bar; Dark flips all tokens. Figma variants: `Style:Light,Dark` `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/footer.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ffooter.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Hero section Centered, Split image or Email capture hero. Figma variants: `Type:Centered,Split image,Email capture` `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/hero-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fhero-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Features section Icon grid: 6 features, 3 / 2 / 1 columns. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/features-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ffeatures-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Feature split section Text + checklist next to an image. Figma variants: `Type:Image right,Image left` `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/feature-split-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ffeature-split-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Bento section Bento grid of feature cards. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/bento-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fbento-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Logo cloud Customer logos row. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/logo-cloud.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Flogo-cloud.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Testimonial Single large quote with rating and author. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/testimonial.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ftestimonial.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Testimonials grid Testimonial cards: 3 / 2 / 1 columns. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/testimonials-grid.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ftestimonials-grid.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Metrics section Key numbers on a brand background. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/metrics-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fmetrics-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Pricing card Pricing tier; Highlighted = recommended plan. Figma variants: `Plan:T` `Price:T` `Description:T` `CTA label:T` `Highlighted:False,True` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/pricing-card.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fpricing-card.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Pricing section Billing toggle and 3 pricing cards. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/pricing-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fpricing-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## FAQ item Accordion row. Figma variants: `Question:T` `Answer:T` `State:Closed,Open` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/faq-item.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ffaq-item.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## FAQ section Heading + 6 FAQ items. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/faq-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Ffaq-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## CTA section Closing call-to-action: brand band or card with image. Figma variants: `Type:Brand band,Card with image` `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/cta-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fcta-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Newsletter section Newsletter sign-up. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/newsletter-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fnewsletter-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Blog card Blog post preview card. Figma variants: `Title:T` `Excerpt:T` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/blog-card.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fblog-card.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Blog section Latest posts: 3 / 2 / 1 cards. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/blog-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fblog-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Team member Team member card. Figma variants: `Name:T` `Role:T` `Bio:T` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/team-member.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fteam-member.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Team section Team grid: 4 / 2 / 1. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/team-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fteam-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Contact section Contact form + contact info cards. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/contact-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fcontact-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Careers section Open roles with department filter and job cards. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/careers-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fcareers-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Comparison table section Plan comparison table. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/comparison-table-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fcomparison-table-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Integrations section Integration cards: 3 / 2 / 1 columns. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/integrations-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fintegrations-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## 404 section Not-found page body with search. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/not-found-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fnot-found-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Blog post content Article layout with rich-text body. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/blog-post-content.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fblog-post-content.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Content section Long-form content with image. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/content-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fcontent-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Press mentions Media logos with press quotes. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/press-mentions.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fpress-mentions.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Legal content Privacy / terms layout with table of contents. Figma variants: `Breakpoint:Desktop,Tablet,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/legal-content.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Flegal-content.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Auth section Log in, Sign up, Forgot password, Verification. Figma variants: `Type:Log in,Sign up,Forgot password,Verification` `Breakpoint:Desktop,Mobile` Add this section to a shadcn project `npx shadcn@latest add https://docs.atomus.io/r/auth-section.json` Copy command [Open in v0](https://v0.app/chat/api/open?url=https%3A%2F%2Fdocs.atomus.io%2Fr%2Fauth-section.json) Installs the component source, its CSS and the Atomus tokens into `components/atomus/`. [How the registry works](https://docs.atomus.io/ai/registry/) ## Example pages Home, Pricing, Blog, Blog post, About, Team, FAQ, Contact, Integrations, Legal, 404, Log in, Sign up — each at Desktop and Mobile, built only from section instances. Recipe: `Header navigation` → hero → 2–4 content sections → `CTA section` → `Footer`. --- # Design tokens > W3C DTCG token files generated from the Figma variables. URL: https://docs.atomus.io/code/tokens/ The [`tokens/`](https://github.com/StanVisionAgency/atomus/tree/main/tokens) folder holds one **DTCG 2025.10** JSON file per collection and mode, plus `$themes.json` (which files make each theme) and `text-styles.tokens.json`. | File | Contents | | ------------------------------------------------------ | ------------------------------------------------ | | `primitives.tokens.json` | Colour ramps, alpha ramps, size scale | | `brand.atomus.tokens.json`, `brand.violet.tokens.json` | Brand ramp per brand mode | | `color.light.tokens.json`, `color.dark.tokens.json` | Semantic colours | | `radius.default/sharp/round.tokens.json` | Corner scale per shape mode | | `spacing-layout.desktop/tablet/mobile.tokens.json` | Spacing, layout, sizes, containers | | `typography.desktop/tablet/mobile.tokens.json` | Families, weights, sizes, line heights | | `effects.light/dark.tokens.json` | Shadow layers per elevation | | `text-styles.tokens.json` | Composite typography tokens for every text style | They import into Tokens Studio, Style Dictionary and Terrazzo. Token names map to the CSS names shown in Figma Dev Mode, for example `Text/text-primary` → `--color-text-primary`. --- # CSS > atomus.css — every token as a CSS custom property, with theme, brand, radius and breakpoint switches. URL: https://docs.atomus.io/code/css/ [`css/atomus.css`](https://github.com/StanVisionAgency/atomus/blob/main/css/atomus.css) works with any stack. ```html <link rel="stylesheet" href="atomus.css"> <html data-theme="light"> <!-- light | dark | system --> <body data-brand="violet"> <!-- omit for Atomus blue --> <section data-radius="round"> <!-- default | sharp | round --> ``` - Switches nest: a `data-theme` or `data-brand` on any element re-themes everything inside it. - Breakpoints follow the Figma modes: Desktop ≥ 1024px, Tablet 768–1023px, Mobile < 768px. Layout spacing, container padding and headline sizes change automatically. - `.text-*` classes match every Figma text style (`.text-headline-h1`, `.text-content-body`, `.text-web-display` …). - Shadows: `--shadow-elevation-1 … 24` and `--shadow-focus-ring`. ## Add a client brand 1. In Figma, add a mode to the **Brand** collection and point `brand-25 … brand-950` at the client ramp. 2. In CSS, copy the `[data-brand="violet"]` block, rename it and paste the client hex values. --- # Tailwind CSS v4 > The Atomus theme for Tailwind v4 with semantic utilities. URL: https://docs.atomus.io/code/tailwind/ ```css @import "tailwindcss"; @import "./atomus.tailwind.css"; ``` ```html <button class="bg-brand-solid text-on-brand rounded-md px-xl h-10 shadow-e2">Save</button> <p class="text-secondary text-body">…</p> <section class="px-layout-md py-layout-xl">…</section> ``` - `@theme` holds the palette (`bg-brand-600`, `text-gray-900` …), radius, spacing (`p-md`, `gap-layout-sm`), type scale (`text-h1`) and shadows (`shadow-e1 … e24`). - 54 semantic utilities: `text-primary`, `bg-secondary`, `border-primary`, `fg-brand`, `text-on-warning` … - `dark:` works with `data-theme="dark"` or `.dark`. Brand, radius and breakpoint switches come from `atomus.css`, which the theme imports. Use **either** this theme **or** the shadcn/ui theme in one app — both define `bg-primary` with different meanings. --- # shadcn/ui > Map shadcn/ui's theme variables onto Atomus tokens. URL: https://docs.atomus.io/code/shadcn/ Replace the `:root` / `.dark` blocks in your `globals.css` with [`shadcn/globals.css`](https://github.com/StanVisionAgency/atomus/blob/main/shadcn/globals.css), after `@import "tailwindcss"`. | shadcn variable | Atomus token | | ------------------------------------- | ------------------------------------------------------ | | `--background`, `--card`, `--popover` | `bg-primary` | | `--foreground` | `text-primary` | | `--primary` / `--primary-foreground` | `bg-brand-solid` / `text-on-brand` | | `--secondary` | `bg-secondary` | | `--muted` / `--muted-foreground` | `bg-tertiary` / `text-tertiary` | | `--accent` / `--accent-foreground` | `bg-brand-subtle` / `text-brand` | | `--destructive` | `bg-error-solid` | | `--border` / `--input` / `--ring` | `border-secondary` / `border-primary` / `border-focus` | | `--chart-1 … 5` | brand 600, 400, 200, gray 400, 200 | | `--sidebar-*` | sidebar surfaces and accents | | `--radius` | `radius-lg` | Brand, theme and radius modes keep working: shadcn components follow `data-brand`, `data-theme` and `data-radius`. ## Install with the shadcn CLI The same mapping ships as the `atomus-theme` item of the [Atomus shadcn registry](https://docs.atomus.io/ai/registry/). It writes the tokens and the variables above into your CSS file: ```bash npx shadcn@latest add https://docs.atomus.io/r/atomus-theme.json ``` --- # 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. ## 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 | ## 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. ## 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.