@gradeui/ui 0.8.2 → 0.10.0

package/components/ui/skeleton.md

@@ -0,0 +1,17 @@
+---
+name: Skeleton
+import: "@gradeui/ui"
+props:
+  - className?: string — required in practice; supply width/height utilities
+  - All native div HTML attrs
+when_to_use: Loading placeholder for content whose shape you know. Set width/height via className to mimic the real content (e.g. "h-4 w-32"). Not a spinner — use it where the real thing will drop in.
+composes_with: [Card, Avatar (inside a Skeleton for avatar loading), any layout]
+aliases: [placeholder, shimmer, loader, loading state]
+---
+
+```jsx
+<div className="space-y-2">
+  <Skeleton className="h-4 w-3/4" />
+  <Skeleton className="h-4 w-1/2" />
+</div>
+```

package/components/ui/slider.md

@@ -0,0 +1,48 @@
+---
+name: Slider
+import: "@gradeui/ui"
+props:
+  - value?: number[] — controlled value; ALWAYS an array even for a single-thumb slider (`[50]`)
+  - defaultValue?: number[] — uncontrolled initial; `[20, 80]` for a two-thumb range
+  - onValueChange?: (value: number[]) => void
+  - min?: number (default 0)
+  - max?: number (default 100)
+  - step?: number (default 1)
+  - disabled?: boolean
+  - orientation? "horizontal" | "vertical" (default "horizontal")
+  - dir? "ltr" | "rtl"
+  - inverted?: boolean — flip the visual direction
+  - name?: string — form name when posting natively
+when_to_use: A continuous-ish numeric pick — volume, opacity, font size, price-range filters. Use a single-thumb slider for one value, two-thumb for a range. For a small set of discrete options (1-5 stars, sm/md/lg) prefer ToggleGroup. For free-text numeric entry use an Input type="number".
+composes_with: [Label (mandatory above), Row (label + current value display), Card (settings rows)]
+aliases: [slider, range slider, range input, volume, opacity slider, scrub, drag value]
+---
+
+```jsx
+// Single-thumb slider with the current value shown alongside.
+<Stack gap="xs">
+  <Row justify="between" align="center">
+    <Label htmlFor="opacity">Opacity</Label>
+    <span className="text-sm text-muted-foreground tabular-nums">{value[0]}%</span>
+  </Row>
+  <Slider
+    id="opacity"
+    min={0}
+    max={100}
+    step={1}
+    value={value}
+    onValueChange={setValue}
+  />
+</Stack>
+```
+
+```jsx
+// Two-thumb price-range filter.
+<Slider
+  min={0}
+  max={500}
+  step={5}
+  defaultValue={[50, 250]}
+  onValueChange={setRange}
+/>
+```

package/components/ui/stack.md

@@ -0,0 +1,32 @@
+---
+name: Stack
+import: "@gradeui/ui"
+role: layout
+props:
+  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "md") — vertical gap between children
+  - align?: "start" | "center" | "end" | "stretch" (default "stretch") — cross-axis (horizontal) alignment of children
+  - asChild?: boolean (default false) — render as the child element via Slot, so `<Stack asChild><section>…</section></Stack>` stamps Stack's classes onto the `<section>` rather than nesting a wrapper div
+  - className?: string
+  - children: React.ReactNode
+when_to_use: Default top-level layout inside the main slot when composing two or more stacked regions (hero + content + footer, auth card + subtext, etc.). Prefer Stack over hand-rolled `flex flex-col gap-*` so the vertical rhythm is editable through the settings panel.
+composes_with: [Section, Row, Split, Hero, any content component]
+aliases: [stack, vstack, vertical, column, vertical layout]
+---
+
+```jsx
+<Stack gap="lg">
+  <Hero>…</Hero>
+  <Section>…</Section>
+  <Section>…</Section>
+</Stack>
+```
+
+```jsx
+// Narrow centred column for auth / marketing copy.
+<Stack gap="md" align="center" className="max-w-md mx-auto">
+  <CardTitle>Sign in</CardTitle>
+  <Input placeholder="Email" />
+  <Input placeholder="Password" type="password" />
+  <Button className="w-full">Continue</Button>
+</Stack>
+```

package/components/ui/switch.md

@@ -0,0 +1,20 @@
+---
+name: Switch
+import: "@gradeui/ui"
+props:
+  - checked?: boolean
+  - onCheckedChange?: (checked: boolean) => void
+  - defaultChecked?: boolean
+  - disabled?: boolean
+  - id?: string
+when_to_use: Instant on/off setting ("Enable notifications", "Dark mode"). Commits on toggle — no submit button needed. For selecting-from-a-list use Checkbox.
+composes_with: [Label (via htmlFor), Card (settings rows)]
+aliases: [toggle]
+---
+
+```jsx
+<div className="flex items-center justify-between">
+  <Label htmlFor="notifications">Email notifications</Label>
+  <Switch id="notifications" />
+</div>
+```

package/components/ui/table.md

@@ -0,0 +1,27 @@
+---
+name: Table
+import: "@gradeui/ui"
+subcomponents: [TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption]
+props:
+  - Each subcomponent accepts native table HTML attrs
+  - No variants — styling follows the active theme tokens
+when_to_use: Structured tabular data — rows × columns with alignment requirements. NOT a layout grid — for that use div+Tailwind grid utilities. Keep to <100 rows; larger datasets need virtualisation (not in DS).
+composes_with: [Card (wrap the table), Badge (inside TableCell for status), Checkbox (row selection), Button (row actions)]
+---
+
+```jsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead className="text-right">Amount</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>Invoice #001</TableCell>
+      <TableCell className="text-right">$250</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```

package/components/ui/tabs.md

@@ -0,0 +1,39 @@
+---
+name: Tabs
+import: "@gradeui/ui"
+subcomponents: [TabsList, TabsTrigger, TabsContent]
+sizes: [sm, md, lg]
+props:
+  - Tabs: defaultValue?, value?, onValueChange?, orientation?
+  - TabsList: size? (sm | md | lg, default md) — t-shirt scale aligned with Button/ToggleGroup heights; cascades to every TabsTrigger via context so set it once on the list
+  - TabsTrigger: value: string — matches a TabsContent value; tooltip?: string — when set, wraps the trigger in the design-system Tooltip and auto-applies aria-label (useful for icon-only triggers); requires a TooltipProvider somewhere above the tabs
+  - TabsContent: value: string — matches a TabsTrigger value
+when_to_use: A small set of peer views within one surface (2–5 tabs). For primary nav use Side Menu/routing. For filters use a filter control, not tabs.
+composes_with: [Card (tabs inside a card body), Dialog, TooltipProvider (required for tooltip prop)]
+aliases: [tabs, tab strip, tab bar]
+---
+
+```jsx
+<Tabs defaultValue="details">
+  <TabsList>
+    <TabsTrigger value="details">Details</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="details">…</TabsContent>
+  <TabsContent value="activity">…</TabsContent>
+</Tabs>
+```
+
+```jsx
+// Icon-only triggers — `tooltip` adds the design-system Tooltip + aria-label.
+<TooltipProvider>
+  <Tabs defaultValue="preview">
+    <TabsList size="sm">
+      <TabsTrigger value="preview" tooltip="Preview"><Eye /></TabsTrigger>
+      <TabsTrigger value="code" tooltip="Code"><Code /></TabsTrigger>
+    </TabsList>
+    <TabsContent value="preview">…</TabsContent>
+    <TabsContent value="code">…</TabsContent>
+  </Tabs>
+</TooltipProvider>
+```

package/components/ui/textarea.md

@@ -0,0 +1,14 @@
+---
+name: Textarea
+import: "@gradeui/ui"
+props:
+  - All native textarea HTML attrs (rows, value, onChange, placeholder, disabled)
+when_to_use: Multi-line text entry (descriptions, messages, comments). Pair with a Label. Single-line input → use Input instead.
+composes_with: [Label, Form, Card (in CardContent)]
+aliases: [text area, multiline, comment box, message field]
+---
+
+```jsx
+<Label htmlFor="bio">Bio</Label>
+<Textarea id="bio" rows={4} placeholder="Tell us about yourself." />
+```

package/components/ui/three-scene.md

@@ -0,0 +1,226 @@
+---
+name: ThreeScene
+import: "@gradeui/ui"
+props:
+  - preset?: "space" | "plasma" | "voronoi" | "synthwave" — shader preset id from the registry
+  - fragmentShader?: string — user-authored GLSL body; takes precedence over preset
+  - onShaderError?: (error: ShaderCompileError) => void — fires on compile failure; scene falls back to `preset="space"`
+  - postPreset?: "none" | "vhs" | "cinematic" | "synthwave" | "crt" (default "vhs") — post-processing pass
+  - palette?: Partial<{ primary; secondary; accent; background }> — any CSS-legal colour string per slot. Re-tints automatically when the theme changes. Unset slots fall back to defaults.
+  - createScene?: (ctx) => SceneHandle — custom full scene factory; takes precedence over preset AND fragmentShader
+  - controls?: boolean (default false) — play/pause overlay
+  - autoPlay?: boolean (default true) — respects reduced-motion
+  - pauseOffscreen?: boolean (default true) — big win for WebGL battery life
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "video")
+  - maxDpr?: number (default min(devicePixelRatio, 2)) — lower for thumbnails / low-end devices
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg")
+when_to_use: WebGL primitive for shader backgrounds, generative visuals, and bespoke three.js scenes. Three authoring paths, in order of preference — (1) pick a `preset` id; (2) if nothing in the registry fits, write a `fragmentShader` against the fixed uniform contract; (3) only as a last resort, pass a full `createScene` factory. For looping video, use VideoPlayer; for interactive animations, use RivePlayer.
+composes_with: [MediaSurface (internal), foreground content stacked above with `position: absolute/relative z-10`]
+aliases: [three, threejs, webgl, shader, scene, 3d, generative, hero background, fragment shader, glsl]
+notes: |
+  Depends on `three` and `postprocessing` (bundled into @gradeui/ui). Safari caps concurrent WebGL contexts at ~8 — for preset galleries, prefer ShaderPresetPreview with `live="hover"`.
+
+  ## Path 1 — `preset` (pick one, fastest, highest quality)
+
+  Valid `preset` ids (complete list — do NOT invent any others):
+    - "space"     — Hyperspace starfield, streaking stars. Default post: "vhs".
+    - "plasma"    — soft rolling colour clouds, ambient/abstract. Default post: "synthwave".
+    - "voronoi"   — jittered cellular grid with glowing edges. Default post: "crt".
+    - "synthwave" — retro perspective grid + banded sun. Default post: "synthwave".
+
+  Any other preset id renders an empty surface. If these don't cover the ask, DO NOT invent a name — jump to Path 2 (`fragmentShader`) and write the shader directly.
+
+  Valid `postPreset` ids (complete list): "none" | "vhs" | "cinematic" | "synthwave" | "crt".
+
+  Re-skin any preset with `palette={{ primary, secondary, accent, background }}` to shift its mood. Preset + palette + postPreset is usually enough to hit ocean / lava / neon / forest vibes.
+
+  ### Palette values — what counts as a valid colour
+
+  Each slot accepts ANY CSS-legal colour expression. Values are normalised via a browser probe before being handed to three.js, so all of these work:
+
+    - CSS custom properties wrapped in a colour function — `"oklch(var(--primary))"`, `"oklch(var(--foreground))"`. **This is the recommended pattern for gradeui consumers.** gradeui tokens (like shadcn) are bare channel triplets (`--primary: 0.610 0.128 20`), so `var(--primary)` alone is NOT a valid CSS colour and will render black. ALWAYS wrap as `oklch(var(--token))`. The shader re-tints automatically on theme change.
+    - Hex — `"#ff5fb9"`, `"#f5b"`.
+    - `rgb()` / `rgba()` — `"rgb(255 95 185)"`, `"rgb(255, 95, 185)"`.
+    - `hsl()` / `hsla()` — `"hsl(330 100% 69%)"`.
+    - `oklch()` / `lab()` / `lch()` / `oklab()` — `"oklch(0.74 0.18 350)"`. Full CSS Color 4.
+    - Named colours — `"tomato"`, `"dodgerblue"`, `"black"`.
+
+  INVALID — these DO NOT work and will silently fall back to the default palette slot:
+
+    - Literal bare triplets passed as a palette string — `"0.4 0.1 0.9"` is NOT a colour; wrap it as `"oklch(0.4 0.1 0.9)"`. (The var()-based auto-wrap above only kicks in when the palette value is `var(--token)` and the token itself is a triplet — it can't rescue a raw triplet passed directly.)
+    - three.js hex numbers — `0xff5fb9` (number). Use the string `"#ff5fb9"`.
+    - Colour arrays — `[0.4, 0.1, 0.9]`. Not accepted.
+
+  Theme reactivity: when the host document's root class or `data-theme` attribute changes, the scene re-reads the palette and pushes new uniforms into the running shader WITHOUT tearing down the WebGL context. Dark/light swaps are essentially free.
+
+  ### gradeui token semantics — pick the RIGHT tokens, and ALWAYS wrap in `oklch()`
+
+  gradeui tokens are bare OKLCH channel triplets (`--primary: 0.610 0.128 20`, no `oklch()` wrapper) — same convention as shadcn. That means **every `var(--token)` passed to the palette MUST be wrapped in `oklch(...)` at the call site**: `"oklch(var(--primary))"`, not `"var(--primary)"`. Unwrapped values resolve to invalid CSS and render black.
+
+  Token role cheat-sheet when picking which slot maps to what:
+
+    - `--primary` — brand hue 1. USE for `palette.primary` (and often `palette.accent` too).
+    - `--accent` — brand hue 2. USE for `palette.secondary` — gradeui's `--secondary` is a NEUTRAL surface (identical to `--muted`) and will render as a flat near-white wash in the shader.
+    - `--foreground` — inverted neutral (dark in light mode, light in dark mode). USE for `palette.background` — the raw `--background` token is the page background (near-white in light mode) and will wash the shader out.
+
+  Idiomatic theme-reactive palette for gradeui consumers (copy verbatim):
+
+    ```jsx
+    palette={{
+      primary: "oklch(var(--primary))",
+      secondary: "oklch(var(--accent))",   // NOT var(--secondary) — that's a neutral
+      accent: "oklch(var(--primary))",
+      background: "oklch(var(--foreground))", // NOT var(--background) — that's the page bg
+    }}
+    ```
+
+  ## Path 2 — `fragmentShader` (custom GLSL)
+
+  Pass a GLSL fragment shader body as a string. Runs on a fullscreen quad. Header is AUTO-INJECTED — write `void main()` only and use the uniforms below as given. Do NOT redeclare them, do NOT add `#version` directives, do NOT `import * as THREE` — you are writing shader text, not JavaScript.
+
+  Auto-injected header (available to every fragmentShader):
+
+    ```glsl
+    precision highp float;
+    varying vec2 vUv;               // [0,1] across the quad
+    uniform float uTime;            // elapsed seconds
+    uniform vec2  uResolution;      // pixel size of the canvas
+    uniform vec2  uMouse;           // [0,1], y-up (GLSL convention); defaults to (0.5, 0.5)
+    uniform vec3  uPrimary;         // palette.primary  (theme-driven)
+    uniform vec3  uSecondary;       // palette.secondary
+    uniform vec3  uAccent;          // palette.accent
+    uniform vec3  uBackground;      // palette.background
+    ```
+
+  Minimal working skeleton:
+
+    ```glsl
+    void main() {
+      vec2 uv = vUv - 0.5;
+      float t = uTime;
+      vec3 col = mix(uBackground, uPrimary, 0.5 + 0.5 * sin(length(uv) * 10.0 - t));
+      gl_FragColor = vec4(col, 1.0);
+    }
+    ```
+
+  GLSL syntax rules:
+    - Use `gl_FragColor` for output (NOT `out vec4`).
+    - Use `varying` for inputs (NOT `in`).
+    - Use `texture2D` if sampling textures (not `texture`). In practice you won't need textures — stick to procedural colour.
+    - Hard cap: keep shaders under ~200 lines. Long raymarchers are usually both slow and wrong.
+
+  Error handling: if the GLSL fails to compile, the component fires `onShaderError` with the GL info log and renders `preset="space"` as a fallback. Never returns a blank surface.
+
+  ## Path 3 — `createScene` (escape hatch)
+
+  A full `SceneFactory` that returns `{ scene, camera, update, resize, setPalette, dispose }`. Only reach for this if you need real geometry, multiple passes, or a custom camera. 95% of "make me a shader" asks are better served by Path 2.
+
+  ## Fullscreen backgrounds
+
+  Surface defaults to `aspect="video"` (16:9). For a full-bleed hero background using `className="absolute inset-0"`, ALWAYS also pass `aspect="auto"` — otherwise the aspect-ratio constraint fights the absolute positioning and you get letterboxing.
+---
+
+```jsx
+// Path 1 — named preset (fastest path)
+<ThreeScene preset="plasma" postPreset="synthwave" aspect="wide" />
+```
+
+```jsx
+// Path 1 — preset + palette re-skin to hit a custom mood
+<ThreeScene
+  preset="space"
+  postPreset="cinematic"
+  palette={{
+    primary: "#00e0ff",
+    secondary: "#1a7eff",
+    accent: "#ffffff",
+    background: "#000512",
+  }}
+/>
+```
+
+```jsx
+// Path 1 — palette from the active theme via CSS variables.
+// Recolors automatically when the theme switches.
+//
+// gradeui tokens are bare OKLCH triplets (shadcn-style), so EVERY var() MUST
+// be wrapped in oklch(...) at the call site — unwrapped `var(--primary)` is
+// invalid CSS and will render black.
+//
+// Slot mapping: `--secondary` is a neutral surface in gradeui (not a brand hue)
+// and `--background` is the page bg (near-white in light mode). Map secondary
+// to `--accent` and background to `--foreground` for a punchy, theme-reactive
+// palette that inverts cleanly on dark-mode toggle.
+<ThreeScene
+  preset="plasma"
+  palette={{
+    primary: "oklch(var(--primary))",
+    secondary: "oklch(var(--accent))",
+    accent: "oklch(var(--primary))",
+    background: "oklch(var(--foreground))",
+  }}
+/>
+```
+
+```jsx
+// Path 1 — CSS Color 4 (oklch) works too.
+<ThreeScene
+  preset="voronoi"
+  palette={{
+    primary: "oklch(0.74 0.18 350)",
+    secondary: "oklch(0.62 0.22 260)",
+    accent: "oklch(0.92 0.11 95)",
+    background: "oklch(0.1 0.04 280)",
+  }}
+/>
+```
+
+```jsx
+// Path 2 — custom fragment shader. Header is auto-injected; just write main().
+// This one: concentric rings in the theme's primary colour, breathing on uTime.
+<ThreeScene
+  fragmentShader={`
+    void main() {
+      vec2 uv = vUv - 0.5;
+      uv.x *= uResolution.x / uResolution.y;
+      float d = length(uv);
+      float rings = 0.5 + 0.5 * sin(d * 30.0 - uTime * 2.0);
+      vec3 col = mix(uBackground, uPrimary, rings);
+      col = mix(col, uAccent, smoothstep(0.45, 0.5, d) * 0.4);
+      gl_FragColor = vec4(col, 1.0);
+    }
+  `}
+  postPreset="vhs"
+  aspect="square"
+/>
+```
+
+```jsx
+// Path 2 — interactive: follow the pointer with uMouse.
+<ThreeScene
+  fragmentShader={`
+    void main() {
+      vec2 uv = vUv;
+      float d = distance(uv, uMouse);
+      float glow = smoothstep(0.3, 0.0, d);
+      vec3 col = mix(uBackground, uPrimary, glow);
+      gl_FragColor = vec4(col, 1.0);
+    }
+  `}
+/>
+```
+
+```jsx
+// Fullscreen hero — shader behind, content on top.
+// `aspect="auto"` is required for inset-0 to fill the parent.
+<div className="relative h-screen w-full overflow-hidden">
+  <ThreeScene
+    preset="synthwave"
+    aspect="auto"
+    className="absolute inset-0"
+  />
+  <div className="relative z-10 py-16 px-6 text-center text-white">
+    <h1 className="text-5xl font-bold">Build at the speed of thought</h1>
+  </div>
+</div>
+```

package/components/ui/toast.md

@@ -0,0 +1,38 @@
+---
+name: Toaster
+import: "@gradeui/ui"
+aliases: [toast, toaster, sonner, notification, snackbar, alert toast, transient alert]
+props:
+  - Toaster: position? "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" (default "bottom-right")
+  - Toaster: theme? "light" | "dark" | "system"
+  - Toaster: richColors?: boolean — colored variants for success/error/warning/info
+  - Toaster: expand?: boolean — keep multiple toasts visually separated rather than stacked
+  - Toaster: visibleToasts?: number — max concurrent toasts on screen (default 3)
+  - Toaster: duration?: number — default ms before auto-dismiss
+when_to_use: Transient, non-blocking feedback that confirms or warns about an action — "Saved", "Failed to upload", "Copied to clipboard", "Invitation sent". For permanent inline messages keep using Alert. For confirmations that block until acknowledged use Dialog. Mount <Toaster /> ONCE at the root of the app; everywhere else, call the `toast` helper.
+composes_with: [App root layout (single <Toaster /> mount), Form submit handlers (success/error toasts), Async actions]
+notes: Backed by Sonner under the hood — `import { toast } from "sonner"` to fire toasts from anywhere.
+---
+
+```jsx
+// At the app root, mount once.
+<Toaster richColors position="bottom-right" />
+```
+
+```jsx
+// Anywhere else, fire via the helper.
+import { toast } from "sonner";
+
+<Button
+  onClick={async () => {
+    try {
+      await saveProfile();
+      toast.success("Saved");
+    } catch (err) {
+      toast.error("Couldn't save", { description: err.message });
+    }
+  }}
+>
+  Save changes
+</Button>
+```

package/components/ui/toggle-group.md

@@ -0,0 +1,36 @@
+---
+name: ToggleGroup
+import: "@gradeui/ui"
+subcomponents: [ToggleGroupItem]
+variants: [default, outline]
+sizes: [sm, md, lg]
+props:
+  - ToggleGroup: type: "single" | "multiple" — single picks one, multiple picks any number
+  - ToggleGroup: value?: string | string[] — controlled; matches `type` (string for single, string[] for multiple)
+  - ToggleGroup: defaultValue?: string | string[] — uncontrolled initial
+  - ToggleGroup: onValueChange?: (value: string | string[]) => void
+  - ToggleGroup: size? (sm | md | lg, default md) — cascades to every ToggleGroupItem via context, matches Tabs/Button heights
+  - ToggleGroup: variant? (default | outline)
+  - ToggleGroupItem: value: string — what the group reports when this item is pressed
+when_to_use: A small set of mutually-exclusive (`type="single"`) or independent (`type="multiple"`) binary options that live side-by-side as a segmented control — viewport size picker (Mobile/Tablet/Desktop), text alignment, view density. Reads identically to a TabsList of the same size; reach for ToggleGroup when each option emits a value (like a form input) rather than swapping panels. Use Tabs for panel switching, Toggle for a single on/off.
+composes_with: [Card (header controls), Row, AppShellHeader chrome, settings panels]
+aliases: [toggle group, segmented control, segmented buttons, button group, pill group, view selector]
+---
+
+```jsx
+// Single-select segmented control — viewport size picker.
+<ToggleGroup type="single" defaultValue="desktop" size="sm">
+  <ToggleGroupItem value="mobile" aria-label="Mobile"><Smartphone /></ToggleGroupItem>
+  <ToggleGroupItem value="tablet" aria-label="Tablet"><Tablet /></ToggleGroupItem>
+  <ToggleGroupItem value="desktop" aria-label="Desktop"><Monitor /></ToggleGroupItem>
+</ToggleGroup>
+```
+
+```jsx
+// Multi-select — text formatting toolbar.
+<ToggleGroup type="multiple">
+  <ToggleGroupItem value="bold" aria-label="Bold"><Bold /></ToggleGroupItem>
+  <ToggleGroupItem value="italic" aria-label="Italic"><Italic /></ToggleGroupItem>
+  <ToggleGroupItem value="underline" aria-label="Underline"><Underline /></ToggleGroupItem>
+</ToggleGroup>
+```

package/components/ui/toggle.md

@@ -0,0 +1,36 @@
+---
+name: Toggle
+import: "@gradeui/ui"
+variants: [default, outline]
+sizes: [default, sm, lg]
+props:
+  - variant? (default | outline) — outline adds a border, default is borderless and ghost-like
+  - size? (default | sm | lg)
+  - pressed?: boolean — controlled pressed state
+  - defaultPressed?: boolean — uncontrolled initial state
+  - onPressedChange?: (pressed: boolean) => void
+  - disabled?: boolean
+  - children: React.ReactNode — usually an icon or short label
+when_to_use: A standalone on/off button — Bold/Italic in a toolbar, "Show grid" in a header, single binary toggle that doesn't belong inside a Switch row. For two-or-more mutually-exclusive options use ToggleGroup. For a labeled settings switch ("Active: on/off") use Switch.
+composes_with: [Tooltip (wrap an icon-only Toggle), Row, TabsList (sibling)]
+aliases: [toggle, toggle button, press button, bold button, italic button]
+---
+
+```jsx
+// Single toolbar toggle — icon + tooltip for screen readers.
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Toggle aria-label="Toggle bold">
+        <Bold />
+      </Toggle>
+    </TooltipTrigger>
+    <TooltipContent>Bold</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+```jsx
+// Borderless variant — fits inline among other controls.
+<Toggle defaultPressed>Show grid</Toggle>
+```

package/components/ui/tooltip.md

@@ -0,0 +1,28 @@
+---
+name: Tooltip
+import: "@gradeui/ui"
+subcomponents: [TooltipTrigger, TooltipContent, TooltipProvider]
+props:
+  - TooltipProvider: delayDuration? number (default 700) — ms hover before show; mount ONCE near the app root
+  - TooltipProvider: skipDelayDuration? number (default 300) — ms gap that still feels like "same hover"
+  - Tooltip: open?, defaultOpen?, onOpenChange?
+  - TooltipTrigger: asChild?: boolean — usually wraps a Button or icon
+  - TooltipContent: side? "top" | "right" | "bottom" | "left" (default "top"); align? "start" | "center" | "end"; sideOffset?: number
+when_to_use: A short, non-essential label that explains a control on hover/focus — icon-only buttons in toolbars, abbreviated column headers, status dots. NEVER hide critical info inside a tooltip — they're invisible on touch and can be skipped by screen readers if implemented carelessly. For richer hover content use HoverCard. For inline help text that's always visible, use a description paragraph.
+composes_with: [Button (icon-only), Toggle, TabsTrigger (the canonical tabs already have a `tooltip` prop that wraps this), Avatar (status badge meaning)]
+aliases: [tooltip, tip, hover tip, hint, label on hover]
+---
+
+```jsx
+// Icon-only Button with a tooltip — accessible name still set via aria-label.
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button variant="ghost" size="icon" aria-label="Open settings">
+        <Settings />
+      </Button>
+    </TooltipTrigger>
+    <TooltipContent>Settings</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```

package/components/ui/video-player.md

@@ -0,0 +1,27 @@
+---
+name: VideoPlayer
+import: "@gradeui/ui"
+props:
+  - src: string — video URL
+  - controls?: boolean (default true) — show native controls; false for chromeless hero/background video
+  - autoPlay?: boolean (default false) — forces muted=true (browser restriction)
+  - loop?: boolean (default false)
+  - muted?: boolean (default = autoPlay)
+  - pauseOffscreen?: boolean (default true) — pause when scrolled out of viewport
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "video")
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--rds-media-radius`
+  - objectFit?: "cover" | "contain" | "fill" (default "cover")
+  - poster?: string — image shown before playback. Always rendered as a `loading="lazy"` `<img>` overlay (not the native `poster` attribute, which fetches eagerly).
+  - playbackRate?: number (default 1)
+when_to_use: HTML5 video wrapped in the shared media surface. Controls-on for a standard player, controls-off (+ autoplay/muted/loop) for hero / background video. Prefer Rive for anything interactive, Three Scene for shader backgrounds.
+composes_with: [MediaSurface (internal), Card (wrap for thumbnail grids)]
+aliases: [video, mp4, movie, webm, clip]
+notes: Poster images are always lazy-loaded. We don't use the native `<video poster>` attribute because browsers fetch it eagerly even when the surface is off-screen, which wastes the offscreen-pause savings. Instead we render `<img loading="lazy" decoding="async">` layered over the video, then fade it out on `onPlaying`. When no `src` is given nothing renders — always pass a URL.
+---
+
+```jsx
+<VideoPlayer src="/sample.mp4" poster="/movie-poster.jpg" controls />
+
+// Chromeless hero video
+<VideoPlayer src="/sample.mp4" controls={false} autoPlay loop muted aspect="wide" />
+```