# DESIGN.md — Arbor Design System

> Visual system context for Arbor, generated from the component registry.
> Companion: https://arbor.linktr.ee/PRODUCT.md (strategy). Follows the design.md format spec.

## Theme

Arbor is token-driven with Light and Dark themes as a semantic swap (never a primitive
inversion). Author against semantic and component tokens, never raw hex.

## Color, typography, spacing, shape (token source of truth)

Do not hardcode values — use Arbor tokens. The canonical compiled values live at:

- All tokens (compiled CSS custom properties): `https://arbor.linktr.ee/r/arbor-tokens.json`
- Tailwind mapping: `https://arbor.linktr.ee/r/arbor-tailwind-preset.json`
- Full component reference: `https://arbor.linktr.ee/llms-full.txt`

Typography is role-based (title / body / detail via `text-*` utilities), a tight ~1.2
scale ratio, fixed rem steps. Spacing is a 4px-base widening scale. Shape uses `rounded-*`
tokens — Arbor overrides Tailwind's defaults (e.g. `rounded-lg` = 24px), so trust the
token, not the class name's usual meaning.

## Components (50)

Prefer these over building new UI. Each is production-ready with full state coverage:

- **Icons** — `npx shadcn@latest add @arbor/icons`
- **Button** — `npx shadcn@latest add @arbor/button`
- **Button Group** — `npx shadcn@latest add @arbor/button-group`
- **Link** — `npx shadcn@latest add @arbor/link`
- **Text** — `npx shadcn@latest add @arbor/text`
- **sanitizeHref Utility** — `npx shadcn@latest add @arbor/sanitize-href`
- **cn Utility** — `npx shadcn@latest add @arbor/cn`
- **Elevation** — `npx shadcn@latest add @arbor/elevation`
- **Icon Button** — `npx shadcn@latest add @arbor/icon-button`
- **Icon List** — `npx shadcn@latest add @arbor/icon-list`
- **Tabs** — `npx shadcn@latest add @arbor/tabs`
- **Segmented Control** — `npx shadcn@latest add @arbor/segmented-control`
- **Header Bar** — `npx shadcn@latest add @arbor/header-bar`
- **Field** — `npx shadcn@latest add @arbor/field`
- **File Input** — `npx shadcn@latest add @arbor/file-input`
- **File Input Item** — `npx shadcn@latest add @arbor/file-input-item`
- **Skeleton** — `npx shadcn@latest add @arbor/skeleton`
- **useMediaQuery** — `npx shadcn@latest add @arbor/use-media-query`
- **Alert Dialog** — `npx shadcn@latest add @arbor/alert-dialog`
- **Dialog** — `npx shadcn@latest add @arbor/dialog`
- **AdaptiveModal** — `npx shadcn@latest add @arbor/adaptive-modal`
- **Radio** — `npx shadcn@latest add @arbor/radio`
- **Radio Group (deprecated alias)** — `npx shadcn@latest add @arbor/radio-group`
- **Checkbox** — `npx shadcn@latest add @arbor/checkbox`
- **Collapsible** — `npx shadcn@latest add @arbor/collapsible`
- **Popover** — `npx shadcn@latest add @arbor/popover`
- **RichTooltip** — `npx shadcn@latest add @arbor/rich-tooltip`
- **Tooltip** — `npx shadcn@latest add @arbor/tooltip`
- **Select** — `npx shadcn@latest add @arbor/select`
- **Badge** — `npx shadcn@latest add @arbor/badge`
- **Indicator Badge** — `npx shadcn@latest add @arbor/indicator-badge`
- **Chip** — `npx shadcn@latest add @arbor/chip`
- **Combobox** — `npx shadcn@latest add @arbor/combobox`
- **Search Bar** — `npx shadcn@latest add @arbor/search-bar`
- **Divider** — `npx shadcn@latest add @arbor/divider`
- **Backdrop** — `npx shadcn@latest add @arbor/backdrop`
- **Switch** — `npx shadcn@latest add @arbor/switch`
- **Toggle** — `npx shadcn@latest add @arbor/toggle`
- **Menu** — `npx shadcn@latest add @arbor/menu`
- **Avatar** — `npx shadcn@latest add @arbor/avatar`
- **Alert** — `npx shadcn@latest add @arbor/alert`
- **Toast** — `npx shadcn@latest add @arbor/toast`
- **NativeSelect** — `npx shadcn@latest add @arbor/native-select`
- **AppIcon** — `npx shadcn@latest add @arbor/app-icon`
- **Fieldset** — `npx shadcn@latest add @arbor/fieldset`
- **One-Time Password Field** — `npx shadcn@latest add @arbor/one-time-password-field`
- **Sidebar** — `npx shadcn@latest add @arbor/sidebar`
- **ProgressBar** — `npx shadcn@latest add @arbor/progress-bar`
- **ColorSwatch** — `npx shadcn@latest add @arbor/color-swatch`
- **ColorField** — `npx shadcn@latest add @arbor/color-field`

## Rules

- Check this component list before inventing UI.
- Every interactive element: default / hover / focus / active / disabled / loading / error.
- Skeletons for loading, not center-screen spinners.
- Empty states teach the interface.
- Modal is a last resort — exhaust inline / progressive disclosure first.