# Shavin Design System (@shavin/ui)

> Enterprise-grade React design system delivering a strict two-tier token architecture, WCAG 2.1 AAA accessible primitives, 24 accent colors, live theme configurator, visual block builder, and zero-hallucination Model Context Protocol (MCP) AI server integration.

## System Overview & Mental Model
- **Package**: `@shavin/ui`
- **Import Rule**: ALWAYS import from root `@shavin/ui`. NEVER deep import (e.g. `@shavin/ui/primitives/...` is strictly forbidden).
- **Two-Tier Tokens**: Foundation scale (`--n-0` through `--n-1000`) is mapped to semantic tokens (`--bg-canvas`, `--bg-surface`, `--fg`, `--border-hairline`, `--accent`).
- **Zero Hex/RGB**: Never use hardcoded hex codes, `rgb()`, or `--n-*` variables in markup. Use semantic Tailwind utilities exclusively (`bg-surface`, `text-fg`, `border-hairline`).
- **Concentric Radius Law**:
  - Controls (buttons, inputs, badges, switches): `rounded-[var(--radius-lg)]` (pill-shaped at Full preset).
  - Containers & Panels (cards, dialogs, popovers, menus): `rounded-[var(--radius-panel)]` (intentionally capped at finite curve, never pill).
  - Concentric Nesting: $R_{\text{inner}} = \max(0, R_{\text{outer}} - P)$ using Tailwind utilities `rounded-panel-p3`, `rounded-panel-p5`, `rounded-panel-inner`.
- **Typography Hierarchy**: Pair title `text-fg` with `text-fg-subtle` (or `color="subtle"`). Never pair `text-fg` with `text-fg-muted`.
- **Radix Selection**:
  - Modals / Palette: Radix Dialog (`Spotlight`, `ProfileModal`, `Dialog`).
  - Destructive: Radix AlertDialog (focus defaults to Cancel, no outside-click dismiss).
  - Select: Radix Select (`value: ""` is forbidden reserved sentinel; scroll via `Select.Viewport`).
  - Overlay Panels: Any floating overlay surface MUST have `data-panel` attribute.
- **Monolithic Context File**: Ingest [llms-full.txt](https://docs.shavin.cc/llms-full.txt) for exhaustive tokens, ThemeProvider props, all 139 component declarations, copy-paste code snippets, and anti-patterns in a single prompt.

## Installation & Quickstart
- **Automated 1-Command Scaffolding (Recommended)**:
  ```bash
  npx @shavin/cli init
  ```
  Auto-detects project framework (Next.js App/Pages Router, Vite, Remix), installs `@shavin/ui`, configures Tailwind preset, imports `@shavin/ui/styles.css`, and wraps root layout in `<ThemeProvider>`.
- **Manual Installation**:
  ```bash
  npm install @shavin/ui
  ```
  1. **Tailwind Preset**: Add `presets: [require("@shavin/ui/tailwind-preset")]` to `tailwind.config.ts`.
  2. **Stylesheet**: Add `@import "@shavin/ui/styles.css";` to root CSS (`globals.css`).
  3. **Root Provider**: Wrap app in `<ThemeProvider accentColor="grass" radius="large">{children}</ThemeProvider>`.
  4. **Next.js Config**: Add `transpilePackages: ["@shavin/ui"]` to `next.config.mjs`.

## Core Documentation & Guides
- [Getting Started](https://docs.shavin.cc/get-started/getting-started): Package installation, Tailwind preset, stylesheet import, and root ThemeProvider setup.
- [What is Shavin](https://docs.shavin.cc/get-started/what-is-shavin): Architectural principles, two-tier token model, and accessibility guarantees.
- [Shavin Ecosystem](https://docs.shavin.cc/get-started/shavin-ecosystem): Monorepo packages (@shavin/ui, @shavin/mcp, @shavin/cli, @shavin/block-schema, @shavin/builder-engine).
- [Working with AI](https://docs.shavin.cc/get-started/working-with-ai): AI agent workflows, zero-hallucination protocols, and coding rules.
- [Model Context Protocol (MCP)](https://docs.shavin.cc/get-started/mcp): 20 modular MCP server tools for tokens, components, guidelines, and live DOM validation.
- [Dev Inspector & Bridge](https://docs.shavin.cc/get-started/dev-inspector): In-browser floating debug tool for live token compliance, contrast audits, and Agent-Browser Bridge (:7428) telemetry.
- [Accessibility (WCAG 2.1 AAA)](https://docs.shavin.cc/get-started/accessibility): Contrast ratios, focus ring management, ARIA roles, and screen-reader testing.
- [Tag Reference Cheat Sheet](https://docs.shavin.cc/components/tag-reference): Exhaustive cheat sheet of all JSX component tags, categories, and use cases.

## Shavin Web Ecosystem & Tooling
- [Shavin Studio](https://www.shavin.cc/studio): Visual canvas, drag-and-drop block builder, and theme inspector.
- [Block Catalog & Registry](https://www.shavin.cc/blocks): 55+ production-ready blocks across Hero, Features, Dashboards, Pricing, Testimonials, Footers.
- [Dev Inspector & Bridge](https://www.shavin.cc/dev-inspector): Live browser bridge daemon (:7428), SSE audit feed, and real-time token compliance.
- [Model Context Protocol](https://www.shavin.cc/mcp): 20 modular AI agent tools for Cursor, Claude Desktop, Antigravity, and VS Code.
- [SHAVIN.md AI Context](https://www.shavin.cc/shavin-md): Declarative AI constitution and zero-hallucination agent rules generator.
- [Open Source & License](https://www.shavin.cc/open-source): MIT-licensed core primitives and zero-telemetry design philosophy.
- [Changelog](https://www.shavin.cc/changelog): Release history and monorepo evolution.
- [About Shavin](https://www.shavin.cc/about): Mission, two-tier token philosophy, and accessibility standards.

## Design Foundations & Tokens
- [Theming Engine](https://docs.shavin.cc/foundations/theming): ThemeProvider configuration, 24 accent palettes, 5 neutral gray scales, radius presets, and scaling options.
- [Colors & Design Tokens](https://docs.shavin.cc/foundations/colors): Semantic token dictionary, background surfaces, foreground text, borders, and status roles.
- [Typography Overview](https://docs.shavin.cc/foundations/typography/overview): Type scales, display and body fonts, measure limits (max-w-2xl), text-balance, and tabular numerals.
- [Spacing System](https://docs.shavin.cc/foundations/spacings): 4px grid rhythm, spatial hierarchy zones (Page, Container, Surface, Element).
- [Radius & Geometry](https://docs.shavin.cc/foundations/radius): Concentric radius laws, control radius vs panel radius, and nested curve calculations.
- [Shadows & Elevation](https://docs.shavin.cc/foundations/shadows): Panel and modal elevation shadows with light/dark elevation matching.
- [Motion & Physics](https://docs.shavin.cc/foundations/motion): Custom cubic-bezier easings, the Frequency Law, and entrance choreography.
- [Layout & App Shell](https://docs.shavin.cc/foundations/layout): AppFrame, Sidebar, NavRail, TopBar, and responsive viewport partitioning.
- [Aspect Ratio](https://docs.shavin.cc/foundations/aspect-ratio): Media framing, video containers, and proportional card insets.

## Layout & Shell Components
- [<Box>](https://docs.shavin.cc/components/box): Low-level layout container supporting display, position, padding, margin, width, and height.
- [<Flex>](https://docs.shavin.cc/components/flex): Flexbox container with direction, align, justify, wrap, and gap props.
- [<Grid>](https://docs.shavin.cc/components/grid): CSS Grid container with responsive columns, rows, gap, and alignment.
- [<Container>](https://docs.shavin.cc/components/container): Centered content wrapper with responsive max-width constraints (sm, md, lg, xl, 2xl).
- [<Section>](https://docs.shavin.cc/components/section): Vertical page section wrapper with token-driven vertical rhythm padding.
- [<AppFrame>](https://docs.shavin.cc/foundations/app-shell): Responsive master application shell organizing Sidebar, NavRail, TopBar, and main view.
- [<Sidebar>](https://docs.shavin.cc/components/sidebar): Collapsible left application sidebar with Header, Body, Footer, Section, and Item sub-components.
- [<NavRail>](https://docs.shavin.cc/foundations/app-shell): Slim icon-only vertical navigation rail for multi-workspace application switchers.
- [<TopBar>](https://docs.shavin.cc/foundations/app-shell): Application header bar with title, search input, actions, and profile trigger slots.
- [<Inset>](https://docs.shavin.cc/components/inset): Negative-margin wrapper clipping children flush to card or panel borders.
- [<AspectRatio>](https://docs.shavin.cc/foundations/aspect-ratio): Proportional aspect-ratio wrapper (16:9, 4:3, 1:1) backed by Radix.

## Typography Components
- [<Heading>](https://docs.shavin.cc/components/typography/headings): Semantic heading (h1-h6) with sizes (xs to 3xl), weight, and text-balance.
- [<Text>](https://docs.shavin.cc/components/typography/body): Paragraph or span body copy with sizes, weights, and semantic color roles (default, subtle, muted, accent).
- [<Em>](https://docs.shavin.cc/components/typography/em-strong): Inline italic emphasis element.
- [<Strong>](https://docs.shavin.cc/components/typography/em-strong): Inline bold weight text element.
- [<Quote>](https://docs.shavin.cc/components/typography/em-strong): Inline curly quotation element.
- [<Blockquote>](https://docs.shavin.cc/components/typography/quotes): Block-level quotation block with left accent bar and muted styling.
- [<Code>](https://docs.shavin.cc/components/typography/code-kbd): Monospace code badge with hairline border and surface background.
- [<Kbd>](https://docs.shavin.cc/components/typography/code-kbd): Keyboard shortcut key badge (e.g. ⌘K, Ctrl+C, Shift+Enter).
- [<Link>](https://docs.shavin.cc/components/typography/links): Accessible hyperlink anchor with hover underline and color variants.

## Buttons & Actions
- [<Button>](https://docs.shavin.cc/components/button): Interactive button with variants (solid, soft, outline, ghost), tones (accent, danger), sizes (sm, md, lg), and loading state.
- [<IconButton>](https://docs.shavin.cc/components/icon-button): Compact icon-only button with accessible aria-label and variant styles.
- [<ActionBar>](https://docs.shavin.cc/components/action-bar): Floating grouped toolbar for multi-item selection, batch operations, or canvas actions.

## Form Controls
- [<TextField>](https://docs.shavin.cc/components/text-field): Single-line text input with leading/trailing icon slots, clear button, and error state.
- [<TextArea>](https://docs.shavin.cc/components/text-area): Multi-line textarea with auto-resize, character counters, and helper text.
- [<Checkbox>](https://docs.shavin.cc/components/checkbox): Accessible boolean checkbox backed by Radix Checkbox.
- [<CheckboxGroup>](https://docs.shavin.cc/components/checkbox): Accessible multi-item checkbox group container with shared label.
- [<CheckboxCards>](https://docs.shavin.cc/components/checkbox): Selectable rich cards with title, description, and check indicators.
- [<RadioGroup>](https://docs.shavin.cc/components/radio-group): Single-selection radio group with Radio items backed by Radix RadioGroup.
- [<Switch>](https://docs.shavin.cc/components/switch): Instant-on/off toggle switch control backed by Radix Switch.
- [<Select>](https://docs.shavin.cc/components/select): Accessible dropdown select with viewport scrolling backed by Radix Select (value="" forbidden).
- [<Dropdown>](https://docs.shavin.cc/components/dropdown): Lightweight native HTML `<select>` styled with design system tokens for mobile sheet support.
- [<Combobox>](https://docs.shavin.cc/components/combobox): Searchable autocomplete dropdown input with real-time query filtering.
- [<Slider>](https://docs.shavin.cc/components/slider): Accessible continuous or stepped numeric range slider backed by Radix Slider.
- [<SegmentedControl>](https://docs.shavin.cc/components/segmented-control): Multi-segment pill toggle button bar backed by Radix ToggleGroup.
- [<Stepper>](https://docs.shavin.cc/components/stepper): Step-by-step progress indicator and stepper for multi-page wizard flows.

## Pickers & Selection
- [<ColorPicker>](https://docs.shavin.cc/components/color-picker): Popover color selection grid supporting preset swatches and custom hex values.
- [<DatePicker>](https://docs.shavin.cc/components/date-picker): Calendar popover for single-date or date-range selection.
- [<TimePicker>](https://docs.shavin.cc/components/time-picker): Time input component with dropdown list, 3-field input, and clock dial options.
- [<IconPicker>](https://docs.shavin.cc/components/icon-picker): Searchable icon catalog picker supporting all Lucide icons with instant filtering.

## Data Display & Feedback
- [<Icon>](https://docs.shavin.cc/components/icon): Vector icon wrapper with size tokens (xs to xl), semantic color tokens, and Lucide integration.
- [<Badge>](https://docs.shavin.cc/components/badge): Compact status pill/chip with variants (solid, soft, outline, surface) and semantic tones.
- [<Avatar>](https://docs.shavin.cc/components/avatar): Accessible user avatar with image loading, fallback initials, and customizable radius.
- [<Card>](https://docs.shavin.cc/components/card): Surface container panel supporting interactive hover, padding presets, and bordered styling.
- [<CardList>](https://docs.shavin.cc/components/card): Stacked container for clean list items and settings rows.
- [<StatCard>](https://docs.shavin.cc/components/card): KPI metric dashboard card with title, large numeric value, trend badge, and sparkline slot.
- [<Table>](https://docs.shavin.cc/components/table): Accessible data table with TableHeader, TableBody, TableRow, TableCell, and column headers.
- [<DataList>](https://docs.shavin.cc/components/data-list): Structured key-value pair summary list (horizontal or vertical orientation).
- [<List>](https://docs.shavin.cc/components/typography/list): Prose list container supporting bullet, decimal, roman, alpha, or unstyled markers.
- [<Row>](https://docs.shavin.cc/components/row): Interactive row element with leading/trailing slots and drag-and-drop handles.
- [<Image>](https://docs.shavin.cc/components/image): Optimized responsive image with shimmer placeholder and error fallback.
- [<Chart>](https://docs.shavin.cc/components/chart): Zero-dependency SVG data chart supporting line, bar, and area visualizations.
- [<CodeBlock>](https://docs.shavin.cc/components/code-block): Syntax-highlighted code block with language indicator and one-click copy button.
- [<CodeEditor>](https://docs.shavin.cc/components/code-editor): Interactive in-browser code editor with line numbering and syntax highlighting.
- [<ChatBubble>](https://docs.shavin.cc/components/chat-bubble): Conversational message bubble with avatar, timestamp, and left/right alignment.
- [<Progress>](https://docs.shavin.cc/components/progress): Accessible horizontal progress bar backed by Radix Progress.
- [<Spinner>](https://docs.shavin.cc/components/spinner): Smooth animated loading spinner with size and tone variants.
- [<Skeleton>](https://docs.shavin.cc/components/skeleton): Animated shimmer loading placeholder mimic for asynchronous content fetching.
- [<Callout>](https://docs.shavin.cc/components/callout): Highlighted notification callout box with semantic tones (info, warning, danger, success).
- [<Calendar>](https://docs.shavin.cc/components/calendar): Interactive month and event calendar grid with CalendarView and CalendarEventChip.

## Overlays & Modals
- [<Dialog>](https://docs.shavin.cc/components/dialog): Accessible modal dialog window with focus trapping, backdrop overlay, and ESC dismiss backed by Radix.
- [<AlertDialog>](https://docs.shavin.cc/components/alert-dialog): Destructive confirmation dialog defaulting focus to Cancel without outside-click dismiss.
- [<Spotlight>](https://docs.shavin.cc/components/spotlight): Global ⌘K command palette modal with keyboard search and quick-action execution.
- [<ProfileModal>](https://docs.shavin.cc/blocks/profile-modal): Pre-configured user settings and account management modal dialog.
- [<Popover>](https://docs.shavin.cc/components/popover): Floating contextual panel triggered on click backed by Radix Popover.
- [<HoverCard>](https://docs.shavin.cc/components/hover-card): Preview card popover triggered on hover backed by Radix HoverCard.
- [<Tooltip>](https://docs.shavin.cc/components/tooltip): Contextual hover/focus micro-copy tooltip backed by Radix Tooltip.
- [<Menu>](https://docs.shavin.cc/components/menu): Accessible dropdown menu with submenus, keyboard navigation, and shortcuts backed by Radix.
- [<ContextMenu>](https://docs.shavin.cc/components/context-menu): Right-click context menu panel backed by Radix ContextMenu.
- [<ToastProvider>](https://docs.shavin.cc/components/toast): Global toast alert notification provider with `useToast()` trigger hook.
- [<Accordion>](https://docs.shavin.cc/components/accordion): Collapsible disclosure panel with AccordionItem, AccordionTrigger, and AccordionContent.

## Navigation & Utilities
- [<Breadcrumbs>](https://docs.shavin.cc/components/breadcrumbs): Hierarchical navigation breadcrumb trail with link items and separators.
- [<Tabs>](https://docs.shavin.cc/components/tabs-full): Multi-mode tabs supporting in-page stateful panels (`as="states"`) and URL routing (`as="navigation"`).
- [<Pagination>](https://docs.shavin.cc/components/pagination): Page navigation bar with page numbers, jump links, and prev/next controls.
- [<BottomNav>](https://docs.shavin.cc/components/bottom-nav): Mobile application bottom navigation bar with active indicator.
- [<ScrollArea>](https://docs.shavin.cc/components/scroll-area): Custom themed scrollbar container preserving native scroll physics backed by Radix.
- [<Separator>](https://docs.shavin.cc/components/separator): Horizontal or vertical hairline divider line backed by Radix.
- [<Sortable>](https://docs.shavin.cc/components/sortable): Drag-and-drop sortable list container with SortableHandle.
- [<ThemeSwitcher>](https://docs.shavin.cc/foundations/theming): Light/Dark mode toggle button with system preference synchronization.
- [<ThemeScript>](https://docs.shavin.cc/foundations/theming): Zero-flash SSR head script for reading stored theme and preventing flash of unstyled content.
- [<ShavinDevInspector>](https://docs.shavin.cc/get-started/dev-inspector): Floating in-browser developer tool for live token validation and contrast audits.

## Pre-Built Blocks & Full Templates
- [Chat Interface Block](https://docs.shavin.cc/blocks/chat): Complete conversational AI chat layout with message history and input bar.
- [Authentication Block](https://docs.shavin.cc/blocks/auth): Sign in, sign up, password recovery, and social OAuth cards.
- [Settings Panel Block](https://docs.shavin.cc/blocks/settings-panel): Tabbed settings interface with profile, billing, and team management.
- [Pricing Plans Block](https://docs.shavin.cc/blocks/pricing-plans): Tiered subscription pricing tables with billing frequency toggles.
- [Dashboard Template](https://docs.shavin.cc/blocks/templates/dashboard): Full SaaS analytics dashboard with AppFrame, sidebar, KPI stat cards, charts, and data tables.
- [E-Commerce Template](https://docs.shavin.cc/blocks/templates/ecommerce): Product catalog, filter sidebars, shopping cart, and checkout flow.
- [Landing Page Template](https://docs.shavin.cc/blocks/templates/landing): High-converting marketing homepage with hero, features, social proof, and CTA.