# Aura Design System

> Aura is an agentic design system: components, tokens, and written rules that people browse and coding agents follow.


- **Get Started**
- [Get started](/docs): Aura is an agentic design system. Install it as a person, or point an agent at the harness — DESIGN.md, rules, Aura skills, Poteto mode, gdp-ts, and the CLI.
- [Registry](/docs/registry): Explore how our registry-based approach gives you full ownership and control over your component code.
- [Namespaces](/docs/namespace): Learn how namespaces work in Aura to manage components from multiple registries without conflicts.
- [Taste](/docs/taste): Discover the design tokens for spacing, colors, and typography that define the Aura aesthetic.
- [Installation](/docs/installation): Install Aura with the CLI on a new or existing Next.js app, then add registry components.
- [CLI](/docs/cli): Commands in @aura-design/cli for initializing Aura, theming, spacing migration, and blueprint scaffolding.
- [MCP](/docs/mcp): Connect Cursor to shadcn registries and recreate components in Aura from a pasted link.
- [Agent blueprint](/docs/mcp-agent-blueprint): Paste this URL to an agent with “Ejecuta” — audit and install MCP, rules, skills, DESIGN.md, lint, gdp-ts proofs, and optional pstack / poteto-mode on an existing Aura project.
- [pstack](/docs/pstack): How Lauren Tan’s pstack and /poteto-mode fit Aura — install, trust model, and how they work with Aura rules, skills, lint, and the agent blueprint.
- [gdp-ts](/docs/gdp-ts): How Aura bootstraps Ghosts of Departed Proofs — install, starter proofs, and the rule that sensitive APIs demand a proof.
- [Emil Kowalski skills](/docs/emil-skills): Aura does not ship these skills. Install them from emilkowalski/skills when you want a UI or motion audit.
- [Audits](/docs/audits): Third-party UI, motion, performance, and WorkOS skills. They are not part of Aura. Install them from upstream when you want an audit.
- [Lint](/docs/lint): Enforce Aura Tailwind policy with @shadcn/lint — tokens, 13px spacing, and no-restyle contracts agents can fix.

- **Foundations**
- [Foundations](/docs/foundations): Aura’s visual foundations — color, type, layout, icons, motion, accessibility, and theming.
- [Accessibility](/docs/foundations/accessibility): Aura’s accessibility foundation — perceivable and operable UI, contrast targets, focus, form type size, and reduced motion.
- [Color](/docs/foundations/color): Aura’s 12-step accent and gray scales, alpha variants, status pairs, and the semantic tokens that point at them.
- [Components](/docs/foundations/components): How Aura components are owned, varianted, and kept on tokens — the registry model behind the component catalog.
- [Data visualization](/docs/foundations/data-visualization): Chart series tokens for Aura charts — accent and status contrast, gray grid and ticks, 250ms motion.
- [Icons](/docs/foundations/icons): Radix icons sized as type, spaced with gap on the container, one icon library per project.
- [Layout](/docs/foundations/layout): The 13px spacing grid, named containers, and the aureole column system.
- [Depth and elevation](/docs/foundations/elevation): Radius on the 13px grid, tonal sheets, and borders at gray steps 6–8. Aura does not define a shadow scale.
- [Motion](/docs/foundations/motion): CSS animation tokens, compositor-friendly properties, and prefers-reduced-motion as shipped in the registry.
- [Patterns](/docs/foundations/patterns): Composition with asChild, form wiring, and the section rhythm Aura already specifies.
- [Theming](/docs/foundations/theming): Light and dark through prefers-color-scheme and .dark, with step roles held constant and a theme color switcher for accent seeds.
- [Typography](/docs/foundations/typography): Fluid clamp scale, Gabarito, a 17px root, and the floor on editable form controls.

- **Handbook**
- [Handbook](/docs/handbook): Reference for styling, animations, composition, and customization when building with Aura.
- [Styling](/docs/handbook/styling): Where design tokens and shared styles live — main.css and globals.css — and how to use them.
- [Animations](/docs/handbook/animations): Component animation tokens and keyframes — accordion, alert-dialog, collapsible, dialog — and where they are imported.
- [Composition](/docs/handbook/composition): Composing Radix primitives with your own elements and components using asChild, and similar patterns from other libraries.
- [Customization](/docs/handbook/customization): Controlling components with state, handling change events, and escape hatches for dialogs and overlays.
- [llms.txt](/docs/handbook/llms.txt): Full documentation as plain text for LLMs and crawlers. Redirects to /llms-full.txt.

- **Rules**
- [Rules](/docs/rules): Always-on Aura process rules. Design guardrails live in the Aura skill.
- [Aura skill](/docs/rules/aura-skill): Design guardrails for agents. One skill at .agents/skills/aura, same layout as the shadcn/ui skill.
- [DESIGN.md (narrative spec)](/docs/rules/design-md): Installs the agent rule into .agents/rules and the project root DESIGN.md (narrative spec). Add with shadcn as @aura/rule-design-md.
- [Feature map](/docs/rules/feature-map): The only project documentation is a feature map in the Obsidian vault, updated in the PR that changes a feature. No progress logs.
- [No code comments](/docs/rules/no-comments): Fix the root cause instead of commenting on it. Only external constraints, directives, licenses, and generated code carry comments.

- **Components**
- [All Components](/docs/components): A comprehensive list of all available components in the Aura Design System.
- [Accordion](/docs/components/accordion): A vertically stacked set of interactive headings that each reveal a section of content.
- [Action Bar](/docs/components/action-bar): A floating toolbar for bulk actions on selected items.
- [Alert Dialog](/docs/components/alert-dialog): A modal dialog that interrupts the user with important content and expects a response.
- [Alert](/docs/components/alert): Displays a callout for user attention with contextual feedback messages.
- [Angle Slider](/docs/components/angle-slider): A circular slider for selecting an angle or value along an arc.
- [Aspect Ratio](/docs/components/aspect-ratio): Displays content within a desired ratio.
- [Autocomplete](/docs/components/autocomplete): An input component that allows users to search and select from a list of options.
- [Avatar Group](/docs/components/avatar-group): Overlapping avatars with truncation, orientation, and custom overflow.
- [Avatar](/docs/components/avatar): An image element with a fallback for representing the user.
- [Badge Overflow](/docs/components/badge-overflow): Measures available space and shows badges with an overflow indicator.
- [Badge](/docs/components/badge): Displays a badge or a component that looks like a badge.
- [Banner](/docs/components/banner): A full-width notice with an optional action and dismiss button.
- [Breadcrumb](/docs/components/breadcrumb): A navigation trail for the current page.
- [Bubble](/docs/components/bubble): Displays conversational content in a message bubble. Supports variants, alignment, grouping, reactions, and polymorphic content.
- [Button Group](/docs/components/button-group): A container that groups buttons (and optional text or separators) with shared styling and orientation.
- [Button](/docs/components/button): Displays a button or a component that looks like a button.
- [Calendar](/docs/components/calendar): Displays a calendar.
- [Card](/docs/components/card): Displays a card with header, content, and footer sections.
- [Carousel](/docs/components/carousel): A carousel component built with Embla, with optional previous/next controls and configurable orientation.
- [Checkbox](/docs/components/checkbox): A control that allows the user to toggle between checked and not checked.
- [Chip](/docs/components/chip): Standalone assist, filter, and input chips.
- [Circular Progress](/docs/components/circular-progress): Determinate progress drawn as a circle.
- [Code Block](/docs/components/code-block): Displays code, terminal output, logs, and diffs with a header, line numbers, and a copy action.
- [Collapsible](/docs/components/collapsible): An interactive component which expands and collapses content.
- [Color Picker](/docs/components/color-picker): A color field with a picker, a typed hex value, and swatches.
- [Color Swatch](/docs/components/color-swatch): A selectable color sample.
- [Combobox](/docs/components/combobox): A combobox component that allows users to search and select from a list of options.
- [Command](/docs/components/command): A command palette that allows users to search and execute commands.
- [Compare Slider](/docs/components/compare-slider): A slider that reveals one view over another.
- [Context Menu](/docs/components/context-menu): Displays a menu to the user triggered by right-click or long-press.
- [Cropper](/docs/components/cropper): A draggable crop region you can also nudge with the arrow keys.
- [Date Picker](/docs/components/date-picker): A single date chosen from Calendar inside a Popover.
- [Dialog](/docs/components/dialog): A window overlaid on the primary content, rendering content in a layer above the page.
- [Drawer](/docs/components/drawer): A drawer component that slides in from the edge of the screen.
- [Dropdown Menu](/docs/components/dropdown-menu): Displays a menu of actions or options triggered by a button.
- [Editable](/docs/components/editable): Inline text that switches between preview and edit modes.
- [Empty](/docs/components/empty): A placeholder component for empty states, with optional icon, title, description, and content slots.
- [Expressive Carousel](/docs/components/expressive-carousel): A carousel whose items resize as you scroll.
- [Fab Menu](/docs/components/fab-menu): A floating button that opens a stack of related actions.
- [Fab](/docs/components/fab): A floating button for a screen's main action, with an optional label.
- [Field](/docs/components/field): Standalone field layout that sits beside Form.
- [File Upload](/docs/components/file-upload): A composable file upload with dropzone, list, previews, and progress indicators.
- [Form](/docs/components/form): A comprehensive form system with schema-based validation, error handling, and field management. Built with Radix UI primitives and AJV validation, supporting text inputs, textareas, selects, checkboxes, switches, and checkbox groups with automatic error propagation and touch state management.
- [Fps](/docs/components/fps): A live frames-per-second meter.
- [Gauge](/docs/components/gauge): A semicircle meter with a needle.
- [Grid](/docs/components/grid): Displays a grid container with configurable column layout.
- [Hover Card](/docs/components/hover-card): For sighted users to preview content available behind a link.
- [Icon](/docs/components/icon): A wrapper for Radix icons.
- [Input Group](/docs/components/input-group): Add addons, buttons, and helper content to inputs.
- [Input OTP](/docs/components/input-otp): A one-time code built from SegmentedInput.
- [Input](/docs/components/input): Displays a form input field or a component that looks like an input field.
- [Item](/docs/components/item): A list row with media, title, description, and actions.
- [Kanban](/docs/components/kanban): Columns of cards that move backward and forward.
- [Kbd](/docs/components/kbd): A keyboard shortcut component that allows users to display keyboard shortcuts.
- [Key Value](/docs/components/key-value): A list of labels and values.
- [Label](/docs/components/label): Renders an accessible label associated with form controls.
- [Listbox](/docs/components/listbox): A list of options with arrow-key selection.
- [Loading Indicator](/docs/components/loading-indicator): A loading status that morphs between shapes.
- [Marker](/docs/components/marker): Displays an inline status, system note, bordered row, or labeled separator in a conversation.
- [Marquee](/docs/components/marquee): A looping row of items that pauses for reduced motion.
- [Mask Input](/docs/components/mask-input): An input that formats values with built-in or custom mask patterns.
- [Masonry](/docs/components/masonry): A two-column layout that keeps items intact.
- [Media Player](/docs/components/media-player): Play, pause, seek, and mute controls for an audio source.
- [Mention](/docs/components/mention): An accessible text input that suggests and inserts items after a trigger character.
- [Menubar](/docs/components/menubar): A visually persistent menu common in desktop applications.
- [Message Scroller](/docs/components/message-scroller): A chat scroll container that anchors turns, follows streamed output, loads history without jumping, and jumps to any message.
- [Message](/docs/components/message): Displays a message in a conversation, with optional avatar, header, footer, and alignment.
- [Native Select](/docs/components/native-select): A native select with the same field chrome as other inputs.
- [Navigation Bar](/docs/components/navigation-bar): Bottom navigation for phones.
- [Navigation Menu](/docs/components/navigation-menu): A collection of links for navigating websites.
- [Navigation Rail](/docs/components/navigation-rail): Side navigation for tablet and desktop, collapsed or expanded.
- [Pagination](/docs/components/pagination): Pagination with page links, previous/next controls, and ellipsis.
- [Phone Input](/docs/components/phone-input): A phone field with a calling code and a typed number.
- [Popover](/docs/components/popover): Displays rich content in a portal triggered by a button.
- [Presentation](/docs/components/presentation): Composable PowerPoint viewer and editor built on @diceui/pptx.
- [Progress](/docs/components/progress): Displays an indicator showing the completion progress of a task.
- [Qr Code](/docs/components/qr-code): A square code for a short string, up to 17 bytes.
- [Questionnaire](/docs/components/questionnaire): A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions.
- [Radio Group](/docs/components/radio-group): Re-usable components built using Radix UI and Tailwind CSS.
- [Rating](/docs/components/rating): A star rating that works with the keyboard.
- [Relative Time Card](/docs/components/relative-time-card): A relative time with the absolute date beside it.
- [Resizable](/docs/components/resizable): Panels that resize by drag or keyboard.
- [Responsive Dialog](/docs/components/responsive-dialog): A dialog on desktop and a drawer on mobile, sharing one API.
- [Responsive Dropdown Menu](/docs/components/responsive-dropdown-menu): A dropdown menu on desktop and a stacked drawer for nested menus on mobile.
- [Scroll Area](/docs/components/scroll-area): Augments native scroll functionality for custom cross-browser styling.
- [Scroll Spy](/docs/components/scroll-spy): A list of links that marks the section in view.
- [Scroller](/docs/components/scroller): A horizontal strip with back and forward controls.
- [Search](/docs/components/search): A search bar that expands into a results view.
- [Section](/docs/components/section): A semantic section container with configurable layout variants.
- [Segmented Input](/docs/components/segmented-input): A group of connected input fields that appear as a single segmented visual unit.
- [Select](/docs/components/select): A select component that allows users to select a value from a list of options.
- [Selection Toolbar](/docs/components/selection-toolbar): A floating toolbar that appears on text selection with formatting and utility actions.
- [Separator](/docs/components/separator): A separator component that allows users to separate content.
- [Shape](/docs/components/shape): A set of shapes that can mask an image and morph between each other.
- [Sheet](/docs/components/sheet): A slide-out panel that overlays the page, with optional header, footer, title, and description. Opens from a trigger (e.g. button).
- [Side Sheet](/docs/components/side-sheet): A side panel that sits beside the content, with no overlay.
- [Sidebar](/docs/components/sidebar): A collapsible side panel for app navigation and layout, with optional mobile sheet, icons, and persistent state.
- [Signature Pad](/docs/components/signature-pad): A component that allows the user to sign a document using a pen.
- [Skeleton](/docs/components/skeleton): A loading placeholder with pulse animation, typically used for content that is being fetched.
- [Slider](/docs/components/slider): An input where the user selects a value from within a given range.
- [Snackbar](/docs/components/snackbar): A short message at the bottom of the screen with one optional action.
- [Sortable](/docs/components/sortable): A sortable list of items.
- [Speed Dial](/docs/components/speed-dial): A floating button that opens a stack of actions. Same parts as the floating action menu.
- [Spinner](/docs/components/spinner): A status spinner reused by Button and FormSubmit.
- [Split Button](/docs/components/split-button): A main action paired with a menu of related actions.
- [Stack](/docs/components/stack): Overlapping panels offset from one another.
- [Stat](/docs/components/stat): Displays a statistic with label, value, optional indicator, trend, and description.
- [Status Dot](/docs/components/status-dot): A 10px status dot for queued, building, error, ready, and canceled.
- [Status](/docs/components/status): A short status label with a tone dot.
- [Stepper](/docs/components/stepper): A sequential progress indicator with navigation controls.
- [Swap](/docs/components/swap): Switches between two views in place.
- [Switch](/docs/components/switch): A control that allows the user to toggle between on and off states.
- [Table](/docs/components/table): A responsive table for organizing related data into rows and columns.
- [Tabs](/docs/components/tabs): A tabs component that allows the user to switch between different views.
- [Tags Input](/docs/components/tags-input): A field that collects tags. Enter adds one, Backspace removes the last.
- [Textarea](/docs/components/textarea): A multi-line text input for longer form content.
- [Time Picker](/docs/components/time-picker): A clock dial paired with a typed time field.
- [Timeline](/docs/components/timeline): A vertical list of titled moments.
- [Toast](/docs/components/toast): Install sileo and style it with Aura tokens. Aura does not ship a Toast component.
- [Toggle Group](/docs/components/toggle-group): A group of toggle buttons where one or more options can be selected, with single or multiple selection modes.
- [Toggle](/docs/components/toggle): A toggle component that allows the user to toggle between on and off states.
- [Toolbar](/docs/components/toolbar): An always-visible bar of related actions.
- [Tooltip](/docs/components/tooltip): A tooltip component that displays informative text when hovering over an element.
- [Tour](/docs/components/tour): A short stepped guide that highlights one target at a time.
- [Trace](/docs/components/trace): A list of agent steps. Each row has an icon, a title, an optional description, and a status.
- [Typography](/docs/components/typography): The fluid type scale as CSS classes. Aura does not ship a Typography component.

- **Charts**
- [Charts](/docs/charts): Area, bar, line, pie, radar, and radial charts, plus tooltip patterns.
- [Area Chart](/docs/charts/area-chart): Area chart family — natural, linear, step, stacked, expanded, legend, icons, gradient, axes, and an interactive range.
- [Bar Chart](/docs/charts/bar-chart): Bar chart family — vertical, horizontal, multiple, stacked, labels, mixed, active, and negative.
- [Line Chart](/docs/charts/line-chart): Line chart family — natural, linear, step, multiple, dots, custom dots, labels, and an interactive range.
- [Pie Chart](/docs/charts/pie-chart): Pie chart family — pie, joined slices, labels, legend, donut, active slice, center total, and stacked rings.
- [Radar Chart](/docs/charts/radar-chart): Radar chart family — default, dots, lines, multiple series, legend, circle grid, filled grid, and icons.
- [Radial Chart](/docs/charts/radial-chart): Radial chart family — rings, labels, grid, center total, rounded shape, and stacked series.
- [Tooltips](/docs/charts/chart-tooltips): Tooltip indicators, labels, icons, and value formatting for Aura charts.

- **Utils**
- [Utils](/docs/utils): Headless helpers and primitives that support Aura components.
- [Client Only](/docs/utils/client-only): Renders children only after the client has mounted.
- [Direction](/docs/utils/direction): Sets reading direction for a subtree and Radix primitives.
- [Hitbox](/docs/utils/hitbox): Expands the hit area around a control without changing its look.
- [Pending](/docs/utils/pending): Marks content as busy and shows a spinner while work is in progress.
- [Portal](/docs/utils/portal): Renders children into another element.
- [Presence](/docs/utils/presence): Keeps content mounted while it fades out.
- [Visually Hidden Input](/docs/utils/visually-hidden-input): A visually hidden input that mirrors a control for form submission.
- [Visually Hidden](/docs/utils/visually-hidden): Hides text visually while keeping it available to assistive tech.

- **Forms**
- [Forms Overview](/docs/forms): Declarative form state, validation, and UI with useFormDynamic and Form components.
- [useFormDynamic](/docs/forms/use-dynamic-form): API reference for the form state hook — parameters, return value, and FieldProps.
- [Form Components](/docs/forms/form-components): Form root, FormSubmit, FormAlert, and field wrappers — FormField, FormSwitch, FormCheckbox, and groups.
- [Form Field Composition](/docs/forms/form-field-composition): FormFieldSelect, FormFieldCombobox, FormFieldEditor, FormFieldSignaturePad, FormFieldSortableList — composed form fields that use field.setValue.
- [Validation](/docs/forms/validation): validateFormData, error shape, touch behavior, and form-level errors.