# Pine Design System

> Token-driven React component library built with Vanilla Extract (zero-runtime CSS). Ships 11 accessible components on top of `@base-ui/react` headless primitives, three swappable design variants (basic, game, crayon), and light/dark mode for each. Package name on npm: `pine-design-system`.

Core mental model for generating code against this library:
- All visual styling comes from design tokens, never raw hex/px values. See the "Foundation & Tokens" section below.
- Wrap the app root in `ThemeProvider` once; components read the active theme via `useTheme()` internally, so consumers never pass a theme prop to individual components.
- Every component accepts `className` for composition and forwards native HTML attributes not listed in its own prop table.
- Prop names, defaults, and per-value guidance for every component are documented as JSDoc directly on each `Props` interface in `src/components/<Component>/<Component>.tsx` — read the source file if a page below is unavailable.
- The main `pine-design-system` entry is a React Server Components client boundary (all components/providers use `useTheme()`, so it ships with `"use client"`) — only render it from a Client Component, or from a Server Component that just renders it as JSX (the RSC-normal "server renders a client tree" pattern). For pure token *values* (colors, radius, spacing, etc.) inside actual server-side logic (e.g. computing an OG image, a metadata value), import from `pine-design-system/tokens` instead — that subpath has zero React/DOM dependency and is safe to evaluate on the server.
- `ThemeProvider`'s `syncWithSystem` (default `true`) is SSR-safe (no hydration mismatch), but a real SSR app still gets one visible correction right after hydration. To eliminate that flash, inline `getThemeInitScript()` (also from `pine-design-system/tokens`) in the root `<head>` before hydration — see "Avoiding a theme flash under SSR" in the Get Started guide / llms-full.txt.

This file ships two ways: live at `https://pine-design-system.vercel.app/llms.txt` (links below resolve on that domain), and inside the npm package itself (`node_modules/pine-design-system/llms.txt`) for agents that only read local files. Links are absolute so both copies work identically.

## Getting Started
- [Introduction](https://pine-design-system.vercel.app/introduction): What Pine is, the three design variants, accessibility model
- [Get Started](https://pine-design-system.vercel.app/get-started): Installation and `ThemeProvider` setup
- [Migration Guide](https://pine-design-system.vercel.app/migration): Upgrading between versions

## Foundation & Tokens
- [Colors](https://pine-design-system.vercel.app/foundation/colors): Foundation palette, theme adapters (toNeon/toPastel), semantic intent tokens
- [Spacing](https://pine-design-system.vercel.app/foundation/spacing): Foundation spacing scale and per-theme component padding
- [Typography](https://pine-design-system.vercel.app/foundation/typography): Font families, size/line-height/weight tokens
- [Radius](https://pine-design-system.vercel.app/foundation/radius): Corner radius scale and per-theme mapping
- [Shadow](https://pine-design-system.vercel.app/foundation/shadow): Elevation shadow scale
- [Design Tokens JSON](https://pine-design-system.vercel.app/tokens/design-tokens.json): All of the above as a single machine-readable file in W3C Design Tokens (DTCG) format — `$value`/`$type` pairs, foundation tokens plus resolved semantic tokens for all 3 themes × 2 modes

## Components
- [Badge](https://pine-design-system.vercel.app/components/badge): Inline status/label/tag indicator
- [Button](https://pine-design-system.vercel.app/components/button): Primary interactive action trigger
- [Checkbox](https://pine-design-system.vercel.app/components/checkbox): Multi-select / agreement control
- [Dialog](https://pine-design-system.vercel.app/components/dialog): Modal for confirmation, forms, or important information
- [Dropdown](https://pine-design-system.vercel.app/components/dropdown): Single-select from a list of options
- [ProgressBar](https://pine-design-system.vercel.app/components/progress-bar): Determinate/indeterminate task completion indicator
- [Switch](https://pine-design-system.vercel.app/components/switch): Immediate-effect on/off toggle
- [Tab](https://pine-design-system.vercel.app/components/tab): Panel navigation for related content
- [Text](https://pine-design-system.vercel.app/components/text): Typography primitive for all text rendering
- [TextField](https://pine-design-system.vercel.app/components/text-field): Single-line or multiline text input with label/validation
- [Tooltip](https://pine-design-system.vercel.app/components/tooltip): Hover/focus popup for supplementary (non-essential) information

## Full Reference
- [llms-full.txt](https://pine-design-system.vercel.app/llms-full.txt): Single-file reference with every component's full prop table, Do/Don't guidance, and a runnable code snippet — also ships as `node_modules/pine-design-system/llms-full.txt`. Use this when you need complete context in one fetch/read instead of following the links above individually.