This is the Components part of the Atomus documentation: every component page: Figma properties, usage rules and React API. --- # 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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. Use the Figma components below. In code, build it from Atomus [tokens](https://docs.atomus.io/code/tokens/) and [CSS](https://docs.atomus.io/code/css/) until a React component ships. ## 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 |