# Arbor Design System

> Install production-ready React components with one command. Built with TypeScript, Tailwind CSS, and Radix UI. Source files land directly in your project — no runtime dependency or lock-in.

## Prerequisites

- Node.js >= 20 (required by shadcn CLI)
- A React 18+ project with Tailwind CSS v3.4+

## Quick Setup (3 steps)

### Step 1: Register the Arbor registry

If no `components.json` exists, first run `npx shadcn@latest init`.

Then add the `@arbor` registry to your `components.json`:

```json
{
  "registries": {
    "@arbor": "https://arbor.linktr.ee/r/{name}.json"
  }
}
```

### Step 2: Install Arbor

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

This single command installs everything you need:
- **Design tokens** — CSS custom properties for colors, spacing, shapes, typography, and themes
- **Tailwind preset** — maps all tokens to Tailwind utility classes
- **cn utility** — Tailwind class merging configured for Arbor's custom tokens

After installation, complete these two wiring steps:

1. **Import the CSS** in your root layout or entry file:
```tsx
import '@/styles/arbor.css'
```

2. **Add the Tailwind preset** to your `tailwind.config.ts` (or `.js`):
```ts
import arborPreset from './config/arbor-tailwind-preset'

export default {
  presets: [arborPreset],
  content: ['./src/**/*.{ts,tsx}'],
}
```

### Step 3: Add components

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

All component dependencies are resolved automatically.

## Troubleshooting

- **Node < 20**: Upgrade via nvm (`nvm install 22`)
- **Yarn workspace errors**: Run `yarn add -W clsx tailwind-merge` first, then retry
- **shadcn not initialized**: Run `npx shadcn@latest init` before adding the registry
- **npx hangs or fails**: See "Fallback: Manual Install" below

## Fallback: Manual Install (no shadcn CLI)

If `npx shadcn` is unavailable or fails, install manually:

1. Fetch the component JSON: `curl https://arbor.linktr.ee/r/button.json`
2. Copy each file's `content` to the corresponding `path` in your project
3. Install the listed `dependencies` with your package manager
4. Repeat for each item in `registryDependencies`

For setup without the CLI, install these three items first:
- `https://arbor.linktr.ee/r/arbor-tokens.json` (CSS custom properties)
- `https://arbor.linktr.ee/r/arbor-tailwind-preset.json` (Tailwind config)
- `https://arbor.linktr.ee/r/cn.json` (class merging utility)

## MCP Integration (optional)

For AI assistants with MCP support, add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "shadcn@latest", "mcp"]
    }
  }
}
```

## Components

- [Icons](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](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](https://arbor.linktr.ee/r/fieldset.json): Semantic grouping for form controls. Wraps radio, checkbox, and other primitives with a legend and description.

## API

- [Registry Manifest](https://arbor.linktr.ee/manifest.json): Full registry manifest with all component metadata
- [Component JSON](https://arbor.linktr.ee/r/{name}.json): Individual component definition (replace {name} with component name)
- [Health Check](https://arbor.linktr.ee/health): Service health status