# ATOM63 Design System > Design system, architecture, and product decision notes behind ATOM63 — a personal monorepo for portfolio, docs, OS63, and teaching surfaces. ## Architecture - [Design system home](/index.md): ATOM63 is the working system behind my portfolio, OS63, these docs, and the tools I use to teach and experiment. It turns design decisions into shared code without forcing every product into the same - [Overview](/architecture.md): Atom63 is a design-system architecture for product-grade personal software. It is built around a simple promise: the same decisions should be legible to code, docs, humans, and agents. - [Layers](/architecture/architecture-layers.md): The system scales by separating values, contracts, renderers, content, and products. Each layer has a different stability level, so promotion is a design decision as much as a code decision. - [Package map](/architecture/architecture-package-map.md): Use this map to choose a public entry point. For value ownership, use `docs/design-system/authoring-surfaces.md`; for the complete export reference, use root `USAGE.md`. - [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. - [Agent instructions](/architecture/architecture-agent-instructions.md): Use this page with the repo handbook to locate the owning package and required validation before changing shared UI. Inspect the source contract rather than guessing when ownership is unclear. - [Workflow](/architecture/architecture-workflow.md): The system grows through a simple loop: build locally, prove the pattern, promote only when it has earned a shared home, then document the current implementation. - [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 - [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 - [Overview](/foundations/brand-overview.md): `@atom63/brand` owns the shared React logo assets and the brand/endpoint SEO data used by first-party apps. Color, typography, motion, and component styling remain in `@atom63/styles` and the UI packa - [Logo](/foundations/brand-logo.md): The primary lockup system has two primitives: a **symbol** (100 × 100 viewBox) and a **wordmark** (280 × 40 viewBox). `AppLogo` assembles them into four layout variants with proportional sizing baked - [Guidelines](/foundations/brand-guidelines.md): Use these logo variants, clear-space rules, and contrast constraints to place the ATOM63 identity without distorting its proportions or weakening legibility. This page covers visual use; implementatio - [Seo](/foundations/brand-seo.md): Every ATOM63 endpoint shares the same runtime brand metadata — author, keywords, structured data, and social cards — but each surface has its own name, description, and purpose. `@atom63/brand/seo` is ## 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. - [Overview](/components/craft-overview.md): The difference between "works" and "feels right" is usually three or four decisions that nobody notices. These case studies break down those decisions — what was wrong, what I changed, and why it matt - [Connected panel](/components/craft-connected-panel.md): Three iterations to get a collapsible panel from "works" to "feels right." Each step solves one problem and reveals the next. ## 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 overview](/patterns/pattern-inform-overview.md): Four surfaces carry every message ATOM63 shows a visitor: a **banner**, a **dialog**, a **corner flyout**, and a **spotlight**. They share one message model, one arbiter, and one dismissal contract, s - [Inform surfaces](/patterns/pattern-inform-surfaces.md): Every surface is **controlled**. It takes what it should render and reports intent upward through `onDismiss`; it never decides on its own whether it should be visible. The runtime is one consumer of - [Inform runtime](/patterns/pattern-inform-runtime.md): The runtime answers one question: **given everything the registry declares, what should each surface show right now?** - [Overview](/patterns/mdx-overview.md): `@atom63/mdx` is the shared React rendering layer for prose, content blocks, lightboxes, and article layout. Its providers do not discover files, define routes, or choose frontmatter fields. The host - [Authoring guide](/patterns/mdx-authoring-guide.md): Write normal Markdown first. Add a block when the content has a distinct meaning, and add a primitive only when the article needs an intentional layout change. - [Prose](/patterns/mdx-prose.md): The provider map gives ordinary Markdown the shared type scale, spacing, links, tables, code treatment, and media behavior. The `docs` variant used here is denser than the `narrow` article variant, bu - [Blocks](/patterns/mdx-blocks.md): Blocks give repeated content structures a stable meaning. Choose them by reader intent; their chrome and responsive behavior follow from that choice. - [Primitives](/patterns/mdx-primitives.md): The `@atom63/mdx/primitives` entry is a public but experimental authoring surface. It names editorial layout and motion decisions that otherwise become one-off utility wrappers. Use it when the articl ## Products - [Overview](/products.md): Use this section to trace how Cipher, Atom63, and OS63 consume shared packages while retaining product-owned behavior, content, and deployment boundaries. - [Scale](/products/product-scale.md): Product-scale guidance defines what stays inside each app, what earns promotion into a shared package, and how each deployable surface builds independently. - [Cipher](/products/product-cipher.md): Cipher by Atom63 is a standalone Figma plugin for creating, importing, managing, and exporting design-system variables and styles. It lives in the monorepo because its portable token and component con - [Cipher token workflow](/products/product-cipher-token-workflow.md): This is a one-way Atom63 artifact pipeline inside the Cipher product boundary. Atom63 keeps code authoritative; the current plugin does not yet expose the generated preset as a selectable user workflo - [Overview](/products/folio-overview.md): Atom63 is the public portfolio product. It owns presentation, content, external integrations, and the visitor journey. Shared packages support that experience, but product-specific behavior stays insi - [Overview](/products/sys63-overview.md): OS63 is Atom63's standalone OS-inspired product. The portfolio no longer embeds an OS implementation: Atom63's `/sys63` and `/sys63-os63` deployment paths redirect to `https://os.atom63.io/`. - [Appearance](/products/sys63-appearance.md): OS63 treats personalization as a product surface while reusing the design-system appearance contract. Product state is adapted into `PersonalizationState`; `applyPersonalization` resolves it to `data- - [Windowing](/products/sys63-windowing.md): Windowing is the core reusable interaction model in `@atom63/os63`. It coordinates lifecycle, focus, geometry, drag, resize, snapping, fullscreen, persistence, and overview without making the window s - [Apps](/products/sys63-apps.md): Every OS63 window is launched from an `AppDefinition`: metadata and a React component joined at the app boundary. The shared window manager owns chrome and geometry; the app owns its content and produ - [Widgets](/products/sys63-widgets.md): Widgets share a three-size view contract across Atom63 and OS63, but hosting stays product-owned. A shared view can render on the Atom63 home page, in either product's agent, or on the OS63 desktop wi - [Icons](/products/sys63-icons.md): OS63 uses the shared icon registry for actions, status, and window chrome, while the app-asset catalog identifies launchable applications and changes with the selected icon appearance mode. - [Wallpaper](/products/sys63-wallpaper.md): Wallpaper is OS63 product state backed by shared theme assets. The package owns catalog metadata and path resolution; the app owns selection, filters, shuffle timers, persistence, loading, transition, - [Agent](/products/sys63-agent.md): Agent Chat is a first-party OS63 app assembled from generic chat infrastructure and portfolio-specific context. The shared agent package does not own You Zhang's facts, and the OS app does not own the