# Arbor Design System — Full Component Reference

> Arbor is Linktree's design system. This document contains the complete reference for all 36 components.

## Quick Setup

Register the `@arbor` registry in `components.json`, then run:

```bash
npx shadcn@latest add @arbor/setup
```

This installs design tokens, Tailwind preset, and the cn utility. Then:
1. Import `@/styles/arbor.css` in your root layout
2. Add the preset to `tailwind.config`: `import arborPreset from './config/arbor-tailwind-preset'` then `presets: [arborPreset]`

See `https://arbor.linktr.ee/llms.txt` for detailed setup instructions.

## Quick Reference

| Component | Install Command | Category |
|-----------|----------------|----------|
| Icons | `npx shadcn@latest add @arbor/icons` | icons |
| Button | `npx shadcn@latest add @arbor/button` | button |
| Link | `npx shadcn@latest add @arbor/link` | navigation |
| Text | `npx shadcn@latest add @arbor/text` | typography |
| sanitizeHref Utility | `npx shadcn@latest add @arbor/sanitize-href` | utility |
| cn Utility | `npx shadcn@latest add @arbor/cn` | utility |
| Elevation | `npx shadcn@latest add @arbor/elevation` | utility |
| Icon Button | `npx shadcn@latest add @arbor/icon-button` | button |
| Tabs | `npx shadcn@latest add @arbor/tabs` | navigation |
| Header Bar | `npx shadcn@latest add @arbor/header-bar` | layout |
| Actions | `npx shadcn@latest add @arbor/actions` | layout |
| Field | `npx shadcn@latest add @arbor/field` | form |
| Skeleton | `npx shadcn@latest add @arbor/skeleton` | feedback |
| useMediaQuery | `npx shadcn@latest add @arbor/use-media-query` | utility |
| Alert Dialog | `npx shadcn@latest add @arbor/alert-dialog` | overlay |
| Dialog | `npx shadcn@latest add @arbor/dialog` | overlay |
| Drawer | `npx shadcn@latest add @arbor/drawer` | overlay |
| AdaptiveModal | `npx shadcn@latest add @arbor/adaptive-modal` | overlay |
| Radio Group | `npx shadcn@latest add @arbor/radio-group` | form |
| Checkbox | `npx shadcn@latest add @arbor/checkbox` | form |
| Collapsible | `npx shadcn@latest add @arbor/collapsible` | layout |
| Popover | `npx shadcn@latest add @arbor/popover` | overlay |
| RichTooltip | `npx shadcn@latest add @arbor/rich-tooltip` | overlay |
| Tooltip | `npx shadcn@latest add @arbor/tooltip` | overlay |
| Select | `npx shadcn@latest add @arbor/select` | form |
| Badge | `npx shadcn@latest add @arbor/badge` | badge |
| Divider | `npx shadcn@latest add @arbor/divider` | layout |
| Backdrop | `npx shadcn@latest add @arbor/backdrop` | overlay |
| Switch | `npx shadcn@latest add @arbor/switch` | form |
| Dropdown Menu | `npx shadcn@latest add @arbor/dropdown-menu` | overlay |
| Avatar | `npx shadcn@latest add @arbor/avatar` | data-display |
| Alert | `npx shadcn@latest add @arbor/alert` | feedback |
| Toast | `npx shadcn@latest add @arbor/toast` | feedback |
| NativeSelect | `npx shadcn@latest add @arbor/native-select` | form |
| AppIcon | `npx shadcn@latest add @arbor/app-icon` | icons |
| Fieldset | `npx shadcn@latest add @arbor/fieldset` | form |

## Components

### Icons

- **Install:** `npx shadcn@latest add @arbor/icons`
- **Type:** registry:ui
- **Categories:** icons
- **Dependencies:** @phosphor-icons/react
- **Registry Dependencies:** none
- **Files:** @/components/icons/index.tsx
- **JSON:** https://arbor.linktr.ee/r/icons.json

Full re-export of @phosphor-icons/react. Every icon is available under bare and Icon-suffixed names; all weights, sizes, and colors are supported.

### Button

- **Install:** `npx shadcn@latest add @arbor/button`
- **Type:** registry:ui
- **Categories:** button
- **Dependencies:** @radix-ui/react-slot, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/sanitize-href
- **Files:** @/components/Button/index.tsx, @/components/shared/VariantDefaultsContext.tsx, @/components/shared/types.ts
- **JSON:** https://arbor.linktr.ee/r/button.json

Action button built on Radix Slot with seven variants, five sizes, two shapes, an optional loading state, and start/end icon slots.

### Link

- **Install:** `npx shadcn@latest add @arbor/link`
- **Type:** registry:ui
- **Categories:** navigation
- **Dependencies:** @radix-ui/react-slot, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/sanitize-href
- **Files:** @/components/Link/index.tsx, @/components/shared/types.ts
- **JSON:** https://arbor.linktr.ee/r/link.json

Inline link with three sizes, four semantic color variants, underline controls, and safe external-URL handling. Composes via asChild.

### Text

- **Install:** `npx shadcn@latest add @arbor/text`
- **Type:** registry:ui
- **Categories:** typography
- **Dependencies:** @radix-ui/react-slot, class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Text/index.tsx, @/components/Text/types.ts
- **JSON:** https://arbor.linktr.ee/r/text.json

Typography component spanning Arbor's full type scale. Maps each variant to semantic HTML and composes via asChild for headings, links, and labels.

### sanitizeHref Utility

- **Install:** `npx shadcn@latest add @arbor/sanitize-href`
- **Type:** registry:lib
- **Categories:** utility
- **Dependencies:** none
- **Registry Dependencies:** none
- **Files:** @/utils/sanitizeHref.ts
- **JSON:** https://arbor.linktr.ee/r/sanitize-href.json

Strips dangerous URI protocols (javascript:, data:, vbscript:) from href values. Returns undefined for unsafe inputs.

### cn Utility

- **Install:** `npx shadcn@latest add @arbor/cn`
- **Type:** registry:lib
- **Categories:** utility
- **Dependencies:** clsx, tailwind-merge
- **Registry Dependencies:** none
- **Files:** @/utils/cn.ts
- **JSON:** https://arbor.linktr.ee/r/cn.json

Class merger extending tailwind-merge with Arbor's color, border, radius, shadow, spacing, height, and typography utilities.

### Elevation

- **Install:** `npx shadcn@latest add @arbor/elevation`
- **Type:** registry:ui
- **Categories:** utility
- **Dependencies:** @radix-ui/react-slot, class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Elevation/index.tsx
- **JSON:** https://arbor.linktr.ee/r/elevation.json

Shadow utility for Arbor elevation levels 100–400. Defaults to asChild composition so it adds no wrapper div.

### Icon Button

- **Install:** `npx shadcn@latest add @arbor/icon-button`
- **Type:** registry:ui
- **Categories:** button
- **Dependencies:** @radix-ui/react-slot, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/sanitize-href
- **Files:** @/components/IconButton/index.tsx, @/components/shared/VariantDefaultsContext.tsx, @/components/shared/types.ts
- **JSON:** https://arbor.linktr.ee/r/icon-button.json

Icon-only button with six variants, five sizes, and squircle or capsule shape. Requires aria-label for screen readers.

### Tabs

- **Install:** `npx shadcn@latest add @arbor/tabs`
- **Type:** registry:ui
- **Categories:** navigation
- **Dependencies:** @radix-ui/react-tabs, class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/text
- **Files:** @/components/Tabs/index.tsx
- **JSON:** https://arbor.linktr.ee/r/tabs.json

Tabbed navigation built on Radix UI with five variants (underline, pill, pill-subtle, segmented, segmented-pill) and three sizes.

### Header Bar

- **Install:** `npx shadcn@latest add @arbor/header-bar`
- **Type:** registry:ui
- **Categories:** layout, navigation
- **Dependencies:** @radix-ui/react-tabs, @radix-ui/react-slot, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/text, @arbor/button, @arbor/icon-button, @arbor/tabs
- **Files:** @/components/HeaderBar/index.tsx, @/components/HeaderBar/HeaderBarContext.tsx, @/components/HeaderBar/HeaderBarDeclarative.tsx, @/components/HeaderBar/HeaderBarLayouts.tsx, @/components/HeaderBar/HeaderBarActions.tsx, @/components/shared/VariantDefaultsContext.tsx, @/components/shared/types.ts
- **JSON:** https://arbor.linktr.ee/r/header-bar.json

Page header bar with title, actions, tabs, and a responsive primary/secondary variant. Supports a declarative context API and emits a headerbar:tab-change event for cross-MFE communication.

### Actions

- **Install:** `npx shadcn@latest add @arbor/actions`
- **Type:** registry:ui
- **Categories:** layout
- **Dependencies:** @radix-ui/react-toolbar, @radix-ui/react-slot, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/button, @arbor/icon-button, @arbor/divider
- **Files:** @/components/Actions/index.tsx
- **JSON:** https://arbor.linktr.ee/r/actions.json

Toolbar built on Radix Toolbar for grouping action buttons. Includes ActionsButton, ActionsIconButton, and ActionsDivider with toolbar variant defaults.

### Field

- **Install:** `npx shadcn@latest add @arbor/field`
- **Type:** registry:ui
- **Categories:** form
- **Dependencies:** @radix-ui/react-select, @radix-ui/react-slot, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Field/index.tsx, @/components/Field/context.tsx, @/components/Field/Root.tsx, @/components/Field/Control.tsx, @/components/Field/Label.tsx, @/components/Field/Input.tsx, @/components/Field/Textarea.tsx, @/components/Field/Addon.tsx, @/components/Field/Message.tsx, @/components/Field/Counter.tsx, @/components/Field/Select.tsx, @/components/Field/Action.tsx
- **JSON:** https://arbor.linktr.ee/r/field.json

Compound input system with floating labels, addons, actions, counters, file-input support, and three control variants (filled, outline, elevated) across two sizes.

### Skeleton

- **Install:** `npx shadcn@latest add @arbor/skeleton`
- **Type:** registry:ui
- **Categories:** feedback
- **Dependencies:** class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Skeleton/index.tsx
- **JSON:** https://arbor.linktr.ee/r/skeleton.json

Loading placeholder with pulse and shimmer animations. Includes Text, Avatar, Button, Input, Card, and ListItem preset compositions.

### useMediaQuery

- **Install:** `npx shadcn@latest add @arbor/use-media-query`
- **Type:** registry:hook
- **Categories:** utility
- **Dependencies:** none
- **Registry Dependencies:** none
- **Files:** @/hooks/useMediaQuery.ts
- **JSON:** https://arbor.linktr.ee/r/use-media-query.json

SSR-safe React hook tracking a CSS media query. Exports the BREAKPOINT_MD constant aligned with Tailwind's md: breakpoint.

### Alert Dialog

- **Install:** `npx shadcn@latest add @arbor/alert-dialog`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** @radix-ui/react-alert-dialog, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/backdrop, @arbor/button, @arbor/cn
- **Files:** @/components/AlertDialog/index.tsx, @/components/shared/overlayClasses.ts, @/components/shared/VariantDefaultsContext.tsx
- **JSON:** https://arbor.linktr.ee/r/alert-dialog.json

Binary-confirmation modal (Cancel/Delete, Cancel/OK, Leave/Stay). Enforces two-button footer with no close button. Built on @radix-ui/react-alert-dialog.

### Dialog

- **Install:** `npx shadcn@latest add @arbor/dialog`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** @radix-ui/react-dialog, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/backdrop, @arbor/cn
- **Files:** @/components/Dialog/index.tsx, @/components/shared/overlayClasses.ts, @/components/shared/VariantDefaultsContext.tsx
- **JSON:** https://arbor.linktr.ee/r/dialog.json

Modal dialog built on Radix UI for blocking interactions. Compound API covers trigger, portal, overlay, content, header, footer, title, description, and close.

### Drawer

- **Install:** `npx shadcn@latest add @arbor/drawer`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** vaul, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/backdrop
- **Files:** @/components/Drawer/index.tsx, @/components/shared/overlayClasses.ts, @/components/shared/VariantDefaultsContext.tsx
- **JSON:** https://arbor.linktr.ee/r/drawer.json

Bottom-sheet drawer built on Vaul. Supports four directions — floating card on bottom/top, edge-docked on left/right — and composes the Backdrop primitive for its overlay.

### AdaptiveModal

- **Install:** `npx shadcn@latest add @arbor/adaptive-modal`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** none
- **Registry Dependencies:** @arbor/use-media-query
- **Files:** @/components/AdaptiveModal/index.tsx
- **JSON:** https://arbor.linktr.ee/r/adaptive-modal.json

Renders a Drawer below the breakpoint and a Dialog at or above it. Only one branch mounts at a time; state stays external.

### Radio Group

- **Install:** `npx shadcn@latest add @arbor/radio-group`
- **Type:** registry:ui
- **Categories:** form
- **Dependencies:** @radix-ui/react-radio-group, class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/text
- **Files:** @/components/RadioGroup/index.tsx
- **JSON:** https://arbor.linktr.ee/r/radio-group.json

Radio selection built on Radix UI with four variants (compact, pill, squircle, card) for inline or full-width layouts.

### Checkbox

- **Install:** `npx shadcn@latest add @arbor/checkbox`
- **Type:** registry:ui
- **Categories:** form
- **Dependencies:** @radix-ui/react-checkbox, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Checkbox/index.tsx
- **JSON:** https://arbor.linktr.ee/r/checkbox.json

Checkbox built on Radix UI with checked, unchecked, and indeterminate states. Theme-aware inverse fill and a press-scale animation.

### Collapsible

- **Install:** `npx shadcn@latest add @arbor/collapsible`
- **Type:** registry:ui
- **Categories:** layout
- **Dependencies:** @radix-ui/react-collapsible, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Collapsible/index.tsx
- **JSON:** https://arbor.linktr.ee/r/collapsible.json

Animated show/hide region built on Radix UI. Supports controlled and uncontrolled modes; honors prefers-reduced-motion.

### Popover

- **Install:** `npx shadcn@latest add @arbor/popover`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** @radix-ui/react-popover, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Popover/index.tsx
- **JSON:** https://arbor.linktr.ee/r/popover.json

Floating content surface built on Radix UI with default and inverse variants, configurable side and align, and portal rendering.

### RichTooltip

- **Install:** `npx shadcn@latest add @arbor/rich-tooltip`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** @radix-ui/react-popover, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/RichTooltip/index.tsx
- **JSON:** https://arbor.linktr.ee/r/rich-tooltip.json

Click-triggered, content-rich tooltip built on Radix Popover (not Tooltip). Use for onboarding nudges and contextual education; theme-aware inverse styling.

### Tooltip

- **Install:** `npx shadcn@latest add @arbor/tooltip`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** @radix-ui/react-tooltip, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Tooltip/index.tsx
- **JSON:** https://arbor.linktr.ee/r/tooltip.json

Hover-triggered label built on Radix UI with inverse styling, configurable positioning, and prefers-reduced-motion support.

### Select

- **Install:** `npx shadcn@latest add @arbor/select`
- **Type:** registry:ui
- **Categories:** form
- **Dependencies:** @radix-ui/react-select, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Select/index.tsx, @/components/shared/menuClasses.ts
- **JSON:** https://arbor.linktr.ee/r/select.json

Dropdown select built on Radix UI with outline and filled triggers across three sizes. Integrates with Field for form usage.

### Badge

- **Install:** `npx shadcn@latest add @arbor/badge`
- **Type:** registry:ui
- **Categories:** badge
- **Dependencies:** class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Badge/index.tsx
- **JSON:** https://arbor.linktr.ee/r/badge.json

Inline label for status, metadata, and classification. Composes Status, Plan, and Notification specialized badges across eight semantic variants.

### Divider

- **Install:** `npx shadcn@latest add @arbor/divider`
- **Type:** registry:ui
- **Categories:** layout
- **Dependencies:** @radix-ui/react-separator, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Divider/index.tsx
- **JSON:** https://arbor.linktr.ee/r/divider.json

Visual separator built on Radix Separator with horizontal or vertical orientation and an optional inline label (e.g. "or").

### Backdrop

- **Install:** `npx shadcn@latest add @arbor/backdrop`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Backdrop/index.tsx
- **JSON:** https://arbor.linktr.ee/r/backdrop.json

Translucent scrim that dims UI behind a modal, sheet, or drawer. Composes with Radix overlay primitives via asChild.

### Switch

- **Install:** `npx shadcn@latest add @arbor/switch`
- **Type:** registry:ui
- **Categories:** form
- **Dependencies:** @radix-ui/react-switch, class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Switch/index.tsx
- **JSON:** https://arbor.linktr.ee/r/switch.json

Toggle switch built on Radix UI with three sizes, an optional inline label, and animated track-and-thumb.

### Dropdown Menu

- **Install:** `npx shadcn@latest add @arbor/dropdown-menu`
- **Type:** registry:ui
- **Categories:** overlay
- **Dependencies:** @radix-ui/react-dropdown-menu, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/DropdownMenu/index.tsx, @/components/shared/menuClasses.ts
- **JSON:** https://arbor.linktr.ee/r/dropdown-menu.json

Dropdown menu built on Radix UI with checkbox items, radio groups, submenus, keyboard shortcuts, and inset alignment.

### Avatar

- **Install:** `npx shadcn@latest add @arbor/avatar`
- **Type:** registry:ui
- **Categories:** data-display
- **Dependencies:** @radix-ui/react-avatar, class-variance-authority, @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Avatar/index.tsx
- **JSON:** https://arbor.linktr.ee/r/avatar.json

User avatar with image, fallback, badge, and overflow-group composition. Five sizes and three shapes (circle, squircle, square).

### Alert

- **Install:** `npx shadcn@latest add @arbor/alert`
- **Type:** registry:ui
- **Categories:** feedback
- **Dependencies:** @phosphor-icons/react, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/icon-button, @arbor/text
- **Files:** @/components/Alert/index.tsx, @/components/Alert/constants.tsx, @/components/Alert/types.ts
- **JSON:** https://arbor.linktr.ee/r/alert.json

Inline status message with five statuses (info, success, warning, error, neutral), primary or secondary visual variants, and an optional dismiss action.

### Toast

- **Install:** `npx shadcn@latest add @arbor/toast`
- **Type:** registry:ui
- **Categories:** feedback
- **Dependencies:** sonner, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/actions, @arbor/cn
- **Files:** @/components/Toast/index.tsx, @/components/Toast/ToastListener.tsx
- **JSON:** https://arbor.linktr.ee/r/toast.json

Notification toast built on Sonner with default and inverse surfaces, optional icon, action button, and stacked chin decoration.

### NativeSelect

- **Install:** `npx shadcn@latest add @arbor/native-select`
- **Type:** registry:ui
- **Categories:** form
- **Dependencies:** @phosphor-icons/react, class-variance-authority, clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn, @arbor/field
- **Files:** @/components/NativeSelect/index.tsx
- **JSON:** https://arbor.linktr.ee/r/native-select.json

Native HTML select styled with Arbor design tokens. Use when platform select behaviour is preferred over a custom dropdown.

### AppIcon

- **Install:** `npx shadcn@latest add @arbor/app-icon`
- **Type:** registry:ui
- **Categories:** icons
- **Dependencies:** clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/AppIcon/index.tsx
- **JSON:** https://arbor.linktr.ee/r/app-icon.json

Typed component for 244 third-party service logos synced from Figma. Five sizes (20, 24, 28, 40, 48px) and three variants (color, mono, outline).

### Fieldset

- **Install:** `npx shadcn@latest add @arbor/fieldset`
- **Type:** registry:ui
- **Categories:** form
- **Dependencies:** clsx, tailwind-merge
- **Registry Dependencies:** @arbor/cn
- **Files:** @/components/Fieldset/index.tsx
- **JSON:** https://arbor.linktr.ee/r/fieldset.json

Semantic grouping for form controls. Wraps radio, checkbox, and other primitives with a legend and description.

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /manifest.json` | Full registry manifest with all component metadata |
| `GET /r/{name}.json` | Individual component definition with source code |
| `GET /r/setup.json` | One-command setup (tokens + preset + cn) |
| `GET /health` | Service health status |
| `GET /llms.txt` | LLM-optimized setup guide |