# ATOM63 Design System

> Atom63 Design System — one token architecture rendered in React, SwiftUI, and Figma: tokens, themes, component contracts, and components.

## Architecture

- [Design system home](/index.md): Atom63 is an open-source design system with one token architecture behind every platform it ships to. The same tokens drive the React components, the SwiftUI components, and the Figma variables, so a 
- [Overview](/architecture.md): Atom63 keeps one token architecture and renders it on every platform it supports. The same decisions should be legible to code, docs, design files, humans, and agents.
- [Appearance ui](/architecture/architecture-appearance-ui.md): Appearance UI lives in `@atom63/ui-react/theme`. Apps choose the host surface, storage integration, and active sections; the controls, controller shape, and attribute application are shared.
- [Changelog](/architecture/architecture-changelog.md): Atom63 uses Changesets as the release source of truth. Pending changesets appear under Unreleased; released versions come from each package's generated `CHANGELOG.md`.

## Foundations

- [Designing in code](/foundations.md): `--a63-*` is the hardened contract. Tailwind/shadcn names are the design surface. I keep both on purpose — and I design against the familiar names first.
- [Personalization](/foundations/foundation-personalization.md): Personalization is not a theme picker bolted onto the UI. It is the shape of the foundation: independent axes stamped as `data-a63-*` attributes (plus one scalar tint token), resolving through one sem
- [Craft rubric](/foundations/foundation-craft-rubric.md): Checks catch a literal color or a missing name. They do not catch a screen whose gaps are all legal tokens but have no rhythm, or a dialog with three primary buttons. This rubric writes that part of t
- [Colors](/foundations/foundation-colors.md): The color system is built around executable indirection. **Foundation** owns the literal palette (`tokens/foundation/*`). **Semantics** (`--a63-*`) name UI jobs. **App JSX** may sketch with Tailwind/s
- [Surface model](/foundations/foundation-surface-model.md): Surfaces are the system's spatial grammar. They decide what feels like the page, what feels like a contained object, and what feels temporarily elevated above the rest of the interface.
- [Typography](/foundations/foundation-typography.md): The type system targets dense information interfaces rather than marketing pages. Body text starts at 15px—between compact 14px UI conventions and the browser's 16px default—to balance information den
- [Radius](/foundations/foundation-radius.md): Corner radius is one of the strongest contributors to a system's visual identity, so I made it anchored and proportional rather than a bag of arbitrary values. Every radius in the system derives from 
- [Effects](/foundations/foundation-effects.md): Shadows and blurs define depth in the system. I use them sparingly — most surfaces are flat with border separation. Shadows appear when something genuinely floats: dropdowns, dialogs, popovers, and th
- [Z-index](/foundations/foundation-z-index.md): Stacking across windows and shell surfaces comes from one ordered scale of `--z-layer-*` tokens. Small numeric z-index values still exist inside isolated component stacking contexts; the shared scale 
- [Motion](/foundations/foundation-motion.md): Motion in this system is feedback, not decoration. Every animation exists to confirm an action, show a spatial relationship, or guide attention. If removing an animation doesn't make the interface har
- [Interaction states](/foundations/foundation-interaction-states.md): Interaction states are the system's feedback contract. A component should make every state it supports visible without inventing a new visual language. Not every component exposes every state: loading

## Themes

- [Overview](/themes.md): Atom63 themes are CSS skins over one semantic system. They change material character without changing component anatomy, behavior, or product structure.
- [System](/themes/theme-system.md): Theme authoring is a cascade problem: establish stable semantic and family contracts, then let one scoped skin assign material values. The difficult part is preserving that boundary as axes and produc

## Components

- [Overview](/components.md): Components turn repeated interaction decisions into typed behavior, semantic structure, and theme-aware material without importing product assumptions. This catalog follows every `src/components/*` fa
- [Contract](/components/component-contract.md): Shared component families in `@atom63/ui-react` combine platform-neutral vocabulary from `@atom63/ui-foundation` with executable recipe CSS backed by `@atom63/styles`.
- [Button](/components/component-button.md): Button is the reference action primitive for the current system: typed variants from `@atom63/ui-foundation`, Base UI-compatible rendering in `@atom63/ui-react`, and material values from the `control`
- [Button group](/components/component-button-group.md): Button Group turns adjacent controls into one welded segment. It is not a row with smaller gaps; it is a composition contract for shared edges, seams, radius, and selected state.
- [Copy button](/components/component-copy-button.md): Copy Button owns clipboard feedback and the temporary copied state for one value.
- [Destination link](/components/component-destination-link.md): Destination Link distinguishes internal navigation from safe external navigation.
- [Autocomplete](/components/component-autocomplete.md): Autocomplete combines text entry with a filtered, keyboard-navigable collection.
- [Calendar](/components/component-calendar.md): Calendar provides themed single, range, and multi-date selection through React DayPicker.
- [Checkbox](/components/component-checkbox.md): Checkbox captures an independent checked, unchecked, or indeterminate choice.
- [Field](/components/component-field.md): Field composes labels, descriptions, errors, and controls into consistent form structure.
- [Form](/components/component-form.md): Form connects React Hook Form state to shared labels, controls, descriptions, and messages.
- [Input](/components/component-input.md): Input is the field archetype in React form: a readable editing surface with consistent border, focus, invalid, disabled, icon, and placeholder treatment.
- [Input otp](/components/component-input-otp.md): Input OTP composes accessible one-time-code slots over the input-otp primitive.
- [Label](/components/component-label.md): Label provides the styled native labeling primitive for form controls.
- [Panel setting button](/components/component-panel-setting-button.md): Panel Setting Button is an icon-and-label pressed control for visual settings choices.
- [Radio](/components/component-radio.md): Radio provides single-choice items and a coordinated radio group.
- [Segmented control](/components/component-segmented-control.md): Segmented Control is a compact choice surface with one active value. It shares the segment archetype with Toggle Group and Button Group, but keeps its own moving indicator behavior.
- [Search field](/components/component-search-field.md): Search Field provides a clearable search input with shared keyboard and form behavior.
- [Select](/components/component-select.md): Select constrains a field to values from a keyboard-navigable popup collection.
- [Slider](/components/component-slider.md): Slider captures a scalar or range value with pointer and keyboard interaction.
- [Switch](/components/component-switch.md): Switch changes one setting between immediate on and off states.
- [Textarea](/components/component-textarea.md): Textarea provides the shared multiline field with size, invalid, disabled, and unstyled states.
- [Toggle](/components/component-toggle.md): Toggle is a pressed control for one independently persistent option.
- [Toggle group](/components/component-toggle-group.md): Toggle Group coordinates single or multiple pressed controls on a shared track.
- [Breadcrumb](/components/component-breadcrumb.md): Breadcrumb exposes the current page within a navigable hierarchy.
- [Command](/components/component-command.md): Command provides a searchable command collection that can render inline or in a dialog.
- [Context menu](/components/component-context-menu.md): Context Menu exposes supplemental actions from right-click or long-press interaction.
- [Dropdown menu](/components/component-dropdown-menu.md): Dropdown Menu presents a trigger-bound list of immediate commands or persistent menu choices. Use Select for a form value, links for navigation, and Dialog or Popover when the content requires reading
- [Menubar](/components/component-menubar.md): Menubar coordinates persistent desktop-style menus and their keyboard relationships.
- [Navigation menu](/components/component-navigation-menu.md): Navigation Menu composes site links with optional positioned navigation panels.
- [Pagination](/components/component-pagination.md): Pagination provides a navigation landmark and consistent previous, next, and page links.
- [Sidebar](/components/component-sidebar.md): Sidebar provides responsive application-shell structure, state, rail, menus, and inset content.
- [Sidebar nav tree](/components/component-sidebar-nav-tree.md): Sidebar Nav Tree composes labelled navigation groups, links, sublists, and collapsible branches.
- [Tabs](/components/component-tabs.md): Tabs organize related panels without leaving the current task. The component owns orientation, keyboard behavior, indicator placement, and panel relationships; the theme owns the material values behin
- [Alert dialog](/components/component-alert-dialog.md): Alert Dialog interrupts a flow to confirm a consequential decision.
- [Dialog](/components/component-dialog.md): Dialog provides modal task structure, focus management, and responsive placement.
- [Drawer](/components/component-drawer.md): Drawer presents modal content from a viewport edge with drag-aware behavior.
- [Hover card](/components/component-hover-card.md): Hover Card reveals contextual preview content from a hover- or focusable trigger.
- [Popover](/components/component-popover.md): Popover anchors non-modal interactive content to a trigger or custom anchor.
- [Portal container](/components/component-portal-container.md): Portal Container supplies a shared mount target to package overlays.
- [Preview card](/components/component-preview-card.md): Preview Card presents a rich linked-resource preview from a hover- or focusable trigger.
- [Sheet](/components/component-sheet.md): Sheet presents modal content from a chosen viewport side using dialog focus behavior.
- [Tooltip](/components/component-tooltip.md): Tooltip supplies brief supplementary text for a hover- or focusable trigger.
- [Accordion](/components/component-accordion.md): Accordion coordinates a set of disclosure sections with shared keyboard behavior.
- [Alert](/components/component-alert.md): Alert presents persistent inline feedback with optional icon, action, and description.
- [Avatar](/components/component-avatar.md): Avatar composes an image, fallback, badge, and grouped identity presentation.
- [Badge](/components/component-badge.md): Badge carries compact status or classification metadata beside primary content.
- [Card](/components/component-card.md): Card composes media, metadata, actions, and content into a reusable surface.
- [Carousel](/components/component-carousel.md): Carousel coordinates an Embla viewport, slides, controls, and shared carousel state.
- [Collapsible](/components/component-collapsible.md): Collapsible controls one trigger and one region while preserving disclosure semantics.
- [Connected panel](/components/component-connected-panel.md): Connected Panel expands a trigger and its content as one continuous inline surface.
- [Empty](/components/component-empty.md): Empty provides composable structure for empty collections and unavailable content.
- [Feedback state](/components/component-feedback-state.md): Feedback State packages common empty, error, and no-results messages with actions.
- [Frame](/components/component-frame.md): Frame composes header, panel, description, and footer regions into a chrome-aware surface.
- [Item](/components/component-item.md): Item provides structured row regions for media, content, actions, and supporting detail.
- [Scroll area](/components/component-scroll-area.md): Scroll Area supplies themed scrollbars while preserving native scrolling behavior.
- [Scrollable list](/components/component-scrollable-list.md): Scrollable List adds edge masks and optional controls to overflowing row or column content.
- [Separator](/components/component-separator.md): Separator draws visual or semantic division in horizontal and vertical layouts.
- [Table](/components/component-table.md): Table provides semantic table regions with shared typography, spacing, and states.
- [Animated check](/components/component-animated-check.md): Animated Check is a decorative completion mark with a reduced-motion fallback.
- [Kbd](/components/component-kbd.md): Kbd presents keyboard input notation without implying an interactive control.
- [Load more trigger](/components/component-load-more-trigger.md): Load More Trigger is an observable sentinel row for incremental collection loading.
- [Marquee](/components/component-marquee.md): Marquee loops arbitrary content horizontally or vertically with pause and direction controls.
- [Progress](/components/component-progress.md): Progress composes labelled determinate or indeterminate task progress.
- [Progressive blur](/components/component-progressive-blur.md): Progressive Blur ramps stacked backdrop blur across a band so text can sit over imagery.
- [Resizable](/components/component-resizable.md): Resizable composes keyboard-operable panel groups, panels, and drag handles.
- [Skeleton](/components/component-skeleton.md): Skeleton reserves content geometry while a known layout is loading.
- [Spinner](/components/component-spinner.md): Spinner announces an indeterminate loading state and stops motion when requested.
- [Text ticker](/components/component-text-ticker.md): Text Ticker truncates text and can reveal overflow with a measured marquee.
- [Toaster](/components/component-toaster.md): Toaster is the app-level host for transient messages raised through the exported toast API.

## Patterns

- [Page layout](/patterns.md): `Page`, `Container`, and `Section` separate three decisions that otherwise drift together: the document landmark, the content frame, and the rhythm between page regions. They are composable defaults, 
- [Section header](/patterns/pattern-section-header.md): `SectionHeader` keeps visual hierarchy and document hierarchy separate. `variant` selects the type treatment; `level` selects the rendered heading element.
- [Local layout](/patterns/pattern-local-layout.md): Page primitives own route measure and section rhythm. Local layout owns the relationship between children inside a toolbar, form, card body, list item, or collection.
- [Inform](/patterns/pattern-inform.md): const [open, setOpen] = useState(false) return ( Open the dialog ) }
- [Agent runtime](/patterns/pattern-agent.md): 'This reply comes from a fake transport. It streams one word at a time as text-delta events, and the runtime appends each one to the assistant message.'
- [Widgets](/patterns/pattern-widgets.md): return ( {children} ) }
- [Templates](/patterns/pattern-templates.md): Templates are known-good starting points above the component level: whole pages and the blocks they are made of. Each one is built only from Atom63 components and tokens, and each is held to the same