@ggui-ai/ui-gen 0.14.0 → 0.16.0

package/dist/index.js

@@ -2,7 +2,8 @@ import { z } from 'zod';
 import * as esbuild2 from 'esbuild';
 import { build } from 'esbuild';
 import Anthropic from '@anthropic-ai/sdk';
-import { classifyUi, MODEL_REGISTRY, listContractGadgets, HOOK_NAME_RE, DANGEROUS_PATTERNS as DANGEROUS_PATTERNS$1, STDLIB_GADGETS_PACKAGE, resolveAppGadgets } from '@ggui-ai/protocol';
+import { getCssTokens, FORBIDDEN_IMPORT_SPECIFIERS } from '@ggui-ai/design/rendering';
+import { classifyUi, MODEL_REGISTRY, listContractGadgets, HOOK_NAME_RE, modelRefOfRoute, isGeneratorId, DANGEROUS_PATTERNS as DANGEROUS_PATTERNS$1, STDLIB_GADGETS_PACKAGE, resolveAppGadgets } from '@ggui-ai/protocol';
 import fs, { mkdirSync, writeFileSync, unlinkSync, existsSync, readFileSync, rm, createReadStream, createWriteStream } from 'fs';
 import { contentHash } from '@ggui-ai/protocol/content-hash';
 import ts7 from 'typescript';
@@ -18,7 +19,6 @@ import { tmpdir } from 'os';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
 import { createBrotliDecompress, createUnzip } from 'zlib';
-import { getCssTokens } from '@ggui-ai/design/rendering';
 import { parseGeneratorSlug, formatGeneratorSlug, isValidGeneratorSlug } from '@ggui-ai/mcp-server-core';
 import git from 'isomorphic-git';
 import { Volume, createFsFromVolume } from 'memfs';
@@ -1403,7 +1403,7 @@ var init_raw4 = __esm({
 var PRIMITIVES_DOCUMENTATION, VALID_PRIMITIVES;
 var init_primitives = __esm({
   "src/validation/primitives.ts"() {
-    PRIMITIVES_DOCUMENTATION = "# ggui Primitives & Design System Reference\n\n> You are a world-class UI engineer working with ggui's component library for the first time.\n> This reference documents every available component, prop, and convention.\n> Components handle theming automatically via built-in variants \u2014 pick the right variant and the theme does the rest.\n> For custom styling beyond variants, use CSS variables: var(--ggui-*, fallback).\n\n## Primitives\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Container\n\nContainer -- Width-constrained wrapper that centers content horizontally.\n\nRenders a `<div>` with `width: 100%` and a `maxWidth` constraint.\nWhen `center` is true (the default), applies `margin: 0 auto`.\nNo background, border, or shadow -- use Card for visual containment.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| maxWidth | `'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| 'full' \\| string` | `'lg'` | Maximum width constraint. Accepts a preset token or any CSS width string. - `'xs'` -- 320px - `'sm'` -- 480px - `'md'` -- 640px - `'lg'` -- 768px - `'xl'` -- 1024px - `'2xl'` -- 1280px - `'3xl'` -- 1536px - `'full'` -- 100%  Custom strings (e.g., `'900px'`, `'60ch'`) are passed through as-is. |\n| center | `boolean` | `true` | Whether to center the container horizontally via `margin: 0 auto`. |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Container maxWidth=\"xl\" padding=\"var(--ggui-spacing-6)\">\n  <Stack gap=\"var(--ggui-spacing-4)\">\n    <Heading level={1}>Dashboard</Heading>\n    <Card shadow=\"md\" padding=\"var(--ggui-spacing-5)\">\n      <Text>Welcome back!</Text>\n    </Card>\n  </Stack>\n</Container>\n```\n\n### Card\n\nCard -- Container with background, shadow, and optional border.\n\nRenders a `<div>` with:\n- Background: `var(--ggui-color-surface)`\n- Border (when enabled): `1px solid var(--ggui-color-outlineVariant)`\n- Shadow and radius controlled by design tokens via CSS variables.\n- No built-in transitions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'lg'` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| shadow | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'sm'` | Shadow elevation level. Maps to design tokens: - `'none'` -- no shadow - `'sm'` -- var(--ggui-shape-shadow-sm) -- subtle, default - `'md'` -- var(--ggui-shape-shadow-md) -- dialogs, emphasized sections - `'lg'` -- var(--ggui-shape-shadow-lg) -- floating panels - `'xl'` -- var(--ggui-shape-shadow-xl) -- popovers, modals |\n| border | `boolean` | `true` | Whether to render a 1px border using `var(--ggui-color-outlineVariant)`. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'lg'` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'transparent'` | `'default'` | Semantic surface slot. Same vocabulary as ; see that prop's docs for the full slot table. Default Card surface is `'default'` (the active theme's `--ggui-color-surface`); pair with `shadow=\"md\"\\|\"lg\"` for elevated cards, or use `'inverted'` for a dark testimonial-style card on a light theme. |\n\n**Example:**\n```tsx\n<Card shadow=\"md\" padding=\"lg\" radius=\"lg\">\n  <Stack gap=\"md\">\n    <Text size=\"sm\" weight=\"medium\">Settings</Text>\n    <Input label=\"Name\" value={name} onChange={setName} />\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Card>\n```\n\n### Stack\n\nStack -- Flexbox layout primitive for arranging children along a single axis.\n\nRenders a `<div>` with `display: flex`. Default layout is vertical (column).\nAll flex shorthand values (`align`, `justify`, `wrap`) are abstracted into\nsemantic prop names.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Main axis direction. - `'vertical'` -- `flex-direction: column` - `'horizontal'` -- `flex-direction: row` |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'sm'` | Gap between children. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| align | `'start' \\| 'center' \\| 'end' \\| 'stretch'` | `'stretch'` | Cross-axis alignment (maps to `align-items`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'stretch'` -- stretch (children fill cross-axis) |\n| justify | `'start' \\| 'center' \\| 'end' \\| 'between' \\| 'around' \\| 'evenly'` | `'start'` | Main-axis content distribution (maps to `justify-content`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'between'` -- space-between - `'around'` -- space-around - `'evenly'` -- space-evenly |\n| wrap | `boolean` | `false` | Whether children wrap to the next line when they overflow. Maps to `flex-wrap: wrap` when true. |\n\n**Example:**\n```tsx\n<Stack gap=\"lg\" align=\"center\">\n  <Heading level={2}>Profile</Heading>\n  <Text>Edit your account details below.</Text>\n  <Stack direction=\"horizontal\" gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\">Cancel</Button>\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Stack>\n```\n\n### Grid\n\nGrid -- 2-D layout primitive. Arranges children into rows AND\ncolumns; reach for it when Stack/Row's single-axis flow isn't\nenough (card galleries, dashboards, stat grids).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| columns | `number \\| ResponsiveColumns` | `2` | Column count. Three forms: - a number \u2014 that many equal columns at every width (`columns={3}`); - a  map \u2014 explicit counts per breakpoint   (`columns={{ base: 1, md: 3 }}` = 1 column on mobile, 3 from `md`).   Use this when the request names exact per-breakpoint counts   (\"3 per row on desktop, 1 on mobile\"). Ignored entirely when `minColumnWidth` is set. |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'md'` | Gap between cells. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`); a number is pixels. |\n| minColumnWidth | `number \\| string` | `undefined (use `columns`)` | When set, the grid becomes responsive \u2014 it fits as many equal columns as possible, each at least this wide, and `columns` is ignored. A number is treated as pixels. |\n\n**Example:**\n```tsx\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n```\n\n### Skeleton\n\nSkeleton -- a pulsing placeholder for content that has not loaded\nyet. ggui UIs are agent-driven (props arrive late, streams start\nempty), so a loading frame is the rule \u2014 render `Skeleton` instead\nof a blank screen or a hand-rolled pulsing `<div>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| variant | `'rect' \\| 'text' \\| 'circle'` | `'rect'` | Shape preset. - `'rect'` -- a block (default); pair with `width` / `height`. - `'text'` -- a single text line (height ~1em). - `'circle'` -- equal width/height, fully rounded (avatar slot). |\n| width | `number \\| string` | - | Width. A number is pixels. Defaults to `100%` (`2.5rem` for circle). |\n| height | `number \\| string` | - | Height. A number is pixels. Defaults by variant when unset. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'sm'` | Corner radius. Prefer a radius-scale name. Ignored for `variant=\"circle\"` (always fully round). |\n\n**Example:**\n```tsx\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n```\n\n### Box\n\nBox -- Generic container with padding, margin, background, and border-radius.\n\nRenders a plain `<div>`. Unlike Card, Box has no default background, shadow,\nor border -- it is a blank canvas for custom styling. Use it for layout\nspacing, colored sections, or wrapping arbitrary content.\n\nWhen both `paddingX`/`paddingY` and `padding` are provided, the axis-specific\nprops take precedence and `padding` is ignored.\n\nCSS variables used: none (all values are passed through directly).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all four sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. Ignored when `paddingX` or `paddingY` is set. |\n| paddingX | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Horizontal (left + right) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingY`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingY`, vertical padding defaults to 0. |\n| paddingY | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Vertical (top + bottom) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingX`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingX`, horizontal padding defaults to 0. |\n| margin | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no margin)` | Margin applied to all four sides. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'transparent'` | `undefined (transparent)` | Semantic surface slot. Picks the right `var(--ggui-color-*)` background token from the active theme. The ONLY way to set a theme-tracking background fill on Box.  Available slots: - `'default'` \u2014 base container surface (most common) - `'elevated'` \u2014 same fill, intended to be paired with shadow   (use Card.shadow for actual elevation) - `'sunken'` \u2014 recessed / inset region (`surfaceVariant` token) - `'accent'` \u2014 highlighted / branded fill (`primary-50` token) - `'inverted'` \u2014 dark surface in light mode, light in dark   (testimonials, code-snippet cards). Pair with    `'inverse'` for legible text. - `'transparent'` \u2014 explicit \"no fill\"  For non-theme-mapped brand colors (e.g. a partner's exact brand hex like Stripe purple) use the  escape \u2014 every other hex / rgba on Box is rejected by tier-0 self-check. |\n| assetColor | `string` | `undefined` | Asset color escape \u2014 the typed valve for legitimate non-theme color values (a partner's exact brand hex, a fixed product surface, etc.). Renders as the Box background.  **MUST be paired with .** The semantic name is human-readable documentation of why this color bypasses the theme \u2014 e.g. `\"stripe-brand-purple\"`, `\"slack-aubergine\"`. Tier-0 self-check allows hex / rgba inside `assetColor` ONLY when `assetSemantic` is a non-empty string; one without the other fails the check.  Reach for `surface` first. This escape exists for the small set of cases where the operator's theme MUST NOT override the value (brand identity rendering). |\n| assetSemantic | `string` | `undefined` | Human-readable semantic label that documents why  bypasses the theme. Required when `assetColor` is set; tier-0 self-check rejects empty strings or a missing `assetSemantic` next to a hex `assetColor`.  Examples: `\"stripe-brand-purple\"`, `\"slack-aubergine\"`, `\"partner-logo-orange\"`. Pure documentation \u2014 no rendering effect. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `undefined (no rounding)` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Box paddingX=\"xl\" paddingY=\"lg\" surface=\"accent\" radius=\"lg\">\n  <Text size=\"sm\" tone=\"emphasized\">\n    Tip: You can customize your theme in Settings.\n  </Text>\n</Box>\n```\n\n### Divider\n\nDivider -- A 1px line to visually separate content sections.\n\nRenders an `<hr>` (horizontal) or `<div>` (vertical) with `role=\"separator\"`.\n- Horizontal: 1px tall, full width, with vertical margin.\n- Vertical: 1px wide, stretches to parent height via `align-self: stretch`,\n  with horizontal margin. Works best inside a horizontal Stack or Row.\n\nDefault color: `var(--ggui-color-outlineVariant)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Line direction. - `'horizontal'` -- renders `<hr>`, full width, 1px height, margin top/bottom - `'vertical'` -- renders `<div>`, 1px width, `align-self: stretch`, margin left/right |\n| margin | `number \\| string` | `16` | Spacing around the divider. Numbers are treated as pixels. Applied as vertical margin for horizontal dividers, horizontal margin for vertical. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-outlineVariant)`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a quiet outline-variant tint when unset (independent of the tone slots). |\n\n**Example:**\n```tsx\n<Stack gap={0}>\n  <Text>Section A</Text>\n  <Divider margin=\"var(--ggui-spacing-3)\" />\n  <Text>Section B</Text>\n</Stack>\n```\n\n### Spacer\n\nSpacer -- Invisible spacing element, either fixed-size or flexible.\n\nRenders an empty `<div>`.\n- Fixed mode (number): sets both `width` and `height` to the given pixel\n  value with `flex-shrink: 0`, creating rigid spacing in any direction.\n- Flex mode (`'flex'`): sets `flex: 1`, expanding to fill remaining space\n  in a flex container. Useful for pushing siblings apart.\n\nCSS variables used: none.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number \\| 'flex'` | `16` | Spacing amount. - Number: fixed square spacer (width and height in pixels, `flex-shrink: 0`). - `'flex'`: expands to fill available space (`flex: 1`). |\n\n**Example:**\n```tsx\n<Stack direction=\"horizontal\" align=\"center\">\n  <Heading level={3}>Logo</Heading>\n  <Spacer size=\"flex\" />\n  <Button variant=\"ghost\">Login</Button>\n</Stack>\n```\n\n### Text\n\nText -- Versatile typography primitive for body copy, captions, and labels.\n\nRenders as `<p>` by default (configurable via `is`). Typography is\ncomposed from three orthogonal axes: `size` (font size, with a\nmatching line-height built in), `weight`, and `tone` (semantic\ncolor). `caps` adds the uppercase, letter-spaced treatment for tiny\nsection labels (the classic overline/eyebrow look).\n\nDefault text color: `var(--ggui-color-onSurface)`.\nAll text renders with `margin: 0` (no default paragraph spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| size | `'xs' \\| 'sm' \\| 'base' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| '4xl'` | `'base'` | Font size. Maps to CSS variables with pixel fallbacks; each size carries a matching line-height (1.5 for `xs`--`base`, 1.625 for `lg`, then tightening on display sizes: 1.375 at `xl`, 1.25 from `2xl` up): - `'xs'` -- var(--ggui-font-size-xs) (12px) - `'sm'` -- var(--ggui-font-size-sm) (14px) - `'base'` -- var(--ggui-font-size-base) (16px) - `'lg'` -- var(--ggui-font-size-lg) (18px) - `'xl'` -- var(--ggui-font-size-xl) (20px) - `'2xl'` -- var(--ggui-font-size-2xl) (24px) - `'3xl'` -- var(--ggui-font-size-3xl) (30px) - `'4xl'` -- var(--ggui-font-size-4xl) (36px) |\n| weight | `'normal' \\| 'medium' \\| 'semibold' \\| 'bold'` | `'normal'` | Font weight. Maps to CSS variables with numeric fallbacks: - `'normal'` -- var(--ggui-font-weight-normal) - `'medium'` -- var(--ggui-font-weight-medium) - `'semibold'` -- var(--ggui-font-weight-semibold) - `'bold'` -- var(--ggui-font-weight-bold) |\n| caps | `boolean` | `false` | When true, uppercases the text and adds 0.05em letter-spacing -- the eyebrow/overline treatment for tiny section labels. Pair with `size=\"xs\" weight=\"semibold\" tone=\"muted\"`. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onSurface))` | Semantic color slot. Picks the right `var(--ggui-color-*)` token from the active theme. The theme decides what each tone LOOKS like \u2014 `'muted'` is a quiet warm grey on Claudic, a cool slate on Indigo, dim cyan on Neon-Noir. Components that use `tone` track the operator's theme switch automatically.  Available slots: `'default'` (primary body text), `'muted'` (secondary / metadata), `'subtle'` (very-low-emphasis hint), `'emphasized'` (branded accent), `'loud'` (strongest accent), `'success'` / `'warning'` / `'error'` / `'info'` (status text), `'inverse'` (text on dark surface), `'inherit'` (parent's color).  `tone` is the ONLY way to set a Text color. The legacy `color?: string` escape was retired \u2014 raw color strings bypass theming and silently override the operator's preset. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n| truncate | `boolean` | `false` | When true, clips overflowing text with an ellipsis. Applies `overflow: hidden`, `text-overflow: ellipsis`, and `white-space: nowrap`. |\n| is | `'p' \\| 'span' \\| 'div' \\| 'label'` | `'p'` | HTML element to render. Choose based on semantic context: - `'p'` -- paragraph (default, block-level) - `'span'` -- inline text within a sentence - `'div'` -- generic block container - `'label'` -- form label (pair with `htmlFor`) |\n| id | `string` | - | `id` for the rendered element \u2014 anchor an in-page link, or pair with a form control's `aria-labelledby`. |\n| htmlFor | `string` | - | Associates an `is=\"label\"` element with a form control by the control's `id`. Only meaningful when `is=\"label\"`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-1)\">\n  <Text size=\"xs\" weight=\"semibold\" caps tone=\"muted\">Account</Text>\n  <Text size=\"lg\">Welcome back, Jane.</Text>\n  <Text size=\"xs\" tone=\"muted\">\n    Last login: 2 hours ago\n  </Text>\n</Stack>\n```\n\n### Heading\n\nHeading -- Semantic heading element (h1-h6) with preset typography styles.\n\nRenders the corresponding `<h1>`-`<h6>` HTML element based on `level`.\nEach level has a preset font size, weight, line height, and letter spacing\nfrom the heading typography tokens:\n- Level 1: 36px / bold / 1.25 line-height / -0.025em tracking\n- Level 2: 30px / bold / 1.25 line-height / -0.025em tracking\n- Level 3: 24px / semibold / 1.375 line-height / 0em tracking\n- Level 4: 20px / semibold / 1.375 line-height / 0em tracking\n- Level 5: 18px / semibold / 1.5 line-height / 0em tracking\n- Level 6: 16px / semibold / 1.5 line-height / 0em tracking\n\nDefault text color: `var(--ggui-color-onSurface)`.\nAll headings render with `margin: 0` (no default heading spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| level | `1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6` | `2` | Semantic heading level. Determines both the HTML element (`<h1>`-`<h6>`) and the preset typography style. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onSurface))` | Semantic color slot. Same vocabulary as ; see that prop's docs for the full slot table. `tone` is the ONLY way to set a Heading color \u2014 the legacy `color?: string` escape was retired so the operator's theme always wins. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-2)\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={3} tone=\"emphasized\">\n    Subsection\n  </Heading>\n  <Text>Body content goes here.</Text>\n</Stack>\n```\n\n### Button\n\nButton -- A clickable button primitive with multiple visual variants and sizes.\n\nRenders a native `<button>` element styled with inline CSS derived from design-token\nCSS variables. Supports a loading spinner, left/right icon slots, and a cross-platform\n`onPress` alias for `onClick`.\n\nBase styles applied to every variant:\n- `border-radius: var(--ggui-shape-radius-md)`\n- `font-weight: var(--ggui-font-weight-medium)`\n- `box-shadow: var(--ggui-shape-shadow-sm)`\n- `gap: var(--ggui-spacing-2)` between icon and text\n- Transitions: background-color, box-shadow, opacity at 200ms ease-in-out\n\nDisabled or loading: `opacity: 0.5`, `cursor: not-allowed`, click handler suppressed.\n\nAlso extends native `ButtonHTMLAttributes` (except `style`/`className`), so props\nlike `type`, `form`, `aria-*`, and `data-*` are forwarded to the `<button>` element.\nThe `type` prop defaults to `'button'` (not `'submit'`), preventing accidental form\nsubmissions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'primary' \\| 'secondary' \\| 'outline' \\| 'ghost' \\| 'danger'` | `'primary'` | Visual style. Maps to CSS variables: - `'primary'` -- `var(--ggui-color-primary-600)` background, white text, no border - `'secondary'` -- `var(--ggui-color-surfaceVariant)` background, `var(--ggui-color-onSurfaceVariant)` text, no border - `'outline'` -- transparent background, `1px solid var(--ggui-color-primary-600)` border, primary-600 text - `'ghost'` -- transparent background, `var(--ggui-color-onSurfaceVariant)` text, no border - `'danger'` -- `var(--ggui-color-error-600)` background, white text, no border |\n| size | `'xs' \\| 'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and minimum height: - `'xs'` -- padding `4px 8px`, font `var(--ggui-font-size-xs)`, min-height 24px - `'sm'` -- padding `6px 12px`, font `var(--ggui-font-size-sm)`, min-height 32px - `'md'` -- padding `10px 16px`, font `var(--ggui-font-size-sm)`, min-height 40px - `'lg'` -- padding `12px 24px`, font `var(--ggui-font-size-base)`, min-height 48px |\n| fullWidth | `boolean` | `false` | When true, sets `width: 100%` so the button fills its container. |\n| loading | `boolean` | `false` | When true, replaces children with a 16px `Spinner` (color: `currentColor`) and disables interaction (same effect as `disabled`). |\n| leftIcon | `ReactNode` | - | ReactNode rendered before children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| rightIcon | `ReactNode` | - | ReactNode rendered after children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| onPress | `() => void` | - | Alias for `onClick` for cross-platform compatibility (React Native convention). If both `onClick` and `onPress` are provided, `onClick` takes precedence. |\n\n**Example:**\n```tsx\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n```\n\n### Input\n\nInput -- A single-line text input with label, validation, and helper text.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<input>`,\nand an optional message `<span>` for error or helper text.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-surface)` (normal),\n  `var(--ggui-color-surface)` (disabled)\n- Text: `var(--ggui-color-onSurface)`\n- Border radius: `var(--ggui-shape-radius-md)`\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n  `var(--ggui-color-onSurfaceVariant)`\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<input>` via `htmlFor`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\nWhen `required` is true, a red asterisk is appended to the label.\n\nAlso extends native `InputHTMLAttributes` (except `style`, `className`, `onChange`,\n`size`), so props like `autoFocus`, `name`, `pattern`, `aria-*` are forwarded.\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<input>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the input. Linked to the input via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| placeholder | `string` | - | Placeholder text shown when the input is empty. |\n| value | `string` | - | Controlled value of the input. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| type | `'text' \\| 'email' \\| 'password' \\| 'number' \\| 'tel' \\| 'url' \\| 'search' \\| 'date' \\| 'time' \\| 'datetime-local'` | `'text'` | HTML input type. Determines browser behavior (keyboard on mobile, validation, masking). The date/time types render the browser's native, localized, keyboard-accessible picker; their `value` stays an ISO string (`'2026-07-29'`, `'14:30'`, `'2026-07-29T14:30'`) delivered through the usual value-first `onChange`. |\n| error | `string` | - | Error message displayed below the input in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the input in `var(--ggui-color-onSurfaceVariant)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<input>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-surface)`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n```\n\n### TextArea\n\nTextArea -- A multiline text input with label, validation, character count, and auto-resize.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<textarea>`,\nand a footer row with error/helper text on the left and character count on the right.\n\nStyling:\n- Padding: `10px 12px`, font: `var(--ggui-font-size-sm)`, `font-family: inherit`\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-surface)` (normal),\n  `var(--ggui-color-surface)` (disabled)\n- Border radius: `var(--ggui-shape-radius-md)`\n- Resize: `vertical` by default, `none` when `autoResize` is true\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: same label/error linking pattern as Input (auto-generated ids,\n`aria-invalid`, `role=\"alert\"` on error message).\n\nAlso extends native `TextareaHTMLAttributes` (except `style`, `className`, `onChange`).\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<textarea>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the textarea. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| placeholder | `string` | - | Placeholder text shown when the textarea is empty. |\n| value | `string` | - | Controlled value of the textarea. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| rows | `number` | `4` | Number of visible text rows (native `rows` attribute on `<textarea>`). |\n| error | `string` | - | Error message displayed below the textarea in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the textarea in `var(--ggui-color-onSurfaceVariant)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<textarea>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-surface)`. |\n| maxLength | `number` | - | Maximum character length (native `maxLength` attribute). Also used as the denominator in the character count display when `showCount` is true. |\n| showCount | `boolean` | `false` | When true AND `maxLength` is set, displays a `{current}/{max}` character counter in the footer row (right-aligned, `var(--ggui-font-size-xs)`). Has no effect without `maxLength`. |\n| autoResize | `boolean` | `false` | When true, sets CSS `resize: none` on the textarea. The flag disables manual resizing to signal that external logic handles sizing. The component does NOT auto-adjust height based on content in the current implementation. |\n\n**Example:**\n```tsx\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n```\n\n### Select\n\nSelect -- A native dropdown selection primitive with label and validation.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<select>`\nwith custom styling, and an optional message `<span>`.\n\nThe native `<select>` has `appearance: none` with a custom chevron SVG rendered\nas a `background-image` (right-aligned, 12px, onSurfaceVariant color). Extra right\npadding (36px) accommodates the chevron.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-surface)` (normal),\n  `var(--ggui-color-surface)` (disabled)\n- Text: `var(--ggui-color-onSurface)` when a value is selected,\n  `var(--ggui-color-onSurfaceVariant)` when showing placeholder\n- Border radius: `var(--ggui-shape-radius-md)`\n- Cursor: `pointer` (normal), `not-allowed` (disabled)\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<select>`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\n\nAlso extends native `SelectHTMLAttributes` (except `style`, `className`,\n`onChange`, `size`).\n\n**IMPORTANT:** `onChange` receives the selected value string directly, NOT a\nReact `ChangeEvent`. This differs from native `<select>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the select. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| value | `string` | - | Controlled value. Should match one of the `options[].value` strings. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the selected option's value string directly, NOT a React event. |\n| options | `SelectOption[]` | - | Array of selectable options. Rendered as native `<option>` elements. Must contain at least one option (or use `placeholder` for an empty-state prompt). |\n| placeholder | `string` | - | Placeholder text rendered as a disabled `<option value=\"\">` at the top of the list. Shown when no value is selected. |\n| error | `string` | - | Error message displayed below the select in `var(--ggui-color-error-500)`. When set, the border turns red and the message has `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the select in `var(--ggui-color-onSurfaceVariant)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-surface)` and cursor becomes `not-allowed`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Select\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  options={[\n    { value: 'us', label: 'United States' },\n    { value: 'uk', label: 'United Kingdom' },\n  ]}\n  placeholder=\"Select a country\"\n/>\n```\n\n### Checkbox\n\nCheckbox -- A custom-styled checkbox with label and description.\n\nRenders a `<label>` wrapper containing a visually-hidden native `<input type=\"checkbox\">`\noverlaid by a custom 18x18px visual box. Supports checked, unchecked, and indeterminate\nstates, each with a distinct SVG icon (checkmark or horizontal dash).\n\nStyling:\n- Box border: `2px solid var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-outline)` (unchecked)\n- Box fill: `var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-surface)` (unchecked)\n- Check/dash icon: white SVG, 12x12px\n- Box radius: `var(--ggui-shape-radius-sm)`\n- Transition: all 0.2s\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`\n- Description: `var(--ggui-font-size-xs)`, `var(--ggui-color-onSurfaceVariant)`\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`\n- Gap between box and text: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the boolean checked state directly, NOT a\nReact `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary label text rendered beside the checkbox box. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| checked | `boolean` | - | Controlled checked state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean checked state directly, NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5` and `cursor: not-allowed`. The native input is also disabled, preventing keyboard and click interaction. |\n| description | `string` | - | Secondary description text rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSurfaceVariant)`). |\n| indeterminate | `boolean` | `false` | When true, displays a horizontal dash instead of a checkmark. Used for \"select all\" states where some (but not all) children are checked. The `indeterminate` property is set via a ref on the native `<input>`. Visually identical to `checked` in terms of border and fill color. |\n\n**Example:**\n```tsx\n<Checkbox\n  label=\"Accept terms\"\n  description=\"You agree to the Terms of Service and Privacy Policy\"\n  checked={accepted}\n  onChange={setAccepted}\n/>\n```\n\n### Toggle\n\nToggle -- A switch/toggle input rendered as a pill-shaped track with a sliding knob.\n\nRenders a `<label>` wrapper with a `<div role=\"switch\">` track and an animated\ncircular knob. Does NOT use a native `<input>` -- keyboard interaction is handled\nmanually (Space and Enter keys toggle the state). The element is focusable via\n`tabIndex={0}` and shows a focus ring on focus.\n\nStyling:\n- Track (on): `var(--ggui-color-primary-600)`\n- Track (off): `var(--ggui-color-outline)`\n- Knob: white circle with `var(--ggui-shape-shadow-sm)`\n- Focus ring: `0 0 0 3px var(--ggui-color-primary-200)`\n- Transitions: background-color, box-shadow, knob position at 200ms ease-in-out\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`, `tabIndex: -1`\n- Gap between toggle and label: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the new boolean state directly (inverted from\ncurrent), NOT a React event.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label text rendered to the right of the toggle track. Also used as `aria-label` on the switch element. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| checked | `boolean` | - | Controlled checked (on/off) state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean state directly (i.e., `!checked`), NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5`, `cursor: not-allowed`, and removes the element from tab order (`tabIndex: -1`). Click and keyboard handlers are suppressed. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track and knob dimensions: - `'sm'` -- track 36x20px, knob 16px diameter - `'md'` -- track 44x24px, knob 20px diameter - `'lg'` -- track 52x28px, knob 24px diameter |\n\n**Example:**\n```tsx\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n```\n\n### RadioGroup\n\nRadioGroup -- A group of mutually exclusive radio options with optional label and error.\n\nRenders a `<div role=\"radiogroup\">` containing a label span, a flex container of\nradio options, and an optional error message. Each option is a `<label>` with a\nvisually-hidden native `<input type=\"radio\">` and a custom 18px circle indicator.\n\nStyling:\n- Selected circle: `2px solid var(--ggui-color-primary-600)` border with\n  an 8px `var(--ggui-color-primary-600)` filled inner dot\n- Unselected circle: `2px solid var(--ggui-color-outline)` border,\n  `var(--ggui-color-surface)` fill\n- Circle radius: `var(--ggui-shape-radius-full)`\n- Transition: all 0.2s\n- Vertical gap: `var(--ggui-spacing-2)`, horizontal gap: `var(--ggui-spacing-4)`\n- Error: `var(--ggui-font-size-xs)`, `var(--ggui-color-error-500)`,\n  `role=\"alert\"`\n- Disabled options: `opacity: 0.5`, `cursor: not-allowed`\n\nAccessibility: the group has `role=\"radiogroup\"` with `aria-labelledby` pointing\nto the label and `aria-describedby` pointing to the error message (when present).\nAll radio inputs share a common auto-generated `name` attribute.\n\n**IMPORTANT:** `onChange` receives the selected option's value string directly,\nNOT a React `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Group label rendered above the options. Used as `aria-labelledby` target on the `role=\"radiogroup\"` container. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| value | `string` | - | Controlled value. Should match one of `options[].value`. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the newly selected option's value string directly, NOT a React event. |\n| options | `RadioOption[]` | - | Array of radio options. Must contain at least two options for meaningful selection. |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Layout direction for the options container: - `'vertical'` -- column layout, `var(--ggui-spacing-2)` gap - `'horizontal'` -- row layout with `flex-wrap: wrap`, `var(--ggui-spacing-4)` gap |\n| disabled | `boolean` | `false` | When true, disables ALL options (individual `RadioOption.disabled` is additive). Each option gets `opacity: 0.5` and `cursor: not-allowed`. |\n| error | `string` | - | Error message displayed below all options in `var(--ggui-color-error-500)` with `role=\"alert\"`. Linked to the radiogroup via `aria-describedby`. |\n\n**Example:**\n```tsx\n<RadioGroup\n  label=\"Plan\"\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: 'free', label: 'Free', description: 'Up to 5 projects' },\n    { value: 'pro', label: 'Pro', description: 'Unlimited projects' },\n  ]}\n/>\n```\n\n### Slider\n\nSlider -- A range input with a custom-styled track, fill, and thumb.\n\nRenders a `<div>` wrapper containing an optional label/value header, and a\ntrack area with three layers: background track, colored fill, and a circular\nthumb. A native `<input type=\"range\">` is overlaid with `opacity: 0` to\nprovide accessible keyboard and pointer interaction.\n\nStyling:\n- Track: 6px tall, `var(--ggui-color-outlineVariant)` background, `border-radius: 3px`\n- Fill: `var(--ggui-color-primary-600)` (normal),\n  `var(--ggui-color-outline)` (disabled)\n- Thumb: 20px white circle with `2px solid var(--ggui-color-primary-600)`,\n  `var(--ggui-shape-shadow-sm)`; disabled border uses outline\n- Value display (when `showValue`): `var(--ggui-color-primary-600)`,\n  `var(--ggui-font-size-sm)`, right-aligned in the header row\n- Fill and thumb transitions: 0.1s for smooth dragging\n\nAccessibility: the native `<input type=\"range\">` carries `aria-valuenow`,\n`aria-valuemin`, `aria-valuemax`, and is linked to the label via `aria-labelledby`.\nFalls back to `aria-label=\"Slider\"` when no label is provided.\n\n**IMPORTANT:** `onChange` receives the numeric value directly, NOT a React\n`ChangeEvent`. The value is coerced via `Number(e.target.value)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the slider track (left-aligned). Used as `aria-labelledby` target on the native range input. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| value | `number` | `0` | Controlled numeric value. Must be between `min` and `max`. |\n| onChange | `(value: number) => void` | - | Change handler. Receives the new numeric value directly, NOT a React event. |\n| min | `number` | `0` | Minimum allowed value. |\n| max | `number` | `100` | Maximum allowed value. |\n| step | `number` | `1` | Step increment for the slider. Determines the granularity of selectable values. |\n| disabled | `boolean` | `false` | When true, sets `cursor: not-allowed` on the native input. The fill color changes to `var(--ggui-color-outline)` and the thumb border also uses outline. |\n| showValue | `boolean` | `false` | When true, displays the current numeric value right-aligned in the header row (beside the label) in `var(--ggui-color-primary-600)`. |\n\n**Example:**\n```tsx\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n```\n\n### Badge\n\nBadge -- Inline label for status indicators, counts, or categories.\n\nRenders a `<span>` with `display: inline-flex`, centered content, and\n`white-space: nowrap`. Semantic variant colors use background/text pairings\nfrom the 100/700 color scale. Pill shape uses `border-radius: 9999px`;\nnon-pill uses `var(--ggui-shape-radius-sm)`.\n\nFont weight: `var(--ggui-font-weight-medium)` across all variants.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'default' \\| 'primary' \\| 'secondary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info'` | `'default'` | Visual style. Maps to background/text color pairings: - `'default'` -- bg `var(--ggui-color-surfaceVariant)`, text `var(--ggui-color-onSurfaceVariant)` - `'primary'` -- bg `var(--ggui-color-primary-100)`, text `var(--ggui-color-primary-700)` - `'secondary'` -- bg `var(--ggui-color-outlineVariant)`, text `var(--ggui-color-onSurface)` - `'success'` -- bg `var(--ggui-color-success-100)`, text `var(--ggui-color-success-700)` - `'warning'` -- bg `var(--ggui-color-warning-100)`, text `var(--ggui-color-warning-700)` - `'error'` -- bg `var(--ggui-color-error-100)`, text `var(--ggui-color-error-700)` - `'info'` -- bg `var(--ggui-color-info-100)`, text `var(--ggui-color-info-700)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `2px 6px`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `2px 8px`, font `var(--ggui-font-size-xs)` - `'lg'` -- padding `4px 10px`, font `var(--ggui-font-size-sm)` |\n| pill | `boolean` | `true` | When true, uses fully rounded corners (`border-radius: 9999px`). When false, uses `var(--ggui-shape-radius-sm)`. |\n\n**Example:**\n```tsx\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n```\n\n### Spinner\n\nSpinner -- Animated SVG loading indicator.\n\nRenders an `<svg>` with `role=\"status\"` and `aria-label=\"Loading\"`.\nThe SVG contains a full outlineVariant background circle and a quarter-arc\nforeground stroke in the spinner color.\n\nAnimation: `ggui-spin 1s linear infinite` (360-degree rotation).\nThe `@keyframes ggui-spin` definition is injected inline via a `<style>` tag.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number` | `24` | Width and height of the SVG element in pixels. The internal viewBox is always `0 0 24 24`, so this controls rendered size only. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the animated foreground arc. Same vocabulary as ; the theme decides the resolved value. The background circle always uses `var(--ggui-color-outlineVariant)`.  Use `'inherit'` when the spinner sits inside a colored container (e.g. inside a Button) \u2014 the stroke picks up `currentColor` from the parent so it tracks the container's foreground. |\n\n**Example:**\n```tsx\n<Spinner size={32} tone=\"success\" />\n```\n\n### Avatar\n\nAvatar -- User or entity representation with image or auto-generated initials.\n\nRenders a `<div role=\"img\">` with `overflow: hidden` and `flex-shrink: 0`.\nWhen `src` is provided and loads successfully, renders an `<img>` with\n`object-fit: cover`. On image error (or when no `src`), falls back to\ninitials derived from `name` (up to 2 characters, uppercase).\n\nInitials background: deterministic color from a 5-color palette based on\nname hash (primary-500, success-500, warning-500, error-500, info-500).\nFalls back to `var(--ggui-color-outline)` when no name is given.\nInitials text: white, `font-weight: var(--ggui-font-weight-semibold)`,\n`font-size: resolvedSize * 0.4`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image URL. When provided and the image loads, it is rendered with `object-fit: cover`. On load error, falls back to initials. |\n| name | `string` | - | Name used for two purposes: 1. Generating initials (splits on spaces, takes first letter of each word, max 2). 2. Deterministic background color selection via character code hash. Also used as `aria-label` on the container. Falls back to `'Avatar'` if omitted. |\n| size | `number \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'md'` | Avatar dimensions. Named sizes map to pixel values: - `'xs'` -- 24px - `'sm'` -- 32px - `'md'` -- 40px - `'lg'` -- 48px - `'xl'` -- 64px  Numeric values are used directly as pixel dimensions. |\n| shape | `'circle' \\| 'square'` | `'circle'` | Container shape. - `'circle'` -- `border-radius: 50%` - `'square'` -- `border-radius: var(--ggui-shape-radius-md)` |\n\n**Example:**\n```tsx\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n```\n\n### Alert\n\nAlert -- Contextual message box for important information with icon and optional dismiss.\n\nRenders a `<div role=\"alert\">` with flex layout (12px gap), variant-specific\nbackground, border, text color, and a leading icon. Each variant provides a\ndefault SVG icon (info circle, checkmark, warning triangle, or X circle) that\ncan be overridden via the `icon` prop.\n\nLayout: icon (flex-shrink: 0) | content column (title + body) | close button.\nBorder radius: `var(--ggui-shape-radius-lg)`.\nPadding: `12px 16px`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets: - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)`, icon `var(--ggui-color-info-500)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)`, icon `var(--ggui-color-success-500)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)`, icon `var(--ggui-color-warning-500)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)`, icon `var(--ggui-color-error-500)` |\n| title | `string` | - | Optional title rendered above the body in semibold (`var(--ggui-font-weight-semibold)`), `var(--ggui-font-size-sm)`. Title and body are separated by `var(--ggui-spacing-1)` gap. |\n| closable | `boolean` | `false` | When true, renders a close button (X icon) in the top-right area. The button has `min-width: 28px`, `min-height: 28px`, and `opacity: 0.7`. Requires `onClose` to be functional. |\n| onClose | `() => void` | - | Callback fired when the close button is clicked. Only relevant when `closable` is true. |\n| icon | `ReactNode` | - | Custom icon ReactNode to replace the default variant icon. Rendered at the leading position with the variant's icon color applied via `color` CSS property. |\n\n**Example:**\n```tsx\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n```\n\n### Progress\n\nProgress -- Horizontal progress bar with determinate and indeterminate modes.\n\nRenders a track `<div role=\"progressbar\">` with a colored fill child.\nThe track background is `var(--ggui-color-outlineVariant)` with\npill-shaped corners (border-radius = height / 2).\n\nDeterminate mode: fill width transitions smoothly (`width 0.3s ease`).\nIndeterminate mode: fill is 30% width, animated with\n`ggui-progress-indeterminate 1.5s ease-in-out infinite`\n(translateX from -100% to 400%). The `@keyframes` are injected inline.\n\nAccessibility: `aria-valuenow` is set in determinate mode, omitted in\nindeterminate. `aria-valuemin` is always 0, `aria-valuemax` matches `max`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `number` | - | Current progress value. Clamped to `[0, max]` and converted to a percentage for the fill width: `Math.min(100, Math.max(0, (value / max) * 100))`. |\n| max | `number` | `100` | Maximum value representing 100% progress. |\n| variant | `'default' \\| 'success' \\| 'warning' \\| 'error'` | `'default'` | Fill bar color. Maps to CSS variables: - `'default'` -- `var(--ggui-color-primary-600)` - `'success'` -- `var(--ggui-color-success-500)` - `'warning'` -- `var(--ggui-color-warning-500)` - `'error'` -- `var(--ggui-color-error-500)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track height in pixels: - `'sm'` -- 4px - `'md'` -- 8px - `'lg'` -- 12px |\n| label | `string` | - | Accessible name describing what this bar measures, e.g. `\"Survey progress\"` or `\"Upload\"`. Becomes the progressbar's `aria-label` and \u2014 when `showLabel` is set \u2014 the visible header text in place of the generic word \"Progress\". Always pass this when the surrounding context does not already make the meaning obvious. |\n| showLabel | `boolean` | `false` | When true, displays a header row above the track with the `label` text (or \"Progress\" if `label` is unset) on the left, and the rounded percentage value on the right. |\n| indeterminate | `boolean` | `false` | When true, ignores `value` for visual width and plays a looping animation instead. The fill bar is 30% width and slides across the track. Animation: `ggui-progress-indeterminate 1.5s ease-in-out infinite`. `aria-valuenow` is omitted from the progressbar element. |\n\n**Example:**\n```tsx\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n```\n\n### Image\n\nImage -- An `<img>` element with built-in error handling and fallback support.\n\nRenders a native `<img>` with `display: block`. On load error, either renders\nthe `fallback` ReactNode (if provided) or a default placeholder `<div>` with a\nsurfaceVariant background and a centered image SVG icon in outline.\n\nSize values: numbers are treated as pixels, strings are passed through as-is.\nWhen no `width` is set, defaults to `100%`. When no `height` is set, defaults\nto `auto`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image source URL. Load failure triggers the fallback state. |\n| alt | `string` | - | Alt text for the image. Used as `aria-label` in the error placeholder too. |\n| width | `number \\| string` | `'100%' (applied at render time, not on the type)` | Image width. Numbers are pixels, strings are CSS values (e.g., `'100%'`, `'50vw'`). |\n| height | `number \\| string` | `'auto' (applied at render time, not on the type)` | Image height. Numbers are pixels, strings are CSS values. |\n| objectFit | `'cover' \\| 'contain' \\| 'fill' \\| 'none' \\| 'scale-down'` | `'cover'` | CSS `object-fit` value controlling how the image fills its box. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | - | Corner radius applied to both the image and the error placeholder. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through. |\n| fallback | `ReactNode` | - | Custom ReactNode rendered when the image fails to load. When provided, completely replaces the default error placeholder (no wrapper div). When omitted, a surfaceVariant background div with an image icon is shown. |\n\n**Example:**\n```tsx\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n```\n\n### Icon\n\nIcon -- 185 Lucide icons + emoji passthrough.\n\nThree resolution layers:\n1. **Lucide icon:** pass any common Lucide icon name (e.g. `sun`, `cloud-rain`, `heart`, `shopping-cart`).\n   Accepts kebab-case, camelCase, or PascalCase. Renders as stroke SVG.\n2. **Emoji:** pass emoji/unicode directly (e.g. `\u2600\uFE0F`, `\u{1F327}\uFE0F`). Rendered as text.\n3. **Custom SVG:** pass children (`<svg>` element) for full control.\n\nContainer: `<span>` with `display: inline-flex`, centered content.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| name | `string` | - | Lucide icon name (kebab-case, camelCase, or PascalCase all work). Also accepts emoji/unicode characters directly. |\n| size | `number` | `24` | Icon dimensions in pixels (applied to both width and height of the wrapper and the inner SVG element). |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (icon uses `currentColor`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Resolves to a CSS `color` on the wrapper which the inner SVG inherits via `currentColor`. Use `'inherit'` (the default behavior when unset) for icons that should pick up the parent's foreground color. |\n| children | `ReactNode` | - | Custom SVG children. When provided, `name` is ignored and children are rendered inside a sized `<span>` wrapper. |\n| 'aria-label' | `string` | - | Accessible name for a standalone, meaning-bearing icon. When set, the icon exposes `role=\"img\"` + this label. When omitted (the default) the icon is decorative and hidden from screen readers (`aria-hidden`) \u2014 the right choice for an icon next to a text label. |\n\n**Example:**\n```tsx\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n```\n\n### Link\n\nLink -- Styled anchor element with external link support.\n\nRenders a native `<a>` element. When `external` is true, sets\n`target=\"_blank\"` and `rel=\"noopener noreferrer\"`, and appends a small\n(12px) external-link SVG icon after the children.\n\nTransition: `color 0.2s`.\nUnderline behavior is controlled via mouseEnter/mouseLeave event handlers\n(for the `'hover'` mode).\n\nAlso extends native `AnchorHTMLAttributes` (except `style`/`className`),\nso props like `aria-*`, `data-*`, `title`, etc. are forwarded to the `<a>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| href | `string` | - | Destination URL. Passed directly to the `<a href>` attribute. |\n| external | `boolean` | `false` | When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener noreferrer\"`) and appends a 12px external-link icon after children. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the link text. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a primary-tinted accent (`'loud'`-ish) when unset. |\n| underline | `'always' \\| 'hover' \\| 'none'` | `'hover'` | Underline behavior: - `'always'` -- `text-decoration: underline` at all times - `'hover'` -- underline appears on mouse enter, removed on mouse leave - `'none'` -- no underline ever |\n\n**Example:**\n```tsx\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n```\n\n### Tooltip\n\nTooltip -- Hoverable information popup positioned relative to a trigger element.\n\nWraps `children` in a `<div>` trigger (display: inline-block) and renders\na fixed-position tooltip `<div role=\"tooltip\">` when visible.\n\nTooltip appearance:\n- Background: `var(--ggui-color-onSurface)`\n- Text: white, `var(--ggui-font-size-xs)`\n- Padding: `6px 10px`, border-radius: `var(--ggui-shape-radius-md)`\n- Max width: 200px, `white-space: nowrap`, `pointer-events: none`\n- Z-index: `zIndex.tooltip` (1800)\n\nShow/hide: triggered by mouseEnter/mouseLeave AND focus/blur on the\ntrigger element. Uses `position: fixed` with coordinates calculated from\n`getBoundingClientRect()` and an 8px offset from the trigger edge.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Trigger element. Wrapped in a `<div>` with mouseEnter/mouseLeave and focus/blur handlers. |\n| content | `ReactNode` | - | Tooltip content. Can be text or any ReactNode. |\n| position | `'top' \\| 'bottom' \\| 'left' \\| 'right'` | `'top'` | Tooltip placement relative to the trigger element: - `'top'` -- above, centered horizontally, transformed `translateX(-50%) translateY(-100%)` - `'bottom'` -- below, centered horizontally, transformed `translateX(-50%)` - `'left'` -- to the left, centered vertically, transformed `translateX(-100%) translateY(-50%)` - `'right'` -- to the right, centered vertically, transformed `translateY(-50%)` |\n| delay | `number` | `200` | Delay in milliseconds before the tooltip becomes visible after hover/focus. Hiding is immediate (no delay). |\n\n**Example:**\n```tsx\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n```\n\n### Table\n\nTable -- Data table with sortable columns, striped rows, and hover highlights.\n\nRenders a scrollable wrapper `<div>` containing a native `<table>` with\n`border-collapse: collapse` and `width: 100%`. The wrapper has\n`overflow-x: auto` for horizontal scrolling on narrow viewports.\n\nHeader row: 2px bottom border (`var(--ggui-color-outlineVariant)`).\nData rows: 1px bottom border (`var(--ggui-color-surfaceVariant)`).\nHover: `var(--ggui-color-surface)` background with 150ms ease transition.\nStriped: alternating rows (odd index) get `var(--ggui-color-surface)`.\n\nSort behavior: clicking a sortable column header calls `onSort(key, direction)`.\nIf the same column is clicked again while ascending, it toggles to descending.\nThe component does NOT sort data internally -- the parent must sort `data` and\npass updated `sortKey`/`sortDirection`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `TableColumn<T>[]` | - | Array of column definitions controlling header labels, data keys, and rendering. |\n| data | `T[]` | - | Array of row data objects. Each object's keys should match the column `key` values. |\n| sortKey | `string` | - | The `key` of the currently sorted column. Used to highlight the active sort indicator and determine toggle direction on next click. |\n| sortDirection | `SortDirection` | `'asc'` | Current sort direction for the column identified by `sortKey`. Controls which triangle indicator is highlighted in the header. |\n| onSort | `(key: string, direction: SortDirection) => void` | - | Sort change handler. Called when a sortable column header is clicked. Receives the column `key` and the new `SortDirection`. The component does NOT sort data internally -- you must sort `data` in your state and pass updated `sortKey`/`sortDirection`. |\n| striped | `boolean` | `false` | When true, alternating rows (odd index) get a `var(--ggui-color-surface)` background. |\n| hoverable | `boolean` | `true` | When true, rows highlight with `var(--ggui-color-surface)` on mouse enter, with a 150ms ease background-color transition. |\n| compact | `boolean` | `false` | When true, reduces cell padding: - Compact: `var(--ggui-spacing-1) var(--ggui-spacing-2)` - Normal: `var(--ggui-spacing-2) var(--ggui-spacing-4)` |\n| bordered | `boolean` | `false` | When true, adds a 1px border around the table wrapper and between cells. Wrapper border: `1px solid var(--ggui-color-outlineVariant)`. Cell borders: `1px solid var(--ggui-color-surfaceVariant)`. Wrapper border-radius: `var(--ggui-shape-radius-lg)`. |\n| caption | `string` | - | Accessible table caption. Rendered as a `<caption>` element with `caption-side: top`, `var(--ggui-font-size-sm)`, `var(--ggui-color-onSurfaceVariant)`. |\n\n**Example:**\n```tsx\n<Table\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'role', header: 'Role' },\n    { key: 'status', header: 'Status', render: (v) => <Badge variant={v as string}>{v as string}</Badge> },\n  ]}\n  data={users}\n  sortKey={sortKey}\n  sortDirection={sortDir}\n  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}\n  striped\n/>\n```\n\n### Tabs\n\nTabs -- Accessible tab navigation with panels and keyboard support.\n\nRenders a `<div role=\"tablist\">` with `<button role=\"tab\">` elements and a\n`<div role=\"tabpanel\">` for the active tab's content. Supports controlled\n(`activeKey` + `onChange`) and uncontrolled (internal state) modes.\n\nKeyboard navigation: ArrowLeft/ArrowRight (and ArrowUp/ArrowDown) cycle\nthrough enabled tabs. Home/End jump to first/last. Focus follows selection.\nDisabled tabs are skipped during keyboard navigation.\n\n**IMPORTANT:** `onChange` receives the tab's `key` string directly, NOT a\nReact event.\n\nTab panel padding: `var(--ggui-spacing-4) 0` (top/bottom only).\nTransitions: color, background-color, border-color at 200ms ease-in-out.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `TabItem[]` | - | Array of tab definitions. Must contain at least one item. |\n| activeKey | `string` | - | Controlled active tab key. When provided, the component is controlled and will not manage its own state. Must match one of `items[].key`. When omitted, defaults to the first item's key (uncontrolled mode). |\n| onChange | `(key: string) => void` | - | Tab change handler. Receives the selected tab's `key` string directly, NOT a React event. In controlled mode, you must update `activeKey` in response to this callback. |\n| variant | `'line' \\| 'pills' \\| 'enclosed'` | `'line'` | Visual style of the tab bar: - `'line'` -- underline indicator (2px solid primary-600 on active), border-bottom on tab list - `'pills'` -- filled pill buttons (primary-600 bg, white text on active), surfaceVariant container with radius-lg - `'enclosed'` -- bordered tab buttons with open bottom (card-style), border-bottom on tab list |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls tab button padding and font size: - `'sm'` -- padding `var(--ggui-spacing-1) var(--ggui-spacing-2)`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `var(--ggui-spacing-2) var(--ggui-spacing-4)`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `var(--ggui-spacing-4) var(--ggui-spacing-6)`, font `var(--ggui-font-size-base)` |\n| fullWidth | `boolean` | `false` | When true, tab buttons expand equally to fill the container width (`flex: 1`, `justify-content: center` on each button). |\n\n**Example:**\n```tsx\n<Tabs\n  variant=\"pills\"\n  items={[\n    { key: 'overview', label: 'Overview', content: <Overview /> },\n    { key: 'settings', label: 'Settings', content: <Settings /> },\n  ]}\n  activeKey={tab}\n  onChange={setTab}\n/>\n```\n\n### Toast\n\nToast -- Notification banner with auto-dismiss and slide-in animation.\n\nRenders a `<div role=\"alert\" aria-live=\"assertive\">` with a variant-specific\nicon, optional title, message body, and optional close button.\n\nAnimation: `ggui-slideInUp 200ms ease-out both` on mount (from the motion\ntoken system). The keyframes are provided by the MotionKeyframes provider.\n\nAuto-dismiss: when `onClose` is provided and `duration > 0`, a timer calls\n`onClose` after `duration` ms. Setting `duration` to `0` disables auto-dismiss.\nThe timer resets if `visible`, `duration`, or `onClose` changes.\n\nDimensions: `min-width: 280px`, `max-width: 420px`.\nShadow: `var(--ggui-shape-shadow-lg)`.\nBorder radius: `var(--ggui-shape-radius-lg)`.\n\nWhen `visible` is false, renders nothing (returns `null`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| message | `ReactNode` | - | Message body content. Can be text or any ReactNode. |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets (same palette as Alert): - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)` |\n| title | `string` | - | Optional title rendered above the message in semibold (`var(--ggui-font-weight-semibold)`, `var(--ggui-font-size-sm)`). |\n| duration | `number` | `5000` | Auto-dismiss delay in milliseconds. After this duration, `onClose` is called automatically. Set to `0` to disable auto-dismiss (toast stays until manually closed). The timer is only active when both `visible` is true and `onClose` is provided. |\n| onClose | `() => void` | - | Callback fired on auto-dismiss timeout or when the close button is clicked. When provided, a close button (X icon, 16px) is rendered in the top-right area. When omitted, no close button is shown and auto-dismiss is disabled. |\n| visible | `boolean` | `true` | Controls rendering. When false, the component returns `null`. Toggling from false to true triggers the slide-in animation. |\n| position | `'top-right' \\| 'top-left' \\| 'bottom-right' \\| 'bottom-left' \\| 'top-center' \\| 'bottom-center'` | - | Intended screen position. This prop is defined on the interface but is NOT implemented by the Toast component itself -- positioning must be handled by a parent container or toast manager. |\n\n**Example:**\n```tsx\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n```\n\n### Accordion\n\nAccordion -- Collapsible content sections with chevron rotation animation.\n\nRenders a vertical list of items, each with a `<button>` header (inside `<h3>`)\nand a `<div role=\"region\">` panel. Supports controlled (`expandedKeys` + `onChange`)\nand uncontrolled (internal state) modes.\n\nChevron animation: the trailing chevron icon rotates from 0deg (collapsed) to\n180deg (expanded) with `transition: transform 200ms ease-in-out`.\n\nHeader button: full-width flex layout (`justify-content: space-between`),\n`var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n`var(--ggui-color-onSurface)`.\nHeader padding: `var(--ggui-spacing-2) var(--ggui-spacing-4)`.\nBackground transition: `background-color 100ms ease-in-out`.\n\n**IMPORTANT:** `onChange` receives the full array of currently expanded keys,\nNOT a single key or a React event. In single mode (`multiple: false`), this\narray will have at most one element.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `AccordionItem[]` | - | Array of collapsible section definitions. |\n| expandedKeys | `string[]` | - | Controlled expanded state. Array of item `key` values that should be open. When provided, the component is controlled and will not manage its own expansion state. When omitted, defaults to `[]` (all collapsed, uncontrolled mode). |\n| onChange | `(expandedKeys: string[]) => void` | - | Expand/collapse handler. Receives the complete array of expanded keys after a toggle. In controlled mode, you must update `expandedKeys` in response to this callback. |\n| multiple | `boolean` | `false` | When true, multiple items can be open simultaneously. When false, opening one item closes any other open item (single-expand mode). |\n| variant | `'default' \\| 'bordered' \\| 'separated'` | `'default'` | Visual style controlling borders and spacing: - `'default'` -- top border on first item, bottom border on all items (`var(--ggui-color-outlineVariant)`), no gap between items - `'bordered'` -- connected card style with left/right/bottom borders on all items, top border on first, shared rounded corners (radius-lg on first/last) - `'separated'` -- each item is an independent card with full border (`1px solid var(--ggui-color-outlineVariant)`), `var(--ggui-shape-radius-lg)` radius, `var(--ggui-spacing-2)` gap between items |\n\n**Example:**\n```tsx\n<Accordion\n  variant=\"separated\"\n  items={[\n    { key: 'faq1', title: 'How do I get started?', content: 'Sign up and...' },\n    { key: 'faq2', title: 'What is the pricing?', content: 'We offer...' },\n  ]}\n  expandedKeys={expanded}\n  onChange={setExpanded}\n  multiple\n/>\n```\n\n### Support Types\n\n**ResponsiveColumns:**\n\nExplicit column count per viewport breakpoint, mobile-first. `base`\napplies from 0 up; each named key overrides at and above its\nbreakpoint width (`sm` 640px, `md` 768px, `lg` 1024px, `xl` 1280px).\nOmit `base` to default to a single column on the narrowest screens.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| base | `number` | Columns below the `sm` breakpoint. |\n| sm | `number` | Columns from 640px up. |\n| md | `number` | Columns from 768px up. |\n| lg | `number` | Columns from 1024px up. |\n| xl | `number` | Columns from 1280px up. |\n\n**SelectOption:**\n\nAn individual option within a `Select` dropdown.\n\nRendered as a native `<option>` element. When `disabled` is true, the option\nis visible but not selectable.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value submitted when this option is selected. Must be unique within the options array. |\n| label | `string` | The display text shown in the dropdown. |\n| disabled | `boolean` | When true, the option is visible but cannot be selected (grayed out by the browser). |\n\n**RadioOption:**\n\nAn individual option within a `RadioGroup`.\n\nRendered as a `<label>` containing a visually-hidden `<input type=\"radio\">`\nand a custom 18px circle indicator. Supports an optional description line\nbelow the label text.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value emitted via `RadioGroupProps.onChange` when this option is selected. Must be unique. |\n| label | `string` | Display text for this option. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSurfaceVariant)`. |\n| description | `string` | Optional secondary description rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSurfaceVariant)`). |\n| disabled | `boolean` | When true, this individual option is grayed out (`opacity: 0.5`) and cannot be selected, regardless of the group-level `disabled` prop. |\n\n**TableColumn:**\n\nColumn definition for the Table component.\n\nEach column maps a `key` in the row data object to a table column with\na header label, optional sorting, alignment, width, and custom rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key in the row data object. Used to extract cell values via `row[key]`. Must be unique across all columns in a Table. |\n| header | `string` | Column header text. Rendered in uppercase, `var(--ggui-font-size-xs)`, `var(--ggui-font-weight-semibold)`, `var(--ggui-color-onSurfaceVariant)`, with `letter-spacing: 0.05em`. |\n| width | `number \\| string` | Fixed column width. Numbers are pixels, strings are CSS values (e.g., `'200px'`, `'30%'`). When omitted, the column auto-sizes based on content. |\n| align | `'left' \\| 'center' \\| 'right'` | Horizontal text alignment for both the header and data cells. |\n| sortable | `boolean` | When true, the header cell becomes clickable and shows sort direction indicators (ascending/descending triangles). Clicking toggles between `'asc'` and `'desc'`. The header gets `cursor: pointer`, `tabIndex: 0`, and keyboard support (Enter/Space to toggle). |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When provided, called instead of rendering `row[key]` directly. Receives the cell value, the full row object, and the row index. |\n\n**TabItem:**\n\nDefinition of a single tab within a Tabs component.\n\nEach item provides a unique `key` for identification, a `label` for the\ntab button, and `content` for the associated panel.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this tab. Used to match `activeKey` and as the value passed to `onChange`. |\n| label | `ReactNode` | Tab button label. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the tab bar when this tab is active. |\n| disabled | `boolean` | When true, the tab button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be selected via click or keyboard navigation. |\n| icon | `ReactNode` | Optional icon rendered before the label inside the tab button, with `var(--ggui-spacing-1)` gap between icon and label. |\n\n**AccordionItem:**\n\nDefinition of a single collapsible section within an Accordion.\n\nEach item provides a unique `key`, a clickable `title` for the header button,\nand `content` revealed when expanded.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this item. Used in `expandedKeys` and passed to `onChange`. |\n| title | `ReactNode` | Header label rendered inside the toggle button. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the header when expanded. Styled with `var(--ggui-font-size-sm)`, `var(--ggui-color-onSurfaceVariant)`, `line-height: var(--ggui-font-lineHeight-normal)`. Padding: `0 var(--ggui-spacing-4) var(--ggui-spacing-4)`. |\n| disabled | `boolean` | When true, the header button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be toggled. |\n\n\n## Components\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### SearchField\n\nA text input with a leading search icon and optional submit button.\n\nComposes: `Input` (native `<input type=\"search\">`), `Button`, `Spinner`, `Icon`.\n\nSupports controlled and uncontrolled usage. When `value` is `undefined` the\ncomponent tracks its own state internally. Pressing **Enter** triggers\n`onSearch` with the current value. When `loading` is `true` the search icon\nis replaced by a `Spinner` and the input is disabled.\n\nTokens used: `colors.gray[300]` border, `colors.gray[50]` disabled bg,\n`colors.gray[400]` icon color, `colors.gray[900]` text color.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | - | Current search value. When provided, the component is **controlled** and the caller must update this via `onChange`. When omitted, the component manages its own internal state. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React `ChangeEvent`). |\n| onSearch | `(value: string) => void` | - | Called when the user presses **Enter** or clicks the search button (if `showButton` is `true`). Receives the current value directly. |\n| placeholder | `string` | `'Search...'` | Placeholder text shown when the input is empty. |\n| showButton | `boolean` | `false` | When `true`, renders a `Button` primitive to the right of the input. The button's label is set by `buttonText`. |\n| buttonText | `string` | `'Search'` | Label rendered inside the submit button. Only visible when `showButton` is `true`. |\n| loading | `boolean` | - | When `true`, replaces the search icon with a `Spinner`, disables the input, and disables the submit button. |\n| disabled | `boolean` | - | When `true`, the input and button are visually disabled and do not respond to interaction. The input background changes to `colors.gray[50]`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls input height and font size. - `'sm'` -- 6px vertical padding, 14px font - `'md'` -- 10px vertical padding, 14px font - `'lg'` -- 12px vertical padding, 16px font  The Button size maps `sm`->`sm`, `md`->`md`, `lg`->`md`. |\n\n**Example:**\n```tsx\n```tsx\n<SearchField\n  value={query}\n  onChange={setQuery}\n  onSearch={(q) => fetchResults(q)}\n  placeholder=\"Search products...\"\n  showButton\n  buttonText=\"Go\"\n  size=\"md\"\n/>\n```\n```\n\n### FormField\n\nA wrapper that adds a label, optional description, error message,\nand helper text around any form input passed as `children`.\n\nComposes: no other primitives -- pure layout with semantic `<label>` and\n`<span>` elements.\n\nVisual hierarchy (top to bottom):\n1. **Label** (required) -- `fontSize.sm`, `fontWeight.medium`, `colors.gray[700]`\n2. **Required indicator** -- red asterisk (`colors.error[500]`) appended to label\n3. **Description** -- `fontSize.xs`, `colors.gray[500]`, 4px bottom margin\n4. **Children** -- the form control itself\n5. **Error / Helper text** -- `fontSize.xs`; error in `colors.error[500]`,\n   helper in `colors.gray[500]`. Error takes priority when both are provided.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Text rendered inside the `<label>` element above the input. |\n| children | `ReactNode` | - | The form control (typically an `Input`, `Select`, or `Textarea` primitive) rendered between the label/description and the error/helper row. |\n| error | `string` | - | Error message displayed below `children` in `colors.error[500]`. When present, it takes precedence over `helperText`. |\n| helperText | `string` | - | Neutral guidance text displayed below `children` in `colors.gray[500]`. Hidden when `error` is present. |\n| required | `boolean` | - | When `true`, appends a red asterisk (`*`) after the label text. Does **not** add any HTML validation attributes -- handle that on the child input. |\n| description | `string` | - | Secondary description rendered between the label and the child control in `fontSize.xs` / `colors.gray[500]`. Use for longer guidance that does not belong in `helperText`. |\n\n**Example:**\n```tsx\n```tsx\n<FormField\n  label=\"Email address\"\n  required\n  description=\"We will never share your email.\"\n  error={errors.email}\n>\n  <Input value={email} onChange={setEmail} placeholder=\"you@example.com\" />\n</FormField>\n```\n```\n\n### MenuItem\n\nA full-width clickable row for menus, sidebars, and action lists.\n\nComposes: none -- renders a native `<button>` element.\n\nBuilt-in transition: `background-color 0.15s` on hover.\n\nColor logic:\n- **Normal**: text `colors.gray[700]`, hover bg `colors.gray[100]`\n- **Active**: bg `colors.primary[50]`, text `colors.gray[700]`, `fontWeight.medium`\n- **Danger**: text `colors.error[600]`, hover bg `colors.error[50]`, active bg `colors.error[100]`\n- **Disabled**: text `colors.gray[400]`, `cursor: not-allowed`\n\nLayout: flexbox row with `8px` gap, `8px 12px` padding, `radius.md` border-radius.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary text content of the menu item. |\n| icon | `ReactNode` | - | Icon or element rendered to the left of the label. Flex-shrink 0. |\n| rightElement | `ReactNode` | - | Element rendered to the right of the label (e.g., a keyboard shortcut badge or a count). Colored `colors.gray[400]`, flex-shrink 0. |\n| onClick | `() => void` | - | Called when the item is clicked. Suppressed when `disabled` is `true`. |\n| disabled | `boolean` | - | When `true`, the item is non-interactive: `colors.gray[400]` text, `cursor: not-allowed`, click handler suppressed. |\n| active | `boolean` | - | Marks this item as the current selection. Applies a tinted background (`colors.primary[50]`, or `colors.error[100]` when `danger` is also set) and `fontWeight.medium`. |\n| danger | `boolean` | - | Switches the item to destructive styling: `colors.error[600]` text, `colors.error[50]` hover background. |\n\n**Example:**\n```tsx\n```tsx\n<MenuItem\n  label=\"Delete project\"\n  icon={<Icon name=\"trash\" size={16} />}\n  danger\n  onClick={() => confirmDelete(projectId)}\n/>\n```\n```\n\n### Tag\n\nAn inline label for categories, filters, statuses, or selections.\nOptionally dismissable via a close button.\n\nComposes: none -- pure `<span>` with an optional close `<button>`.\n\nEach `variant` maps to a background / text / border color triple from the\ndesign tokens:\n- `'default'`  -- `gray[100]` / `gray[700]` / `gray[200]`\n- `'primary'`  -- `primary[50]` / `primary[700]` / `primary[200]`\n- `'success'`  -- `success[50]` / `success[700]` / `success[200]`\n- `'warning'`  -- `warning[50]` / `warning[700]` / `warning[200]`\n- `'error'`    -- `error[50]` / `error[700]` / `error[200]`\n- `'info'`     -- `info[50]` / `info[700]` / `info[200]`\n\nThe close button renders an inline SVG \"x\" icon (12x12) with `opacity: 0.7`\nand an `aria-label=\"Remove\"`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Tag content -- typically a short text string. |\n| variant | `'default' \\| 'primary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info'` | `'default'` | Semantic color variant applied to background, text, and border. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and internal gap. - `'sm'` -- 2px/6px padding, `fontSize.xs`, 4px gap - `'md'` -- 4px/8px padding, `fontSize.xs`, 6px gap - `'lg'` -- 6px/10px padding, `fontSize.sm`, 6px gap |\n| closable | `boolean` | - | When `true`, renders a small close (\"x\") button after the content. Clicking it fires `onClose`. |\n| onClose | `() => void` | - | Called when the close button is clicked. Only relevant when `closable` is `true`. |\n| icon | `ReactNode` | - | Icon or element rendered before the text content. |\n\n**Example:**\n```tsx\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n```\n\n### Dropdown\n\nA click-triggered menu anchored to a trigger element. Manages its own\nopen/close state internally.\n\nComposes: `MenuItem` for each option.\n\nBehavior:\n- Clicking the trigger toggles the menu open/closed.\n- Selecting an option calls `onChange(option.value)` and closes the menu.\n- Clicking outside the container or pressing **Escape** closes the menu.\n- The currently selected option (matching `value`) is rendered with\n  `MenuItem`'s `active` state.\n\nMenu panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, 160px min-width, 4px padding.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| trigger | `ReactNode` | - | The element the user clicks to open the menu. Receives a wrapping `<div>` with `cursor: pointer` (or `not-allowed` when disabled). |\n| options | `DropdownOption[]` | - | Array of selectable options rendered as `MenuItem` rows. |\n| value | `string` | - | The `value` of the currently selected option. The matching `MenuItem` is rendered with `active` styling. |\n| onChange | `(value: string) => void` | - | Called with the `value` string of the selected option (not the full `DropdownOption` object). The menu closes immediately after. |\n| placement | `'bottom-start' \\| 'bottom-end' \\| 'top-start' \\| 'top-end'` | `'bottom-start'` | Where to anchor the menu panel relative to the trigger. - `'bottom-start'` -- below, aligned to left edge - `'bottom-end'`   -- below, aligned to right edge - `'top-start'`    -- above, aligned to left edge - `'top-end'`      -- above, aligned to right edge |\n| disabled | `boolean` | - | When `true`, the trigger shows `cursor: not-allowed` and clicking it does not open the menu. |\n\n**Example:**\n```tsx\n```tsx\n<Dropdown\n  trigger={<Button variant=\"outline\">Sort by</Button>}\n  options={[\n    { value: 'name', label: 'Name' },\n    { value: 'date', label: 'Date created' },\n    { value: 'delete', label: 'Delete', danger: true },\n  ]}\n  value={sortBy}\n  onChange={setSortBy}\n  placement=\"bottom-end\"\n/>\n```\n```\n\n### Autocomplete\n\nA text input with a filterable suggestion dropdown, keyboard navigation,\nand loading/empty states.\n\nComposes: `Input` primitive (with `label`, `error`, `placeholder` forwarded),\n`Spinner` (loading state).\n\nFiltering: options are filtered client-side by case-insensitive substring\nmatch against both `option.label` and `option.value`.\n\nKeyboard support:\n- **ArrowDown / ArrowUp** -- move highlight through filtered options\n  (opens dropdown if closed)\n- **Enter** -- selects the highlighted option\n- **Escape** -- closes the dropdown\n\nOn selection, `onChange` is called with `option.label` (the display text)\nand `onSelect` is called with the full `AutocompleteOption` object.\n\nDropdown panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, max-height 240px with\noverflow scroll.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | `''` | Current text in the input field. On selection, this is set to the selected option's `label`. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React event). Also called on selection with `option.label`. |\n| onSelect | `(option: AutocompleteOption) => void` | - | Called when the user selects an option (click or Enter on highlighted item). Receives the full `AutocompleteOption` object, not just the value string. |\n| options | `AutocompleteOption[]` | - | The full list of available options. Filtering is handled internally via case-insensitive substring match on `label` and `value`. |\n| placeholder | `string` | - | Placeholder text forwarded to the inner `Input` primitive. |\n| label | `string` | - | Label text forwarded to the inner `Input` primitive. |\n| loading | `boolean` | - | When `true`, the dropdown shows a centered `Spinner` instead of the option list. The input remains interactive. |\n| disabled | `boolean` | - | When `true`, the inner `Input` is disabled and the dropdown does not open. |\n| error | `string` | - | Error message forwarded to the inner `Input` primitive. |\n| noResultsText | `string` | `'No results found'` | Text shown in the dropdown when filtering produces zero matches. Rendered centered in `colors.gray[500]` / `fontSize.sm`. |\n\n**Example:**\n```tsx\n```tsx\n<Autocomplete\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  onSelect={(opt) => setCountryCode(opt.value)}\n  options={countries}\n  placeholder=\"Type to search...\"\n  noResultsText=\"No countries found\"\n/>\n```\n```\n\n### Breadcrumb\n\nA horizontal navigation trail showing the user's location within a\nhierarchy. Renders a `<nav aria-label=\"Breadcrumb\">`.\n\nComposes: `Link` primitive (for items with `href`).\n\nRendering rules per item:\n- **Last item**: static `<span>` with `colors.gray[900]`, `fontWeight: 500`,\n  and `aria-current=\"page\"`.\n- **Non-last with `href`**: `Link` in `colors.gray[500]` with\n  `underline=\"hover\"`. If `onItemClick` is provided, `e.preventDefault()`\n  is called and the handler fires instead of navigating.\n- **Non-last without `href`**: unstyled `<button>` in `colors.gray[500]`.\n\nLayout: flexbox row, `8px` gap, `fontSize.sm`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `BreadcrumbItem[]` | - | Ordered array of breadcrumb segments from root to current page. |\n| separator | `ReactNode` | `'/'` | Separator rendered between each pair of items. Can be a string (e.g., `\"/\"`, `\">\"`) or a ReactNode (e.g., an `Icon`). Rendered in `colors.gray[400]`. |\n| onItemClick | `(item: BreadcrumbItem, index: number) => void` | - | Called when a non-last item is clicked. Receives the `BreadcrumbItem` and its zero-based `index`. When provided on items that have `href`, the default navigation is prevented via `e.preventDefault()`. |\n\n**Example:**\n```tsx\n```tsx\n<Breadcrumb\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Projects', href: '/projects' },\n    { label: 'ggui' },\n  ]}\n  separator=\"/\"\n  onItemClick={(item) => router.push(item.href!)}\n/>\n```\n```\n\n### Pagination\n\nPage navigation controls with previous/next arrows, numbered page buttons,\nand optional first/last jumps. Renders a `<nav aria-label=\"Pagination\">`.\n\nComposes: `Button` (ghost variant for prev/next/first/last arrows),\n`Icon` (`chevron-left`, `chevron-right`).\n\nBuilt-in transition: `all 0.15s` on page number buttons.\n\nPage windowing: when `totalPages > maxVisible`, the component shows the\nfirst page, last page, a window of pages around `currentPage`, and\nellipsis (\"...\") markers for gaps. The window adjusts when near the\nstart or end of the range.\n\nActive page button: `colors.primary[600]` bg, `colors.white` text,\n`fontWeight.medium`. Inactive: transparent bg, `colors.gray[700]` text.\n\nArrow buttons are automatically disabled at boundary pages (first/last).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| currentPage | `number` | - | Current active page. **1-indexed** (first page is `1`). |\n| totalPages | `number` | - | Total number of pages. Determines when last-page / next-page buttons disable. |\n| onPageChange | `(page: number) => void` | - | Called when the user clicks a page number, arrow, or first/last button. Receives the target page number (1-indexed) directly. |\n| showFirstLast | `boolean` | `true` | When `true`, renders double-chevron buttons for jumping to the first and last page. These buttons are disabled when already on the respective boundary. |\n| maxVisible | `number` | `5` | Maximum number of page buttons visible at once (including the first and last page, but excluding ellipsis markers). When `totalPages` exceeds this value, ellipsis gaps appear. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls button dimensions and icon sizes. - `'sm'` -- 28px buttons, 14px icons, Button size `xs` - `'md'` -- 32px buttons, 16px icons, Button size `sm` - `'lg'` -- 40px buttons, 20px icons, Button size `md` |\n| disabled | `boolean` | - | When `true`, all page buttons and arrows are visually dimmed (`opacity: 0.5`) and clicks are suppressed. |\n\n**Example:**\n```tsx\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n```\n\n### EmptyState\n\nEmptyState -- placeholder for a region with no data: empty lists,\nzero search results, an error fallback. Render it instead of\nnothing whenever a data array could be empty \u2014 a list that shows\nnothing when empty looks broken.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| icon | `string \\| ReactNode` | - | A Lucide icon name (kebab-case), rendered large and subtle above the title, or a custom node. Omit for a text-only empty state. |\n| title | `string` | - | The headline, e.g. \"No results found\". |\n| description | `string` | - | Optional supporting line below the title. |\n| action | `ReactNode` | - | Optional call-to-action, typically a `<Button>`. |\n\n**Example:**\n```tsx\n{results.length === 0\n  ? <EmptyState icon=\"search-x\" title=\"No matches\" description=\"Try a broader query.\" />\n  : results.map((r) => <Row key={r.id}>\u2026</Row>)}\n```\n\n### Stat\n\nStat -- a single KPI / metric: a label, a large value, an optional\ntrend-coloured delta and icon. Reach for it whenever the UI is\n\"show a number\" \u2014 dashboards, weather and price cards, analytics\ntiles. Drop several into a `<Grid>` for a stat grid.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | The metric name, e.g. \"Revenue\". Rendered small and uppercase above the value. |\n| value | `string \\| number` | - | The headline value \u2014 the big number. A number, or a pre-formatted string (`\"$48.2k\"`, `\"18\xB0C\"`). |\n| delta | `string` | - | Optional change indicator, pre-formatted, e.g. `\"+12.5%\"` or `\"-3\"`. |\n| trend | `'up' \\| 'down' \\| 'neutral'` | `'neutral'` | Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error, `'neutral'` muted. |\n| icon | `string \\| ReactNode` | - | Optional Lucide icon name (kebab-case) or custom node, shown next to the label. |\n\n**Example:**\n```tsx\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n```\n\n### Stepper\n\nStepper -- a display-only step indicator for multi-step flows\n(wizards, checkouts, onboarding): numbered markers joined by\nconnector lines, with completed (check), current (filled), and\nupcoming (outlined) states styled distinctly.\n\nStepper renders step state; it never owns it. Declare the step\nlabels as a top-level `const`, track the current index in\n`useState`, and advance it from your own Next/Back buttons (or\n`onStepClick`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| steps | `string[]` | - | Ordered step labels, one per step. Declare as a top-level `const` array \u2014 never as state. |\n| current | `number` | - | Zero-based index of the active step. Steps before it render as completed (check mark), steps after it as upcoming. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Flow direction. `'horizontal'` joins the markers with connector lines in a row; `'vertical'` stacks the steps with short connector columns \u2014 better for sidebars or long step labels. |\n| onStepClick | `(index: number) => void` | - | When provided, each step becomes a real button and clicks receive the step's zero-based index. Typical use: jumping back to a completed step; guard forward jumps in the handler if the flow validates per step. |\n\n**Example:**\n```tsx\nconst STEPS = ['Account', 'Profile', 'Review'];\n// In the component: const [step, setStep] = useState(0);\n<Stack gap=\"lg\">\n  <Stepper steps={STEPS} current={step} />\n  {step === 0 && <AccountFields />}\n  <Row gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\" disabled={step === 0} onClick={() => setStep(step - 1)}>Back</Button>\n    <Button onClick={() => setStep(step + 1)}>Next</Button>\n  </Row>\n</Stack>\n```\n\n### Markdown\n\nMarkdown -- renders markdown-formatted text as styled content:\nheadings, paragraphs, **bold** / *italic*, `inline code`, fenced\ncode blocks, bulleted and numbered lists, pipe tables, and links.\n\nUse it whenever a prop or context slot carries prose the agent\nauthors in markdown -- article bodies, AI-generated explanations,\ndescriptions, notes, help text. Pass the raw markdown string\nstraight through; never pre-parse it, never split it into per-line\n`Text` elements, and never rebuild formatting with nested\n`<strong>`/`<em>` markup yourself.\n\nSafe by construction: raw HTML in the source displays as literal\ntext (never markup), and links render inert unless their scheme is\nhttp(s)/mailto. Streaming-tolerant: a mid-stream prefix parses\ncleanly and completed constructs never change shape, so binding a\ngrowing string re-renders correctly.\n\nFor a single line of formatted text INSIDE another element (a table\ncell, a list row, a caption), use `MarkdownInline` instead -- same\n`markdown` prop, inline-level constructs only (no headings, lists,\nor code fences), renders inside the parent's typography.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Markdown source text, passed through verbatim. Supports the conversational subset: `#`-`###` headings, paragraphs, bold, italic, inline code, fenced code blocks, `-`/`1.` lists, `\\|` pipe tables, and `[label](url)` links. Bind stateful or streamed prose directly. |\n\n**Example:**\n```tsx\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n```\n\n### MarkdownInline\n\nMarkdownInline -- renders ONE line of inline-level markdown (bold,\nitalic, inline code, links) inside the parent's typography -- a table\ncell, a list row, a caption, a summary line. Same `markdown` prop as\n`Markdown`; block constructs (headings, lists, code fences) are not\nrendered -- reach for `Markdown` for multi-paragraph bodies.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Inline markdown source -- bold, italic, inline code, and `[label](url)` links. Block-level syntax renders as plain text. |\n\n**Example:**\n```tsx\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n```\n\n### Support Types\n\n**DropdownOption:**\n\nA single option inside a `Dropdown`. Each option maps to one `MenuItem`\ninternally.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier returned to `onChange` when this option is selected. |\n| label | `string` | Human-readable text shown in the menu row. |\n| icon | `ReactNode` | Optional icon rendered to the left of the label via `MenuItem.icon`. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive. |\n| danger | `boolean` | When `true`, the option uses destructive (red) styling via `MenuItem.danger`. |\n\n**AutocompleteOption:**\n\nA single option in the `Autocomplete` suggestion list.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier for this option. Also used for case-insensitive filtering against the input value. |\n| label | `string` | Primary display text. Also used for case-insensitive filtering and is written into the input on selection. |\n| description | `string` | Secondary description rendered below the label in `fontSize.xs` / `colors.gray[500]`. |\n| icon | `ReactNode` | Icon rendered to the left of the label/description block. Flex-shrink 0. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive (`cursor: not-allowed`, `colors.gray[400]` text). |\n\n**BreadcrumbItem:**\n\nA single segment in a `Breadcrumb` trail. Items with `href` render as\n`Link` primitives; items without render as plain `<button>` elements.\nThe last item in the array is always rendered as static text with\n`aria-current=\"page\"`.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for this breadcrumb segment. |\n| href | `string` | URL for this segment. When provided (and this is not the last item), the segment renders as a `Link` primitive with `underline=\"hover\"`. When omitted, it renders as a `<button>`. |\n| icon | `ReactNode` | Icon rendered immediately before the label. Its color follows the segment's text color: `colors.gray[500]` for navigable items, `colors.gray[900]` for the current (last) item. |\n\n\n## Compositions\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Header\n\nProps for the `Header` composition.\n\nA horizontal page header that arranges a logo, navigation, and action slots\nin a flex row (`justify-content: space-between`). Internally renders a `<header>` element;\ndoes not compose other ggui primitives.\n\nWhen `sticky` is true the header gets `position: sticky; top: 0` with `zIndex.sticky`\nand a `shadow.sm` box-shadow.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| logo | `ReactNode` | - | Logo or brand element rendered at the start (flex-shrink: 0). |\n| navigation | `ReactNode` | - | Navigation content rendered in a `<nav>` element with `flex: 1` and a 32 px left margin. |\n| actions | `ReactNode` | - | Right-side action elements (buttons, avatar, etc.) rendered with a 12 px gap. |\n| sticky | `boolean` | `false` | When true, the header becomes `position: sticky` at the top of its scroll container with `zIndex.sticky` and `shadow.sm`. |\n| background | `string` | `colors.white` | Background color of the header. |\n| bordered | `boolean` | `true` | When true, renders a 1 px bottom border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Header\n  logo={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  navigation={<a href=\"/docs\">Docs</a>}\n  actions={<Button size=\"sm\">Sign In</Button>}\n  sticky\n  bordered\n/>\n```\n```\n\n### Sidebar\n\nProps for the `Sidebar` composition.\n\nA vertical navigation panel that composes the `Icon` primitive for chevron indicators.\nItems are rendered as `<button>` elements inside a scrollable `<nav>`. Nested items\nare indented 16 px per depth level. The sidebar animates width changes with a 200 ms\nCSS transition. Active items are highlighted with `colors.primary[50]` background\nand `colors.primary[700]` text.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `SidebarItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Matched items get a highlighted background and bold text. |\n| onItemClick | `(item: SidebarItem) => void` | - | Called when any item (including parent items with children) is clicked. |\n| collapsed | `boolean` | `false` | When true, hides labels and badges; only icons remain visible, centered in the collapsed width. Nested children are hidden entirely. |\n| header | `ReactNode` | - | Content rendered above the item list, separated by a bottom border. |\n| footer | `ReactNode` | - | Content rendered below the item list, separated by a top border. |\n| width | `number` | `256` | Width in pixels when expanded. |\n| collapsedWidth | `number` | `64` | Width in pixels when collapsed. |\n\n**Example:**\n```tsx\n```tsx\n<Sidebar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'settings', label: 'Settings', icon: <Icon name=\"settings\" />,\n      children: [\n        { id: 'profile', label: 'Profile' },\n        { id: 'billing', label: 'Billing' },\n      ]},\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.href)}\n  collapsed={false}\n  width={256}\n/>\n```\n```\n\n### CardGrid\n\nProps for the `CardGrid` composition.\n\nA CSS Grid wrapper that arranges children in equal-width columns. When `columns`\nis a number, it produces `repeat(N, 1fr)`. When it is a responsive object,\nit falls back to `repeat(auto-fit, minmax(280px, 1fr))` for fluid responsive behavior.\n\nDoes not compose any ggui primitives internally \u2014 it is a pure layout container.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Card elements to arrange in the grid. |\n| columns | `number \\| { sm?: number; md?: number; lg?: number }` | `3` | Number of columns, or a responsive breakpoint map.  - `number` \u2014 fixed column count via `repeat(N, 1fr)`. - `{ sm?, md?, lg? }` \u2014 triggers `repeat(auto-fit, minmax(280px, 1fr))` for fluid layout. |\n| gap | `number` | `16` | Gap between grid items in pixels. |\n\n**Example:**\n```tsx\n```tsx\n<CardGrid columns={3} gap={24}>\n  <Card>A</Card>\n  <Card>B</Card>\n  <Card>C</Card>\n</CardGrid>\n```\n```\n\n### CommentThread\n\nProps for the `CommentThread` composition.\n\nA threaded comment section that composes `Avatar`, `Button`, `TextArea`, and `Spinner`\nprimitives. Comments are rendered recursively with 40 px indentation per nesting level.\nEach comment shows author avatar, name, timestamp, content, reactions, and a \"Reply\" toggle.\nWhen `currentUser` is provided, a new-comment input with avatar and submit button is shown\nabove the thread.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| comments | `Comment[]` | - | Array of top-level comments to render. Replies are nested within each comment. |\n| currentUser | `{     /** Display name for the current user's avatar. */     name: string;     /** Avatar image URL for the current user. */     avatar?: string;   }` | - | Current user info. When provided, a new-comment input area is rendered above the thread. |\n| onAddComment | `(content: string, parentId?: string) => void` | - | Called when the user submits a new top-level comment. |\n| onReply | `(commentId: string, content: string) => void` | - | Called when the user submits a reply to an existing comment. |\n| onReaction | `(commentId: string, emoji: string) => void` | - | Called when the user clicks an emoji reaction on a comment. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the comment list. |\n\n**Example:**\n```tsx\n```tsx\n<CommentThread\n  comments={[\n    { id: '1', author: { name: 'Alice' }, content: 'Great work!', timestamp: new Date(),\n      replies: [{ id: '2', author: { name: 'Bob' }, content: 'Thanks!', timestamp: new Date() }] }\n  ]}\n  currentUser={{ name: 'Alice', avatar: '/alice.jpg' }}\n  onAddComment={(content) => post(content)}\n  onReply={(commentId, content) => reply(commentId, content)}\n  onReaction={(commentId, emoji) => react(commentId, emoji)}\n/>\n```\n```\n\n### DataTable\n\nProps for the `DataTable` composition.\n\nA sortable, selectable data table that composes `Checkbox`, `Spinner`, and `Icon`\nprimitives. Renders a `<table>` inside a bordered container with 8 px border-radius.\nThe header row has a `colors.gray[50]` background. Sortable columns show a chevron\nicon on click (toggles asc/desc). Selected rows are highlighted with `colors.primary[50]`.\nRow background transitions use a 150 ms ease. The \"select all\" checkbox supports an\nindeterminate state when a subset of rows is selected.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `DataTableColumn<T>[]` | - | Column definitions that control header, alignment, sorting, and rendering. |\n| data | `T[]` | - | Row data array. Each entry corresponds to one table row. |\n| rowKey | `string \\| ((row: T) => string)` | `'id'` | Property name or function used to derive a unique key for each row. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of table body rows. |\n| emptyText | `string` | `'No data'` | Text shown when `data` is empty and not loading. |\n| onSort | `(key: string, direction: 'asc' \\| 'desc') => void` | - | Called when a sortable column header is clicked. Toggles direction automatically (asc -> desc) if the same column is clicked again. |\n| sortKey | `string` | - | The column key currently being sorted. |\n| sortDirection | `'asc' \\| 'desc'` | - | The current sort direction. |\n| onRowClick | `(row: T, index: number) => void` | - | Called when a row is clicked. Rows get `cursor: pointer` when this handler is provided. |\n| selectable | `boolean` | - | When true, adds a checkbox column at the start of each row. |\n| selectedKeys | `string[]` | `[]` | Array of currently selected row keys. |\n| onSelectionChange | `(keys: string[]) => void` | - | Called when the set of selected row keys changes (via row checkbox or select-all). |\n\n**Example:**\n```tsx\n```tsx\n<DataTable\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'email', header: 'Email' },\n    { key: 'role', header: 'Role', render: (v) => <Badge>{v}</Badge> },\n  ]}\n  data={users}\n  rowKey=\"id\"\n  selectable\n  selectedKeys={selected}\n  onSelectionChange={setSelected}\n  onSort={(key, dir) => sort(key, dir)}\n  sortKey=\"name\"\n  sortDirection=\"asc\"\n/>\n```\n```\n\n### ChatWindow\n\nProps for the `ChatWindow` composition.\n\nA messaging interface that composes `Avatar`, `Button`, `Spinner`, and `Icon` primitives.\nLayout is a flex column filling 100% height with a bordered `radius.lg` container.\nMessages from the current user align right with `colors.primary[600]` bubbles and white text.\nOther users' messages align left with `colors.gray[100]` bubbles. The message area\nauto-scrolls to the bottom on new messages via `scrollIntoView({ behavior: 'smooth' })`.\nThe text input sends on Enter (Shift+Enter for newline).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| messages | `ChatMessage[]` | - | Array of chat messages to display in chronological order. |\n| currentUserId | `string` | - | ID of the current user. Messages from this user render right-aligned with a primary color bubble. |\n| onSendMessage | `(content: string) => void` | - | Called when the user submits a message (Enter key or send button). |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the message list. |\n| typing | `{ name: string } \\| null` | - | When non-null, displays a typing indicator below the last message (e.g., \"Alice is typing...\"). |\n| placeholder | `string` | `'Type a message...'` | Placeholder text for the message input field. |\n| header | `ReactNode` | - | Optional header content rendered above the message area, separated by a bottom border. |\n\n**Example:**\n```tsx\n```tsx\n<ChatWindow\n  messages={messages}\n  currentUserId=\"user-1\"\n  onSendMessage={(content) => send(content)}\n  typing={{ name: 'Alice' }}\n  placeholder=\"Type a message...\"\n  header={<h3>Chat with Alice</h3>}\n/>\n```\n```\n\n### NavigationBar\n\nProps for the `NavigationBar` composition.\n\nA horizontal or vertical navigation menu. Does not compose other ggui primitives\n(uses plain `<button>` and `<a>` elements). Active items are styled per variant:\n\n- `'default'` \u2014 active item gets `colors.primary[600]` text and medium font weight.\n- `'pills'` \u2014 active item gets a `radius.full` pill with `colors.primary[100]` background.\n- `'underline'` \u2014 active item gets a 2 px bottom border in `colors.primary[600]`.\n  When horizontal, the entire nav also has a 1 px bottom border.\n\nAll items have a 150 ms transition on all properties.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `NavItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Controls visual highlighting per variant style. |\n| onItemClick | `(item: NavItem) => void` | - | Called when a non-disabled item is clicked. For `<a>` elements, `preventDefault` is called first. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Layout direction. - `'horizontal'` \u2014 flex-row with 4 px gap. - `'vertical'` \u2014 flex-column with 2 px gap. |\n| variant | `'default' \\| 'pills' \\| 'underline'` | `'default'` | Visual style for active/inactive items. - `'default'` \u2014 text color change only. - `'pills'` \u2014 rounded pill background on active items. - `'underline'` \u2014 bottom border on active items. |\n\n**Example:**\n```tsx\n```tsx\n<NavigationBar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'about', label: 'About' },\n    { id: 'contact', label: 'Contact' },\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.id)}\n  orientation=\"horizontal\"\n  variant=\"pills\"\n/>\n```\n```\n\n### FileUploader\n\nProps for the `FileUploader` composition.\n\nA drag-and-drop file upload area that composes `Button`, `Progress`, and `Icon` primitives.\nThe drop zone is a dashed-border container that highlights in `colors.primary[400]`/`colors.primary[50]`\non drag-over. Below the drop zone, each file in `files` is listed with its name, size,\noptional progress bar (for uploading status), and a remove button.\n\nFile validation (max size, max count) is applied client-side before calling `onFilesSelected`.\nFiles exceeding `maxSize` are silently filtered out; files exceeding `maxFiles` are truncated.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| files | `UploadedFile[]` | `[]` | Array of files currently in the upload queue, shown below the drop zone. |\n| onFilesSelected | `(files: File[]) => void` | - | Called when the user selects files via click or drag-and-drop. Receives native `File` objects after client-side filtering (maxSize, maxFiles). |\n| onFileRemove | `(fileId: string) => void` | - | Called when the user clicks the remove button on a file entry. |\n| accept | `string` | - | Accepted file types passed to the hidden `<input type=\"file\" accept=\"...\">`. E.g., `'image/*,.pdf'`. |\n| multiple | `boolean` | `true` | When true, allows selecting multiple files at once. |\n| maxSize | `number` | - | Maximum file size in bytes. Files exceeding this are silently excluded from the selection. |\n| maxFiles | `number` | - | Maximum number of files. Excess files beyond `maxFiles - files.length` are truncated. |\n| disabled | `boolean` | - | When true, the drop zone is visually dimmed (opacity 0.5) and non-interactive. |\n| dragDrop | `boolean` | `true` | When true, enables drag-and-drop on the drop zone. When false, the prompt text changes to \"Click to browse files\". |\n\n**Example:**\n```tsx\n```tsx\n<FileUploader\n  files={uploadedFiles}\n  onFilesSelected={(files) => startUpload(files)}\n  onFileRemove={(id) => removeFile(id)}\n  accept=\"image/*,.pdf\"\n  multiple\n  maxSize={5 * 1024 * 1024}\n  maxFiles={10}\n  dragDrop\n/>\n```\n```\n\n### NotificationCenter\n\nProps for the `NotificationCenter` composition.\n\nA notification list with a header bar that composes `Button`, `Spinner`, and `Icon`\nprimitives. The header shows a \"Notifications\" title, an unread count badge\n(pill in `colors.primary[100]`), and \"Mark all read\" / \"Clear all\" buttons.\nEach notification item shows a colored status dot, title, message, timestamp,\n\"Mark as read\" link, and optional action. The list is scrollable (`overflowY: auto`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| notifications | `Notification[]` | - | Array of notifications to display, in the order provided. |\n| onMarkAsRead | `(id: string) => void` | - | Called when the user clicks \"Mark as read\" on an individual notification. |\n| onMarkAllAsRead | `() => void` | - | Called when the user clicks the \"Mark all read\" header button. Only shown when there are unread items. |\n| onDismiss | `(id: string) => void` | - | Called when the user clicks the dismiss (X) button on an individual notification. |\n| onClearAll | `() => void` | - | Called when the user clicks the \"Clear all\" header button. Only shown when there are any notifications. |\n| emptyText | `string` | `'No notifications'` | Text shown when `notifications` is empty and not loading. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the notification list. |\n\n**Example:**\n```tsx\n```tsx\n<NotificationCenter\n  notifications={[\n    { id: '1', title: 'Deployment complete', type: 'success', timestamp: new Date(), read: false },\n    { id: '2', title: 'Build failed', type: 'error', message: 'Lint errors', timestamp: new Date() },\n  ]}\n  onMarkAsRead={(id) => markRead(id)}\n  onMarkAllAsRead={() => markAllRead()}\n  onDismiss={(id) => dismiss(id)}\n  onClearAll={() => clearAll()}\n/>\n```\n```\n\n### Modal\n\nProps for the `Modal` composition.\n\nA dialog overlay that composes `Button`, `Icon`, and `Heading` primitives.\nThe overlay uses `animation.fadeIn` (`ggui-fadeIn`) and the dialog panel uses\n`animation.scaleIn` (`ggui-scaleIn`) \u2014 both GPU-composited (opacity + transform).\nWhen open, `document.body.style.overflow` is set to `'hidden'` to prevent background\nscrolling, and restored on close. The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`.\n\nSize widths: `sm` = 400 px, `md` = 500 px, `lg` = 640 px, `xl` = 800 px,\n`full` = 100vw (no border-radius, no padding).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls modal visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the modal (overlay click, escape key, or close button). |\n| title | `string` | - | Optional title rendered in the modal header via the `Heading` primitive (level 4). |\n| children | `ReactNode` | - | Modal body content rendered in a scrollable area (`overflowY: auto`). |\n| footer | `ReactNode` | - | Footer content rendered below the body, right-aligned with an 8 px gap, separated by a top border. |\n| size | `'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'` | Controls the width of the modal panel. - `'sm'` \u2014 400 px - `'md'` \u2014 500 px - `'lg'` \u2014 640 px - `'xl'` \u2014 800 px - `'full'` \u2014 100vw, no border-radius, stretches to fill viewport |\n| closeOnOverlayClick | `boolean` | `true` | When true, clicking the semi-transparent overlay behind the modal calls `onClose`. |\n| closeOnEscape | `boolean` | `true` | When true, pressing the Escape key calls `onClose`. |\n| showCloseButton | `boolean` | `true` | When true, renders a ghost close button (X icon) in the modal header. |\n\n**Example:**\n```tsx\n```tsx\n<Modal\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  title=\"Confirm Action\"\n  size=\"md\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleConfirm}>Confirm</Button>\n    </>\n  }\n>\n  <p>Are you sure you want to proceed?</p>\n</Modal>\n```\n```\n\n### CommandPalette\n\nProps for the `CommandPalette` composition.\n\nA searchable command menu (Cmd+K / Ctrl+K pattern) that composes `Spinner` and `Icon`\nprimitives. Appears as a centered overlay at 15vh from the top. Commands are filtered\nby label and description (case-insensitive substring match). Results are grouped under\nuppercase section headers. Keyboard navigation is fully supported:\nArrow Up/Down to navigate, Enter to select, Escape to close.\n\nWhen `recentIds` are provided and the search query is empty, matching commands appear\nin a \"Recent\" section at the top (deduplicated from their original groups).\n\nThe footer shows navigation hints: \"Up/Down Navigate\", \"Enter Select\", \"Esc Close\".\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls palette visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the palette (overlay click, Escape key, or after command selection). |\n| commands | `Command[]` | - | Full array of available commands. Filtered client-side by the search query. |\n| onSelect | `(command: Command) => void` | - | Called when a non-disabled command is selected (Enter key or click). The palette auto-closes after selection. |\n| placeholder | `string` | `'Search commands...'` | Placeholder text for the search input. |\n| recentIds | `string[]` | `[]` | IDs of recently used commands. When the query is empty, these appear in a \"Recent\" section at the top of the results. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the command list. |\n\n**Example:**\n```tsx\n```tsx\n<CommandPalette\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  commands={[\n    { id: 'new', label: 'New File', shortcut: 'Ctrl+N', group: 'File' },\n    { id: 'save', label: 'Save', shortcut: 'Ctrl+S', group: 'File' },\n    { id: 'theme', label: 'Toggle Theme', group: 'Preferences' },\n  ]}\n  onSelect={(cmd) => executeCommand(cmd.id)}\n  recentIds={['save']}\n  placeholder=\"Search commands...\"\n/>\n```\n```\n\n### Footer\n\nProps for the `Footer` composition.\n\nA site footer with `role=\"contentinfo\"` that lays out a brand slot, link columns,\nsocial icons, and a bottom bar. Does not compose other ggui primitives (uses plain\nHTML elements). Content is constrained to `max-width: 1280px` with auto margins.\nLink columns use a responsive flex layout (`flex: 0 1 180px`). The bottom bar\nincludes copyright text, social links, and bottom-bar links separated by a top border.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| brand | `ReactNode` | - | Brand element (logo, tagline) rendered in a flexible column (`flex: 1 1 280px`). |\n| columns | `FooterColumn[]` | - | Array of link columns rendered in a flex-wrap layout with 48 px gap. |\n| socialLinks | `FooterSocialLink[]` | - | Social media icon links rendered in the bottom bar. |\n| bottomText | `string` | - | Text displayed at the start of the bottom bar (e.g., copyright notice). |\n| bottomLinks | `FooterLink[]` | - | Links displayed in the bottom bar after social icons (e.g., Privacy, Terms). |\n| background | `string` | `colors.gray[50]` | Background color of the footer. |\n| bordered | `boolean` | `true` | When true, renders a 1 px top border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Footer\n  brand={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  columns={[\n    { title: 'Product', links: [{ label: 'Features', href: '/features' }] },\n    { title: 'Company', links: [{ label: 'About', href: '/about' }] },\n  ]}\n  socialLinks={[\n    { label: 'Twitter', href: 'https://twitter.com/acme', icon: <TwitterIcon /> },\n  ]}\n  bottomText=\"&copy; 2026 Acme Inc.\"\n  bottomLinks={[{ label: 'Privacy', href: '/privacy' }]}\n  bordered\n/>\n```\n```\n\n### Hero\n\nProps for the `Hero` composition.\n\nA prominent landing-page hero section that renders heading, description, CTA buttons,\nand an optional media slot. Does not compose other ggui primitives (uses plain HTML\nelements styled with design tokens). Content is constrained to `max-width: 1280px`.\n\nLayout modes:\n- `align='center'` \u2014 single-column centered layout with `max-width: 800px` text area.\n- `align='left'` \u2014 two-column side-by-side layout (50/50 split with media slot).\n\nSize controls vertical padding and font sizes:\n- `'sm'` \u2014 48 px vertical padding, 3xl heading, lg description.\n- `'md'` \u2014 80 px vertical padding, 4xl heading, xl description.\n- `'lg'` \u2014 120 px vertical padding, 5xl heading, xl description.\n\nThe primary action button uses `colors.primary[600]` fill; the secondary action uses\nan outlined style. When `overlay` is true with a `backgroundImage`, text switches to white\nand borders become semi-transparent.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| heading | `string` | - | Main heading text rendered as an `<h1>` with bold weight and tight line-height. |\n| description | `string` | - | Description paragraph rendered below the heading with relaxed line-height. |\n| primaryAction | `HeroAction` | - | Primary CTA button rendered with `colors.primary[600]` background and white text. |\n| secondaryAction | `HeroAction` | - | Secondary CTA button rendered with a transparent background and a 1 px border. |\n| media | `ReactNode` | - | Media element (image, video, illustration) rendered beside or below the text content. |\n| align | `'center' \\| 'left'` | `'center'` | Text and layout alignment. - `'center'` \u2014 centered single-column layout. - `'left'` \u2014 left-aligned text with media in a right column (50/50 split). |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls vertical padding and heading/description font sizes. - `'sm'` \u2014 compact (48 px padding, 3xl/lg fonts). - `'md'` \u2014 standard (80 px padding, 4xl/xl fonts). - `'lg'` \u2014 spacious (120 px padding, 5xl/xl fonts). |\n| background | `string` | `colors.white (when no backgroundImage is set)` | Background color of the hero section. |\n| backgroundImage | `string` | - | Background image URL applied as `background-size: cover; background-position: center`. |\n| overlay | `boolean` | `false` | When true and `backgroundImage` is set, renders a semi-transparent black overlay (`rgba(0,0,0,0.5)`) and switches text to white/semi-transparent white for contrast. |\n\n**Example:**\n```tsx\n```tsx\n<Hero\n  heading=\"Build Better UIs, Faster\"\n  description=\"The universal interface layer between AI agents and humans.\"\n  primaryAction={{ label: 'Get Started', onClick: () => navigate('/signup') }}\n  secondaryAction={{ label: 'Learn More', href: '/docs' }}\n  media={<img src=\"/hero.png\" alt=\"Hero\" />}\n  align=\"left\"\n  size=\"lg\"\n/>\n```\n```\n\n### Support Types\n\n**SidebarItem:**\n\nA single navigation entry in a `Sidebar`. Supports nested children for\ncollapsible sub-menus and an optional badge slot.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the item. Hidden when the sidebar is collapsed. |\n| icon | `ReactNode` | Leading icon rendered before the label. Remains visible when collapsed. |\n| href | `string` | Optional URL associated with this item (not rendered as a link by default). |\n| badge | `ReactNode` | Trailing badge element (e.g., unread count). Hidden when collapsed. |\n| children | `SidebarItem[]` | Nested child items. When present, the item acts as a collapsible section (chevron indicator shown). |\n| disabled | `boolean` | When true, the item is visually dimmed and non-interactive (`cursor: not-allowed`). |\n\n**Comment:**\n\nA single comment entry in a `CommentThread`. Supports nested replies\nand emoji reactions with counts.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this comment. |\n| author | `{     /** Display name of the author. */     name: string;     /** URL for the author's avatar image. Passed to the `Avatar` primitive. */     avatar?: string;   }` | Comment author metadata. |\n| content | `string` | The comment body text. |\n| timestamp | `string \\| Date` | Timestamp of the comment. Rendered via `toLocaleString()` when a `Date` object. |\n| replies | `Comment[]` | Nested reply comments. Each reply is rendered indented 40 px deeper. |\n| reactions | `{ emoji: string; count: number }[]` | Emoji reactions with their aggregated counts (e.g., `{ emoji: \"\u{1F44D}\", count: 3 }`). |\n\n**DataTableColumn:**\n\nColumn definition for a `DataTable`. Controls header text, width, alignment,\nsorting, and custom cell rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key on the row object used to extract cell values. Also serves as the sort key. |\n| header | `string` | Column header text displayed in the `<thead>`. |\n| width | `number \\| string` | Column width as a CSS value (number for pixels, string for any CSS unit). |\n| sortable | `boolean` | When true, the column header is clickable and triggers `onSort`. An arrow icon indicates direction. |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When omitted, the raw value is stringified via `String()`. |\n| align | `'left' \\| 'center' \\| 'right'` | Text alignment for both header and body cells. |\n\n**ChatMessage:**\n\nA single message in a `ChatWindow`. Includes sender metadata, delivery status,\nand a timestamp.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this message. |\n| content | `string` | The message body text. |\n| sender | `{     /** Unique ID of the sender. Compared to `currentUserId` to determine alignment. */     id: string;     /** Display name of the sender. */     name: string;     /** Avatar image URL. Only shown for non-current-user messages (xs size). */     avatar?: string;   }` | Sender metadata used for avatar rendering and alignment. |\n| timestamp | `string \\| Date` | Message timestamp. Rendered as `HH:MM` via `toLocaleTimeString` when a `Date` object. |\n| status | `'sending' \\| 'sent' \\| 'delivered' \\| 'read' \\| 'error'` | Delivery status indicator shown on the current user's messages. - `'sending'` \u2014 shows a dot bullet - `'sent'` \u2014 shows a single checkmark - `'delivered'` \u2014 shows double checkmarks - `'read'` \u2014 shows double checkmarks (same visual as delivered) - `'error'` \u2014 shows an exclamation mark |\n\n**NavItem:**\n\nA single navigation entry in a `NavigationBar`. Supports nested children\nfor sub-menus (rendered by the parent via dropdown, not built-in).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the navigation link. |\n| href | `string` | URL for the item. When provided, renders an `<a>` element instead of `<button>`. |\n| icon | `ReactNode` | Optional icon rendered before the label. |\n| children | `NavItem[]` | Nested child items (for sub-menu structures; rendering is consumer-defined). |\n| disabled | `boolean` | When true, the item is visually dimmed (opacity 0.5) and non-interactive. |\n\n**UploadedFile:**\n\nA file entry in the `FileUploader` composition. Tracks upload progress,\nstatus, and optional error messages.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this file entry. Used as a key and for removal callbacks. |\n| name | `string` | Original file name. Rendered with text-overflow ellipsis when too long. |\n| size | `number` | File size in bytes. Formatted as B/KB/MB/GB for display. |\n| type | `string` | MIME type of the file (e.g., `'image/png'`). |\n| progress | `number` | Upload progress as a percentage (0-100). Shown via the `Progress` primitive when status is `'uploading'`. |\n| status | `'pending' \\| 'uploading' \\| 'success' \\| 'error'` | Current upload lifecycle status. - `'pending'` \u2014 file selected but upload not started. - `'uploading'` \u2014 upload in progress; `progress` bar is shown. - `'success'` \u2014 upload completed. - `'error'` \u2014 upload failed; `error` message is shown in `colors.error[500]`. |\n| error | `string` | Error message displayed when status is `'error'`. |\n| url | `string` | The remote URL of the uploaded file after successful upload. |\n\n**Notification:**\n\nA single notification entry in the `NotificationCenter`. Supports semantic type coloring,\nread state, and an optional inline action button.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this notification. |\n| title | `string` | Notification title rendered in medium weight. |\n| message | `string` | Optional body text rendered below the title in a smaller font. |\n| timestamp | `string \\| Date` | Timestamp of the notification. Rendered via `toLocaleString()` when a `Date` object. |\n| read | `boolean` | Read state. Unread notifications get a `colors.primary[50]` background and a colored status dot matching the notification type. |\n| type | `'info' \\| 'success' \\| 'warning' \\| 'error'` | Semantic type that controls the status dot color on unread notifications. - `'info'` \u2014 `colors.info[500]` (blue) - `'success'` \u2014 `colors.success[500]` (green) - `'warning'` \u2014 `colors.warning[500]` (amber) - `'error'` \u2014 `colors.error[500]` (red) |\n| icon | `ReactNode` | Optional icon rendered alongside the notification (not used by the default implementation). |\n| action | `{     /** Button label text. */     label: string;     /** Click handler for the action. */     onClick: () => void;   }` | Optional inline action button rendered next to the timestamp. |\n\n**Command:**\n\nA single command entry in a `CommandPalette`. Commands can be grouped,\nhave keyboard shortcuts, and support a disabled state.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this command. |\n| label | `string` | Display label for the command. Searchable by the palette's query filter. |\n| description | `string` | Optional description text shown below the label. Also searchable. |\n| icon | `ReactNode` | Icon rendered at the start of the command row. |\n| shortcut | `string` | Keyboard shortcut hint displayed at the end of the row in a `<kbd>` element. |\n| group | `string` | Group name for visual sectioning. Commands with the same group are rendered under a shared header. Defaults to `'Commands'` if omitted. |\n| disabled | `boolean` | When true, the command is visually dimmed and cannot be selected. |\n\n**FooterLink:**\n\nA single link entry in a footer column or the bottom bar. Supports both\n`href` navigation and `onClick` handlers (onClick takes precedence via `preventDefault`).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for the link. |\n| href | `string` | URL for the link. |\n| onClick | `() => void` | Click handler. When provided, `preventDefault` is called on the anchor click. |\n\n**FooterColumn:**\n\nA named column of links in the `Footer` layout. Each column has an optional title\nand a list of links rendered as a vertical stack with 10 px gap.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| title | `string` | Column heading rendered as an `<h4>` with semibold weight. |\n| links | `FooterLink[]` | Links displayed in this column. |\n\n**FooterSocialLink:**\n\nA social media link in the `Footer` bottom bar. Rendered as an icon-only anchor\nwith `aria-label` for accessibility.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Accessible label for the social link (used as `aria-label`). |\n| href | `string` | URL for the social media profile or page. |\n| icon | `ReactNode` | Icon element rendered inside the anchor (typically an SVG or `Icon` primitive). |\n\n**HeroAction:**\n\nA call-to-action button definition for the `Hero` composition.\nUsed for both the primary (filled) and secondary (outlined) action buttons.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Button label text. |\n| onClick | `() => void` | Click handler for the button. |\n| href | `string` | Optional URL (not used by the default implementation; available for consumer routing). |\n\n\n## System Conventions\n\n### onChange Behavior (CRITICAL)\n\nAll form control onChange handlers receive the VALUE DIRECTLY, not a React event object.\n\n```tsx\n// CORRECT \u2014 onChange receives value directly\n<Input value={name} onChange={setName} />\n<Input value={email} onChange={(value) => setEmail(value)} />\n<Select value={country} onChange={setCountry} options={countries} />\n<Checkbox checked={agreed} onChange={setAgreed} />\n\n// WRONG \u2014 DO NOT use e.target.value!\n<Input value={name} onChange={(e) => setName(e.target.value)} /> // WILL BREAK\n```\n\nApplies to: Input, TextArea, Select, Checkbox, RadioGroup, Slider, Tabs, Accordion.\n\n### Available Motion & Animation\n\nRender `<MotionKeyframes />` once (anywhere in tree) to enable all keyframes.\n\n**Entrance/exit:** fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n**State feedback:** flash (background-color highlight), pulse (opacity breathing), bounce (scale overshoot)\n**Easing:** linear, easeIn, easeOut, easeInOut, spring (bouncy)\n**Durations:** instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n\n```tsx\n// Entrance animation on mount\n<div style={{ animation: 'ggui-fadeIn 200ms ease-out' }}>Content</div>\n\n// Stagger list items\n{items.map((item, i) => (\n  <div key={item.id} style={{ animation: \\`ggui-slideInUp 300ms ease-out \\${i * 50}ms both\\` }}>\n    {item.name}\n  </div>\n))}\n\n// Flash highlight when data changes (e.g., stock price update)\n// useAnimationKey returns a key that increments when dep changes \u2192 remounts element \u2192 replays animation\nconst priceKey = useAnimationKey(stock.price);\n<div key={priceKey} style={{\n  animation: animation.flash,\n  '--ggui-flash-color': stock.change > 0 ? 'var(--ggui-color-success-100)' : 'var(--ggui-color-error-100)',\n} as React.CSSProperties}>\n  {stock.price}\n</div>\n\n// Respect reduced-motion preference\nconst { motionEnabled } = useMotion();\n<div style={motionEnabled ? { animation: 'ggui-scaleIn 200ms ease-out' } : undefined}>\n  Content\n</div>\n```\n\n### Elevation System\n\n6 levels mapping shadow intensity to z-index for layering:\n- Level 0: flat (no shadow, z: auto) \u2014 inline content\n- Level 1: sm shadow (z: auto) \u2014 cards, sections\n- Level 2: md shadow (z: 1000) \u2014 dropdowns, popovers\n- Level 3: lg shadow (z: 1200) \u2014 sticky banners\n- Level 4: xl shadow (z: 1400) \u2014 modals, dialogs\n- Level 5: 2xl shadow (z: 1800) \u2014 tooltips, toasts\n\n### Import Constraints\n\nOnly these imports are allowed:\n- `react`\n- `@ggui-ai/design` \u2014 the whole design system (primitives, components, compositions, and the `Clickable` / `Hoverable` / `Pressable` traits) is one import; there are no subpaths\n- `@ggui-ai/wire` (wire hooks)\n\nNo external libraries (lodash, date-fns, etc.). No fetch(). No eval().";
+    PRIMITIVES_DOCUMENTATION = "# ggui Primitives & Design System Reference\n\n> You are a world-class UI engineer working with ggui's component library for the first time.\n> This reference documents every available component, prop, and convention.\n> Components handle theming automatically via built-in variants \u2014 pick the right variant and the theme does the rest.\n> For custom styling beyond variants, use CSS variables: var(--ggui-*, fallback).\n\n## Primitives\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Container\n\nContainer -- Width-constrained wrapper that centers content horizontally.\n\nRenders a `<div>` with `width: 100%` and a `maxWidth` constraint.\nWhen `center` is true (the default), applies `margin: 0 auto`.\nNo background, border, or shadow -- use Card for visual containment.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| maxWidth | `'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| 'full' \\| string` | `'lg'` | Maximum width constraint. Accepts a preset token or any CSS width string. - `'xs'` -- 320px - `'sm'` -- 480px - `'md'` -- 640px - `'lg'` -- 768px - `'xl'` -- 1024px - `'2xl'` -- 1280px - `'3xl'` -- 1536px - `'full'` -- 100%  Custom strings (e.g., `'900px'`, `'60ch'`) are passed through as-is. |\n| center | `boolean` | `true` | Whether to center the container horizontally via `margin: 0 auto`. |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Container maxWidth=\"xl\" padding=\"var(--ggui-spacing-6)\">\n  <Stack gap=\"var(--ggui-spacing-4)\">\n    <Heading level={1}>Dashboard</Heading>\n    <Card shadow=\"md\" padding=\"var(--ggui-spacing-5)\">\n      <Text>Welcome back!</Text>\n    </Card>\n  </Stack>\n</Container>\n```\n\n### Card\n\nCard -- Container with background, shadow, and optional border.\n\nRenders a `<div>` with:\n- Background: `var(--ggui-color-container)`\n- Border (when enabled): `1px solid var(--ggui-color-outlineVariant)`\n- Shadow and radius controlled by design tokens via CSS variables.\n- No built-in transitions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'lg'` | Padding applied to all sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| shadow | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'sm'` | Shadow elevation level. Maps to design tokens: - `'none'` -- no shadow - `'sm'` -- var(--ggui-shape-shadow-sm) -- subtle, default - `'md'` -- var(--ggui-shape-shadow-md) -- dialogs, emphasized sections - `'lg'` -- var(--ggui-shape-shadow-lg) -- floating panels - `'xl'` -- var(--ggui-shape-shadow-xl) -- popovers, modals |\n| border | `boolean` | `true` | Whether to render a 1px border using `var(--ggui-color-outlineVariant)`. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'lg'` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'transparent'` | `'default'` | Semantic surface slot. Same vocabulary as ; see that prop's docs for the full slot table. Default Card surface is `'default'` (the active theme's `--ggui-color-container`); pair with `shadow=\"md\"\\|\"lg\"` for elevated cards, or use `'inverted'` for a dark testimonial-style card on a light theme. |\n\n**Example:**\n```tsx\n<Card shadow=\"md\" padding=\"lg\" radius=\"lg\">\n  <Stack gap=\"md\">\n    <Text size=\"sm\" weight=\"medium\">Settings</Text>\n    <Input label=\"Name\" value={name} onChange={setName} />\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Card>\n```\n\n### Stack\n\nStack -- Flexbox layout primitive for arranging children along a single axis.\n\nRenders a `<div>` with `display: flex`. Default layout is vertical (column).\nAll flex shorthand values (`align`, `justify`, `wrap`) are abstracted into\nsemantic prop names.\n\nCSS variables used: none (pure layout primitive).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Main axis direction. - `'vertical'` -- `flex-direction: column` - `'horizontal'` -- `flex-direction: row` |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'sm'` | Gap between children. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n| align | `'start' \\| 'center' \\| 'end' \\| 'stretch'` | `'stretch'` | Cross-axis alignment (maps to `align-items`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'stretch'` -- stretch (children fill cross-axis) |\n| justify | `'start' \\| 'center' \\| 'end' \\| 'between' \\| 'around' \\| 'evenly'` | `'start'` | Main-axis content distribution (maps to `justify-content`). - `'start'` -- flex-start - `'center'` -- center - `'end'` -- flex-end - `'between'` -- space-between - `'around'` -- space-around - `'evenly'` -- space-evenly |\n| wrap | `boolean` | `false` | Whether children wrap to the next line when they overflow. Maps to `flex-wrap: wrap` when true. |\n\n**Example:**\n```tsx\n<Stack gap=\"lg\" align=\"center\">\n  <Heading level={2}>Profile</Heading>\n  <Text>Edit your account details below.</Text>\n  <Stack direction=\"horizontal\" gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\">Cancel</Button>\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Stack>\n```\n\n### Grid\n\nGrid -- 2-D layout primitive. Arranges children into rows AND\ncolumns; reach for it when Stack/Row's single-axis flow isn't\nenough (card galleries, dashboards, stat grids).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| columns | `number \\| ResponsiveColumns` | `2` | Column count. Three forms: - a number \u2014 that many equal columns at every width (`columns={3}`); - a  map \u2014 explicit counts per breakpoint   (`columns={{ base: 1, md: 3 }}` = 1 column on mobile, 3 from `md`).   Use this when the request names exact per-breakpoint counts   (\"3 per row on desktop, 1 on mobile\"). Ignored entirely when `minColumnWidth` is set. |\n| gap | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `'md'` | Gap between cells. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`); a number is pixels. |\n| minColumnWidth | `number \\| string` | `undefined (use `columns`)` | When set, the grid becomes responsive \u2014 it fits as many equal columns as possible, each at least this wide, and `columns` is ignored. A number is treated as pixels. |\n\n**Example:**\n```tsx\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n```\n\n### Skeleton\n\nSkeleton -- a pulsing placeholder for content that has not loaded\nyet. ggui UIs are agent-driven (props arrive late, streams start\nempty), so a loading frame is the rule \u2014 render `Skeleton` instead\nof a blank screen or a hand-rolled pulsing `<div>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| variant | `'rect' \\| 'text' \\| 'circle'` | `'rect'` | Shape preset. - `'rect'` -- a block (default); pair with `width` / `height`. - `'text'` -- a single text line (height ~1em). - `'circle'` -- equal width/height, fully rounded (avatar slot). |\n| width | `number \\| string` | - | Width. A number is pixels. Defaults to `100%` (`2.5rem` for circle). |\n| height | `number \\| string` | - | Height. A number is pixels. Defaults by variant when unset. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `'sm'` | Corner radius. Prefer a radius-scale name. Ignored for `variant=\"circle\"` (always fully round). |\n\n**Example:**\n```tsx\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n```\n\n### Box\n\nBox -- Generic container with padding, margin, background, and border-radius.\n\nRenders a plain `<div>`. Unlike Card, Box has no default background, shadow,\nor border -- it is a blank canvas for custom styling. Use it for layout\nspacing, colored sections, or wrapping arbitrary content.\n\nWhen both `paddingX`/`paddingY` and `padding` are provided, the axis-specific\nprops take precedence and `padding` is ignored.\n\nCSS variables used: none (all values are passed through directly).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| padding | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no padding)` | Padding applied to all four sides. Prefer a spacing-scale name (`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`) \u2014 each resolves to the matching `--ggui-spacing-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. Ignored when `paddingX` or `paddingY` is set. |\n| paddingX | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Horizontal (left + right) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingY`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingY`, vertical padding defaults to 0. |\n| paddingY | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined` | Vertical (top + bottom) padding. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . When set alongside `paddingX`, they combine into a shorthand `padding: {Y} {X}`. When set without `paddingX`, horizontal padding defaults to 0. |\n| margin | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl' \\| number \\| string` | `undefined (no margin)` | Margin applied to all four sides. Accepts a spacing-scale name, a pixel number, or a raw CSS string \u2014 see . |\n| surface | `'default' \\| 'elevated' \\| 'sunken' \\| 'accent' \\| 'inverted' \\| 'transparent'` | `undefined (transparent)` | Semantic surface slot. Picks the right `var(--ggui-color-*)` background token from the active theme. The ONLY way to set a theme-tracking background fill on Box.  Available slots: - `'default'` \u2014 base container surface (most common) - `'elevated'` \u2014 same fill, intended to be paired with shadow   (use Card.shadow for actual elevation) - `'sunken'` \u2014 recessed / inset region (`surfaceVariant` token) - `'accent'` \u2014 highlighted / branded fill (`primary-50` token) - `'inverted'` \u2014 dark surface in light mode, light in dark   (testimonials, code-snippet cards). Pair with    `'inverse'` for legible text. - `'transparent'` \u2014 explicit \"no fill\"  For non-theme-mapped brand colors (e.g. a partner's exact brand hex like Stripe purple) use the  escape \u2014 every other hex / rgba on Box is rejected by tier-0 self-check. |\n| assetColor | `string` | `undefined` | Asset color escape \u2014 the typed valve for legitimate non-theme color values (a partner's exact brand hex, a fixed product surface, etc.). Renders as the Box background.  **MUST be paired with .** The semantic name is human-readable documentation of why this color bypasses the theme \u2014 e.g. `\"stripe-brand-purple\"`, `\"slack-aubergine\"`. Tier-0 self-check allows hex / rgba inside `assetColor` ONLY when `assetSemantic` is a non-empty string; one without the other fails the check.  Reach for `surface` first. This escape exists for the small set of cases where the operator's theme MUST NOT override the value (brand identity rendering). |\n| assetSemantic | `string` | `undefined` | Human-readable semantic label that documents why  bypasses the theme. Required when `assetColor` is set; tier-0 self-check rejects empty strings or a missing `assetSemantic` next to a hex `assetColor`.  Examples: `\"stripe-brand-purple\"`, `\"slack-aubergine\"`, `\"partner-logo-orange\"`. Pure documentation \u2014 no rendering effect. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | `undefined (no rounding)` | Corner radius. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through as a raw CSS value. |\n\n**Example:**\n```tsx\n<Box paddingX=\"xl\" paddingY=\"lg\" surface=\"accent\" radius=\"lg\">\n  <Text size=\"sm\" tone=\"emphasized\">\n    Tip: You can customize your theme in Settings.\n  </Text>\n</Box>\n```\n\n### Divider\n\nDivider -- A 1px line to visually separate content sections.\n\nRenders an `<hr>` (horizontal) or `<div>` (vertical) with `role=\"separator\"`.\n- Horizontal: 1px tall, full width, with vertical margin.\n- Vertical: 1px wide, stretches to parent height via `align-self: stretch`,\n  with horizontal margin. Works best inside a horizontal Stack or Row.\n\nDefault color: `var(--ggui-color-outlineVariant)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Line direction. - `'horizontal'` -- renders `<hr>`, full width, 1px height, margin top/bottom - `'vertical'` -- renders `<div>`, 1px width, `align-self: stretch`, margin left/right |\n| margin | `number \\| string` | `16` | Spacing around the divider. Numbers are treated as pixels. Applied as vertical margin for horizontal dividers, horizontal margin for vertical. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-outlineVariant)`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a quiet outline-variant tint when unset (independent of the tone slots). |\n\n**Example:**\n```tsx\n<Stack gap={0}>\n  <Text>Section A</Text>\n  <Divider margin=\"var(--ggui-spacing-3)\" />\n  <Text>Section B</Text>\n</Stack>\n```\n\n### Spacer\n\nSpacer -- Invisible spacing element, either fixed-size or flexible.\n\nRenders an empty `<div>`.\n- Fixed mode (number): sets both `width` and `height` to the given pixel\n  value with `flex-shrink: 0`, creating rigid spacing in any direction.\n- Flex mode (`'flex'`): sets `flex: 1`, expanding to fill remaining space\n  in a flex container. Useful for pushing siblings apart.\n\nCSS variables used: none.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number \\| 'flex'` | `16` | Spacing amount. - Number: fixed square spacer (width and height in pixels, `flex-shrink: 0`). - `'flex'`: expands to fill available space (`flex: 1`). |\n\n**Example:**\n```tsx\n<Stack direction=\"horizontal\" align=\"center\">\n  <Heading level={3}>Logo</Heading>\n  <Spacer size=\"flex\" />\n  <Button variant=\"ghost\">Login</Button>\n</Stack>\n```\n\n### Text\n\nText -- Versatile typography primitive for body copy, captions, and labels.\n\nRenders as `<p>` by default (configurable via `is`). Typography is\ncomposed from three orthogonal axes: `size` (font size, with a\nmatching line-height built in), `weight`, and `tone` (semantic\ncolor). `caps` adds the uppercase, letter-spaced treatment for tiny\nsection labels (the classic overline/eyebrow look).\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll text renders with `margin: 0` (no default paragraph spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| size | `'xs' \\| 'sm' \\| 'base' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl' \\| '4xl'` | `'base'` | Font size. Maps to CSS variables with pixel fallbacks; each size carries a matching line-height (1.5 for `xs`--`base`, 1.625 for `lg`, then tightening on display sizes: 1.375 at `xl`, 1.25 from `2xl` up): - `'xs'` -- var(--ggui-font-size-xs) (12px) - `'sm'` -- var(--ggui-font-size-sm) (14px) - `'base'` -- var(--ggui-font-size-base) (16px) - `'lg'` -- var(--ggui-font-size-lg) (18px) - `'xl'` -- var(--ggui-font-size-xl) (20px) - `'2xl'` -- var(--ggui-font-size-2xl) (24px) - `'3xl'` -- var(--ggui-font-size-3xl) (30px) - `'4xl'` -- var(--ggui-font-size-4xl) (36px) |\n| weight | `'normal' \\| 'medium' \\| 'semibold' \\| 'bold'` | `'normal'` | Font weight. Maps to CSS variables with numeric fallbacks: - `'normal'` -- var(--ggui-font-weight-normal) - `'medium'` -- var(--ggui-font-weight-medium) - `'semibold'` -- var(--ggui-font-weight-semibold) - `'bold'` -- var(--ggui-font-weight-bold) |\n| caps | `boolean` | `false` | When true, uppercases the text and adds 0.05em letter-spacing -- the eyebrow/overline treatment for tiny section labels. Pair with `size=\"xs\" weight=\"semibold\" tone=\"muted\"`. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Picks the right `var(--ggui-color-*)` token from the active theme. The theme decides what each tone LOOKS like \u2014 `'muted'` is a quiet warm grey on Claudic, a cool slate on Indigo, dim cyan on Neon-Noir. Components that use `tone` track the operator's theme switch automatically.  Available slots: `'default'` (primary body text), `'muted'` (secondary / metadata), `'subtle'` (very-low-emphasis hint), `'emphasized'` (branded accent), `'loud'` (strongest accent), `'success'` / `'warning'` / `'error'` / `'info'` (status text), `'inverse'` (text on dark surface), `'inherit'` (parent's color).  `tone` is the ONLY way to set a Text color. The legacy `color?: string` escape was retired \u2014 raw color strings bypass theming and silently override the operator's preset. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n| truncate | `boolean` | `false` | When true, clips overflowing text with an ellipsis. Applies `overflow: hidden`, `text-overflow: ellipsis`, and `white-space: nowrap`. |\n| is | `'p' \\| 'span' \\| 'div' \\| 'label'` | `'p'` | HTML element to render. Choose based on semantic context: - `'p'` -- paragraph (default, block-level) - `'span'` -- inline text within a sentence - `'div'` -- generic block container - `'label'` -- form label (pair with `htmlFor`) |\n| id | `string` | - | `id` for the rendered element \u2014 anchor an in-page link, or pair with a form control's `aria-labelledby`. |\n| htmlFor | `string` | - | Associates an `is=\"label\"` element with a form control by the control's `id`. Only meaningful when `is=\"label\"`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-1)\">\n  <Text size=\"xs\" weight=\"semibold\" caps tone=\"muted\">Account</Text>\n  <Text size=\"lg\">Welcome back, Jane.</Text>\n  <Text size=\"xs\" tone=\"muted\">\n    Last login: 2 hours ago\n  </Text>\n</Stack>\n```\n\n### Heading\n\nHeading -- Semantic heading element (h1-h6) with preset typography styles.\n\nRenders the corresponding `<h1>`-`<h6>` HTML element based on `level`.\nEach level has a preset font size, weight, line height, and letter spacing\nfrom the heading typography tokens:\n- Level 1: 36px / bold / 1.25 line-height / -0.025em tracking\n- Level 2: 30px / bold / 1.25 line-height / -0.025em tracking\n- Level 3: 24px / semibold / 1.375 line-height / 0em tracking\n- Level 4: 20px / semibold / 1.375 line-height / 0em tracking\n- Level 5: 18px / semibold / 1.5 line-height / 0em tracking\n- Level 6: 16px / semibold / 1.5 line-height / 0em tracking\n\nDefault text color: `var(--ggui-color-onContainer)`.\nAll headings render with `margin: 0` (no default heading spacing).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| level | `1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6` | `2` | Semantic heading level. Determines both the HTML element (`<h1>`-`<h6>`) and the preset typography style. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `'default' (var(--ggui-color-onContainer))` | Semantic color slot. Same vocabulary as ; see that prop's docs for the full slot table. `tone` is the ONLY way to set a Heading color \u2014 the legacy `color?: string` escape was retired so the operator's theme always wins. |\n| align | `'left' \\| 'center' \\| 'right'` | `undefined (inherits from parent)` | Horizontal text alignment. Maps directly to `text-align`. |\n\n**Example:**\n```tsx\n<Stack gap=\"var(--ggui-spacing-2)\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={3} tone=\"emphasized\">\n    Subsection\n  </Heading>\n  <Text>Body content goes here.</Text>\n</Stack>\n```\n\n### Button\n\nButton -- A clickable button primitive with multiple visual variants and sizes.\n\nRenders a native `<button>` element styled with inline CSS derived from design-token\nCSS variables. Supports a loading spinner, left/right icon slots, and a cross-platform\n`onPress` alias for `onClick`.\n\nBase styles applied to every variant:\n- `border-radius: var(--ggui-shape-radius-md)`\n- `font-weight: var(--ggui-font-weight-medium)`\n- `box-shadow: var(--ggui-shape-shadow-sm)`\n- `gap: var(--ggui-spacing-2)` between icon and text\n- Transitions: background-color, box-shadow, opacity at 200ms ease-in-out\n\nDisabled or loading: `opacity: 0.5`, `cursor: not-allowed`, click handler suppressed.\n\nAlso extends native `ButtonHTMLAttributes` (except `style`/`className`), so props\nlike `type`, `form`, `aria-*`, and `data-*` are forwarded to the `<button>` element.\nThe `type` prop defaults to `'button'` (not `'submit'`), preventing accidental form\nsubmissions.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'primary' \\| 'secondary' \\| 'outline' \\| 'ghost' \\| 'danger'` | `'primary'` | Visual style. Maps to CSS variables: - `'primary'` -- `var(--ggui-color-primary-600)` background, white text, no border - `'secondary'` -- `var(--ggui-color-sunken)` background, `var(--ggui-color-onSunken)` text, no border - `'outline'` -- transparent background, `1px solid var(--ggui-color-primary-600)` border, primary-600 text - `'ghost'` -- transparent background, `var(--ggui-color-onSunken)` text, no border - `'danger'` -- `var(--ggui-color-error-600)` background, white text, no border |\n| size | `'xs' \\| 'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and minimum height: - `'xs'` -- padding `4px 8px`, font `var(--ggui-font-size-xs)`, min-height 24px - `'sm'` -- padding `6px 12px`, font `var(--ggui-font-size-sm)`, min-height 32px - `'md'` -- padding `10px 16px`, font `var(--ggui-font-size-sm)`, min-height 40px - `'lg'` -- padding `12px 24px`, font `var(--ggui-font-size-base)`, min-height 48px |\n| fullWidth | `boolean` | `false` | When true, sets `width: 100%` so the button fills its container. |\n| loading | `boolean` | `false` | When true, replaces children with a 16px `Spinner` (color: `currentColor`) and disables interaction (same effect as `disabled`). |\n| leftIcon | `ReactNode` | - | ReactNode rendered before children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| rightIcon | `ReactNode` | - | ReactNode rendered after children, inside the flex layout with `var(--ggui-spacing-2)` gap. |\n| onPress | `() => void` | - | Alias for `onClick` for cross-platform compatibility (React Native convention). If both `onClick` and `onPress` are provided, `onClick` takes precedence. |\n\n**Example:**\n```tsx\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n```\n\n### Input\n\nInput -- A single-line text input with label, validation, and helper text.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<input>`,\nand an optional message `<span>` for error or helper text.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)`\n- Border radius: `var(--ggui-shape-radius-md)`\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n  `var(--ggui-color-onSunken)`\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<input>` via `htmlFor`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\nWhen `required` is true, a red asterisk is appended to the label.\n\nAlso extends native `InputHTMLAttributes` (except `style`, `className`, `onChange`,\n`size`), so props like `autoFocus`, `name`, `pattern`, `aria-*` are forwarded.\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<input>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the input. Linked to the input via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the input is empty. |\n| value | `string` | - | Controlled value of the input. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| type | `'text' \\| 'email' \\| 'password' \\| 'number' \\| 'tel' \\| 'url' \\| 'search' \\| 'date' \\| 'time' \\| 'datetime-local'` | `'text'` | HTML input type. Determines browser behavior (keyboard on mobile, validation, masking). The date/time types render the browser's native, localized, keyboard-accessible picker; their `value` stays an ISO string (`'2026-07-29'`, `'14:30'`, `'2026-07-29T14:30'`) delivered through the usual value-first `onChange`. |\n| error | `string` | - | Error message displayed below the input in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the input in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<input>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n```\n\n### TextArea\n\nTextArea -- A multiline text input with label, validation, character count, and auto-resize.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<textarea>`,\nand a footer row with error/helper text on the left and character count on the right.\n\nStyling:\n- Padding: `10px 12px`, font: `var(--ggui-font-size-sm)`, `font-family: inherit`\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Border radius: `var(--ggui-shape-radius-md)`\n- Resize: `vertical` by default, `none` when `autoResize` is true\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: same label/error linking pattern as Input (auto-generated ids,\n`aria-invalid`, `role=\"alert\"` on error message).\n\nAlso extends native `TextareaHTMLAttributes` (except `style`, `className`, `onChange`).\n\n**IMPORTANT:** `onChange` receives the string value directly, NOT a React\n`ChangeEvent`. This differs from native `<textarea>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the textarea. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| placeholder | `string` | - | Placeholder text shown when the textarea is empty. |\n| value | `string` | - | Controlled value of the textarea. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the new string value directly, NOT a React event. |\n| rows | `number` | `4` | Number of visible text rows (native `rows` attribute on `<textarea>`). |\n| error | `string` | - | Error message displayed below the textarea in `var(--ggui-color-error-500)`. When set, the border turns red and the message element gets `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the textarea in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute on the `<textarea>`. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)`. |\n| maxLength | `number` | - | Maximum character length (native `maxLength` attribute). Also used as the denominator in the character count display when `showCount` is true. |\n| showCount | `boolean` | `false` | When true AND `maxLength` is set, displays a `{current}/{max}` character counter in the footer row (right-aligned, `var(--ggui-font-size-xs)`). Has no effect without `maxLength`. |\n| autoResize | `boolean` | `false` | When true, sets CSS `resize: none` on the textarea. The flag disables manual resizing to signal that external logic handles sizing. The component does NOT auto-adjust height based on content in the current implementation. |\n\n**Example:**\n```tsx\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n```\n\n### Select\n\nSelect -- A native dropdown selection primitive with label and validation.\n\nRenders a `<div>` wrapper containing an optional `<label>`, a native `<select>`\nwith custom styling, and an optional message `<span>`.\n\nThe native `<select>` has `appearance: none` with a custom chevron SVG rendered\nas a `background-image` (right-aligned, 12px, onSurfaceVariant color). Extra right\npadding (36px) accommodates the chevron.\n\nStyling:\n- Border: `1px solid var(--ggui-color-outline)` (normal),\n  `var(--ggui-color-error-500)` (error)\n- Background: `var(--ggui-color-container)` (normal),\n  `var(--ggui-color-container)` (disabled)\n- Text: `var(--ggui-color-onContainer)` when a value is selected,\n  `var(--ggui-color-onSunken)` when showing placeholder\n- Border radius: `var(--ggui-shape-radius-md)`\n- Cursor: `pointer` (normal), `not-allowed` (disabled)\n- Transitions: border-color, box-shadow at 200ms ease-in-out\n\nAccessibility: auto-generated `id` links `<label>` to `<select>`.\nWhen `error` is set, `aria-invalid` is true and the message has `role=\"alert\"`.\n\nAlso extends native `SelectHTMLAttributes` (except `style`, `className`,\n`onChange`, `size`).\n\n**IMPORTANT:** `onChange` receives the selected value string directly, NOT a\nReact `ChangeEvent`. This differs from native `<select>` behavior.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the select. Linked via auto-generated `htmlFor`/`id`. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of the `options[].value` strings. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the selected option's value string directly, NOT a React event. |\n| options | `SelectOption[]` | - | Array of selectable options. Rendered as native `<option>` elements. Must contain at least one option (or use `placeholder` for an empty-state prompt). |\n| placeholder | `string` | - | Placeholder text rendered as a disabled `<option value=\"\">` at the top of the list. Shown when no value is selected. |\n| error | `string` | - | Error message displayed below the select in `var(--ggui-color-error-500)`. When set, the border turns red and the message has `role=\"alert\"`. Takes precedence over `helperText`. |\n| helperText | `string` | - | Helper text displayed below the select in `var(--ggui-color-onSunken)`. Only shown when `error` is not set. |\n| required | `boolean` | `false` | When true, appends a red asterisk (`*`) to the label and sets the native `required` attribute. |\n| disabled | `boolean` | `false` | When true, sets the native `disabled` attribute. Background changes to `var(--ggui-color-container)` and cursor becomes `not-allowed`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `6px 10px`, font `var(--ggui-font-size-sm)` - `'md'` -- padding `10px 12px`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `12px 14px`, font `var(--ggui-font-size-base)` |\n\n**Example:**\n```tsx\n<Select\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  options={[\n    { value: 'us', label: 'United States' },\n    { value: 'uk', label: 'United Kingdom' },\n  ]}\n  placeholder=\"Select a country\"\n/>\n```\n\n### Checkbox\n\nCheckbox -- A custom-styled checkbox with label and description.\n\nRenders a `<label>` wrapper containing a visually-hidden native `<input type=\"checkbox\">`\noverlaid by a custom 18x18px visual box. Supports checked, unchecked, and indeterminate\nstates, each with a distinct SVG icon (checkmark or horizontal dash).\n\nStyling:\n- Box border: `2px solid var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-outline)` (unchecked)\n- Box fill: `var(--ggui-color-primary-600)` (checked/indeterminate),\n  `var(--ggui-color-container)` (unchecked)\n- Check/dash icon: white SVG, 12x12px\n- Box radius: `var(--ggui-shape-radius-sm)`\n- Transition: all 0.2s\n- Label: `var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`\n- Description: `var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`\n- Gap between box and text: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the boolean checked state directly, NOT a\nReact `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary label text rendered beside the checkbox box. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| checked | `boolean` | - | Controlled checked state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean checked state directly, NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5` and `cursor: not-allowed`. The native input is also disabled, preventing keyboard and click interaction. |\n| description | `string` | - | Secondary description text rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| indeterminate | `boolean` | `false` | When true, displays a horizontal dash instead of a checkmark. Used for \"select all\" states where some (but not all) children are checked. The `indeterminate` property is set via a ref on the native `<input>`. Visually identical to `checked` in terms of border and fill color. |\n\n**Example:**\n```tsx\n<Checkbox\n  label=\"Accept terms\"\n  description=\"You agree to the Terms of Service and Privacy Policy\"\n  checked={accepted}\n  onChange={setAccepted}\n/>\n```\n\n### Toggle\n\nToggle -- A switch/toggle input rendered as a pill-shaped track with a sliding knob.\n\nRenders a `<label>` wrapper with a `<div role=\"switch\">` track and an animated\ncircular knob. Does NOT use a native `<input>` -- keyboard interaction is handled\nmanually (Space and Enter keys toggle the state). The element is focusable via\n`tabIndex={0}` and shows a focus ring on focus.\n\nStyling:\n- Track (on): `var(--ggui-color-primary-600)`\n- Track (off): `var(--ggui-color-outline)`\n- Knob: white circle with `var(--ggui-shape-shadow-sm)`\n- Focus ring: `0 0 0 3px var(--ggui-color-primary-200)`\n- Transitions: background-color, box-shadow, knob position at 200ms ease-in-out\n- Disabled: `opacity: 0.5`, `cursor: not-allowed`, `tabIndex: -1`\n- Gap between toggle and label: `var(--ggui-spacing-2)`\n\n**IMPORTANT:** `onChange` receives the new boolean state directly (inverted from\ncurrent), NOT a React event.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label text rendered to the right of the toggle track. Also used as `aria-label` on the switch element. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| checked | `boolean` | - | Controlled checked (on/off) state. |\n| onChange | `(checked: boolean) => void` | - | Change handler. Receives the new boolean state directly (i.e., `!checked`), NOT a React event. |\n| disabled | `boolean` | `false` | When true, sets `opacity: 0.5`, `cursor: not-allowed`, and removes the element from tab order (`tabIndex: -1`). Click and keyboard handlers are suppressed. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track and knob dimensions: - `'sm'` -- track 36x20px, knob 16px diameter - `'md'` -- track 44x24px, knob 20px diameter - `'lg'` -- track 52x28px, knob 24px diameter |\n\n**Example:**\n```tsx\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n```\n\n### RadioGroup\n\nRadioGroup -- A group of mutually exclusive radio options with optional label and error.\n\nRenders a `<div role=\"radiogroup\">` containing a label span, a flex container of\nradio options, and an optional error message. Each option is a `<label>` with a\nvisually-hidden native `<input type=\"radio\">` and a custom 18px circle indicator.\n\nStyling:\n- Selected circle: `2px solid var(--ggui-color-primary-600)` border with\n  an 8px `var(--ggui-color-primary-600)` filled inner dot\n- Unselected circle: `2px solid var(--ggui-color-outline)` border,\n  `var(--ggui-color-container)` fill\n- Circle radius: `var(--ggui-shape-radius-full)`\n- Transition: all 0.2s\n- Vertical gap: `var(--ggui-spacing-2)`, horizontal gap: `var(--ggui-spacing-4)`\n- Error: `var(--ggui-font-size-xs)`, `var(--ggui-color-error-500)`,\n  `role=\"alert\"`\n- Disabled options: `opacity: 0.5`, `cursor: not-allowed`\n\nAccessibility: the group has `role=\"radiogroup\"` with `aria-labelledby` pointing\nto the label and `aria-describedby` pointing to the error message (when present).\nAll radio inputs share a common auto-generated `name` attribute.\n\n**IMPORTANT:** `onChange` receives the selected option's value string directly,\nNOT a React `ChangeEvent`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Group label rendered above the options. Used as `aria-labelledby` target on the `role=\"radiogroup\"` container. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `string` | - | Controlled value. Should match one of `options[].value`. |\n| onChange | `(value: string) => void` | - | Change handler. Receives the newly selected option's value string directly, NOT a React event. |\n| options | `RadioOption[]` | - | Array of radio options. Must contain at least two options for meaningful selection. |\n| direction | `'vertical' \\| 'horizontal'` | `'vertical'` | Layout direction for the options container: - `'vertical'` -- column layout, `var(--ggui-spacing-2)` gap - `'horizontal'` -- row layout with `flex-wrap: wrap`, `var(--ggui-spacing-4)` gap |\n| disabled | `boolean` | `false` | When true, disables ALL options (individual `RadioOption.disabled` is additive). Each option gets `opacity: 0.5` and `cursor: not-allowed`. |\n| error | `string` | - | Error message displayed below all options in `var(--ggui-color-error-500)` with `role=\"alert\"`. Linked to the radiogroup via `aria-describedby`. |\n\n**Example:**\n```tsx\n<RadioGroup\n  label=\"Plan\"\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: 'free', label: 'Free', description: 'Up to 5 projects' },\n    { value: 'pro', label: 'Pro', description: 'Unlimited projects' },\n  ]}\n/>\n```\n\n### Slider\n\nSlider -- A range input with a custom-styled track, fill, and thumb.\n\nRenders a `<div>` wrapper containing an optional label/value header, and a\ntrack area with three layers: background track, colored fill, and a circular\nthumb. A native `<input type=\"range\">` is overlaid with `opacity: 0` to\nprovide accessible keyboard and pointer interaction.\n\nStyling:\n- Track: 6px tall, `var(--ggui-color-outlineVariant)` background, `border-radius: 3px`\n- Fill: `var(--ggui-color-primary-600)` (normal),\n  `var(--ggui-color-outline)` (disabled)\n- Thumb: 20px white circle with `2px solid var(--ggui-color-primary-600)`,\n  `var(--ggui-shape-shadow-sm)`; disabled border uses outline\n- Value display (when `showValue`): `var(--ggui-color-primary-600)`,\n  `var(--ggui-font-size-sm)`, right-aligned in the header row\n- Fill and thumb transitions: 0.1s for smooth dragging\n\nAccessibility: the native `<input type=\"range\">` carries `aria-valuenow`,\n`aria-valuemin`, `aria-valuemax`, and is linked to the label via `aria-labelledby`.\nFalls back to `aria-label=\"Slider\"` when no label is provided.\n\n**IMPORTANT:** `onChange` receives the numeric value directly, NOT a React\n`ChangeEvent`. The value is coerced via `Number(e.target.value)`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Label rendered above the slider track (left-aligned). Used as `aria-labelledby` target on the native range input. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| value | `number` | `0` | Controlled numeric value. Must be between `min` and `max`. |\n| onChange | `(value: number) => void` | - | Change handler. Receives the new numeric value directly, NOT a React event. |\n| min | `number` | `0` | Minimum allowed value. |\n| max | `number` | `100` | Maximum allowed value. |\n| step | `number` | `1` | Step increment for the slider. Determines the granularity of selectable values. |\n| disabled | `boolean` | `false` | When true, sets `cursor: not-allowed` on the native input. The fill color changes to `var(--ggui-color-outline)` and the thumb border also uses outline. |\n| showValue | `boolean` | `false` | When true, displays the current numeric value right-aligned in the header row (beside the label) in `var(--ggui-color-primary-600)`. |\n\n**Example:**\n```tsx\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n```\n\n### Badge\n\nBadge -- Inline label for status indicators, counts, or categories.\n\nRenders a `<span>` with `display: inline-flex`, centered content, and\n`white-space: nowrap`. Semantic variant colors use background/text pairings\nfrom the 100/700 color scale. Pill shape uses `border-radius: 9999px`;\nnon-pill uses `var(--ggui-shape-radius-sm)`.\n\nFont weight: `var(--ggui-font-weight-medium)` across all variants.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'default' \\| 'primary' \\| 'secondary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info' \\| 'tertiary'` | `'default'` | Visual style. Maps to background/text color pairings: - `'default'` -- bg `var(--ggui-color-sunken)`, text `var(--ggui-color-onSunken)` - `'primary'` -- bg `var(--ggui-color-primary-100)`, text `var(--ggui-color-primary-700)` - `'secondary'` -- bg `var(--ggui-color-outlineVariant)`, text `var(--ggui-color-onContainer)` - `'success'` -- bg `var(--ggui-color-success-100)`, text `var(--ggui-color-success-700)` - `'warning'` -- bg `var(--ggui-color-warning-100)`, text `var(--ggui-color-warning-700)` - `'error'` -- bg `var(--ggui-color-error-100)`, text `var(--ggui-color-error-700)` - `'info'` -- bg `var(--ggui-color-info-100)`, text `var(--ggui-color-info-700)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding and font size: - `'sm'` -- padding `2px 6px`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `2px 8px`, font `var(--ggui-font-size-xs)` - `'lg'` -- padding `4px 10px`, font `var(--ggui-font-size-sm)` |\n| pill | `boolean` | `true` | When true, uses fully rounded corners (`border-radius: 9999px`). When false, uses `var(--ggui-shape-radius-sm)`. |\n\n**Example:**\n```tsx\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n```\n\n### Spinner\n\nSpinner -- Animated SVG loading indicator.\n\nRenders an `<svg>` with `role=\"status\"` and `aria-label=\"Loading\"`.\nThe SVG contains a full outlineVariant background circle and a quarter-arc\nforeground stroke in the spinner color.\n\nAnimation: `ggui-spin 1s linear infinite` (360-degree rotation).\nThe `@keyframes ggui-spin` definition is injected inline via a `<style>` tag.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| size | `number` | `24` | Width and height of the SVG element in pixels. The internal viewBox is always `0 0 24 24`, so this controls rendered size only. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the animated foreground arc. Same vocabulary as ; the theme decides the resolved value. The background circle always uses `var(--ggui-color-outlineVariant)`.  Use `'inherit'` when the spinner sits inside a colored container (e.g. inside a Button) \u2014 the stroke picks up `currentColor` from the parent so it tracks the container's foreground. |\n\n**Example:**\n```tsx\n<Spinner size={32} tone=\"success\" />\n```\n\n### Avatar\n\nAvatar -- User or entity representation with image or auto-generated initials.\n\nRenders a `<div role=\"img\">` with `overflow: hidden` and `flex-shrink: 0`.\nWhen `src` is provided and loads successfully, renders an `<img>` with\n`object-fit: cover`. On image error (or when no `src`), falls back to\ninitials derived from `name` (up to 2 characters, uppercase).\n\nInitials background: deterministic color from a 5-color palette based on\nname hash (primary-500, success-500, warning-500, error-500, info-500).\nFalls back to `var(--ggui-color-outline)` when no name is given.\nInitials text: white, `font-weight: var(--ggui-font-weight-semibold)`,\n`font-size: resolvedSize * 0.4`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image URL. When provided and the image loads, it is rendered with `object-fit: cover`. On load error, falls back to initials. |\n| name | `string` | - | Name used for two purposes: 1. Generating initials (splits on spaces, takes first letter of each word, max 2). 2. Deterministic background color selection via character code hash. Also used as `aria-label` on the container. Falls back to `'Avatar'` if omitted. |\n| size | `number \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'md'` | Avatar dimensions. Named sizes map to pixel values: - `'xs'` -- 24px - `'sm'` -- 32px - `'md'` -- 40px - `'lg'` -- 48px - `'xl'` -- 64px  Numeric values are used directly as pixel dimensions. |\n| shape | `'circle' \\| 'square'` | `'circle'` | Container shape. - `'circle'` -- `border-radius: 50%` - `'square'` -- `border-radius: var(--ggui-shape-radius-md)` |\n\n**Example:**\n```tsx\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n```\n\n### Alert\n\nAlert -- Contextual message box for important information with icon and optional dismiss.\n\nRenders a `<div role=\"alert\">` with flex layout (12px gap), variant-specific\nbackground, border, text color, and a leading icon. Each variant provides a\ndefault SVG icon (info circle, checkmark, warning triangle, or X circle) that\ncan be overridden via the `icon` prop.\n\nLayout: icon (flex-shrink: 0) | content column (title + body) | close button.\nBorder radius: `var(--ggui-shape-radius-lg)`.\nPadding: `12px 16px`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets: - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)`, icon `var(--ggui-color-info-500)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)`, icon `var(--ggui-color-success-500)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)`, icon `var(--ggui-color-warning-500)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)`, icon `var(--ggui-color-error-500)` |\n| title | `string` | - | Optional title rendered above the body in semibold (`var(--ggui-font-weight-semibold)`), `var(--ggui-font-size-sm)`. Title and body are separated by `var(--ggui-spacing-1)` gap. |\n| closable | `boolean` | `false` | When true, renders a close button (X icon) in the top-right area. The button has `min-width: 28px`, `min-height: 28px`, and `opacity: 0.7`. Requires `onClose` to be functional. |\n| onClose | `() => void` | - | Callback fired when the close button is clicked. Only relevant when `closable` is true. |\n| icon | `ReactNode` | - | Custom icon ReactNode to replace the default variant icon. Rendered at the leading position with the variant's icon color applied via `color` CSS property. |\n\n**Example:**\n```tsx\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n```\n\n### Progress\n\nProgress -- Horizontal progress bar with determinate and indeterminate modes.\n\nRenders a track `<div role=\"progressbar\">` with a colored fill child.\nThe track background is `var(--ggui-color-outlineVariant)` with\npill-shaped corners (border-radius = height / 2).\n\nDeterminate mode: fill width transitions smoothly (`width 0.3s ease`).\nIndeterminate mode: fill is 30% width, animated with\n`ggui-progress-indeterminate 1.5s ease-in-out infinite`\n(translateX from -100% to 400%). The `@keyframes` are injected inline.\n\nAccessibility: `aria-valuenow` is set in determinate mode, omitted in\nindeterminate. `aria-valuemin` is always 0, `aria-valuemax` matches `max`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `number` | - | Current progress value. Clamped to `[0, max]` and converted to a percentage for the fill width: `Math.min(100, Math.max(0, (value / max) * 100))`. |\n| max | `number` | `100` | Maximum value representing 100% progress. |\n| variant | `'default' \\| 'success' \\| 'warning' \\| 'error'` | `'default'` | Fill bar color. Maps to CSS variables: - `'default'` -- `var(--ggui-color-primary-600)` - `'success'` -- `var(--ggui-color-success-500)` - `'warning'` -- `var(--ggui-color-warning-500)` - `'error'` -- `var(--ggui-color-error-500)` |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls track height in pixels: - `'sm'` -- 4px - `'md'` -- 8px - `'lg'` -- 12px |\n| label | `string` | - | Accessible name describing what this bar measures, e.g. `\"Survey progress\"` or `\"Upload\"`. Becomes the progressbar's `aria-label` and \u2014 when `showLabel` is set \u2014 the visible header text in place of the generic word \"Progress\". Always pass this when the surrounding context does not already make the meaning obvious. |\n| showLabel | `boolean` | `false` | When true, displays a header row above the track with the `label` text (or \"Progress\" if `label` is unset) on the left, and the rounded percentage value on the right. |\n| indeterminate | `boolean` | `false` | When true, ignores `value` for visual width and plays a looping animation instead. The fill bar is 30% width and slides across the track. Animation: `ggui-progress-indeterminate 1.5s ease-in-out infinite`. `aria-valuenow` is omitted from the progressbar element. |\n\n**Example:**\n```tsx\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n```\n\n### Image\n\nImage -- An `<img>` element with built-in error handling and fallback support.\n\nRenders a native `<img>` with `display: block`. On load error, either renders\nthe `fallback` ReactNode (if provided) or a default placeholder `<div>` with a\nsurfaceVariant background and a centered image SVG icon in outline.\n\nSize values: numbers are treated as pixels, strings are passed through as-is.\nWhen no `width` is set, defaults to `100%`. When no `height` is set, defaults\nto `auto`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| src | `string` | - | Image source URL. Load failure triggers the fallback state. |\n| alt | `string` | - | Alt text for the image. Used as `aria-label` in the error placeholder too. |\n| width | `number \\| string` | `'100%' (applied at render time, not on the type)` | Image width. Numbers are pixels, strings are CSS values (e.g., `'100%'`, `'50vw'`). |\n| height | `number \\| string` | `'auto' (applied at render time, not on the type)` | Image height. Numbers are pixels, strings are CSS values. |\n| objectFit | `'cover' \\| 'contain' \\| 'fill' \\| 'none' \\| 'scale-down'` | `'cover'` | CSS `object-fit` value controlling how the image fills its box. |\n| radius | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| number \\| string` | - | Corner radius applied to both the image and the error placeholder. Prefer a radius-scale name (`'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`) \u2014 each resolves to the matching `--ggui-shape-radius-*` token. A number is treated as pixels; any other string is passed through. |\n| fallback | `ReactNode` | - | Custom ReactNode rendered when the image fails to load. When provided, completely replaces the default error placeholder (no wrapper div). When omitted, a surfaceVariant background div with an image icon is shown. |\n\n**Example:**\n```tsx\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n```\n\n### Icon\n\nIcon -- 185 Lucide icons + emoji passthrough.\n\nThree resolution layers:\n1. **Lucide icon:** pass any common Lucide icon name (e.g. `sun`, `cloud-rain`, `heart`, `shopping-cart`).\n   Accepts kebab-case, camelCase, or PascalCase. Renders as stroke SVG.\n2. **Emoji:** pass emoji/unicode directly (e.g. `\u2600\uFE0F`, `\u{1F327}\uFE0F`). Rendered as text.\n3. **Custom SVG:** pass children (`<svg>` element) for full control.\n\nContainer: `<span>` with `display: inline-flex`, centered content.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| name | `string` | - | Lucide icon name (kebab-case, camelCase, or PascalCase all work). Also accepts emoji/unicode characters directly. |\n| size | `number` | `24` | Icon dimensions in pixels (applied to both width and height of the wrapper and the inner SVG element). |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (icon uses `currentColor`)` | Semantic color slot. Same vocabulary as ; the theme decides what each tone LOOKS like. Resolves to a CSS `color` on the wrapper which the inner SVG inherits via `currentColor`. Use `'inherit'` (the default behavior when unset) for icons that should pick up the parent's foreground color. |\n| children | `ReactNode` | - | Custom SVG children. When provided, `name` is ignored and children are rendered inside a sized `<span>` wrapper. |\n| 'aria-label' | `string` | - | Accessible name for a standalone, meaning-bearing icon. When set, the icon exposes `role=\"img\"` + this label. When omitted (the default) the icon is decorative and hidden from screen readers (`aria-hidden`) \u2014 the right choice for an icon next to a text label. |\n\n**Example:**\n```tsx\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n```\n\n### Link\n\nLink -- Styled anchor element with external link support.\n\nRenders a native `<a>` element. When `external` is true, sets\n`target=\"_blank\"` and `rel=\"noopener noreferrer\"`, and appends a small\n(12px) external-link SVG icon after the children.\n\nTransition: `color 0.2s`.\nUnderline behavior is controlled via mouseEnter/mouseLeave event handlers\n(for the `'hover'` mode).\n\nAlso extends native `AnchorHTMLAttributes` (except `style`/`className`),\nso props like `aria-*`, `data-*`, `title`, etc. are forwarded to the `<a>`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | children |\n| href | `string` | - | Destination URL. Passed directly to the `<a href>` attribute. |\n| external | `boolean` | `false` | When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener noreferrer\"`) and appends a 12px external-link icon after children. |\n| tone | `\\| 'default'     \\| 'muted'     \\| 'subtle'     \\| 'emphasized'     \\| 'loud'     \\| 'success'     \\| 'warning'     \\| 'error'     \\| 'info'     \\| 'inverse'     \\| 'inherit'` | `undefined (uses `var(--ggui-color-primary-600)`)` | Semantic color slot for the link text. Same vocabulary as ; the theme decides what each tone LOOKS like. Defaults to a primary-tinted accent (`'loud'`-ish) when unset. |\n| underline | `'always' \\| 'hover' \\| 'none'` | `'hover'` | Underline behavior: - `'always'` -- `text-decoration: underline` at all times - `'hover'` -- underline appears on mouse enter, removed on mouse leave - `'none'` -- no underline ever |\n\n**Example:**\n```tsx\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n```\n\n### Tooltip\n\nTooltip -- Hoverable information popup positioned relative to a trigger element.\n\nWraps `children` in a `<div>` trigger (display: inline-block) and renders\na fixed-position tooltip `<div role=\"tooltip\">` when visible.\n\nTooltip appearance:\n- Background: `var(--ggui-color-onContainer)`\n- Text: white, `var(--ggui-font-size-xs)`\n- Padding: `6px 10px`, border-radius: `var(--ggui-shape-radius-md)`\n- Max width: 200px, `white-space: nowrap`, `pointer-events: none`\n- Z-index: `zIndex.tooltip` (1800)\n\nShow/hide: triggered by mouseEnter/mouseLeave AND focus/blur on the\ntrigger element. Uses `position: fixed` with coordinates calculated from\n`getBoundingClientRect()` and an 8px offset from the trigger edge.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Trigger element. Wrapped in a `<div>` with mouseEnter/mouseLeave and focus/blur handlers. |\n| content | `ReactNode` | - | Tooltip content. Can be text or any ReactNode. |\n| position | `'top' \\| 'bottom' \\| 'left' \\| 'right'` | `'top'` | Tooltip placement relative to the trigger element: - `'top'` -- above, centered horizontally, transformed `translateX(-50%) translateY(-100%)` - `'bottom'` -- below, centered horizontally, transformed `translateX(-50%)` - `'left'` -- to the left, centered vertically, transformed `translateX(-100%) translateY(-50%)` - `'right'` -- to the right, centered vertically, transformed `translateY(-50%)` |\n| delay | `number` | `200` | Delay in milliseconds before the tooltip becomes visible after hover/focus. Hiding is immediate (no delay). |\n\n**Example:**\n```tsx\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n```\n\n### Table\n\nTable -- Data table with sortable columns, striped rows, and hover highlights.\n\nRenders a scrollable wrapper `<div>` containing a native `<table>` with\n`border-collapse: collapse` and `width: 100%`. The wrapper has\n`overflow-x: auto` for horizontal scrolling on narrow viewports.\n\nHeader row: 2px bottom border (`var(--ggui-color-outlineVariant)`).\nData rows: 1px bottom border (`var(--ggui-color-sunken)`).\nHover: `var(--ggui-color-container)` background with 150ms ease transition.\nStriped: alternating rows (odd index) get `var(--ggui-color-container)`.\n\nSort behavior: clicking a sortable column header calls `onSort(key, direction)`.\nIf the same column is clicked again while ascending, it toggles to descending.\nThe component does NOT sort data internally -- the parent must sort `data` and\npass updated `sortKey`/`sortDirection`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `TableColumn<T>[]` | - | Array of column definitions controlling header labels, data keys, and rendering. |\n| data | `T[]` | - | Array of row data objects. Each object's keys should match the column `key` values. |\n| sortKey | `string` | - | The `key` of the currently sorted column. Used to highlight the active sort indicator and determine toggle direction on next click. |\n| sortDirection | `SortDirection` | `'asc'` | Current sort direction for the column identified by `sortKey`. Controls which triangle indicator is highlighted in the header. |\n| onSort | `(key: string, direction: SortDirection) => void` | - | Sort change handler. Called when a sortable column header is clicked. Receives the column `key` and the new `SortDirection`. The component does NOT sort data internally -- you must sort `data` in your state and pass updated `sortKey`/`sortDirection`. |\n| striped | `boolean` | `false` | When true, alternating rows (odd index) get a `var(--ggui-color-container)` background. |\n| hoverable | `boolean` | `true` | When true, rows highlight with `var(--ggui-color-container)` on mouse enter, with a 150ms ease background-color transition. |\n| compact | `boolean` | `false` | When true, reduces cell padding: - Compact: `var(--ggui-spacing-1) var(--ggui-spacing-2)` - Normal: `var(--ggui-spacing-2) var(--ggui-spacing-4)` |\n| bordered | `boolean` | `false` | When true, adds a 1px border around the table wrapper and between cells. Wrapper border: `1px solid var(--ggui-color-outlineVariant)`. Cell borders: `1px solid var(--ggui-color-sunken)`. Wrapper border-radius: `var(--ggui-shape-radius-lg)`. |\n| caption | `string` | - | Accessible table caption. Rendered as a `<caption>` element with `caption-side: top`, `var(--ggui-font-size-sm)`, `var(--ggui-color-onSunken)`. |\n\n**Example:**\n```tsx\n<Table\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'role', header: 'Role' },\n    { key: 'status', header: 'Status', render: (v) => <Badge variant={v as string}>{v as string}</Badge> },\n  ]}\n  data={users}\n  sortKey={sortKey}\n  sortDirection={sortDir}\n  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}\n  striped\n/>\n```\n\n### Tabs\n\nTabs -- Accessible tab navigation with panels and keyboard support.\n\nRenders a `<div role=\"tablist\">` with `<button role=\"tab\">` elements and a\n`<div role=\"tabpanel\">` for the active tab's content. Supports controlled\n(`activeKey` + `onChange`) and uncontrolled (internal state) modes.\n\nKeyboard navigation: ArrowLeft/ArrowRight (and ArrowUp/ArrowDown) cycle\nthrough enabled tabs. Home/End jump to first/last. Focus follows selection.\nDisabled tabs are skipped during keyboard navigation.\n\n**IMPORTANT:** `onChange` receives the tab's `key` string directly, NOT a\nReact event.\n\nTab panel padding: `var(--ggui-spacing-4) 0` (top/bottom only).\nTransitions: color, background-color, border-color at 200ms ease-in-out.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `TabItem[]` | - | Array of tab definitions. Must contain at least one item. |\n| activeKey | `string` | - | Controlled active tab key. When provided, the component is controlled and will not manage its own state. Must match one of `items[].key`. When omitted, defaults to the first item's key (uncontrolled mode). |\n| onChange | `(key: string) => void` | - | Tab change handler. Receives the selected tab's `key` string directly, NOT a React event. In controlled mode, you must update `activeKey` in response to this callback. |\n| variant | `'line' \\| 'pills' \\| 'enclosed'` | `'line'` | Visual style of the tab bar: - `'line'` -- underline indicator (2px solid primary-600 on active), border-bottom on tab list - `'pills'` -- filled pill buttons (primary-600 bg, white text on active), surfaceVariant container with radius-lg - `'enclosed'` -- bordered tab buttons with open bottom (card-style), border-bottom on tab list |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls tab button padding and font size: - `'sm'` -- padding `var(--ggui-spacing-1) var(--ggui-spacing-2)`, font `var(--ggui-font-size-xs)` - `'md'` -- padding `var(--ggui-spacing-2) var(--ggui-spacing-4)`, font `var(--ggui-font-size-sm)` - `'lg'` -- padding `var(--ggui-spacing-4) var(--ggui-spacing-6)`, font `var(--ggui-font-size-base)` |\n| fullWidth | `boolean` | `false` | When true, tab buttons expand equally to fill the container width (`flex: 1`, `justify-content: center` on each button). |\n\n**Example:**\n```tsx\n<Tabs\n  variant=\"pills\"\n  items={[\n    { key: 'overview', label: 'Overview', content: <Overview /> },\n    { key: 'settings', label: 'Settings', content: <Settings /> },\n  ]}\n  activeKey={tab}\n  onChange={setTab}\n/>\n```\n\n### Toast\n\nToast -- Notification banner with auto-dismiss and slide-in animation.\n\nRenders a `<div role=\"alert\" aria-live=\"assertive\">` with a variant-specific\nicon, optional title, message body, and optional close button.\n\nAnimation: `ggui-slideInUp 200ms ease-out both` on mount (from the motion\ntoken system). The keyframes are provided by the MotionKeyframes provider.\n\nAuto-dismiss: when `onClose` is provided and `duration > 0`, a timer calls\n`onClose` after `duration` ms. Setting `duration` to `0` disables auto-dismiss.\nThe timer resets if `visible`, `duration`, or `onClose` changes.\n\nDimensions: `min-width: 280px`, `max-width: 420px`.\nShadow: `var(--ggui-shape-shadow-lg)`.\nBorder radius: `var(--ggui-shape-radius-lg)`.\n\nWhen `visible` is false, renders nothing (returns `null`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| message | `ReactNode` | - | Message body content. Can be text or any ReactNode. |\n| variant | `'info' \\| 'success' \\| 'warning' \\| 'error'` | `'info'` | Visual style. Maps to background/border/text/icon color sets (same palette as Alert): - `'info'` -- bg `var(--ggui-color-info-50)`, border `var(--ggui-color-info-200)`, text `var(--ggui-color-info-800)` - `'success'` -- bg `var(--ggui-color-success-50)`, border `var(--ggui-color-success-200)`, text `var(--ggui-color-success-800)` - `'warning'` -- bg `var(--ggui-color-warning-50)`, border `var(--ggui-color-warning-200)`, text `var(--ggui-color-warning-800)` - `'error'` -- bg `var(--ggui-color-error-50)`, border `var(--ggui-color-error-200)`, text `var(--ggui-color-error-800)` |\n| title | `string` | - | Optional title rendered above the message in semibold (`var(--ggui-font-weight-semibold)`, `var(--ggui-font-size-sm)`). |\n| duration | `number` | `5000` | Auto-dismiss delay in milliseconds. After this duration, `onClose` is called automatically. Set to `0` to disable auto-dismiss (toast stays until manually closed). The timer is only active when both `visible` is true and `onClose` is provided. |\n| onClose | `() => void` | - | Callback fired on auto-dismiss timeout or when the close button is clicked. When provided, a close button (X icon, 16px) is rendered in the top-right area. When omitted, no close button is shown and auto-dismiss is disabled. |\n| visible | `boolean` | `true` | Controls rendering. When false, the component returns `null`. Toggling from false to true triggers the slide-in animation. |\n| position | `'top-right' \\| 'top-left' \\| 'bottom-right' \\| 'bottom-left' \\| 'top-center' \\| 'bottom-center'` | - | Intended screen position. This prop is defined on the interface but is NOT implemented by the Toast component itself -- positioning must be handled by a parent container or toast manager. |\n\n**Example:**\n```tsx\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n```\n\n### Accordion\n\nAccordion -- Collapsible content sections with chevron rotation animation.\n\nRenders a vertical list of items, each with a `<button>` header (inside `<h3>`)\nand a `<div role=\"region\">` panel. Supports controlled (`expandedKeys` + `onChange`)\nand uncontrolled (internal state) modes.\n\nChevron animation: the trailing chevron icon rotates from 0deg (collapsed) to\n180deg (expanded) with `transition: transform 200ms ease-in-out`.\n\nHeader button: full-width flex layout (`justify-content: space-between`),\n`var(--ggui-font-size-sm)`, `var(--ggui-font-weight-medium)`,\n`var(--ggui-color-onContainer)`.\nHeader padding: `var(--ggui-spacing-2) var(--ggui-spacing-4)`.\nBackground transition: `background-color 100ms ease-in-out`.\n\n**IMPORTANT:** `onChange` receives the full array of currently expanded keys,\nNOT a single key or a React event. In single mode (`multiple: false`), this\narray will have at most one element.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `AccordionItem[]` | - | Array of collapsible section definitions. |\n| expandedKeys | `string[]` | - | Controlled expanded state. Array of item `key` values that should be open. When provided, the component is controlled and will not manage its own expansion state. When omitted, defaults to `[]` (all collapsed, uncontrolled mode). |\n| onChange | `(expandedKeys: string[]) => void` | - | Expand/collapse handler. Receives the complete array of expanded keys after a toggle. In controlled mode, you must update `expandedKeys` in response to this callback. |\n| multiple | `boolean` | `false` | When true, multiple items can be open simultaneously. When false, opening one item closes any other open item (single-expand mode). |\n| variant | `'default' \\| 'bordered' \\| 'separated'` | `'default'` | Visual style controlling borders and spacing: - `'default'` -- top border on first item, bottom border on all items (`var(--ggui-color-outlineVariant)`), no gap between items - `'bordered'` -- connected card style with left/right/bottom borders on all items, top border on first, shared rounded corners (radius-lg on first/last) - `'separated'` -- each item is an independent card with full border (`1px solid var(--ggui-color-outlineVariant)`), `var(--ggui-shape-radius-lg)` radius, `var(--ggui-spacing-2)` gap between items |\n\n**Example:**\n```tsx\n<Accordion\n  variant=\"separated\"\n  items={[\n    { key: 'faq1', title: 'How do I get started?', content: 'Sign up and...' },\n    { key: 'faq2', title: 'What is the pricing?', content: 'We offer...' },\n  ]}\n  expandedKeys={expanded}\n  onChange={setExpanded}\n  multiple\n/>\n```\n\n### Support Types\n\n**ResponsiveColumns:**\n\nExplicit column count per viewport breakpoint, mobile-first. `base`\napplies from 0 up; each named key overrides at and above its\nbreakpoint width (`sm` 640px, `md` 768px, `lg` 1024px, `xl` 1280px).\nOmit `base` to default to a single column on the narrowest screens.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| base | `number` | Columns below the `sm` breakpoint. |\n| sm | `number` | Columns from 640px up. |\n| md | `number` | Columns from 768px up. |\n| lg | `number` | Columns from 1024px up. |\n| xl | `number` | Columns from 1280px up. |\n\n**SelectOption:**\n\nAn individual option within a `Select` dropdown.\n\nRendered as a native `<option>` element. When `disabled` is true, the option\nis visible but not selectable.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value submitted when this option is selected. Must be unique within the options array. |\n| label | `string` | The display text shown in the dropdown. |\n| disabled | `boolean` | When true, the option is visible but cannot be selected (grayed out by the browser). |\n\n**RadioOption:**\n\nAn individual option within a `RadioGroup`.\n\nRendered as a `<label>` containing a visually-hidden `<input type=\"radio\">`\nand a custom 18px circle indicator. Supports an optional description line\nbelow the label text.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | The value emitted via `RadioGroupProps.onChange` when this option is selected. Must be unique. |\n| label | `string` | Display text for this option. Styled with `var(--ggui-font-size-sm)` and `var(--ggui-color-onSunken)`. |\n| description | `string` | Optional secondary description rendered below the label in smaller, muted type (`var(--ggui-font-size-xs)`, `var(--ggui-color-onSunken)`). |\n| disabled | `boolean` | When true, this individual option is grayed out (`opacity: 0.5`) and cannot be selected, regardless of the group-level `disabled` prop. |\n\n**TableColumn:**\n\nColumn definition for the Table component.\n\nEach column maps a `key` in the row data object to a table column with\na header label, optional sorting, alignment, width, and custom rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key in the row data object. Used to extract cell values via `row[key]`. Must be unique across all columns in a Table. |\n| header | `string` | Column header text. Rendered in uppercase, `var(--ggui-font-size-xs)`, `var(--ggui-font-weight-semibold)`, `var(--ggui-color-onSunken)`, with `letter-spacing: 0.05em`. |\n| width | `number \\| string` | Fixed column width. Numbers are pixels, strings are CSS values (e.g., `'200px'`, `'30%'`). When omitted, the column auto-sizes based on content. |\n| align | `'left' \\| 'center' \\| 'right'` | Horizontal text alignment for both the header and data cells. |\n| sortable | `boolean` | When true, the header cell becomes clickable and shows sort direction indicators (ascending/descending triangles). Clicking toggles between `'asc'` and `'desc'`. The header gets `cursor: pointer`, `tabIndex: 0`, and keyboard support (Enter/Space to toggle). |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When provided, called instead of rendering `row[key]` directly. Receives the cell value, the full row object, and the row index. |\n\n**TabItem:**\n\nDefinition of a single tab within a Tabs component.\n\nEach item provides a unique `key` for identification, a `label` for the\ntab button, and `content` for the associated panel.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this tab. Used to match `activeKey` and as the value passed to `onChange`. |\n| label | `ReactNode` | Tab button label. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the tab bar when this tab is active. |\n| disabled | `boolean` | When true, the tab button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be selected via click or keyboard navigation. |\n| icon | `ReactNode` | Optional icon rendered before the label inside the tab button, with `var(--ggui-spacing-1)` gap between icon and label. |\n\n**AccordionItem:**\n\nDefinition of a single collapsible section within an Accordion.\n\nEach item provides a unique `key`, a clickable `title` for the header button,\nand `content` revealed when expanded.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Unique identifier for this item. Used in `expandedKeys` and passed to `onChange`. |\n| title | `ReactNode` | Header label rendered inside the toggle button. Can be text or any ReactNode. |\n| content | `ReactNode` | Panel content rendered below the header when expanded. Styled with `var(--ggui-font-size-sm)`, `var(--ggui-color-onSunken)`, `line-height: var(--ggui-font-lineHeight-normal)`. Padding: `0 var(--ggui-spacing-4) var(--ggui-spacing-4)`. |\n| disabled | `boolean` | When true, the header button shows `opacity: 0.5`, `cursor: not-allowed`, and cannot be toggled. |\n\n\n## Components\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### SearchField\n\nA text input with a leading search icon and optional submit button.\n\nComposes: `Input` (native `<input type=\"search\">`), `Button`, `Spinner`, `Icon`.\n\nSupports controlled and uncontrolled usage. When `value` is `undefined` the\ncomponent tracks its own state internally. Pressing **Enter** triggers\n`onSearch` with the current value. When `loading` is `true` the search icon\nis replaced by a `Spinner` and the input is disabled.\n\nTokens used: `colors.gray[300]` border, `colors.gray[50]` disabled bg,\n`colors.gray[400]` icon color, `colors.gray[900]` text color.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | - | Current search value. When provided, the component is **controlled** and the caller must update this via `onChange`. When omitted, the component manages its own internal state. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React `ChangeEvent`). |\n| onSearch | `(value: string) => void` | - | Called when the user presses **Enter** or clicks the search button (if `showButton` is `true`). Receives the current value directly. |\n| placeholder | `string` | `'Search...'` | Placeholder text shown when the input is empty. |\n| showButton | `boolean` | `false` | When `true`, renders a `Button` primitive to the right of the input. The button's label is set by `buttonText`. |\n| buttonText | `string` | `'Search'` | Label rendered inside the submit button. Only visible when `showButton` is `true`. |\n| loading | `boolean` | - | When `true`, replaces the search icon with a `Spinner`, disables the input, and disables the submit button. |\n| disabled | `boolean` | - | When `true`, the input and button are visually disabled and do not respond to interaction. The input background changes to `colors.gray[50]`. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls input height and font size. - `'sm'` -- 6px vertical padding, 14px font - `'md'` -- 10px vertical padding, 14px font - `'lg'` -- 12px vertical padding, 16px font  The Button size maps `sm`->`sm`, `md`->`md`, `lg`->`md`. |\n\n**Example:**\n```tsx\n```tsx\n<SearchField\n  value={query}\n  onChange={setQuery}\n  onSearch={(q) => fetchResults(q)}\n  placeholder=\"Search products...\"\n  showButton\n  buttonText=\"Go\"\n  size=\"md\"\n/>\n```\n```\n\n### FormField\n\nA wrapper that adds a label, optional description, error message,\nand helper text around any form input passed as `children`.\n\nComposes: no other primitives -- pure layout with semantic `<label>` and\n`<span>` elements.\n\nVisual hierarchy (top to bottom):\n1. **Label** (required) -- `fontSize.sm`, `fontWeight.medium`, `colors.gray[700]`\n2. **Required indicator** -- red asterisk (`colors.error[500]`) appended to label\n3. **Description** -- `fontSize.xs`, `colors.gray[500]`, 4px bottom margin\n4. **Children** -- the form control itself\n5. **Error / Helper text** -- `fontSize.xs`; error in `colors.error[500]`,\n   helper in `colors.gray[500]`. Error takes priority when both are provided.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Text rendered inside the `<label>` element above the input. |\n| children | `ReactNode` | - | The form control (typically an `Input`, `Select`, or `Textarea` primitive) rendered between the label/description and the error/helper row. |\n| error | `string` | - | Error message displayed below `children` in `colors.error[500]`. When present, it takes precedence over `helperText`. |\n| helperText | `string` | - | Neutral guidance text displayed below `children` in `colors.gray[500]`. Hidden when `error` is present. |\n| required | `boolean` | - | When `true`, appends a red asterisk (`*`) after the label text. Does **not** add any HTML validation attributes -- handle that on the child input. |\n| description | `string` | - | Secondary description rendered between the label and the child control in `fontSize.xs` / `colors.gray[500]`. Use for longer guidance that does not belong in `helperText`. |\n\n**Example:**\n```tsx\n```tsx\n<FormField\n  label=\"Email address\"\n  required\n  description=\"We will never share your email.\"\n  error={errors.email}\n>\n  <Input value={email} onChange={setEmail} placeholder=\"you@example.com\" />\n</FormField>\n```\n```\n\n### MenuItem\n\nA full-width clickable row for menus, sidebars, and action lists.\n\nComposes: none -- renders a native `<button>` element.\n\nBuilt-in transition: `background-color 0.15s` on hover.\n\nColor logic:\n- **Normal**: text `colors.gray[700]`, hover bg `colors.gray[100]`\n- **Active**: bg `colors.primary[50]`, text `colors.gray[700]`, `fontWeight.medium`\n- **Danger**: text `colors.error[600]`, hover bg `colors.error[50]`, active bg `colors.error[100]`\n- **Disabled**: text `colors.gray[400]`, `cursor: not-allowed`\n\nLayout: flexbox row with `8px` gap, `8px 12px` padding, `radius.md` border-radius.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | Primary text content of the menu item. |\n| icon | `ReactNode` | - | Icon or element rendered to the left of the label. Flex-shrink 0. |\n| rightElement | `ReactNode` | - | Element rendered to the right of the label (e.g., a keyboard shortcut badge or a count). Colored `colors.gray[400]`, flex-shrink 0. |\n| onClick | `() => void` | - | Called when the item is clicked. Suppressed when `disabled` is `true`. |\n| disabled | `boolean` | - | When `true`, the item is non-interactive: `colors.gray[400]` text, `cursor: not-allowed`, click handler suppressed. |\n| active | `boolean` | - | Marks this item as the current selection. Applies a tinted background (`colors.primary[50]`, or `colors.error[100]` when `danger` is also set) and `fontWeight.medium`. |\n| danger | `boolean` | - | Switches the item to destructive styling: `colors.error[600]` text, `colors.error[50]` hover background. |\n\n**Example:**\n```tsx\n```tsx\n<MenuItem\n  label=\"Delete project\"\n  icon={<Icon name=\"trash\" size={16} />}\n  danger\n  onClick={() => confirmDelete(projectId)}\n/>\n```\n```\n\n### Tag\n\nAn inline label for categories, filters, statuses, or selections.\nOptionally dismissable via a close button.\n\nComposes: none -- pure `<span>` with an optional close `<button>`.\n\nEach `variant` maps to a background / text / border color triple from the\ndesign tokens:\n- `'default'`  -- `gray[100]` / `gray[700]` / `gray[200]`\n- `'primary'`  -- `primary[50]` / `primary[700]` / `primary[200]`\n- `'success'`  -- `success[50]` / `success[700]` / `success[200]`\n- `'warning'`  -- `warning[50]` / `warning[700]` / `warning[200]`\n- `'error'`    -- `error[50]` / `error[700]` / `error[200]`\n- `'info'`     -- `info[50]` / `info[700]` / `info[200]`\n\nThe close button renders an inline SVG \"x\" icon (12x12) with `opacity: 0.7`\nand an `aria-label=\"Remove\"`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Tag content -- typically a short text string. |\n| variant | `'default' \\| 'primary' \\| 'success' \\| 'warning' \\| 'error' \\| 'info'` | `'default'` | Semantic color variant applied to background, text, and border. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls padding, font size, and internal gap. - `'sm'` -- 2px/6px padding, `fontSize.xs`, 4px gap - `'md'` -- 4px/8px padding, `fontSize.xs`, 6px gap - `'lg'` -- 6px/10px padding, `fontSize.sm`, 6px gap |\n| closable | `boolean` | - | When `true`, renders a small close (\"x\") button after the content. Clicking it fires `onClose`. |\n| onClose | `() => void` | - | Called when the close button is clicked. Only relevant when `closable` is `true`. |\n| icon | `ReactNode` | - | Icon or element rendered before the text content. |\n\n**Example:**\n```tsx\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n```\n\n### Dropdown\n\nA click-triggered menu anchored to a trigger element. Manages its own\nopen/close state internally.\n\nComposes: `MenuItem` for each option.\n\nBehavior:\n- Clicking the trigger toggles the menu open/closed.\n- Selecting an option calls `onChange(option.value)` and closes the menu.\n- Clicking outside the container or pressing **Escape** closes the menu.\n- The currently selected option (matching `value`) is rendered with\n  `MenuItem`'s `active` state.\n\nMenu panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, 160px min-width, 4px padding.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| trigger | `ReactNode` | - | The element the user clicks to open the menu. Receives a wrapping `<div>` with `cursor: pointer` (or `not-allowed` when disabled). |\n| options | `DropdownOption[]` | - | Array of selectable options rendered as `MenuItem` rows. |\n| value | `string` | - | The `value` of the currently selected option. The matching `MenuItem` is rendered with `active` styling. |\n| onChange | `(value: string) => void` | - | Called with the `value` string of the selected option (not the full `DropdownOption` object). The menu closes immediately after. |\n| placement | `'bottom-start' \\| 'bottom-end' \\| 'top-start' \\| 'top-end'` | `'bottom-start'` | Where to anchor the menu panel relative to the trigger. - `'bottom-start'` -- below, aligned to left edge - `'bottom-end'`   -- below, aligned to right edge - `'top-start'`    -- above, aligned to left edge - `'top-end'`      -- above, aligned to right edge |\n| disabled | `boolean` | - | When `true`, the trigger shows `cursor: not-allowed` and clicking it does not open the menu. |\n\n**Example:**\n```tsx\n```tsx\n<Dropdown\n  trigger={<Button variant=\"outline\">Sort by</Button>}\n  options={[\n    { value: 'name', label: 'Name' },\n    { value: 'date', label: 'Date created' },\n    { value: 'delete', label: 'Delete', danger: true },\n  ]}\n  value={sortBy}\n  onChange={setSortBy}\n  placement=\"bottom-end\"\n/>\n```\n```\n\n### Autocomplete\n\nA text input with a filterable suggestion dropdown, keyboard navigation,\nand loading/empty states.\n\nComposes: `Input` primitive (with `label`, `error`, `placeholder` forwarded),\n`Spinner` (loading state).\n\nFiltering: options are filtered client-side by case-insensitive substring\nmatch against both `option.label` and `option.value`.\n\nKeyboard support:\n- **ArrowDown / ArrowUp** -- move highlight through filtered options\n  (opens dropdown if closed)\n- **Enter** -- selects the highlighted option\n- **Escape** -- closes the dropdown\n\nOn selection, `onChange` is called with `option.label` (the display text)\nand `onSelect` is called with the full `AutocompleteOption` object.\n\nDropdown panel: `colors.white` bg, `colors.gray[200]` border, `radius.lg`\nborder-radius, `shadow.lg`, `zIndex.dropdown`, max-height 240px with\noverflow scroll.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| value | `string` | `''` | Current text in the input field. On selection, this is set to the selected option's `label`. |\n| onChange | `(value: string) => void` | - | Called on every keystroke with the new input string (value directly, not a React event). Also called on selection with `option.label`. |\n| onSelect | `(option: AutocompleteOption) => void` | - | Called when the user selects an option (click or Enter on highlighted item). Receives the full `AutocompleteOption` object, not just the value string. |\n| options | `AutocompleteOption[]` | - | The full list of available options. Filtering is handled internally via case-insensitive substring match on `label` and `value`. |\n| placeholder | `string` | - | Placeholder text forwarded to the inner `Input` primitive. |\n| label | `string` | - | Label text forwarded to the inner `Input` primitive. |\n| loading | `boolean` | - | When `true`, the dropdown shows a centered `Spinner` instead of the option list. The input remains interactive. |\n| disabled | `boolean` | - | When `true`, the inner `Input` is disabled and the dropdown does not open. |\n| error | `string` | - | Error message forwarded to the inner `Input` primitive. |\n| noResultsText | `string` | `'No results found'` | Text shown in the dropdown when filtering produces zero matches. Rendered centered in `colors.gray[500]` / `fontSize.sm`. |\n\n**Example:**\n```tsx\n```tsx\n<Autocomplete\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  onSelect={(opt) => setCountryCode(opt.value)}\n  options={countries}\n  placeholder=\"Type to search...\"\n  noResultsText=\"No countries found\"\n/>\n```\n```\n\n### Breadcrumb\n\nA horizontal navigation trail showing the user's location within a\nhierarchy. Renders a `<nav aria-label=\"Breadcrumb\">`.\n\nComposes: `Link` primitive (for items with `href`).\n\nRendering rules per item:\n- **Last item**: static `<span>` with `colors.gray[900]`, `fontWeight: 500`,\n  and `aria-current=\"page\"`.\n- **Non-last with `href`**: `Link` in `colors.gray[500]` with\n  `underline=\"hover\"`. If `onItemClick` is provided, `e.preventDefault()`\n  is called and the handler fires instead of navigating.\n- **Non-last without `href`**: unstyled `<button>` in `colors.gray[500]`.\n\nLayout: flexbox row, `8px` gap, `fontSize.sm`.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `BreadcrumbItem[]` | - | Ordered array of breadcrumb segments from root to current page. |\n| separator | `ReactNode` | `'/'` | Separator rendered between each pair of items. Can be a string (e.g., `\"/\"`, `\">\"`) or a ReactNode (e.g., an `Icon`). Rendered in `colors.gray[400]`. |\n| onItemClick | `(item: BreadcrumbItem, index: number) => void` | - | Called when a non-last item is clicked. Receives the `BreadcrumbItem` and its zero-based `index`. When provided on items that have `href`, the default navigation is prevented via `e.preventDefault()`. |\n\n**Example:**\n```tsx\n```tsx\n<Breadcrumb\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Projects', href: '/projects' },\n    { label: 'ggui' },\n  ]}\n  separator=\"/\"\n  onItemClick={(item) => router.push(item.href!)}\n/>\n```\n```\n\n### Pagination\n\nPage navigation controls with previous/next arrows, numbered page buttons,\nand optional first/last jumps. Renders a `<nav aria-label=\"Pagination\">`.\n\nComposes: `Button` (ghost variant for prev/next/first/last arrows),\n`Icon` (`chevron-left`, `chevron-right`).\n\nBuilt-in transition: `all 0.15s` on page number buttons.\n\nPage windowing: when `totalPages > maxVisible`, the component shows the\nfirst page, last page, a window of pages around `currentPage`, and\nellipsis (\"...\") markers for gaps. The window adjusts when near the\nstart or end of the range.\n\nActive page button: `colors.primary[600]` bg, `colors.white` text,\n`fontWeight.medium`. Inactive: transparent bg, `colors.gray[700]` text.\n\nArrow buttons are automatically disabled at boundary pages (first/last).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| currentPage | `number` | - | Current active page. **1-indexed** (first page is `1`). |\n| totalPages | `number` | - | Total number of pages. Determines when last-page / next-page buttons disable. |\n| onPageChange | `(page: number) => void` | - | Called when the user clicks a page number, arrow, or first/last button. Receives the target page number (1-indexed) directly. |\n| showFirstLast | `boolean` | `true` | When `true`, renders double-chevron buttons for jumping to the first and last page. These buttons are disabled when already on the respective boundary. |\n| maxVisible | `number` | `5` | Maximum number of page buttons visible at once (including the first and last page, but excluding ellipsis markers). When `totalPages` exceeds this value, ellipsis gaps appear. |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls button dimensions and icon sizes. - `'sm'` -- 28px buttons, 14px icons, Button size `xs` - `'md'` -- 32px buttons, 16px icons, Button size `sm` - `'lg'` -- 40px buttons, 20px icons, Button size `md` |\n| disabled | `boolean` | - | When `true`, all page buttons and arrows are visually dimmed (`opacity: 0.5`) and clicks are suppressed. |\n\n**Example:**\n```tsx\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n```\n\n### EmptyState\n\nEmptyState -- placeholder for a region with no data: empty lists,\nzero search results, an error fallback. Render it instead of\nnothing whenever a data array could be empty \u2014 a list that shows\nnothing when empty looks broken.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| icon | `string \\| ReactNode` | - | A Lucide icon name (kebab-case), rendered large and subtle above the title, or a custom node. Omit for a text-only empty state. |\n| title | `string` | - | The headline, e.g. \"No results found\". |\n| description | `string` | - | Optional supporting line below the title. |\n| action | `ReactNode` | - | Optional call-to-action, typically a `<Button>`. |\n\n**Example:**\n```tsx\n{results.length === 0\n  ? <EmptyState icon=\"search-x\" title=\"No matches\" description=\"Try a broader query.\" />\n  : results.map((r) => <Row key={r.id}>\u2026</Row>)}\n```\n\n### Stat\n\nStat -- a single KPI / metric: a label, a large value, an optional\ntrend-coloured delta and icon. Reach for it whenever the UI is\n\"show a number\" \u2014 dashboards, weather and price cards, analytics\ntiles. Drop several into a `<Grid>` for a stat grid.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| label | `string` | - | The metric name, e.g. \"Revenue\". Rendered small and uppercase above the value. |\n| value | `string \\| number` | - | The headline value \u2014 the big number. A number, or a pre-formatted string (`\"$48.2k\"`, `\"18\xB0C\"`). |\n| delta | `string` | - | Optional change indicator, pre-formatted, e.g. `\"+12.5%\"` or `\"-3\"`. |\n| trend | `'up' \\| 'down' \\| 'neutral'` | `'neutral'` | Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error, `'neutral'` muted. |\n| icon | `string \\| ReactNode` | - | Optional Lucide icon name (kebab-case) or custom node, shown next to the label. |\n\n**Example:**\n```tsx\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n```\n\n### Stepper\n\nStepper -- a display-only step indicator for multi-step flows\n(wizards, checkouts, onboarding): numbered markers joined by\nconnector lines, with completed (check), current (filled), and\nupcoming (outlined) states styled distinctly.\n\nStepper renders step state; it never owns it. Declare the step\nlabels as a top-level `const`, track the current index in\n`useState`, and advance it from your own Next/Back buttons (or\n`onStepClick`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| steps | `string[]` | - | Ordered step labels, one per step. Declare as a top-level `const` array \u2014 never as state. |\n| current | `number` | - | Zero-based index of the active step. Steps before it render as completed (check mark), steps after it as upcoming. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Flow direction. `'horizontal'` joins the markers with connector lines in a row; `'vertical'` stacks the steps with short connector columns \u2014 better for sidebars or long step labels. |\n| onStepClick | `(index: number) => void` | - | When provided, each step becomes a real button and clicks receive the step's zero-based index. Typical use: jumping back to a completed step; guard forward jumps in the handler if the flow validates per step. |\n\n**Example:**\n```tsx\nconst STEPS = ['Account', 'Profile', 'Review'];\n// In the component: const [step, setStep] = useState(0);\n<Stack gap=\"lg\">\n  <Stepper steps={STEPS} current={step} />\n  {step === 0 && <AccountFields />}\n  <Row gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\" disabled={step === 0} onClick={() => setStep(step - 1)}>Back</Button>\n    <Button onClick={() => setStep(step + 1)}>Next</Button>\n  </Row>\n</Stack>\n```\n\n### Markdown\n\nMarkdown -- renders markdown-formatted text as styled content:\nheadings, paragraphs, **bold** / *italic*, `inline code`, fenced\ncode blocks, bulleted and numbered lists, pipe tables, and links.\n\nUse it whenever a prop or context slot carries prose the agent\nauthors in markdown -- article bodies, AI-generated explanations,\ndescriptions, notes, help text. Pass the raw markdown string\nstraight through; never pre-parse it, never split it into per-line\n`Text` elements, and never rebuild formatting with nested\n`<strong>`/`<em>` markup yourself.\n\nSafe by construction: raw HTML in the source displays as literal\ntext (never markup), and links render inert unless their scheme is\nhttp(s)/mailto. Streaming-tolerant: a mid-stream prefix parses\ncleanly and completed constructs never change shape, so binding a\ngrowing string re-renders correctly.\n\nFor a single line of formatted text INSIDE another element (a table\ncell, a list row, a caption), use `MarkdownInline` instead -- same\n`markdown` prop, inline-level constructs only (no headings, lists,\nor code fences), renders inside the parent's typography.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Markdown source text, passed through verbatim. Supports the conversational subset: `#`-`###` headings, paragraphs, bold, italic, inline code, fenced code blocks, `-`/`1.` lists, `\\|` pipe tables, and `[label](url)` links. Bind stateful or streamed prose directly. |\n\n**Example:**\n```tsx\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n```\n\n### MarkdownInline\n\nMarkdownInline -- renders ONE line of inline-level markdown (bold,\nitalic, inline code, links) inside the parent's typography -- a table\ncell, a list row, a caption, a summary line. Same `markdown` prop as\n`Markdown`; block constructs (headings, lists, code fences) are not\nrendered -- reach for `Markdown` for multi-paragraph bodies.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| markdown | `string` | - | Inline markdown source -- bold, italic, inline code, and `[label](url)` links. Block-level syntax renders as plain text. |\n\n**Example:**\n```tsx\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n```\n\n### Support Types\n\n**DropdownOption:**\n\nA single option inside a `Dropdown`. Each option maps to one `MenuItem`\ninternally.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier returned to `onChange` when this option is selected. |\n| label | `string` | Human-readable text shown in the menu row. |\n| icon | `ReactNode` | Optional icon rendered to the left of the label via `MenuItem.icon`. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive. |\n| danger | `boolean` | When `true`, the option uses destructive (red) styling via `MenuItem.danger`. |\n\n**AutocompleteOption:**\n\nA single option in the `Autocomplete` suggestion list.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| value | `string` | Unique identifier for this option. Also used for case-insensitive filtering against the input value. |\n| label | `string` | Primary display text. Also used for case-insensitive filtering and is written into the input on selection. |\n| description | `string` | Secondary description rendered below the label in `fontSize.xs` / `colors.gray[500]`. |\n| icon | `ReactNode` | Icon rendered to the left of the label/description block. Flex-shrink 0. |\n| disabled | `boolean` | When `true`, the option is visible but non-interactive (`cursor: not-allowed`, `colors.gray[400]` text). |\n\n**BreadcrumbItem:**\n\nA single segment in a `Breadcrumb` trail. Items with `href` render as\n`Link` primitives; items without render as plain `<button>` elements.\nThe last item in the array is always rendered as static text with\n`aria-current=\"page\"`.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for this breadcrumb segment. |\n| href | `string` | URL for this segment. When provided (and this is not the last item), the segment renders as a `Link` primitive with `underline=\"hover\"`. When omitted, it renders as a `<button>`. |\n| icon | `ReactNode` | Icon rendered immediately before the label. Its color follows the segment's text color: `colors.gray[500]` for navigable items, `colors.gray[900]` for the current (last) item. |\n\n\n## Compositions\n\nImport: `import { Component } from '@ggui-ai/design'`\n\n### Header\n\nProps for the `Header` composition.\n\nA horizontal page header that arranges a logo, navigation, and action slots\nin a flex row (`justify-content: space-between`). Internally renders a `<header>` element;\ndoes not compose other ggui primitives.\n\nWhen `sticky` is true the header gets `position: sticky; top: 0` with `zIndex.sticky`\nand a `shadow.sm` box-shadow.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| logo | `ReactNode` | - | Logo or brand element rendered at the start (flex-shrink: 0). |\n| navigation | `ReactNode` | - | Navigation content rendered in a `<nav>` element with `flex: 1` and a 32 px left margin. |\n| actions | `ReactNode` | - | Right-side action elements (buttons, avatar, etc.) rendered with a 12 px gap. |\n| sticky | `boolean` | `false` | When true, the header becomes `position: sticky` at the top of its scroll container with `zIndex.sticky` and `shadow.sm`. |\n| background | `string` | `colors.white` | Background color of the header. |\n| bordered | `boolean` | `true` | When true, renders a 1 px bottom border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Header\n  logo={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  navigation={<a href=\"/docs\">Docs</a>}\n  actions={<Button size=\"sm\">Sign In</Button>}\n  sticky\n  bordered\n/>\n```\n```\n\n### Sidebar\n\nProps for the `Sidebar` composition.\n\nA vertical navigation panel that composes the `Icon` primitive for chevron indicators.\nItems are rendered as `<button>` elements inside a scrollable `<nav>`. Nested items\nare indented 16 px per depth level. The sidebar animates width changes with a 200 ms\nCSS transition. Active items are highlighted with `colors.primary[50]` background\nand `colors.primary[700]` text.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `SidebarItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Matched items get a highlighted background and bold text. |\n| onItemClick | `(item: SidebarItem) => void` | - | Called when any item (including parent items with children) is clicked. |\n| collapsed | `boolean` | `false` | When true, hides labels and badges; only icons remain visible, centered in the collapsed width. Nested children are hidden entirely. |\n| header | `ReactNode` | - | Content rendered above the item list, separated by a bottom border. |\n| footer | `ReactNode` | - | Content rendered below the item list, separated by a top border. |\n| width | `number` | `256` | Width in pixels when expanded. |\n| collapsedWidth | `number` | `64` | Width in pixels when collapsed. |\n\n**Example:**\n```tsx\n```tsx\n<Sidebar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'settings', label: 'Settings', icon: <Icon name=\"settings\" />,\n      children: [\n        { id: 'profile', label: 'Profile' },\n        { id: 'billing', label: 'Billing' },\n      ]},\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.href)}\n  collapsed={false}\n  width={256}\n/>\n```\n```\n\n### CardGrid\n\nProps for the `CardGrid` composition.\n\nA CSS Grid wrapper that arranges children in equal-width columns. When `columns`\nis a number, it produces `repeat(N, 1fr)`. When it is a responsive object,\nit falls back to `repeat(auto-fit, minmax(280px, 1fr))` for fluid responsive behavior.\n\nDoes not compose any ggui primitives internally \u2014 it is a pure layout container.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| children | `ReactNode` | - | Card elements to arrange in the grid. |\n| columns | `number \\| { sm?: number; md?: number; lg?: number }` | `3` | Number of columns, or a responsive breakpoint map.  - `number` \u2014 fixed column count via `repeat(N, 1fr)`. - `{ sm?, md?, lg? }` \u2014 triggers `repeat(auto-fit, minmax(280px, 1fr))` for fluid layout. |\n| gap | `number` | `16` | Gap between grid items in pixels. |\n\n**Example:**\n```tsx\n```tsx\n<CardGrid columns={3} gap={24}>\n  <Card>A</Card>\n  <Card>B</Card>\n  <Card>C</Card>\n</CardGrid>\n```\n```\n\n### CommentThread\n\nProps for the `CommentThread` composition.\n\nA threaded comment section that composes `Avatar`, `Button`, `TextArea`, and `Spinner`\nprimitives. Comments are rendered recursively with 40 px indentation per nesting level.\nEach comment shows author avatar, name, timestamp, content, reactions, and a \"Reply\" toggle.\nWhen `currentUser` is provided, a new-comment input with avatar and submit button is shown\nabove the thread.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| comments | `Comment[]` | - | Array of top-level comments to render. Replies are nested within each comment. |\n| currentUser | `{     /** Display name for the current user's avatar. */     name: string;     /** Avatar image URL for the current user. */     avatar?: string;   }` | - | Current user info. When provided, a new-comment input area is rendered above the thread. |\n| onAddComment | `(content: string, parentId?: string) => void` | - | Called when the user submits a new top-level comment. |\n| onReply | `(commentId: string, content: string) => void` | - | Called when the user submits a reply to an existing comment. |\n| onReaction | `(commentId: string, emoji: string) => void` | - | Called when the user clicks an emoji reaction on a comment. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the comment list. |\n\n**Example:**\n```tsx\n```tsx\n<CommentThread\n  comments={[\n    { id: '1', author: { name: 'Alice' }, content: 'Great work!', timestamp: new Date(),\n      replies: [{ id: '2', author: { name: 'Bob' }, content: 'Thanks!', timestamp: new Date() }] }\n  ]}\n  currentUser={{ name: 'Alice', avatar: '/alice.jpg' }}\n  onAddComment={(content) => post(content)}\n  onReply={(commentId, content) => reply(commentId, content)}\n  onReaction={(commentId, emoji) => react(commentId, emoji)}\n/>\n```\n```\n\n### DataTable\n\nProps for the `DataTable` composition.\n\nA sortable, selectable data table that composes `Checkbox`, `Spinner`, and `Icon`\nprimitives. Renders a `<table>` inside a bordered container with 8 px border-radius.\nThe header row has a `colors.gray[50]` background. Sortable columns show a chevron\nicon on click (toggles asc/desc). Selected rows are highlighted with `colors.primary[50]`.\nRow background transitions use a 150 ms ease. The \"select all\" checkbox supports an\nindeterminate state when a subset of rows is selected.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| columns | `DataTableColumn<T>[]` | - | Column definitions that control header, alignment, sorting, and rendering. |\n| data | `T[]` | - | Row data array. Each entry corresponds to one table row. |\n| rowKey | `string \\| ((row: T) => string)` | `'id'` | Property name or function used to derive a unique key for each row. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of table body rows. |\n| emptyText | `string` | `'No data'` | Text shown when `data` is empty and not loading. |\n| onSort | `(key: string, direction: 'asc' \\| 'desc') => void` | - | Called when a sortable column header is clicked. Toggles direction automatically (asc -> desc) if the same column is clicked again. |\n| sortKey | `string` | - | The column key currently being sorted. |\n| sortDirection | `'asc' \\| 'desc'` | - | The current sort direction. |\n| onRowClick | `(row: T, index: number) => void` | - | Called when a row is clicked. Rows get `cursor: pointer` when this handler is provided. |\n| selectable | `boolean` | - | When true, adds a checkbox column at the start of each row. |\n| selectedKeys | `string[]` | `[]` | Array of currently selected row keys. |\n| onSelectionChange | `(keys: string[]) => void` | - | Called when the set of selected row keys changes (via row checkbox or select-all). |\n\n**Example:**\n```tsx\n```tsx\n<DataTable\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'email', header: 'Email' },\n    { key: 'role', header: 'Role', render: (v) => <Badge>{v}</Badge> },\n  ]}\n  data={users}\n  rowKey=\"id\"\n  selectable\n  selectedKeys={selected}\n  onSelectionChange={setSelected}\n  onSort={(key, dir) => sort(key, dir)}\n  sortKey=\"name\"\n  sortDirection=\"asc\"\n/>\n```\n```\n\n### ChatWindow\n\nProps for the `ChatWindow` composition.\n\nA messaging interface that composes `Avatar`, `Button`, `Spinner`, and `Icon` primitives.\nLayout is a flex column filling 100% height with a bordered `radius.lg` container.\nMessages from the current user align right with `colors.primary[600]` bubbles and white text.\nOther users' messages align left with `colors.gray[100]` bubbles. The message area\nauto-scrolls to the bottom on new messages via `scrollIntoView({ behavior: 'smooth' })`.\nThe text input sends on Enter (Shift+Enter for newline).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| messages | `ChatMessage[]` | - | Array of chat messages to display in chronological order. |\n| currentUserId | `string` | - | ID of the current user. Messages from this user render right-aligned with a primary color bubble. |\n| onSendMessage | `(content: string) => void` | - | Called when the user submits a message (Enter key or send button). |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the message list. |\n| typing | `{ name: string } \\| null` | - | When non-null, displays a typing indicator below the last message (e.g., \"Alice is typing...\"). |\n| placeholder | `string` | `'Type a message...'` | Placeholder text for the message input field. |\n| header | `ReactNode` | - | Optional header content rendered above the message area, separated by a bottom border. |\n\n**Example:**\n```tsx\n```tsx\n<ChatWindow\n  messages={messages}\n  currentUserId=\"user-1\"\n  onSendMessage={(content) => send(content)}\n  typing={{ name: 'Alice' }}\n  placeholder=\"Type a message...\"\n  header={<h3>Chat with Alice</h3>}\n/>\n```\n```\n\n### NavigationBar\n\nProps for the `NavigationBar` composition.\n\nA horizontal or vertical navigation menu. Does not compose other ggui primitives\n(uses plain `<button>` and `<a>` elements). Active items are styled per variant:\n\n- `'default'` \u2014 active item gets `colors.primary[600]` text and medium font weight.\n- `'pills'` \u2014 active item gets a `radius.full` pill with `colors.primary[100]` background.\n- `'underline'` \u2014 active item gets a 2 px bottom border in `colors.primary[600]`.\n  When horizontal, the entire nav also has a 1 px bottom border.\n\nAll items have a 150 ms transition on all properties.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| items | `NavItem[]` | - | Array of navigation items to render. |\n| activeId | `string` | - | ID of the currently active item. Controls visual highlighting per variant style. |\n| onItemClick | `(item: NavItem) => void` | - | Called when a non-disabled item is clicked. For `<a>` elements, `preventDefault` is called first. |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` | Layout direction. - `'horizontal'` \u2014 flex-row with 4 px gap. - `'vertical'` \u2014 flex-column with 2 px gap. |\n| variant | `'default' \\| 'pills' \\| 'underline'` | `'default'` | Visual style for active/inactive items. - `'default'` \u2014 text color change only. - `'pills'` \u2014 rounded pill background on active items. - `'underline'` \u2014 bottom border on active items. |\n\n**Example:**\n```tsx\n```tsx\n<NavigationBar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'about', label: 'About' },\n    { id: 'contact', label: 'Contact' },\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.id)}\n  orientation=\"horizontal\"\n  variant=\"pills\"\n/>\n```\n```\n\n### FileUploader\n\nProps for the `FileUploader` composition.\n\nA drag-and-drop file upload area that composes `Button`, `Progress`, and `Icon` primitives.\nThe drop zone is a dashed-border container that highlights in `colors.primary[400]`/`colors.primary[50]`\non drag-over. Below the drop zone, each file in `files` is listed with its name, size,\noptional progress bar (for uploading status), and a remove button.\n\nFile validation (max size, max count) is applied client-side before calling `onFilesSelected`.\nFiles exceeding `maxSize` are silently filtered out; files exceeding `maxFiles` are truncated.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| files | `UploadedFile[]` | `[]` | Array of files currently in the upload queue, shown below the drop zone. |\n| onFilesSelected | `(files: File[]) => void` | - | Called when the user selects files via click or drag-and-drop. Receives native `File` objects after client-side filtering (maxSize, maxFiles). |\n| onFileRemove | `(fileId: string) => void` | - | Called when the user clicks the remove button on a file entry. |\n| accept | `string` | - | Accepted file types passed to the hidden `<input type=\"file\" accept=\"...\">`. E.g., `'image/*,.pdf'`. |\n| multiple | `boolean` | `true` | When true, allows selecting multiple files at once. |\n| maxSize | `number` | - | Maximum file size in bytes. Files exceeding this are silently excluded from the selection. |\n| maxFiles | `number` | - | Maximum number of files. Excess files beyond `maxFiles - files.length` are truncated. |\n| disabled | `boolean` | - | When true, the drop zone is visually dimmed (opacity 0.5) and non-interactive. |\n| dragDrop | `boolean` | `true` | When true, enables drag-and-drop on the drop zone. When false, the prompt text changes to \"Click to browse files\". |\n\n**Example:**\n```tsx\n```tsx\n<FileUploader\n  files={uploadedFiles}\n  onFilesSelected={(files) => startUpload(files)}\n  onFileRemove={(id) => removeFile(id)}\n  accept=\"image/*,.pdf\"\n  multiple\n  maxSize={5 * 1024 * 1024}\n  maxFiles={10}\n  dragDrop\n/>\n```\n```\n\n### NotificationCenter\n\nProps for the `NotificationCenter` composition.\n\nA notification list with a header bar that composes `Button`, `Spinner`, and `Icon`\nprimitives. The header shows a \"Notifications\" title, an unread count badge\n(pill in `colors.primary[100]`), and \"Mark all read\" / \"Clear all\" buttons.\nEach notification item shows a colored status dot, title, message, timestamp,\n\"Mark as read\" link, and optional action. The list is scrollable (`overflowY: auto`).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| notifications | `Notification[]` | - | Array of notifications to display, in the order provided. |\n| onMarkAsRead | `(id: string) => void` | - | Called when the user clicks \"Mark as read\" on an individual notification. |\n| onMarkAllAsRead | `() => void` | - | Called when the user clicks the \"Mark all read\" header button. Only shown when there are unread items. |\n| onDismiss | `(id: string) => void` | - | Called when the user clicks the dismiss (X) button on an individual notification. |\n| onClearAll | `() => void` | - | Called when the user clicks the \"Clear all\" header button. Only shown when there are any notifications. |\n| emptyText | `string` | `'No notifications'` | Text shown when `notifications` is empty and not loading. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the notification list. |\n\n**Example:**\n```tsx\n```tsx\n<NotificationCenter\n  notifications={[\n    { id: '1', title: 'Deployment complete', type: 'success', timestamp: new Date(), read: false },\n    { id: '2', title: 'Build failed', type: 'error', message: 'Lint errors', timestamp: new Date() },\n  ]}\n  onMarkAsRead={(id) => markRead(id)}\n  onMarkAllAsRead={() => markAllRead()}\n  onDismiss={(id) => dismiss(id)}\n  onClearAll={() => clearAll()}\n/>\n```\n```\n\n### Modal\n\nProps for the `Modal` composition.\n\nA dialog overlay that composes `Button`, `Icon`, and `Heading` primitives.\nThe overlay uses `animation.fadeIn` (`ggui-fadeIn`) and the dialog panel uses\n`animation.scaleIn` (`ggui-scaleIn`) \u2014 both GPU-composited (opacity + transform).\nWhen open, `document.body.style.overflow` is set to `'hidden'` to prevent background\nscrolling, and restored on close. The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`.\n\nSize widths: `sm` = 400 px, `md` = 500 px, `lg` = 640 px, `xl` = 800 px,\n`full` = 100vw (no border-radius, no padding).\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls modal visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the modal (overlay click, escape key, or close button). |\n| title | `string` | - | Optional title rendered in the modal header via the `Heading` primitive (level 4). |\n| children | `ReactNode` | - | Modal body content rendered in a scrollable area (`overflowY: auto`). |\n| footer | `ReactNode` | - | Footer content rendered below the body, right-aligned with an 8 px gap, separated by a top border. |\n| size | `'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'` | Controls the width of the modal panel. - `'sm'` \u2014 400 px - `'md'` \u2014 500 px - `'lg'` \u2014 640 px - `'xl'` \u2014 800 px - `'full'` \u2014 100vw, no border-radius, stretches to fill viewport |\n| closeOnOverlayClick | `boolean` | `true` | When true, clicking the semi-transparent overlay behind the modal calls `onClose`. |\n| closeOnEscape | `boolean` | `true` | When true, pressing the Escape key calls `onClose`. |\n| showCloseButton | `boolean` | `true` | When true, renders a ghost close button (X icon) in the modal header. |\n\n**Example:**\n```tsx\n```tsx\n<Modal\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  title=\"Confirm Action\"\n  size=\"md\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleConfirm}>Confirm</Button>\n    </>\n  }\n>\n  <p>Are you sure you want to proceed?</p>\n</Modal>\n```\n```\n\n### CommandPalette\n\nProps for the `CommandPalette` composition.\n\nA searchable command menu (Cmd+K / Ctrl+K pattern) that composes `Spinner` and `Icon`\nprimitives. Appears as a centered overlay at 15vh from the top. Commands are filtered\nby label and description (case-insensitive substring match). Results are grouped under\nuppercase section headers. Keyboard navigation is fully supported:\nArrow Up/Down to navigate, Enter to select, Escape to close.\n\nWhen `recentIds` are provided and the search query is empty, matching commands appear\nin a \"Recent\" section at the top (deduplicated from their original groups).\n\nThe footer shows navigation hints: \"Up/Down Navigate\", \"Enter Select\", \"Esc Close\".\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| open | `boolean` | - | Controls palette visibility. When false, the component renders nothing. |\n| onClose | `() => void` | - | Called to close the palette (overlay click, Escape key, or after command selection). |\n| commands | `Command[]` | - | Full array of available commands. Filtered client-side by the search query. |\n| onSelect | `(command: Command) => void` | - | Called when a non-disabled command is selected (Enter key or click). The palette auto-closes after selection. |\n| placeholder | `string` | `'Search commands...'` | Placeholder text for the search input. |\n| recentIds | `string[]` | `[]` | IDs of recently used commands. When the query is empty, these appear in a \"Recent\" section at the top of the results. |\n| loading | `boolean` | - | When true, shows a centered `Spinner` instead of the command list. |\n\n**Example:**\n```tsx\n```tsx\n<CommandPalette\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  commands={[\n    { id: 'new', label: 'New File', shortcut: 'Ctrl+N', group: 'File' },\n    { id: 'save', label: 'Save', shortcut: 'Ctrl+S', group: 'File' },\n    { id: 'theme', label: 'Toggle Theme', group: 'Preferences' },\n  ]}\n  onSelect={(cmd) => executeCommand(cmd.id)}\n  recentIds={['save']}\n  placeholder=\"Search commands...\"\n/>\n```\n```\n\n### Footer\n\nProps for the `Footer` composition.\n\nA site footer with `role=\"contentinfo\"` that lays out a brand slot, link columns,\nsocial icons, and a bottom bar. Does not compose other ggui primitives (uses plain\nHTML elements). Content is constrained to `max-width: 1280px` with auto margins.\nLink columns use a responsive flex layout (`flex: 0 1 180px`). The bottom bar\nincludes copyright text, social links, and bottom-bar links separated by a top border.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| brand | `ReactNode` | - | Brand element (logo, tagline) rendered in a flexible column (`flex: 1 1 280px`). |\n| columns | `FooterColumn[]` | - | Array of link columns rendered in a flex-wrap layout with 48 px gap. |\n| socialLinks | `FooterSocialLink[]` | - | Social media icon links rendered in the bottom bar. |\n| bottomText | `string` | - | Text displayed at the start of the bottom bar (e.g., copyright notice). |\n| bottomLinks | `FooterLink[]` | - | Links displayed in the bottom bar after social icons (e.g., Privacy, Terms). |\n| background | `string` | `colors.gray[50]` | Background color of the footer. |\n| bordered | `boolean` | `true` | When true, renders a 1 px top border in `colors.gray[200]`. |\n\n**Example:**\n```tsx\n```tsx\n<Footer\n  brand={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  columns={[\n    { title: 'Product', links: [{ label: 'Features', href: '/features' }] },\n    { title: 'Company', links: [{ label: 'About', href: '/about' }] },\n  ]}\n  socialLinks={[\n    { label: 'Twitter', href: 'https://twitter.com/acme', icon: <TwitterIcon /> },\n  ]}\n  bottomText=\"&copy; 2026 Acme Inc.\"\n  bottomLinks={[{ label: 'Privacy', href: '/privacy' }]}\n  bordered\n/>\n```\n```\n\n### Hero\n\nProps for the `Hero` composition.\n\nA prominent landing-page hero section that renders heading, description, CTA buttons,\nand an optional media slot. Does not compose other ggui primitives (uses plain HTML\nelements styled with design tokens). Content is constrained to `max-width: 1280px`.\n\nLayout modes:\n- `align='center'` \u2014 single-column centered layout with `max-width: 800px` text area.\n- `align='left'` \u2014 two-column side-by-side layout (50/50 split with media slot).\n\nSize controls vertical padding and font sizes:\n- `'sm'` \u2014 48 px vertical padding, 3xl heading, lg description.\n- `'md'` \u2014 80 px vertical padding, 4xl heading, xl description.\n- `'lg'` \u2014 120 px vertical padding, 5xl heading, xl description.\n\nThe primary action button uses `colors.primary[600]` fill; the secondary action uses\nan outlined style. When `overlay` is true with a `backgroundImage`, text switches to white\nand borders become semi-transparent.\n\n**Props:**\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| heading | `string` | - | Main heading text rendered as an `<h1>` with bold weight and tight line-height. |\n| description | `string` | - | Description paragraph rendered below the heading with relaxed line-height. |\n| primaryAction | `HeroAction` | - | Primary CTA button rendered with `colors.primary[600]` background and white text. |\n| secondaryAction | `HeroAction` | - | Secondary CTA button rendered with a transparent background and a 1 px border. |\n| media | `ReactNode` | - | Media element (image, video, illustration) rendered beside or below the text content. |\n| align | `'center' \\| 'left'` | `'center'` | Text and layout alignment. - `'center'` \u2014 centered single-column layout. - `'left'` \u2014 left-aligned text with media in a right column (50/50 split). |\n| size | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Controls vertical padding and heading/description font sizes. - `'sm'` \u2014 compact (48 px padding, 3xl/lg fonts). - `'md'` \u2014 standard (80 px padding, 4xl/xl fonts). - `'lg'` \u2014 spacious (120 px padding, 5xl/xl fonts). |\n| background | `string` | `colors.white (when no backgroundImage is set)` | Background color of the hero section. |\n| backgroundImage | `string` | - | Background image URL applied as `background-size: cover; background-position: center`. |\n| overlay | `boolean` | `false` | When true and `backgroundImage` is set, renders a semi-transparent black overlay (`rgba(0,0,0,0.5)`) and switches text to white/semi-transparent white for contrast. |\n\n**Example:**\n```tsx\n```tsx\n<Hero\n  heading=\"Build Better UIs, Faster\"\n  description=\"The universal interface layer between AI agents and humans.\"\n  primaryAction={{ label: 'Get Started', onClick: () => navigate('/signup') }}\n  secondaryAction={{ label: 'Learn More', href: '/docs' }}\n  media={<img src=\"/hero.png\" alt=\"Hero\" />}\n  align=\"left\"\n  size=\"lg\"\n/>\n```\n```\n\n### Support Types\n\n**SidebarItem:**\n\nA single navigation entry in a `Sidebar`. Supports nested children for\ncollapsible sub-menus and an optional badge slot.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the item. Hidden when the sidebar is collapsed. |\n| icon | `ReactNode` | Leading icon rendered before the label. Remains visible when collapsed. |\n| href | `string` | Optional URL associated with this item (not rendered as a link by default). |\n| badge | `ReactNode` | Trailing badge element (e.g., unread count). Hidden when collapsed. |\n| children | `SidebarItem[]` | Nested child items. When present, the item acts as a collapsible section (chevron indicator shown). |\n| disabled | `boolean` | When true, the item is visually dimmed and non-interactive (`cursor: not-allowed`). |\n\n**Comment:**\n\nA single comment entry in a `CommentThread`. Supports nested replies\nand emoji reactions with counts.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this comment. |\n| author | `{     /** Display name of the author. */     name: string;     /** URL for the author's avatar image. Passed to the `Avatar` primitive. */     avatar?: string;   }` | Comment author metadata. |\n| content | `string` | The comment body text. |\n| timestamp | `string \\| Date` | Timestamp of the comment. Rendered via `toLocaleString()` when a `Date` object. |\n| replies | `Comment[]` | Nested reply comments. Each reply is rendered indented 40 px deeper. |\n| reactions | `{ emoji: string; count: number }[]` | Emoji reactions with their aggregated counts (e.g., `{ emoji: \"\u{1F44D}\", count: 3 }`). |\n\n**DataTableColumn:**\n\nColumn definition for a `DataTable`. Controls header text, width, alignment,\nsorting, and custom cell rendering.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| key | `string` | Property key on the row object used to extract cell values. Also serves as the sort key. |\n| header | `string` | Column header text displayed in the `<thead>`. |\n| width | `number \\| string` | Column width as a CSS value (number for pixels, string for any CSS unit). |\n| sortable | `boolean` | When true, the column header is clickable and triggers `onSort`. An arrow icon indicates direction. |\n| render | `(value: unknown, row: T, index: number) => ReactNode` | Custom cell renderer. When omitted, the raw value is stringified via `String()`. |\n| align | `'left' \\| 'center' \\| 'right'` | Text alignment for both header and body cells. |\n\n**ChatMessage:**\n\nA single message in a `ChatWindow`. Includes sender metadata, delivery status,\nand a timestamp.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this message. |\n| content | `string` | The message body text. |\n| sender | `{     /** Unique ID of the sender. Compared to `currentUserId` to determine alignment. */     id: string;     /** Display name of the sender. */     name: string;     /** Avatar image URL. Only shown for non-current-user messages (xs size). */     avatar?: string;   }` | Sender metadata used for avatar rendering and alignment. |\n| timestamp | `string \\| Date` | Message timestamp. Rendered as `HH:MM` via `toLocaleTimeString` when a `Date` object. |\n| status | `'sending' \\| 'sent' \\| 'delivered' \\| 'read' \\| 'error'` | Delivery status indicator shown on the current user's messages. - `'sending'` \u2014 shows a dot bullet - `'sent'` \u2014 shows a single checkmark - `'delivered'` \u2014 shows double checkmarks - `'read'` \u2014 shows double checkmarks (same visual as delivered) - `'error'` \u2014 shows an exclamation mark |\n\n**NavItem:**\n\nA single navigation entry in a `NavigationBar`. Supports nested children\nfor sub-menus (rendered by the parent via dropdown, not built-in).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier used for active-state matching and React keys. |\n| label | `string` | Display label for the navigation link. |\n| href | `string` | URL for the item. When provided, renders an `<a>` element instead of `<button>`. |\n| icon | `ReactNode` | Optional icon rendered before the label. |\n| children | `NavItem[]` | Nested child items (for sub-menu structures; rendering is consumer-defined). |\n| disabled | `boolean` | When true, the item is visually dimmed (opacity 0.5) and non-interactive. |\n\n**UploadedFile:**\n\nA file entry in the `FileUploader` composition. Tracks upload progress,\nstatus, and optional error messages.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this file entry. Used as a key and for removal callbacks. |\n| name | `string` | Original file name. Rendered with text-overflow ellipsis when too long. |\n| size | `number` | File size in bytes. Formatted as B/KB/MB/GB for display. |\n| type | `string` | MIME type of the file (e.g., `'image/png'`). |\n| progress | `number` | Upload progress as a percentage (0-100). Shown via the `Progress` primitive when status is `'uploading'`. |\n| status | `'pending' \\| 'uploading' \\| 'success' \\| 'error'` | Current upload lifecycle status. - `'pending'` \u2014 file selected but upload not started. - `'uploading'` \u2014 upload in progress; `progress` bar is shown. - `'success'` \u2014 upload completed. - `'error'` \u2014 upload failed; `error` message is shown in `colors.error[500]`. |\n| error | `string` | Error message displayed when status is `'error'`. |\n| url | `string` | The remote URL of the uploaded file after successful upload. |\n\n**Notification:**\n\nA single notification entry in the `NotificationCenter`. Supports semantic type coloring,\nread state, and an optional inline action button.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this notification. |\n| title | `string` | Notification title rendered in medium weight. |\n| message | `string` | Optional body text rendered below the title in a smaller font. |\n| timestamp | `string \\| Date` | Timestamp of the notification. Rendered via `toLocaleString()` when a `Date` object. |\n| read | `boolean` | Read state. Unread notifications get a `colors.primary[50]` background and a colored status dot matching the notification type. |\n| type | `'info' \\| 'success' \\| 'warning' \\| 'error'` | Semantic type that controls the status dot color on unread notifications. - `'info'` \u2014 `colors.info[500]` (blue) - `'success'` \u2014 `colors.success[500]` (green) - `'warning'` \u2014 `colors.warning[500]` (amber) - `'error'` \u2014 `colors.error[500]` (red) |\n| icon | `ReactNode` | Optional icon rendered alongside the notification (not used by the default implementation). |\n| action | `{     /** Button label text. */     label: string;     /** Click handler for the action. */     onClick: () => void;   }` | Optional inline action button rendered next to the timestamp. |\n\n**Command:**\n\nA single command entry in a `CommandPalette`. Commands can be grouped,\nhave keyboard shortcuts, and support a disabled state.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| id | `string` | Unique identifier for this command. |\n| label | `string` | Display label for the command. Searchable by the palette's query filter. |\n| description | `string` | Optional description text shown below the label. Also searchable. |\n| icon | `ReactNode` | Icon rendered at the start of the command row. |\n| shortcut | `string` | Keyboard shortcut hint displayed at the end of the row in a `<kbd>` element. |\n| group | `string` | Group name for visual sectioning. Commands with the same group are rendered under a shared header. Defaults to `'Commands'` if omitted. |\n| disabled | `boolean` | When true, the command is visually dimmed and cannot be selected. |\n\n**FooterLink:**\n\nA single link entry in a footer column or the bottom bar. Supports both\n`href` navigation and `onClick` handlers (onClick takes precedence via `preventDefault`).\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Display text for the link. |\n| href | `string` | URL for the link. |\n| onClick | `() => void` | Click handler. When provided, `preventDefault` is called on the anchor click. |\n\n**FooterColumn:**\n\nA named column of links in the `Footer` layout. Each column has an optional title\nand a list of links rendered as a vertical stack with 10 px gap.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| title | `string` | Column heading rendered as an `<h4>` with semibold weight. |\n| links | `FooterLink[]` | Links displayed in this column. |\n\n**FooterSocialLink:**\n\nA social media link in the `Footer` bottom bar. Rendered as an icon-only anchor\nwith `aria-label` for accessibility.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Accessible label for the social link (used as `aria-label`). |\n| href | `string` | URL for the social media profile or page. |\n| icon | `ReactNode` | Icon element rendered inside the anchor (typically an SVG or `Icon` primitive). |\n\n**HeroAction:**\n\nA call-to-action button definition for the `Hero` composition.\nUsed for both the primary (filled) and secondary (outlined) action buttons.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| label | `string` | Button label text. |\n| onClick | `() => void` | Click handler for the button. |\n| href | `string` | Optional URL (not used by the default implementation; available for consumer routing). |\n\n\n## System Conventions\n\n### onChange Behavior (CRITICAL)\n\nAll form control onChange handlers receive the VALUE DIRECTLY, not a React event object.\n\n```tsx\n// CORRECT \u2014 onChange receives value directly\n<Input value={name} onChange={setName} />\n<Input value={email} onChange={(value) => setEmail(value)} />\n<Select value={country} onChange={setCountry} options={countries} />\n<Checkbox checked={agreed} onChange={setAgreed} />\n\n// WRONG \u2014 DO NOT use e.target.value!\n<Input value={name} onChange={(e) => setName(e.target.value)} /> // WILL BREAK\n```\n\nApplies to: Input, TextArea, Select, Checkbox, RadioGroup, Slider, Tabs, Accordion.\n\n### Available Motion & Animation\n\nRender `<MotionKeyframes />` once (anywhere in tree) to enable all keyframes.\n\n**Entrance/exit:** fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n**State feedback:** flash (background-color highlight), pulse (opacity breathing), bounce (scale overshoot)\n**Easing:** linear, easeIn, easeOut, easeInOut, spring (bouncy)\n**Durations:** instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n\n```tsx\n// Entrance animation on mount\n<div style={{ animation: 'ggui-fadeIn 200ms ease-out' }}>Content</div>\n\n// Stagger list items\n{items.map((item, i) => (\n  <div key={item.id} style={{ animation: \\`ggui-slideInUp 300ms ease-out \\${i * 50}ms both\\` }}>\n    {item.name}\n  </div>\n))}\n\n// Flash highlight when data changes (e.g., stock price update)\n// useAnimationKey returns a key that increments when dep changes \u2192 remounts element \u2192 replays animation\nconst priceKey = useAnimationKey(stock.price);\n<div key={priceKey} style={{\n  animation: animation.flash,\n  '--ggui-flash-color': stock.change > 0 ? 'var(--ggui-color-success-100)' : 'var(--ggui-color-error-100)',\n} as React.CSSProperties}>\n  {stock.price}\n</div>\n\n// Respect reduced-motion preference\nconst { motionEnabled } = useMotion();\n<div style={motionEnabled ? { animation: 'ggui-scaleIn 200ms ease-out' } : undefined}>\n  Content\n</div>\n```\n\n### Elevation System\n\n6 levels mapping shadow intensity to z-index for layering:\n- Level 0: flat (no shadow, z: auto) \u2014 inline content\n- Level 1: sm shadow (z: auto) \u2014 cards, sections\n- Level 2: md shadow (z: 1000) \u2014 dropdowns, popovers\n- Level 3: lg shadow (z: 1200) \u2014 sticky banners\n- Level 4: xl shadow (z: 1400) \u2014 modals, dialogs\n- Level 5: 2xl shadow (z: 1800) \u2014 tooltips, toasts\n\n### Import Constraints\n\nOnly these imports are allowed:\n- `react`\n- `@ggui-ai/design` \u2014 the whole design system (primitives, components, compositions, and the `Clickable` / `Hoverable` / `Pressable` traits) is one import; there are no subpaths\n- `@ggui-ai/wire` (wire hooks)\n\nNo external libraries (lodash, date-fns, etc.). No fetch(). No eval().";
     VALID_PRIMITIVES = [
       "Container",
       "Card",
@@ -1467,16 +1467,15 @@ var init_primitives = __esm({
     ];
   }
 });
-
-// src/validation/allowed-imports.ts
 function isAllowedImport(specifier, gadgetPackages) {
+  if (FORBIDDEN_IMPORT_SPECIFIERS.includes(specifier)) return false;
   for (const base of ALLOWED_IMPORT_BASES) {
     if (specifier === base || specifier.startsWith(`${base}/`)) return true;
   }
   return gadgetPackages?.has(specifier) ?? false;
 }
 function describeAllowedImports() {
-  return "react, @ggui-ai/design, @ggui-ai/wire, @ggui-ai/gadgets, or a gadget package declared on the contract";
+  return "react, @ggui-ai/design, @ggui-ai/wire, @ggui-ai/gadgets, or a gadget package declared on the contract \u2014 never @ggui-ai/wire/internal (the writer side of the wire; components read useRender().isConnected)";
 }
 var ALLOWED_IMPORT_BASES;
 var init_allowed_imports = __esm({
@@ -2461,7 +2460,8 @@ async function loadVfs() {
 function resolveRelativeInVfs(vfs, containingFile, importPath) {
   const normalized = containingFile.startsWith("/") ? containingFile.slice(1) : containingFile;
   const dir = path.posix.dirname(normalized);
-  const resolved2 = path.posix.normalize(`${dir}/${importPath}`);
+  const specifier = importPath.replace(/\.(?:m|c)?js$/, "");
+  const resolved2 = path.posix.normalize(`${dir}/${specifier}`);
   const withDts = `${resolved2}.d.ts`;
   if (vfs.has(withDts)) return withDts;
   const withIndexDts = `${resolved2}/index.d.ts`;
@@ -2807,6 +2807,89 @@ var init_react_linter = __esm({
   }
 });
 
+// src/design-mode.ts
+function canvasDisplayModeForShell(shell) {
+  return shell === "chat" || shell === "inline" ? "inline" : "fullscreen";
+}
+function canvasForViewportWidth(mode, width) {
+  if (mode === "inline") return "xs-chat-card";
+  if (width < CANVAS_BREAKPOINTS.md) return "mobile-fullscreen-small";
+  if (width < CANVAS_BREAKPOINTS.lg) return "md";
+  if (width < CANVAS_BREAKPOINTS.xl) return "lg";
+  return "xl";
+}
+function canvasForRendering(shellType, screen) {
+  const shell = shellType ?? "fullscreen";
+  if (canvasDisplayModeForShell(shell) === "inline") return "xs-chat-card";
+  if (shell === "spatial") return "md";
+  switch (screen ?? "universal") {
+    case "mobile":
+      return "mobile-fullscreen-small";
+    case "tablet":
+      return "md";
+    default:
+      return "lg";
+  }
+}
+function describeCanvas(canvas) {
+  const d = CANVAS_DESCRIPTORS[canvas];
+  return `This component renders on the \`${canvas}\` canvas (${d.label}): ${d.minWidthPx}\u2013${d.maxWidthPx}px wide, ${d.host}. Design for the whole range \u2014 the host may size the iframe anywhere inside it.`;
+}
+var DESIGN_MODES, DEFAULT_DESIGN_MODE, CANVAS_CLASSES, CANVAS_VIEWPORTS, CANVAS_BREAKPOINTS, CANVAS_DESCRIPTORS;
+var init_design_mode = __esm({
+  "src/design-mode.ts"() {
+    DESIGN_MODES = ["constrained", "free"];
+    DEFAULT_DESIGN_MODE = "constrained";
+    CANVAS_CLASSES = [
+      "xs-chat-card",
+      "mobile-fullscreen-small",
+      "md",
+      "lg",
+      "xl"
+    ];
+    CANVAS_VIEWPORTS = {
+      "xs-chat-card": { width: 400, height: 640 },
+      "mobile-fullscreen-small": { width: 390, height: 844 },
+      md: { width: 768, height: 1024 },
+      lg: { width: 1024, height: 768 },
+      xl: { width: 1440, height: 900 }
+    };
+    CANVAS_BREAKPOINTS = { md: 600, lg: 1024, xl: 1440 };
+    CANVAS_DESCRIPTORS = {
+      "xs-chat-card": {
+        label: "extra-small chat card",
+        minWidthPx: 320,
+        maxWidthPx: 480,
+        host: "an inline card inside a chat message bubble \u2014 the host draws the card border, shadow and rounded corners; the component fills the bubble width and takes its natural height"
+      },
+      "mobile-fullscreen-small": {
+        label: "small mobile fullscreen",
+        minWidthPx: 320,
+        maxWidthPx: 599,
+        host: "a phone-sized viewport the component owns edge to edge \u2014 single column, touch targets at least 44px, the component manages its own scroll"
+      },
+      md: {
+        label: "medium panel",
+        minWidthPx: 600,
+        maxWidthPx: 1023,
+        host: "a tablet viewport or a floating panel (spatial / picture-in-picture) \u2014 one or two columns, medium density"
+      },
+      lg: {
+        label: "large fullscreen",
+        minWidthPx: 1024,
+        maxWidthPx: 1439,
+        host: "a desktop viewport the component owns edge to edge \u2014 multi-column layouts, hover states and pointer interactions are available"
+      },
+      xl: {
+        label: "extra-large fullscreen",
+        minWidthPx: 1440,
+        maxWidthPx: 1920,
+        host: "a wide desktop viewport the component owns edge to edge \u2014 cap content width or use the extra room deliberately; never stretch a single column across the whole width"
+      }
+    };
+  }
+});
+
 // src/evaluation/types-public.ts
 function notApplicableCoverage(reason) {
   return LLM_EVAL_STATIC_CRITERIA.map(({ criterion, tier }) => ({
@@ -2837,17 +2920,23 @@ function priorityForIssue(category) {
 function getActionableIssues(result, mode) {
   return result.issues.filter((i) => i.result === "fail" || i.result === "warn");
 }
-function getCriteriaByPriority(priority) {
-  return CRITERIA.filter((c) => c.priority === priority);
+function criteriaFor(designMode = "constrained") {
+  if (designMode === "constrained") return CRITERIA;
+  return CRITERIA.map(
+    (c) => FREE_DESIGN_CRITERIA_OVERRIDES.find((o) => o.id === c.id) ?? c
+  );
+}
+function getCriteriaByPriority(priority, designMode = "constrained") {
+  return criteriaFor(designMode).filter((c) => c.priority === priority);
 }
-function getCriterionById(id) {
-  return CRITERIA.find((c) => c.id === id);
+function getCriterionById(id, designMode = "constrained") {
+  return criteriaFor(designMode).find((c) => c.id === id);
 }
-function buildCodingCriteriaSummary() {
+function buildCodingCriteriaSummary(designMode = "constrained") {
   const lines = ["## Priority (P0 first, then P1, then P2)", ""];
   for (const priority of ["P0", "P1", "P2"]) {
     const label = priority === "P0" ? "Must (compile + complete)" : priority === "P1" ? "Should (safety)" : "Nice (quality)";
-    const criteria = getCriteriaByPriority(priority);
+    const criteria = getCriteriaByPriority(priority, designMode);
     lines.push(`**${priority} \u2014 ${label}:**`);
     for (const c of criteria) {
       lines.push(`- ${c.codingGuidance}`);
@@ -2856,7 +2945,7 @@ function buildCodingCriteriaSummary() {
   }
   return lines.join("\n");
 }
-var LLM_EVAL_STATIC_CRITERIA, CRITERIA;
+var LLM_EVAL_STATIC_CRITERIA, CRITERIA, FREE_DESIGN_CRITERIA_OVERRIDES;
 var init_types_public = __esm({
   "src/evaluation/types-public.ts"() {
     LLM_EVAL_STATIC_CRITERIA = [
@@ -3045,6 +3134,31 @@ Intentional custom colors (status indicators) are acceptable when no semantic to
 Only list ACTUAL violations. Use 'fail' only for pervasive violations.`
       }
     ];
+    FREE_DESIGN_CRITERIA_OVERRIDES = [
+      {
+        id: "tokens",
+        name: "Color tokens",
+        priority: "P1",
+        tier: 0,
+        failOutcome: "warn",
+        codingGuidance: "Every color is a bare var(--ggui-color-*) from the token manifest \u2014 no hex, rgb()/hsl(), CSS named colors or literal fallbacks, in style props and <style> blocks alike. Spacing, typography, radius and shadow geometry may be literals.",
+        evalInstruction: "Flag hardcoded hex colors, rgba/hsl functions, CSS named colors, and literal fallbacks inside var(--ggui-*) references. Do NOT flag literal spacing, font sizes, radii or pixel values \u2014 they are allowed in this mode."
+      },
+      {
+        id: "visual",
+        name: "Visual composition",
+        priority: "P2",
+        tier: 2,
+        failOutcome: "warn",
+        codingGuidance: "Compose deliberately: one clear focal point, consistent spacing rhythm, a coherent theme-token palette, a fit to the rendering canvas.",
+        evalInstruction: `Evaluate VISUAL COMPOSITION: Is the component composed deliberately for its canvas?
+
+Judge: visual hierarchy (one clear focal point, headings distinct from body text), consistent spacing rhythm and alignment, a coherent palette drawn from the theme tokens, fit to the canvas (fluid width, no fixed widths, nothing cramped or stretched).
+Do NOT reward or penalise the use of design-system primitives \u2014 raw HTML with inline CSS is a first-class choice here. Literal spacing / typography / radius values are fine.
+
+Only list ACTUAL composition problems. Use 'fail' only for a fundamentally incoherent composition.`
+      }
+    ];
   }
 });
 function stripComments(code) {
@@ -3062,10 +3176,11 @@ function stripComments(code) {
   }
   return out;
 }
-function detectCertainDoubleWiredActions(sourceCode, actionBindings) {
+function detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode = DEFAULT_DESIGN_MODE) {
   const issues = [];
   if (actionBindings.length === 0) return issues;
   const bindings = new Set(actionBindings);
+  const anyElementIsInteractive = designMode === "free";
   const TRAIT_HOST_TAGS = /* @__PURE__ */ new Set(["Card", "Box", "Stack", "Row"]);
   const TRAITS_THAT_FIRE = /* @__PURE__ */ new Set(["Clickable", "Pressable"]);
   const INTERACTIVE_DESCENDANTS = /* @__PURE__ */ new Set([
@@ -3101,7 +3216,9 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings) {
   }
   function isTraitHostWithFiringAs(node) {
     const tag = tagNameText(node);
-    if (tag === void 0 || !TRAIT_HOST_TAGS.has(tag)) return false;
+    if (tag === void 0) return false;
+    if (anyElementIsInteractive) return true;
+    if (!TRAIT_HOST_TAGS.has(tag)) return false;
     const asExpr = attrExpression(node, "as");
     return asExpr !== void 0 && ts7.isIdentifier(asExpr) && TRAITS_THAT_FIRE.has(asExpr.text);
   }
@@ -3130,7 +3247,7 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings) {
       const opening = ts7.isJsxElement(node) ? node.openingElement : ts7.isJsxSelfClosingElement(node) ? node : void 0;
       if (opening !== void 0) {
         const tag = tagNameText(opening);
-        if (tag !== void 0 && INTERACTIVE_DESCENDANTS.has(tag)) {
+        if (tag !== void 0 && (anyElementIsInteractive || INTERACTIVE_DESCENDANTS.has(tag))) {
           for (const attrName of HANDLER_ATTRS) {
             const callee = extractCalleeName(attrExpression(opening, attrName));
             if (callee === expectedBinding) {
@@ -3156,14 +3273,15 @@ function detectCertainDoubleWiredActions(sourceCode, actionBindings) {
         if (match !== void 0) {
           const outerTag = tagNameText(node.openingElement);
           const outerLine = sf.getLineAndCharacterOfPosition(node.openingElement.getStart()).line + 1;
+          const outerLabel = anyElementIsInteractive ? `<${outerTag}>` : `<${outerTag} as={...}>`;
           issues.push({
             tier: 0,
             result: "fail",
             category: "interactivity",
             subcategory: "double-wired-action:certain",
             severity: "critical",
-            description: `Nested-interactive double-wire: outer <${outerTag} as={...}> at line ${outerLine} and inner <${match.tag}> at line ${match.line} both dispatch the same useAction binding '${outerCallee}'. One user click on the inner control fires its handler AND bubbles to the outer handler \u2014 '${outerCallee}' dispatches TWICE, the action runs back-to-back, and a toggle-style action silently reverts the user's change.`,
-            fix: `Pick ONE surface for the gesture: either drop \`as={...}\` + onClick on the outer <${outerTag}> and let the inner <${match.tag}> own the gesture, OR remove the inner <${match.tag}> and let the outer <${outerTag} as={...}> own it. Don't wire both to the same useAction binding.`,
+            description: `Nested-interactive double-wire: outer ${outerLabel} at line ${outerLine} and inner <${match.tag}> at line ${match.line} both dispatch the same useAction binding '${outerCallee}'. One user click on the inner control fires its handler AND bubbles to the outer handler \u2014 '${outerCallee}' dispatches TWICE, the action runs back-to-back, and a toggle-style action silently reverts the user's change.`,
+            fix: anyElementIsInteractive ? `Pick ONE gesture surface for '${outerCallee}': either remove the onClick from the outer <${outerTag}> and let the inner <${match.tag}> own the gesture, OR drop the inner <${match.tag}>'s handler and let the outer <${outerTag}> own it. Never wire both to the same useAction binding \u2014 stopPropagation is not a fix.` : `Pick ONE surface for the gesture: either drop \`as={...}\` + onClick on the outer <${outerTag}> and let the inner <${match.tag}> own the gesture, OR remove the inner <${match.tag}> and let the outer <${outerTag} as={...}> own it. Don't wire both to the same useAction binding.`,
             line: outerLine
           });
         }
@@ -3188,9 +3306,10 @@ function isGadgetExportImported(source, pkg, exportName) {
   }
   return false;
 }
-async function runTier0Checks(sourceCode, contract, buildErrors, gadgetTypes) {
+async function runTier0Checks(sourceCode, contract, buildErrors, gadgetTypes, designMode = DEFAULT_DESIGN_MODE) {
   const issues = [];
   const lines = sourceCode.split("\n");
+  const enforceDesignVocabulary = designMode === "constrained";
   if (buildErrors && buildErrors.length > 0) {
     const errorDetail = buildErrors.map((e) => {
       const match = e.match(/<stdin>:(\d+):\d+: ERROR: (.+)/);
@@ -3319,7 +3438,7 @@ ${errorDetail}`,
         subcategory: "hardcoded-color-fn",
         severity: "critical",
         description: `Hardcoded ${colorFnMatch[1]}() breaks theme switching \u2014 use design tokens.`,
-        fix: "Replace with a primitive variant OR a semantic token: var(--ggui-color-surface), var(--ggui-color-onSurface), var(--ggui-color-outline), etc.",
+        fix: "Replace with a primitive variant OR a layering role: var(--ggui-color-container), var(--ggui-color-onContainer), var(--ggui-color-outline), etc.",
         line: lineNum
       });
     }
@@ -3336,13 +3455,13 @@ ${errorDetail}`,
         subcategory: "off-manifest-token",
         severity: "critical",
         description: `Token "${name}" is not in the design system's token manifest \u2014 no theme defines it, so it renders unset.`,
-        fix: `Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onSurface), \u2026; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
+        fix: `Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onContainer), \u2026; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
         line: lineNum
       });
     }
-    const rawSpacingMatch = line.match(
+    const rawSpacingMatch = enforceDesignVocabulary ? line.match(
       /\b(gap|padding|paddingX|paddingY|margin|radius)\s*=\s*["'][\d.]+(?:px|rem|em)["']/
-    );
+    ) : null;
     if (rawSpacingMatch) {
       issues.push({
         tier: 0,
@@ -3436,12 +3555,12 @@ ${errorDetail}`,
           subcategory: "named-color",
           severity: "critical",
           description: `Hardcoded CSS named color "${named}" breaks theme switching \u2014 use design tokens.`,
-          fix: `Replace with a typed slot (Text tone="muted" / Box surface="accent" / Badge variant="success") OR a semantic token: var(--ggui-color-onSurfaceVariant), var(--ggui-color-primary-500), etc. The keyword "${named}" maps to a fixed RGB; the operator's theme has no effect on it.`,
+          fix: `Replace with a typed slot (Text tone="muted" / Box surface="accent" / Badge variant="success") OR a semantic token: var(--ggui-color-onSunken), var(--ggui-color-primary-500), etc. The keyword "${named}" maps to a fixed RGB; the operator's theme has no effect on it.`,
           line: lineNum
         });
       }
     }
-    const pxMatch = line.match(/(?:padding|margin|gap|borderRadius)\s*:\s*['"]?\d+px/);
+    const pxMatch = enforceDesignVocabulary ? line.match(/(?:padding|margin|gap|borderRadius)\s*:\s*['"]?\d+px/) : null;
     if (pxMatch && !line.includes("var(--ggui-")) {
       issues.push({
         tier: 0,
@@ -3449,11 +3568,11 @@ ${errorDetail}`,
         category: "tokens",
         subcategory: "raw-pixels",
         description: "Raw pixel value in spacing \u2014 must use design tokens",
-        fix: "Replace with var(--ggui-spacing-*, fallback)",
+        fix: 'Replace with a bare var(--ggui-spacing-*) token \u2014 no literal fallback (the runtime injects every token) \u2014 or the scale name on the primitive prop (gap="md", padding="lg")',
         line: lineNum
       });
     }
-    const numericSpacingMatch = line.match(/\b(padding|paddingX|paddingY|gap|margin)\s*=\s*\{?\s*(\d+)\s*\}?/);
+    const numericSpacingMatch = enforceDesignVocabulary ? line.match(/\b(padding|paddingX|paddingY|gap|margin)\s*=\s*\{?\s*(\d+)\s*\}?/) : null;
     if (numericSpacingMatch && !line.includes("var(--ggui-")) {
       issues.push({
         tier: 0,
@@ -3467,7 +3586,7 @@ ${errorDetail}`,
     }
   }
   const clickablePattern = /<(?:Card|Box|Stack|Row)\s[^>]*onClick/;
-  for (let i = 0; i < lines.length; i++) {
+  for (let i = 0; enforceDesignVocabulary && i < lines.length; i++) {
     if (clickablePattern.test(lines[i]) && !lines[i].includes("as={Clickable}") && !lines[i].includes("as={Pressable}")) {
       issues.push({
         tier: 0,
@@ -3480,9 +3599,8 @@ ${errorDetail}`,
       });
     }
   }
-  const actionBindings = [
-    ...sourceCode.matchAll(/(?:const|let)\s+(\w+)\s*=\s*useAction\s*\(/g)
-  ].map((m) => m[1]).filter((name) => typeof name === "string");
+  const bindingRe = designMode === "free" ? /(?:const|let)\s+(\w+)\s*=\s*useAction\s*(?:<[^>]*>)?\s*\(/g : /(?:const|let)\s+(\w+)\s*=\s*useAction\s*\(/g;
+  const actionBindings = [...sourceCode.matchAll(bindingRe)].map((m) => m[1]).filter((name) => typeof name === "string");
   for (const binding of actionBindings) {
     const callSites = (sourceCode.match(new RegExp(`\\b${binding}\\s*\\(`, "g")) ?? []).length;
     if (callSites >= 2) {
@@ -3498,7 +3616,7 @@ ${errorDetail}`,
   }
   if (actionBindings.length > 0) {
     issues.push(
-      ...detectCertainDoubleWiredActions(sourceCode, actionBindings)
+      ...detectCertainDoubleWiredActions(sourceCode, actionBindings, designMode)
     );
   }
   if (/\buseRender\s*\(/.test(sourceCode)) {
@@ -3543,7 +3661,7 @@ ${errorDetail}`,
   const ALIGN_VALUES = /* @__PURE__ */ new Set(["start", "center", "end", "stretch"]);
   const JUSTIFY_VALUES = /* @__PURE__ */ new Set(["start", "center", "end", "between", "around", "evenly"]);
   const tagRegex = /<(Stack|Row)\b([^>]*)>/gs;
-  for (const tag of sourceCode.matchAll(tagRegex)) {
+  for (const tag of enforceDesignVocabulary ? sourceCode.matchAll(tagRegex) : []) {
     const tagName = tag[1];
     const attrs = tag[2];
     const tagLine = sourceCode.slice(0, tag.index).split("\n").length;
@@ -3829,8 +3947,8 @@ Import \`${exportName}\` ONLY from '${use.package}' \u2014 that is the package i
   }
   return issues;
 }
-async function runTier0(sourceCode, contract) {
-  const issues = await runTier0Checks(sourceCode, contract);
+async function runTier0(sourceCode, contract, designMode = DEFAULT_DESIGN_MODE) {
+  const issues = await runTier0Checks(sourceCode, contract, void 0, void 0, designMode);
   const pass = [];
   const failedCategories = new Set(issues.map((i) => i.category));
   const tier0Categories = ["compile", "security", "contract", "types", "imports", "tokens"];
@@ -3844,6 +3962,7 @@ async function runTier0(sourceCode, contract) {
 var MANIFEST_TOKENS, TOKEN_REF_RE, HOOK_NAME_FOR, CONTRACT_FIELD_FOR;
 var init_run_tier0 = __esm({
   "src/check/run-tier0.ts"() {
+    init_design_mode();
     init_contract_validation();
     init_type_checker();
     init_react_linter();
@@ -6021,9 +6140,15 @@ function coerceStringArray(value) {
 }
 function buildMotherPrompt(ctx) {
   const parts = [];
-  parts.push(`You are evaluating a generated React component built with the ggui design system.
+  const designMode = ctx.designMode ?? DEFAULT_DESIGN_MODE;
+  const free = designMode === "free";
+  parts.push(
+    free ? `You are evaluating a generated React component. It was composed freely \u2014 raw HTML elements, inline styles and <style> blocks are allowed and the ggui design package is optional \u2014 against a data contract and a theme-token color rule.
+The code has already passed automated checks (compilation, security, imports, color tokens).
+Your job is to evaluate ONE specific quality criterion per call.` : `You are evaluating a generated React component built with the ggui design system.
 The code has already passed automated checks (compilation, security, imports, design tokens).
-Your job is to evaluate ONE specific quality criterion per call.`);
+Your job is to evaluate ONE specific quality criterion per call.`
+  );
   parts.push(`## About This Prompt
 This system prompt has 2 sections:
 1. **Context** \u2014 the original user request and data contract
@@ -6076,11 +6201,7 @@ ${JSON.stringify(ctx.contract).slice(0, 6e3)}
     parts.push(`## Design System
 ${ctx.designSystemSummary}`);
   }
-  parts.push(`## Design System Rules (important for evaluation)
-- Spacing props (\`gap\`, \`padding\`, \`margin\`) take a t-shirt-scale name: \`gap="md"\`, \`padding="lg"\` (\`none|xs|sm|md|lg|xl|2xl\`). **These ARE design tokens** \u2014 each resolves to a \`--ggui-spacing-*\` variable. A raw \`var(--ggui-spacing-*)\` string is an accepted escape hatch. NEVER flag a scale name as "hardcoded". Only a numeric prop (\`padding={24}\`) or a raw CSS length (\`gap="13px"\`) bypasses the scale and should be warned.
-- All colors must use CSS variables: \`color="var(--ggui-color-primary-600)"\` \u2014 hardcoded #hex or rgb() is a fail
-- Component props that take enum/scale values \u2014 \`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`padding="lg"\`, \`shadow="md"\`, \`radius="lg"\`, \`tone="muted"\`, \`surface="accent"\` \u2014 are all design system tokens and are always valid
-- One \`export default function Component\` \u2014 helper components as named functions above it are fine
+  parts.push(`${free ? FREE_STYLING_RULES : CONSTRAINED_STYLING_RULES}
 
 ## Evaluation Criteria Reference
 
@@ -6124,11 +6245,7 @@ ${ctx.designSystemSummary}`);
 - Error boundaries or error messages for failure cases
 - Empty states ("No items found") when data arrays could be empty
 
-**visual**: Design system consistency.
-- Uses CSS variables (var(--ggui-*)) for colors, not hardcoded values
-- Consistent use of spacing tokens
-- Proper use of component variants (primary, outline, ghost)
-- Shadow, border-radius from design system tokens
+${free ? FREE_VISUAL_REFERENCE : CONSTRAINED_VISUAL_REFERENCE}
 
 ## Primitive Accessibility (built-in \u2014 do NOT flag as missing)
 
@@ -6162,8 +6279,7 @@ role, aria-*, label, or keyboard support \u2014 it is already there:
   to text is CORRECTLY silent \u2014 never ask for \`aria-hidden\`, it is there.
 
 REAL accessibility gaps worth flagging:
-- A raw \`<div>\` / \`<span>\` used as a click target without \`as={Clickable}\`
-  (no role, no keyboard) \u2014 or any hand-rolled interactive element.
+${free ? FREE_RAW_CLICK_TARGET_GAP : CONSTRAINED_RAW_CLICK_TARGET_GAP}
 - A hand-rolled control whose state (checked / selected / expanded /
   pressed) is conveyed ONLY by styling \u2014 e.g. a styled-div "checkbox"
   with a check icon + strikethrough label but no \`role="checkbox"\` /
@@ -6218,13 +6334,13 @@ function makeTier2Tool(criterion) {
     }
   };
 }
-function getCriterionPrompt(criterion, numberedSource) {
+function getCriterionPrompt(criterion, numberedSource, designMode) {
   const sourceBlock = `
 Source code (with line numbers):
 \`\`\`tsx
 ${numberedSource}
 \`\`\``;
-  const criterionDef = getCriterionById(criterion);
+  const criterionDef = getCriterionById(criterion, designMode);
   if (criterionDef && criterionDef.tier > 0) {
     return `${criterionDef.evalInstruction}
 ${sourceBlock}
@@ -6371,7 +6487,7 @@ Return your evaluation using the evaluate_visual tool.
 
 Example outputs:
 - Clean: {"result": "pass"}
-- Minor issues: {"result": "warn", "issues": ["Line 45: hardcoded '#f3f4f6' should use var(--ggui-color-surfaceVariant)", "Line 80: numeric padding={16} should use a scale name like padding='md'"]}
+- Minor issues: {"result": "warn", "issues": ["Line 45: hardcoded '#f3f4f6' should use var(--ggui-color-sunken)", "Line 80: numeric padding={16} should use a scale name like padding='md'"]}
 - Severe: {"result": "fail", "issues": ["Component uses entirely custom styling with no design system tokens"]}
 
 Use 'fail' only for pervasive design system violations. Use 'warn' for isolated cases.`;
@@ -6393,10 +6509,10 @@ function getDefaultEvalModel(provider) {
       return "claude-haiku-4-5-20251001";
   }
 }
-async function evalCriterion(criterion, tier, motherPrompt, numberedSource, agent, model) {
+async function evalCriterion(criterion, tier, motherPrompt, numberedSource, agent, model, designMode) {
   const start = Date.now();
   const tool = tier === 1 ? makeTier1Tool(criterion) : makeTier2Tool(criterion);
-  const userPrompt = getCriterionPrompt(criterion, numberedSource);
+  const userPrompt = getCriterionPrompt(criterion, numberedSource, designMode);
   try {
     const response = await agent.callTools(
       model,
@@ -6492,7 +6608,8 @@ async function preWarmEval(context, _config) {
   const motherPrompt = buildMotherPrompt({
     originalPrompt: context.originalPrompt,
     contract: context.contract,
-    designSystemSummary: context.designContext
+    designSystemSummary: context.designContext,
+    designMode: context.designMode
   });
   return { motherPrompt, dynamicCriteria: [] };
 }
@@ -6525,10 +6642,12 @@ async function runLLMEvaluation(context, config, preWarmedContext) {
   const providerName = config.provider;
   const model = config.model || getDefaultEvalModel(providerName);
   const routerProvider = providerName === "claude" ? "anthropic" : providerName;
+  const designMode = context.designMode ?? DEFAULT_DESIGN_MODE;
   const motherPrompt = preWarmedContext?.motherPrompt ?? buildMotherPrompt({
     originalPrompt: context.originalPrompt,
     contract: context.contract,
-    designSystemSummary: context.designContext
+    designSystemSummary: context.designContext,
+    designMode
   });
   const numberedSource = context.sourceCode.split("\n").map((line, i) => `${String(i + 1).padStart(4)} | ${line}`).join("\n");
   const agent = createAgent({
@@ -6539,8 +6658,8 @@ async function runLLMEvaluation(context, config, preWarmedContext) {
   const evalStart = Date.now();
   const totalCriteriaCount = TIER_1_CRITERIA.length + TIER_2_CRITERIA.length;
   const results = await Promise.all([
-    ...TIER_1_CRITERIA.map((c) => evalCriterion(c, 1, motherPrompt, numberedSource, agent, model)),
-    ...TIER_2_CRITERIA.map((c) => evalCriterion(c, 2, motherPrompt, numberedSource, agent, model))
+    ...TIER_1_CRITERIA.map((c) => evalCriterion(c, 1, motherPrompt, numberedSource, agent, model, designMode)),
+    ...TIER_2_CRITERIA.map((c) => evalCriterion(c, 2, motherPrompt, numberedSource, agent, model, designMode))
   ]);
   const allIssues = [];
   const passCategories = [];
@@ -6584,12 +6703,39 @@ async function runLLMEvaluation(context, config, preWarmedContext) {
     outputTokens: totalOut
   };
 }
-var TIER_1_CRITERIA, TIER_2_CRITERIA, TIER_1_CATEGORIES, TIER_2_CATEGORIES, VALID_CATEGORIES;
+var FREE_STYLING_RULES, CONSTRAINED_STYLING_RULES, CONSTRAINED_VISUAL_REFERENCE, FREE_VISUAL_REFERENCE, CONSTRAINED_RAW_CLICK_TARGET_GAP, FREE_RAW_CLICK_TARGET_GAP, TIER_1_CRITERIA, TIER_2_CRITERIA, TIER_1_CATEGORIES, TIER_2_CATEGORIES, VALID_CATEGORIES;
 var init_llm_evaluator = __esm({
   "src/evaluation/llm-evaluator.ts"() {
     init_types_public();
     init_llm_router();
     init_types_public();
+    init_design_mode();
+    FREE_STYLING_RULES = `## Styling Rules (important for evaluation)
+- Color: every color must be a bare \`var(--ggui-color-*)\` token \u2014 a hardcoded #hex, rgb()/hsl() or CSS named color is a fail, and so is a literal fallback inside \`var(--ggui-*, \u2026)\`.
+- Spacing, typography, radius, shadow geometry and layout values MAY be literals (\`padding: '20px'\`, \`fontSize: 18\`, \`borderRadius: 12\`) \u2014 NEVER flag them.
+- Raw HTML elements with inline styles or \`<style>\` blocks are a first-class choice \u2014 never flag "not using the design system" or reward using it.
+- When \`@ggui-ai/design\` primitives ARE used, their enum/scale props (\`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`tone="muted"\`, \`surface="accent"\`) are valid.
+- One \`export default function Component\` \u2014 helper components as named functions above it are fine`;
+    CONSTRAINED_STYLING_RULES = `## Design System Rules (important for evaluation)
+- Spacing props (\`gap\`, \`padding\`, \`margin\`) take a t-shirt-scale name: \`gap="md"\`, \`padding="lg"\` (\`none|xs|sm|md|lg|xl|2xl\`). **These ARE design tokens** \u2014 each resolves to a \`--ggui-spacing-*\` variable. A raw \`var(--ggui-spacing-*)\` string is an accepted escape hatch. NEVER flag a scale name as "hardcoded". Only a numeric prop (\`padding={24}\`) or a raw CSS length (\`gap="13px"\`) bypasses the scale and should be warned.
+- All colors must use CSS variables: \`color="var(--ggui-color-primary-600)"\` \u2014 hardcoded #hex or rgb() is a fail
+- Component props that take enum/scale values \u2014 \`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`padding="lg"\`, \`shadow="md"\`, \`radius="lg"\`, \`tone="muted"\`, \`surface="accent"\` \u2014 are all design system tokens and are always valid
+- One \`export default function Component\` \u2014 helper components as named functions above it are fine`;
+    CONSTRAINED_VISUAL_REFERENCE = `**visual**: Design system consistency.
+- Uses CSS variables (var(--ggui-*)) for colors, not hardcoded values
+- Consistent use of spacing tokens
+- Proper use of component variants (primary, outline, ghost)
+- Shadow, border-radius from design system tokens`;
+    FREE_VISUAL_REFERENCE = `**visual**: Visual composition.
+- Clear hierarchy (one focal point, headings distinct from body), consistent spacing rhythm
+- Coherent palette drawn from the theme color tokens
+- Fit to the canvas: fluid width, nothing cramped or stretched
+- No reward or penalty for using (or not using) the design-system primitives`;
+    CONSTRAINED_RAW_CLICK_TARGET_GAP = `- A raw \`<div>\` / \`<span>\` used as a click target without \`as={Clickable}\`
+  (no role, no keyboard) \u2014 or any hand-rolled interactive element.`;
+    FREE_RAW_CLICK_TARGET_GAP = `- A raw \`<div>\` / \`<span>\` used as a click target with no \`role="button"\`,
+  \`tabIndex\` and keyboard handler \u2014 a real \`<button>\` / \`<a href>\` is the
+  correct raw element and is never a gap.`;
     TIER_1_CRITERIA = LLM_EVAL_STATIC_CRITERIA.filter((c) => c.tier === 1).map((c) => c.criterion);
     TIER_2_CRITERIA = LLM_EVAL_STATIC_CRITERIA.filter((c) => c.tier === 2).map((c) => c.criterion);
     TIER_1_CATEGORIES = /* @__PURE__ */ new Set(["functionality", "crash"]);
@@ -9910,13 +10056,22 @@ var init_build = __esm({
 // src/evaluation/visual-evaluator.ts
 var visual_evaluator_exports = {};
 __export(visual_evaluator_exports, {
+  EXECUTABLE_PATH_LAUNCH_ARGS: () => EXECUTABLE_PATH_LAUNCH_ARGS,
   buildRenderHTML: () => buildRenderHTML,
   bundleForRendering: () => bundleForRendering,
   callMultimodalLLM: () => callMultimodalLLM,
+  captureScreenshot: () => captureScreenshot,
   resolveDesignPackageDir: () => resolveDesignPackageDir,
+  resolveLaunchOptions: () => resolveLaunchOptions,
+  resolveUiGenPackageDir: () => resolveUiGenPackageDir,
   runVisualEval: () => runVisualEval,
-  runVisualEvaluation: () => runVisualEvaluation
+  runVisualEvaluation: () => runVisualEvaluation,
+  summarizeVisualResult: () => summarizeVisualResult
 });
+function resolveUiGenPackageDir() {
+  const selfDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(selfDir, "..", "..");
+}
 function resolveDesignPackageDir() {
   const selfDir = dirname(fileURLToPath(import.meta.url));
   return resolve(selfDir, "..", "..", "..", "design");
@@ -9931,12 +10086,32 @@ async function bundleForRendering(compiledCode, sampleProps) {
   const entryCode = `
 import React from 'react';
 import { createRoot } from 'react-dom/client';
+import { GguiWireProvider } from '@ggui-ai/wire';
 import Component from './component.tsx';
 
 const props = ${JSON.stringify(sampleProps)};
+const wireConfig = {
+  app: { appId: 'visual-eval', appName: 'Visual evaluation' },
+  render: { sessionId: 'visual-eval', isConnected: true },
+  auth: { isAuthenticated: false },
+  dispatch: () => {},
+  subscribe: () => () => {},
+};
+class RenderErrorBoundary extends React.Component<{ children: React.ReactNode }, { message: string | null }> {
+  state = { message: null as string | null };
+  static getDerivedStateFromError(err: unknown) { return { message: err instanceof Error ? err.message : String(err) }; }
+  render() {
+    return this.state.message === null
+      ? this.props.children
+      : React.createElement('div', { className: 'error' }, 'Render error: ' + this.state.message);
+  }
+}
 const root = createRoot(document.getElementById('root')!);
 try {
-  root.render(React.createElement(Component, props));
+  root.render(
+    React.createElement(GguiWireProvider, { config: wireConfig },
+      React.createElement(RenderErrorBoundary, null, React.createElement(Component, props))),
+  );
 } catch (err) {
   root.render(React.createElement('div', { className: 'error' }, 'Render error: ' + (err as Error).message));
 }
@@ -9962,6 +10137,10 @@ try {
         "@ggui-ai/design/compositions": resolve(designPkgDir, "src", "compositions", "index.ts"),
         "@ggui-ai/design/interact": resolve(designPkgDir, "src", "interact", "index.ts")
       },
+      // Bare imports in the generated component resolve against ui-gen's
+      // own node_modules — the temp entry dir has none. Without this every
+      // wire-bearing component (`@ggui-ai/wire`) failed to bundle.
+      nodePaths: [resolve(resolveUiGenPackageDir(), "node_modules")],
       logLevel: "silent"
     });
     return result.outputFiles[0]?.text ?? "";
@@ -10012,17 +10191,37 @@ ${bundledCode}
 </body>
 </html>`;
 }
-async function captureScreenshot(html, viewport = { width: 1280, height: 800 }) {
-  try {
-    const puppeteer = await import('puppeteer-core');
-    const chromium = await Promise.resolve().then(() => (init_build(), build_exports));
-    const launchOptions = {
-      args: chromium.default.args,
+async function loadSparticuzChromium() {
+  const chromium = await Promise.resolve().then(() => (init_build(), build_exports));
+  return chromium.default;
+}
+async function resolveLaunchOptions(viewport, deps = {}) {
+  const env = deps.env ?? process.env;
+  const override = env.PUPPETEER_EXECUTABLE_PATH?.trim();
+  if (override) {
+    return {
+      executablePath: override,
+      args: [...EXECUTABLE_PATH_LAUNCH_ARGS],
       defaultViewport: viewport,
-      executablePath: await chromium.default.executablePath(),
       headless: true
     };
-    const browser = await puppeteer.default.launch(launchOptions);
+  }
+  const chromium = await (deps.loadChromium ?? loadSparticuzChromium)();
+  return {
+    args: chromium.args,
+    defaultViewport: viewport,
+    executablePath: await chromium.executablePath(),
+    headless: true
+  };
+}
+async function launchWithPuppeteer(options) {
+  const puppeteer = await import('puppeteer-core');
+  return puppeteer.default.launch(options);
+}
+async function captureScreenshot(html, viewport = DEFAULT_SCREENSHOT_VIEWPORT, deps = {}) {
+  try {
+    const launchOptions = await resolveLaunchOptions(viewport, deps);
+    const browser = await (deps.launch ?? launchWithPuppeteer)(launchOptions);
     try {
       const page = await browser.newPage();
       await page.setContent(html, { waitUntil: "load", timeout: 15e3 });
@@ -10030,9 +10229,9 @@ async function captureScreenshot(html, viewport = { width: 1280, height: 800 })
       });
       await page.waitForSelector("#root > *", { timeout: 1e4 }).catch(() => {
       });
-      await new Promise((r) => setTimeout(r, 1e3));
+      await new Promise((r) => setTimeout(r, deps.settleMs ?? 1e3));
       const screenshot = await page.screenshot({ type: "png", fullPage: true });
-      return screenshot;
+      return Buffer.from(screenshot);
     } finally {
       await browser.close();
     }
@@ -10059,22 +10258,56 @@ Evaluate the screenshot of the generated component.`;
     1500
   );
 }
-async function runVisualEvaluation(context, config) {
+async function runVisualEvaluation(context, config, deps = {}) {
   const startTime = Date.now();
+  const judge = deps.judge ?? callMultimodalLLM;
   const bundledCode = await bundleForRendering(
     context.compiledCode,
     config.sampleProps ?? {}
   );
   console.log(`[visual-eval] bundled: ${bundledCode.length}B (${Date.now() - startTime}ms)`);
   const html = buildRenderHTML(bundledCode, context.cssTokens);
-  const screenshot = await captureScreenshot(html, config.viewport);
+  const model = config.model ?? getDefaultVisualModel(config.provider);
+  if (config.canvases !== void 0 && config.canvases.length > 0) {
+    const perCanvas = [];
+    const perCanvasResults = [];
+    for (const canvas of config.canvases) {
+      const viewport = CANVAS_VIEWPORTS[canvas];
+      const screenshot2 = await captureScreenshot(html, viewport, deps);
+      if (!screenshot2) {
+        console.warn(`[visual-eval] no browser available at canvas ${canvas} \u2014 skipping visual evaluation`);
+        return null;
+      }
+      const response2 = await judge(config, model, VISUAL_EVAL_PROMPT, screenshot2, context.originalPrompt);
+      const result2 = parseVisualResponse(response2.text, config.passThreshold);
+      result2.inputTokens = response2.inputTokens;
+      result2.outputTokens = response2.outputTokens;
+      perCanvasResults.push(result2);
+      perCanvas.push({
+        canvas,
+        viewport,
+        score: result2.finalScore,
+        passed: result2.passed,
+        screenshotPng: screenshot2
+      });
+      console.log(
+        `[visual-eval] canvas=${canvas} ${viewport.width}\xD7${viewport.height} score=${result2.finalScore} ${result2.passed ? "pass" : "FAIL"} | in=${response2.inputTokens} out=${response2.outputTokens}`
+      );
+    }
+    const aggregate = aggregateCanvasResults(perCanvas, perCanvasResults);
+    const elapsed2 = Date.now() - startTime;
+    console.log(
+      `[visual-eval] score=${aggregate.finalScore} (mean of ${perCanvas.length} canvases; ${aggregate.passed ? "every canvas passed" : `${perCanvas.filter((c) => !c.passed).length} failed`}) (${elapsed2}ms)`
+    );
+    return aggregate;
+  }
+  const screenshot = await captureScreenshot(html, config.viewport, deps);
   if (!screenshot) {
     console.warn("[visual-eval] no browser available \u2014 skipping visual evaluation");
     return null;
   }
   console.log(`[visual-eval] screenshot: ${screenshot.length}B (${Date.now() - startTime}ms)`);
-  const model = config.model ?? getDefaultVisualModel(config.provider);
-  const response = await callMultimodalLLM(
+  const response = await judge(
     config,
     model,
     VISUAL_EVAL_PROMPT,
@@ -10088,6 +10321,48 @@ async function runVisualEvaluation(context, config) {
   console.log(`[visual-eval] score=${result.finalScore} (${elapsed}ms) | in=${response.inputTokens} out=${response.outputTokens}`);
   return result;
 }
+function aggregateCanvasResults(perCanvas, results) {
+  const n = results.length;
+  const mean = (pick) => Math.round(results.reduce((sum, r) => sum + pick(r), 0) / n);
+  const dimensions = {
+    completeness: mean((r) => r.dimensions.completeness),
+    visualPolish: mean((r) => r.dimensions.visualPolish),
+    interactivity: mean((r) => r.dimensions.interactivity),
+    accessibility: mean((r) => r.dimensions.accessibility),
+    codeQuality: mean((r) => r.dimensions.codeQuality)
+  };
+  const issues = [];
+  const critiques = [];
+  let inputTokens = 0;
+  let outputTokens = 0;
+  results.forEach((r, i) => {
+    const canvas = perCanvas[i].canvas;
+    for (const issue of r.issues) issues.push({ ...issue, description: `[${canvas}] ${issue.description}` });
+    if (r.critique) critiques.push(`${canvas}: ${r.critique}`);
+    inputTokens += r.inputTokens ?? 0;
+    outputTokens += r.outputTokens ?? 0;
+  });
+  return {
+    passed: perCanvas.every((c) => c.passed),
+    finalScore: mean((r) => r.finalScore),
+    dimensions,
+    issues,
+    ...critiques.length > 0 ? { critique: critiques.join("\n") } : {},
+    inputTokens,
+    outputTokens,
+    canvases: [...perCanvas]
+  };
+}
+function summarizeVisualResult(result) {
+  if (result.canvases === void 0) return void 0;
+  const canvases = result.canvases.map((c) => ({
+    canvas: c.canvas,
+    viewport: c.viewport,
+    score: c.score,
+    passed: c.passed
+  }));
+  return { score: result.finalScore, passed: result.passed, canvases };
+}
 function parseVisualResponse(text, passThreshold) {
   const jsonMatch = text.match(/\{[\s\S]*\}/);
   if (!jsonMatch) {
@@ -10135,8 +10410,8 @@ function getDefaultVisualModel(provider) {
 }
 async function runVisualEval(context, config) {
   const result = await runVisualEvaluation(context, config);
-  if (!result) return [];
-  return (result.issues || []).map((issue) => ({
+  if (!result) return { issues: [] };
+  const issues = (result.issues || []).map((issue) => ({
     tier: 2,
     result: issue.severity === "critical" ? "fail" : "warn",
     category: "visual",
@@ -10145,11 +10420,16 @@ async function runVisualEval(context, config) {
     description: issue.description,
     fix: issue.fix || ""
   }));
+  const summary = summarizeVisualResult(result);
+  return summary === void 0 ? { issues } : { issues, summary };
 }
-var VISUAL_EVAL_PROMPT;
+var EXECUTABLE_PATH_LAUNCH_ARGS, DEFAULT_SCREENSHOT_VIEWPORT, VISUAL_EVAL_PROMPT;
 var init_visual_evaluator = __esm({
   "src/evaluation/visual-evaluator.ts"() {
     init_llm_router();
+    init_design_mode();
+    EXECUTABLE_PATH_LAUNCH_ARGS = ["--no-sandbox", "--disable-dev-shm-usage"];
+    DEFAULT_SCREENSHOT_VIEWPORT = { width: 1280, height: 800 };
     VISUAL_EVAL_PROMPT = `You are a visual quality evaluator for ggui \u2014 a platform where AI agents generate React UI components on demand.
 
 ## Context
@@ -10517,7 +10797,7 @@ __export(get_primitives_ts_exports, {
 var PRIMITIVES_DOCUMENTATION_TS;
 var init_get_primitives_ts = __esm({
   "src/tools/get-primitives-ts.ts"() {
-    PRIMITIVES_DOCUMENTATION_TS = "// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// GGUI DESIGN SYSTEM \u2014 COMPONENT REFERENCE\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// CRITICAL \u2014 Props take enum STRING LITERALS, not CSS variables:\n//   <Text size=\"sm\" weight=\"bold\" />                         \u2713\n//   <Text size=\"var(--ggui-font-size-sm)\" />                 \u2717  (breaks)\n//   The enum strings map to CSS variables internally.\n//\n// CRITICAL \u2014 onChange receives the VALUE directly, not an event:\n//   <Input value={x} onChange={setX} />                      \u2713\n//   <Input onChange={(e) => setX(e.target.value)} />         \u2717\n//\n// Imports allowed: 'react', '@ggui-ai/design', '@ggui-ai/wire'.\n//   The WHOLE design system \u2014 primitives, components, compositions,\n//   traits \u2014 is one import: import { Card, Grid, Modal, Clickable }\n//   from '@ggui-ai/design'. No subpaths. No external libs, no\n//   fetch(), no eval().\n//\n// All components accept 'style' + 'className' (omitted below).\n// Structural primitives (Box, Stack, Row, Card) also take a trait via\n// 'as': 'as={Clickable}' adds onClick + keyboard a11y; likewise\n// 'as={Hoverable}' and 'as={Pressable}'. Semantic components\n// (Button/Link/Input) are already interactive and take no 'as'.\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Primitives   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Container \u2014 Width-constrained wrapper that centers content horizontally\ninterface ContainerProps {\n  children?: ReactNode;\n  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full' | string;  // default 'lg'; Maximum width constraint\n  center?: boolean;  // default true; Whether to center the container horizontally via `margin: 0 auto`\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all sides\n}\n\n// Example:\n<Container maxWidth=\"xl\" padding=\"var(--ggui-spacing-6)\">\n  <Stack gap=\"var(--ggui-spacing-4)\">\n    <Heading level={1}>Dashboard</Heading>\n    <Card shadow=\"md\" padding=\"var(--ggui-spacing-5)\">\n      <Text>Welcome back!</Text>\n    </Card>\n  </Stack>\n</Container>\n\n// Card \u2014 Container with background, shadow, and optional border\ninterface CardProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'lg'; Padding applied to all sides\n  shadow?: 'none' | 'sm' | 'md' | 'lg' | 'xl';  // default 'sm'; Shadow elevation level\n  border?: boolean;  // default true; Whether to render a 1px border using `var(--ggui-color-outlineVariant)`\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'lg'; Corner radius\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'transparent';  // default 'default'; Semantic surface slot\n}\n\n// Example:\n<Card shadow=\"md\" padding=\"lg\" radius=\"lg\">\n  <Stack gap=\"md\">\n    <Text size=\"sm\" weight=\"medium\">Settings</Text>\n    <Input label=\"Name\" value={name} onChange={setName} />\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Card>\n\n// Stack \u2014 Flexbox layout primitive for arranging children along a single axis\ninterface StackProps {\n  children?: ReactNode;\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Main axis direction\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\n<Stack gap=\"lg\" align=\"center\">\n  <Heading level={2}>Profile</Heading>\n  <Text>Edit your account details below.</Text>\n  <Stack direction=\"horizontal\" gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\">Cancel</Button>\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Stack>\n\n// Grid \u2014 2-D layout primitive\ninterface GridProps {\n  children?: ReactNode;\n  columns?: number | ResponsiveColumns;  // default 2; Column count\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'md'; Gap between cells\n  minColumnWidth?: number | string;  // default undefined (use `columns`); When set, the grid becomes responsive \u2014 it fits as many equal\n}\n\n// Example:\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n\n// Skeleton \u2014 a pulsing placeholder for content that has not loaded\ninterface SkeletonProps {\n  variant?: 'rect' | 'text' | 'circle';  // default 'rect'; Shape preset\n  width?: number | string;\n  height?: number | string;\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'sm'; Corner radius\n}\n\n// Example:\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n\n// Box \u2014 Generic container with padding, margin, background, and border-radius\ninterface BoxProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all four sides\n  paddingX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Horizontal (left + right) padding\n  paddingY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Vertical (top + bottom) padding\n  margin?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no margin); Margin applied to all four sides\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'transparent';  // default undefined (transparent); Semantic surface slot\n  assetColor?: string;  // default undefined; Asset color escape \u2014 the typed valve for legitimate non-theme\n  assetSemantic?: string;  // default undefined; Human-readable semantic label that documents why\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default undefined (no rounding); Corner radius\n}\n\n// Example:\n<Box paddingX=\"xl\" paddingY=\"lg\" surface=\"accent\" radius=\"lg\">\n  <Text size=\"sm\" tone=\"emphasized\">\n    Tip: You can customize your theme in Settings.\n  </Text>\n</Box>\n\n// Divider \u2014 A 1px line to visually separate content sections\ninterface DividerProps {\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Line direction\n  margin?: number | string;  // default 16; Spacing around the divider\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-outlineVariant)`); Semantic color slot\n}\n\n// Example:\n<Stack gap={0}>\n  <Text>Section A</Text>\n  <Divider margin=\"var(--ggui-spacing-3)\" />\n  <Text>Section B</Text>\n</Stack>\n\n// Spacer \u2014 Invisible spacing element, either fixed-size or flexible\ninterface SpacerProps {\n  size?: number | 'flex';  // default 16; Spacing amount\n}\n\n// Example:\n<Stack direction=\"horizontal\" align=\"center\">\n  <Heading level={3}>Logo</Heading>\n  <Spacer size=\"flex\" />\n  <Button variant=\"ghost\">Login</Button>\n</Stack>\n\n// Text \u2014 Versatile typography primitive for body copy, captions, and labels\ninterface TextProps {\n  children?: ReactNode;\n  size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';  // default 'base'; Font size\n  weight?: 'normal' | 'medium' | 'semibold' | 'bold';  // default 'normal'; Font weight\n  caps?: boolean;  // default false; When true, uppercases the text and adds 0\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onSurface)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n  truncate?: boolean;  // default false; When true, clips overflowing text with an ellipsis\n  is?: 'p' | 'span' | 'div' | 'label';  // default 'p'; HTML element to render\n  id?: string;  // `id` for the rendered element \u2014 anchor an in-page link, or pair\n  htmlFor?: string;  // Associates an `is=\"label\"` element with a form control by the\n}\n\n// Example:\n<Stack gap=\"var(--ggui-spacing-1)\">\n  <Text size=\"xs\" weight=\"semibold\" caps tone=\"muted\">Account</Text>\n  <Text size=\"lg\">Welcome back, Jane.</Text>\n  <Text size=\"xs\" tone=\"muted\">\n    Last login: 2 hours ago\n  </Text>\n</Stack>\n\n// Heading \u2014 Semantic heading element (h1-h6) with preset typography styles\ninterface HeadingProps {\n  children?: ReactNode;\n  level?: 1 | 2 | 3 | 4 | 5 | 6;  // default 2; Semantic heading level\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onSurface)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n}\n\n// Example:\n<Stack gap=\"var(--ggui-spacing-2)\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={3} tone=\"emphasized\">\n    Subsection\n  </Heading>\n  <Text>Body content goes here.</Text>\n</Stack>\n\n// Button \u2014 A clickable button primitive with multiple visual variants and sizes\ninterface ButtonProps {\n  children?: ReactNode;\n  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';  // default 'primary'; Visual style\n  size?: 'xs' | 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and minimum height:\n  fullWidth?: boolean;  // default false; When true, sets `width: 100%` so the button fills its container\n  loading?: boolean;  // default false; When true, replaces children with a 16px `Spinner` (color: `currentColor`)\n  leftIcon?: ReactNode;  // ReactNode rendered before children, inside the flex layout with `var(--ggui-s...\n  rightIcon?: ReactNode;  // ReactNode rendered after children, inside the flex layout with `var(--ggui-sp...\n  onPress?: () => void;  // Alias for `onClick` for cross-platform compatibility (React Native convention)\n}\n\n// Example:\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n\n// Input \u2014 A single-line text input with label, validation, and helper text\ninterface InputProps {\n  label?: string;  // Label rendered above the input\n  placeholder?: string;  // Placeholder text shown when the input is empty\n  value?: string;  // Controlled value of the input\n  onChange?: (value: string) => void;  // Change handler\n  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | 'datetime-local';  // default 'text'; HTML input type\n  error?: string;  // Error message displayed below the input in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the input in `var(--ggui-color-onSurfaceVariant)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n\n// TextArea \u2014 A multiline text input with label, validation, character count, a...\ninterface TextAreaProps {\n  label?: string;  // Label rendered above the textarea\n  placeholder?: string;  // Placeholder text shown when the textarea is empty\n  value?: string;  // Controlled value of the textarea\n  onChange?: (value: string) => void;  // Change handler\n  rows?: number;  // default 4; Number of visible text rows (native `rows` attribute on `<textarea>`)\n  error?: string;  // Error message displayed below the textarea in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the textarea in `var(--ggui-color-onSurfaceVariant)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  maxLength?: number;  // Maximum character length (native `maxLength` attribute)\n  showCount?: boolean;  // default false; When true AND `maxLength` is set, displays a `{current}/{max}` character\n  autoResize?: boolean;  // default false; When true, sets CSS `resize: none` on the textarea\n}\n\n// Example:\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n\n// Select \u2014 A native dropdown selection primitive with label and validation\ninterface SelectProps {\n  label?: string;  // Label rendered above the select\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: SelectOption[];  // Array of selectable options\n  placeholder?: string;  // Placeholder text rendered as a disabled `<option value=\"\">` at the top of the\n  error?: string;  // Error message displayed below the select in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the select in `var(--ggui-color-onSurfaceVariant)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\n<Select\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  options={[\n    { value: 'us', label: 'United States' },\n    { value: 'uk', label: 'United Kingdom' },\n  ]}\n  placeholder=\"Select a country\"\n/>\n\n// Checkbox \u2014 A custom-styled checkbox with label and description\ninterface CheckboxProps {\n  label?: string;  // Primary label text rendered beside the checkbox box\n  checked?: boolean;  // Controlled checked state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  description?: string;  // Secondary description text rendered below the label in smaller, muted type\n  indeterminate?: boolean;  // default false; When true, displays a horizontal dash instead of a checkmark\n}\n\n// Example:\n<Checkbox\n  label=\"Accept terms\"\n  description=\"You agree to the Terms of Service and Privacy Policy\"\n  checked={accepted}\n  onChange={setAccepted}\n/>\n\n// Toggle \u2014 A switch/toggle input rendered as a pill-shaped track with a slidin...\ninterface ToggleProps {\n  label?: string;  // Label text rendered to the right of the toggle track\n  checked?: boolean;  // Controlled checked (on/off) state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track and knob dimensions:\n}\n\n// Example:\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n\n// RadioGroup \u2014 A group of mutually exclusive radio options with optional label...\ninterface RadioGroupProps {\n  label?: string;  // Group label rendered above the options\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: RadioOption[];  // Array of radio options\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Layout direction for the options container:\n  disabled?: boolean;  // default false; When true, disables ALL options (individual `RadioOption\n  error?: string;  // Error message displayed below all options in `var(--ggui-color-error-500)`\n}\n\n// Example:\n<RadioGroup\n  label=\"Plan\"\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: 'free', label: 'Free', description: 'Up to 5 projects' },\n    { value: 'pro', label: 'Pro', description: 'Unlimited projects' },\n  ]}\n/>\n\n// Slider \u2014 A range input with a custom-styled track, fill, and thumb\ninterface SliderProps {\n  label?: string;  // Label rendered above the slider track (left-aligned)\n  value?: number;  // default 0; Controlled numeric value\n  onChange?: (value: number) => void;  // Change handler\n  min?: number;  // default 0; Minimum allowed value\n  max?: number;  // default 100; Maximum allowed value\n  step?: number;  // default 1; Step increment for the slider\n  disabled?: boolean;  // default false; When true, sets `cursor: not-allowed` on the native input\n  showValue?: boolean;  // default false; When true, displays the current numeric value right-aligned in the header row\n}\n\n// Example:\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n\n// Badge \u2014 Inline label for status indicators, counts, or categories\ninterface BadgeProps {\n  children?: ReactNode;\n  variant?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info';  // default 'default'; Visual style\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n  pill?: boolean;  // default true; When true, uses fully rounded corners (`border-radius: 9999px`)\n}\n\n// Example:\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n\n// Spinner \u2014 Animated SVG loading indicator\ninterface SpinnerProps {\n  size?: number;  // default 24; Width and height of the SVG element in pixels\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the animated foreground arc\n}\n\n// Example:\n<Spinner size={32} tone=\"success\" />\n\n// Avatar \u2014 User or entity representation with image or auto-generated initials\ninterface AvatarProps {\n  src?: string;  // Image URL\n  name?: string;  // Name used for two purposes:\n  size?: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl';  // default 'md'; Avatar dimensions\n  shape?: 'circle' | 'square';  // default 'circle'; Container shape\n}\n\n// Example:\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n\n// Alert \u2014 Contextual message box for important information with icon and optio...\ninterface AlertProps {\n  children?: ReactNode;\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the body in semibold (`var(--ggui-font-weight-s...\n  closable?: boolean;  // default false; When true, renders a close button (X icon) in the top-right area\n  onClose?: () => void;  // Callback fired when the close button is clicked\n  icon?: ReactNode;  // Custom icon ReactNode to replace the default variant icon\n}\n\n// Example:\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n\n// Progress \u2014 Horizontal progress bar with determinate and indeterminate modes\ninterface ProgressProps {\n  value: number;  // Current progress value\n  max?: number;  // default 100; Maximum value representing 100% progress\n  variant?: 'default' | 'success' | 'warning' | 'error';  // default 'default'; Fill bar color\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track height in pixels:\n  label?: string;  // Accessible name describing what this bar measures, e\n  showLabel?: boolean;  // default false; When true, displays a header row above the track with the `label` text\n  indeterminate?: boolean;  // default false; When true, ignores `value` for visual width and plays a looping animation\n}\n\n// Example:\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n\n// Image \u2014 An `<img>` element with built-in error handling and fallback support\ninterface ImageProps {\n  src: string;  // Image source URL\n  alt: string;  // Alt text for the image\n  width?: number | string;  // default '100%' (applied at render time, not on the type); Image width\n  height?: number | string;  // default 'auto' (applied at render time, not on the type); Image height\n  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';  // default 'cover'; CSS `object-fit` value controlling how the image fills its box\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // Corner radius applied to both the image and the error placeholder\n  fallback?: ReactNode;  // Custom ReactNode rendered when the image fails to load\n}\n\n// Example:\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n\n// Icon \u2014 185 Lucide icons + emoji passthrough\ninterface IconProps {\n  name?: string;  // Lucide icon name (kebab-case, camelCase, or PascalCase all work)\n  size?: number;  // default 24; Icon dimensions in pixels (applied to both width and height of the wrapper\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (icon uses `currentColor`); Semantic color slot\n  children?: ReactNode;  // Custom SVG children\n  'aria-label'?: string;  // Accessible name for a standalone, meaning-bearing icon\n}\n\n// Example:\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n\n// Link \u2014 Styled anchor element with external link support\ninterface LinkProps {\n  children?: ReactNode;\n  href: string;  // Destination URL\n  external?: boolean;  // default false; When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener norefer...\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the link text\n  underline?: 'always' | 'hover' | 'none';  // default 'hover'; Underline behavior:\n}\n\n// Example:\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n\n// Tooltip \u2014 Hoverable information popup positioned relative to a trigger element\ninterface TooltipProps {\n  children: ReactNode;  // Trigger element\n  content: ReactNode;  // Tooltip content\n  position?: 'top' | 'bottom' | 'left' | 'right';  // default 'top'; Tooltip placement relative to the trigger element:\n  delay?: number;  // default 200; Delay in milliseconds before the tooltip becomes visible after hover/focus\n}\n\n// Example:\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n\n// Table \u2014 Data table with sortable columns, striped rows, and hover highlights\ninterface TableProps {\n  columns: TableColumn<T>[];  // Array of column definitions controlling header labels, data keys, and rendering\n  data: T[];  // Array of row data objects\n  sortKey?: string;  // The `key` of the currently sorted column\n  sortDirection?: SortDirection;  // default 'asc'; Current sort direction for the column identified by `sortKey`\n  onSort?: (key: string, direction: SortDirection) => void;  // Sort change handler\n  striped?: boolean;  // default false; When true, alternating rows (odd index) get a\n  hoverable?: boolean;  // default true; When true, rows highlight with `var(--ggui-color-surface)`\n  compact?: boolean;  // default false; When true, reduces cell padding:\n  bordered?: boolean;  // default false; When true, adds a 1px border around the table wrapper and between cells\n  caption?: string;  // Accessible table caption\n}\n\n// Example:\n<Table\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'role', header: 'Role' },\n    { key: 'status', header: 'Status', render: (v) => <Badge variant={v as string}>{v as string}</Badge> },\n  ]}\n  data={users}\n  sortKey={sortKey}\n  sortDirection={sortDir}\n  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}\n  striped\n/>\n\n// Tabs \u2014 Accessible tab navigation with panels and keyboard support\ninterface TabsProps {\n  items: TabItem[];  // Array of tab definitions\n  activeKey?: string;  // Controlled active tab key\n  onChange?: (key: string) => void;  // Tab change handler\n  variant?: 'line' | 'pills' | 'enclosed';  // default 'line'; Visual style of the tab bar:\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls tab button padding and font size:\n  fullWidth?: boolean;  // default false; When true, tab buttons expand equally to fill the container width\n}\n\n// Example:\n<Tabs\n  variant=\"pills\"\n  items={[\n    { key: 'overview', label: 'Overview', content: <Overview /> },\n    { key: 'settings', label: 'Settings', content: <Settings /> },\n  ]}\n  activeKey={tab}\n  onChange={setTab}\n/>\n\n// Toast \u2014 Notification banner with auto-dismiss and slide-in animation\ninterface ToastProps {\n  message: ReactNode;  // Message body content\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the message in semibold\n  duration?: number;  // default 5000; Auto-dismiss delay in milliseconds\n  onClose?: () => void;  // Callback fired on auto-dismiss timeout or when the close button is clicked\n  visible?: boolean;  // default true; Controls rendering\n  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';  // Intended screen position\n}\n\n// Example:\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n\n// Accordion \u2014 Collapsible content sections with chevron rotation animation\ninterface AccordionProps {\n  items: AccordionItem[];  // Array of collapsible section definitions\n  expandedKeys?: string[];  // Controlled expanded state\n  onChange?: (expandedKeys: string[]) => void;  // Expand/collapse handler\n  multiple?: boolean;  // default false; When true, multiple items can be open simultaneously\n  variant?: 'default' | 'bordered' | 'separated';  // default 'default'; Visual style controlling borders and spacing:\n}\n\n// Example:\n<Accordion\n  variant=\"separated\"\n  items={[\n    { key: 'faq1', title: 'How do I get started?', content: 'Sign up and...' },\n    { key: 'faq2', title: 'What is the pricing?', content: 'We offer...' },\n  ]}\n  expandedKeys={expanded}\n  onChange={setExpanded}\n  multiple\n/>\n\n// Row \u2014 Convenience alias for a horizontal Stack\ninterface RowProps {\n  children?: ReactNode;\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\n<Row gap=\"md\" align=\"center\" justify=\"between\">\n  <Text size=\"sm\" weight=\"medium\">Total</Text>\n  <Text weight=\"bold\">$42.00</Text>\n</Row>\n\n// Support types:\n// ResponsiveColumns \u2014 Explicit column count per viewport breakpoint, mobile-first\ninterface ResponsiveColumns {\n  base?: number;  // default 1; Columns below the `sm` breakpoint\n  sm?: number;  // Columns from 640px up\n  md?: number;  // Columns from 768px up\n  lg?: number;  // Columns from 1024px up\n  xl?: number;  // Columns from 1280px up\n}\n\n// SelectOption \u2014 An individual option within a `Select` dropdown\ninterface SelectOption {\n  value: string;  // The value submitted when this option is selected\n  label: string;  // The display text shown in the dropdown\n  disabled?: boolean;  // default false; When true, the option is visible but cannot be selected (grayed out by the br...\n}\n\n// RadioOption \u2014 An individual option within a `RadioGroup`\ninterface RadioOption {\n  value: string;  // The value emitted via `RadioGroupProps\n  label: string;  // Display text for this option\n  description?: string;  // Optional secondary description rendered below the label in smaller, muted type\n  disabled?: boolean;  // default false; When true, this individual option is grayed out (`opacity: 0\n}\n\n// TableColumn \u2014 Column definition for the Table component\ninterface TableColumn {\n  key: string;  // Property key in the row data object\n  header: string;  // Column header text\n  width?: number | string;  // Fixed column width\n  align?: 'left' | 'center' | 'right';  // default 'left'; Horizontal text alignment for both the header and data cells\n  sortable?: boolean;  // default false; When true, the header cell becomes clickable and shows sort direction\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n}\n\n// TabItem \u2014 Definition of a single tab within a Tabs component\ninterface TabItem {\n  key: string;  // Unique identifier for this tab\n  label: ReactNode;  // Tab button label\n  content: ReactNode;  // Panel content rendered below the tab bar when this tab is active\n  disabled?: boolean;  // default false; When true, the tab button shows `opacity: 0\n  icon?: ReactNode;  // Optional icon rendered before the label inside the tab button, with\n}\n\n// AccordionItem \u2014 Definition of a single collapsible section within an Accordion\ninterface AccordionItem {\n  key: string;  // Unique identifier for this item\n  title: ReactNode;  // Header label rendered inside the toggle button\n  content: ReactNode;  // Panel content rendered below the header when expanded\n  disabled?: boolean;  // default false; When true, the header button shows `opacity: 0\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Components   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// SearchField \u2014 A text input with a leading search icon and optional submit button\ninterface SearchFieldProps {\n  value?: string;  // Current search value\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly, not\n  onSearch?: (value: string) => void;  // Called when the user presses **Enter** or clicks the search button\n  placeholder?: string;  // default 'Search...'; Placeholder text shown when the input is empty\n  showButton?: boolean;  // default false; When `true`, renders a `Button` primitive to the right of the input\n  buttonText?: string;  // default 'Search'; Label rendered inside the submit button\n  loading?: boolean;  // When `true`, replaces the search icon with a `Spinner`, disables the\n  disabled?: boolean;  // When `true`, the input and button are visually disabled and do not\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls input height and font size\n}\n\n// Example:\n```tsx\n<SearchField\n  value={query}\n  onChange={setQuery}\n  onSearch={(q) => fetchResults(q)}\n  placeholder=\"Search products...\"\n  showButton\n  buttonText=\"Go\"\n  size=\"md\"\n/>\n```\n\n// FormField \u2014 A wrapper that adds a label, optional description, error message,\ninterface FormFieldProps {\n  label: string;  // Text rendered inside the `<label>` element above the input\n  children: ReactNode;  // The form control (typically an `Input`, `Select`, or `Textarea` primitive) re...\n  error?: string;  // Error message displayed below `children` in `colors\n  helperText?: string;  // Neutral guidance text displayed below `children` in `colors\n  required?: boolean;  // When `true`, appends a red asterisk (`*`) after the label text\n  description?: string;  // Secondary description rendered between the label and the child control\n}\n\n// Example:\n```tsx\n<FormField\n  label=\"Email address\"\n  required\n  description=\"We will never share your email.\"\n  error={errors.email}\n>\n  <Input value={email} onChange={setEmail} placeholder=\"you@example.com\" />\n</FormField>\n```\n\n// MenuItem \u2014 A full-width clickable row for menus, sidebars, and action lists\ninterface MenuItemProps {\n  label: string;  // Primary text content of the menu item\n  icon?: ReactNode;  // Icon or element rendered to the left of the label\n  rightElement?: ReactNode;  // Element rendered to the right of the label (e\n  onClick?: () => void;  // Called when the item is clicked\n  disabled?: boolean;  // When `true`, the item is non-interactive: `colors\n  active?: boolean;  // Marks this item as the current selection\n  danger?: boolean;  // Switches the item to destructive styling: `colors\n}\n\n// Example:\n```tsx\n<MenuItem\n  label=\"Delete project\"\n  icon={<Icon name=\"trash\" size={16} />}\n  danger\n  onClick={() => confirmDelete(projectId)}\n/>\n```\n\n// Tag \u2014 An inline label for categories, filters, statuses, or selections\ninterface TagProps {\n  children: ReactNode;  // Tag content -- typically a short text string\n  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';  // default 'default'; Semantic color variant applied to background, text, and border\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and internal gap\n  closable?: boolean;  // When `true`, renders a small close (\"x\") button after the content\n  onClose?: () => void;  // Called when the close button is clicked\n  icon?: ReactNode;  // Icon or element rendered before the text content\n}\n\n// Example:\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n\n// Dropdown \u2014 A click-triggered menu anchored to a trigger element\ninterface DropdownProps {\n  trigger: ReactNode;  // The element the user clicks to open the menu\n  options: DropdownOption[];  // Array of selectable options rendered as `MenuItem` rows\n  value?: string;  // The `value` of the currently selected option\n  onChange?: (value: string) => void;  // Called with the `value` string of the selected option (not the full\n  placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';  // default 'bottom-start'; Where to anchor the menu panel relative to the trigger\n  disabled?: boolean;  // When `true`, the trigger shows `cursor: not-allowed` and clicking\n}\n\n// Example:\n```tsx\n<Dropdown\n  trigger={<Button variant=\"outline\">Sort by</Button>}\n  options={[\n    { value: 'name', label: 'Name' },\n    { value: 'date', label: 'Date created' },\n    { value: 'delete', label: 'Delete', danger: true },\n  ]}\n  value={sortBy}\n  onChange={setSortBy}\n  placement=\"bottom-end\"\n/>\n```\n\n// Autocomplete \u2014 A text input with a filterable suggestion dropdown, keyboard navigation,\ninterface AutocompleteProps {\n  value?: string;  // default ''; Current text in the input field\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly,\n  onSelect?: (option: AutocompleteOption) => void;  // Called when the user selects an option (click or Enter on highlighted\n  options: AutocompleteOption[];  // The full list of available options\n  placeholder?: string;  // Placeholder text forwarded to the inner `Input` primitive\n  label?: string;  // Label text forwarded to the inner `Input` primitive\n  loading?: boolean;  // When `true`, the dropdown shows a centered `Spinner` instead of\n  disabled?: boolean;  // When `true`, the inner `Input` is disabled and the dropdown\n  error?: string;  // Error message forwarded to the inner `Input` primitive\n  noResultsText?: string;  // default 'No results found'; Text shown in the dropdown when filtering produces zero matches\n}\n\n// Example:\n```tsx\n<Autocomplete\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  onSelect={(opt) => setCountryCode(opt.value)}\n  options={countries}\n  placeholder=\"Type to search...\"\n  noResultsText=\"No countries found\"\n/>\n```\n\n// Breadcrumb \u2014 A horizontal navigation trail showing the user's location within a\ninterface BreadcrumbProps {\n  items: BreadcrumbItem[];  // Ordered array of breadcrumb segments from root to current page\n  separator?: ReactNode;  // default '/'; Separator rendered between each pair of items\n  onItemClick?: (item: BreadcrumbItem, index: number) => void;  // Called when a non-last item is clicked\n}\n\n// Example:\n```tsx\n<Breadcrumb\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Projects', href: '/projects' },\n    { label: 'ggui' },\n  ]}\n  separator=\"/\"\n  onItemClick={(item) => router.push(item.href!)}\n/>\n```\n\n// Pagination \u2014 Page navigation controls with previous/next arrows, numbered page buttons,\ninterface PaginationProps {\n  currentPage: number;  // Current active page\n  totalPages: number;  // Total number of pages\n  onPageChange?: (page: number) => void;  // Called when the user clicks a page number, arrow, or first/last button\n  showFirstLast?: boolean;  // default true; When `true`, renders double-chevron buttons for jumping to the first\n  maxVisible?: number;  // default 5; Maximum number of page buttons visible at once (including the first\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls button dimensions and icon sizes\n  disabled?: boolean;  // When `true`, all page buttons and arrows are visually dimmed\n}\n\n// Example:\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n\n// EmptyState \u2014 placeholder for a region with no data: empty lists,\ninterface EmptyStateProps {\n  icon?: string | ReactNode;  // A Lucide icon name (kebab-case), rendered large and subtle above\n  title: string;  // The headline, e\n  description?: string;  // Optional supporting line below the title\n  action?: ReactNode;  // Optional call-to-action, typically a `<Button>`\n}\n\n// Example:\n{results.length === 0\n  ? <EmptyState icon=\"search-x\" title=\"No matches\" description=\"Try a broader query.\" />\n  : results.map((r) => <Row key={r.id}>\u2026</Row>)}\n\n// Stat \u2014 a single KPI / metric: a label, a large value, an optional\ninterface StatProps {\n  label: string;  // The metric name, e\n  value: string | number;  // The headline value \u2014 the big number\n  delta?: string;  // Optional change indicator, pre-formatted, e\n  trend?: 'up' | 'down' | 'neutral';  // default 'neutral'; Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error,\n  icon?: string | ReactNode;  // Optional Lucide icon name (kebab-case) or custom node, shown next\n}\n\n// Example:\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n\n// Stepper \u2014 a display-only step indicator for multi-step flows\ninterface StepperProps {\n  steps: string[];  // Ordered step labels, one per step\n  current: number;  // Zero-based index of the active step\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Flow direction\n  onStepClick?: (index: number) => void;  // When provided, each step becomes a real button and clicks receive\n}\n\n// Example:\nconst STEPS = ['Account', 'Profile', 'Review'];\n// In the component: const [step, setStep] = useState(0);\n<Stack gap=\"lg\">\n  <Stepper steps={STEPS} current={step} />\n  {step === 0 && <AccountFields />}\n  <Row gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\" disabled={step === 0} onClick={() => setStep(step - 1)}>Back</Button>\n    <Button onClick={() => setStep(step + 1)}>Next</Button>\n  </Row>\n</Stack>\n\n// Markdown \u2014 renders markdown-formatted text as styled content:\ninterface MarkdownProps {\n  markdown: string;  // Markdown source text, passed through verbatim\n}\n\n// Example:\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n\n// MarkdownInline \u2014 renders ONE line of inline-level markdown (bold,\ninterface MarkdownInlineProps {\n  markdown: string;  // Inline markdown source -- bold, italic, inline code, and\n}\n\n// Example:\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n\n// Support types:\n// DropdownOption \u2014 A single option inside a `Dropdown`\ninterface DropdownOption {\n  value: string;  // Unique identifier returned to `onChange` when this option is selected\n  label: string;  // Human-readable text shown in the menu row\n  icon?: ReactNode;  // Optional icon rendered to the left of the label via `MenuItem\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive\n  danger?: boolean;  // When `true`, the option uses destructive (red) styling via\n}\n\n// AutocompleteOption \u2014 A single option in the `Autocomplete` suggestion list\ninterface AutocompleteOption {\n  value: string;  // Unique identifier for this option\n  label: string;  // Primary display text\n  description?: string;  // Secondary description rendered below the label in `fontSize\n  icon?: ReactNode;  // Icon rendered to the left of the label/description block\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive (`cursor: not-allowed`...\n}\n\n// BreadcrumbItem \u2014 A single segment in a `Breadcrumb` trail\ninterface BreadcrumbItem {\n  label: string;  // Display text for this breadcrumb segment\n  href?: string;  // URL for this segment\n  icon?: ReactNode;  // Icon rendered immediately before the label\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Compositions   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Header \u2014 Props for the `Header` composition\ninterface HeaderProps {\n  logo?: ReactNode;  // Logo or brand element rendered at the start (flex-shrink: 0)\n  navigation?: ReactNode;  // Navigation content rendered in a `<nav>` element with `flex: 1` and a 32 px l...\n  actions?: ReactNode;  // Right-side action elements (buttons, avatar, etc\n  sticky?: boolean;  // default false; When true, the header becomes `position: sticky` at the top of its scroll con...\n  background?: string;  // default colors.white; Background color of the header\n  bordered?: boolean;  // default true; When true, renders a 1 px bottom border in `colors\n}\n\n// Example:\n```tsx\n<Header\n  logo={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  navigation={<a href=\"/docs\">Docs</a>}\n  actions={<Button size=\"sm\">Sign In</Button>}\n  sticky\n  bordered\n/>\n```\n\n// Sidebar \u2014 Props for the `Sidebar` composition\ninterface SidebarProps {\n  items: SidebarItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: SidebarItem) => void;  // Called when any item (including parent items with children) is clicked\n  collapsed?: boolean;  // default false; When true, hides labels and badges; only icons remain visible, centered in th...\n  header?: ReactNode;  // Content rendered above the item list, separated by a bottom border\n  footer?: ReactNode;  // Content rendered below the item list, separated by a top border\n  width?: number;  // default 256; Width in pixels when expanded\n  collapsedWidth?: number;  // default 64; Width in pixels when collapsed\n}\n\n// Example:\n```tsx\n<Sidebar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'settings', label: 'Settings', icon: <Icon name=\"settings\" />,\n      children: [\n        { id: 'profile', label: 'Profile' },\n        { id: 'billing', label: 'Billing' },\n      ]},\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.href)}\n  collapsed={false}\n  width={256}\n/>\n```\n\n// CardGrid \u2014 Props for the `CardGrid` composition\ninterface CardGridProps {\n  children: ReactNode;  // Card elements to arrange in the grid\n  columns?: number | { sm?: number; md?: number; lg?: number };  // default 3; Number of columns, or a responsive breakpoint map\n  gap?: number;  // default 16; Gap between grid items in pixels\n}\n\n// Example:\n```tsx\n<CardGrid columns={3} gap={24}>\n  <Card>A</Card>\n  <Card>B</Card>\n  <Card>C</Card>\n</CardGrid>\n```\n\n// CommentThread \u2014 Props for the `CommentThread` composition\ninterface CommentThreadProps {\n  comments: Comment[];  // Array of top-level comments to render\n  currentUser?: { /** Display name for the current user's avatar. */ name: string; /** Avatar image URL for the current user. */ avatar?: string; };  // Current user info\n  onAddComment?: (content: string, parentId?: string) => void;  // Called when the user submits a new top-level comment\n  onReply?: (commentId: string, content: string) => void;  // Called when the user submits a reply to an existing comment\n  onReaction?: (commentId: string, emoji: string) => void;  // Called when the user clicks an emoji reaction on a comment\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the comment list\n}\n\n// Example:\n```tsx\n<CommentThread\n  comments={[\n    { id: '1', author: { name: 'Alice' }, content: 'Great work!', timestamp: new Date(),\n      replies: [{ id: '2', author: { name: 'Bob' }, content: 'Thanks!', timestamp: new Date() }] }\n  ]}\n  currentUser={{ name: 'Alice', avatar: '/alice.jpg' }}\n  onAddComment={(content) => post(content)}\n  onReply={(commentId, content) => reply(commentId, content)}\n  onReaction={(commentId, emoji) => react(commentId, emoji)}\n/>\n```\n\n// DataTable \u2014 Props for the `DataTable` composition\ninterface DataTableProps {\n  columns: DataTableColumn<T>[];  // Column definitions that control header, alignment, sorting, and rendering\n  data: T[];  // Row data array\n  rowKey?: string | ((row: T) => string);  // default 'id'; Property name or function used to derive a unique key for each row\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of table body rows\n  emptyText?: string;  // default 'No data'; Text shown when `data` is empty and not loading\n  onSort?: (key: string, direction: 'asc' | 'desc') => void;  // Called when a sortable column header is clicked\n  sortKey?: string;  // The column key currently being sorted\n  sortDirection?: 'asc' | 'desc';  // The current sort direction\n  onRowClick?: (row: T, index: number) => void;  // Called when a row is clicked\n  selectable?: boolean;  // When true, adds a checkbox column at the start of each row\n  selectedKeys?: string[];  // default []; Array of currently selected row keys\n  onSelectionChange?: (keys: string[]) => void;  // Called when the set of selected row keys changes (via row checkbox or select-...\n}\n\n// Example:\n```tsx\n<DataTable\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'email', header: 'Email' },\n    { key: 'role', header: 'Role', render: (v) => <Badge>{v}</Badge> },\n  ]}\n  data={users}\n  rowKey=\"id\"\n  selectable\n  selectedKeys={selected}\n  onSelectionChange={setSelected}\n  onSort={(key, dir) => sort(key, dir)}\n  sortKey=\"name\"\n  sortDirection=\"asc\"\n/>\n```\n\n// ChatWindow \u2014 Props for the `ChatWindow` composition\ninterface ChatWindowProps {\n  messages: ChatMessage[];  // Array of chat messages to display in chronological order\n  currentUserId: string;  // ID of the current user\n  onSendMessage?: (content: string) => void;  // Called when the user submits a message (Enter key or send button)\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the message list\n  typing?: { name: string } | null;  // When non-null, displays a typing indicator below the last message (e\n  placeholder?: string;  // default 'Type a message...'; Placeholder text for the message input field\n  header?: ReactNode;  // Optional header content rendered above the message area, separated by a botto...\n}\n\n// Example:\n```tsx\n<ChatWindow\n  messages={messages}\n  currentUserId=\"user-1\"\n  onSendMessage={(content) => send(content)}\n  typing={{ name: 'Alice' }}\n  placeholder=\"Type a message...\"\n  header={<h3>Chat with Alice</h3>}\n/>\n```\n\n// NavigationBar \u2014 Props for the `NavigationBar` composition\ninterface NavigationBarProps {\n  items: NavItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: NavItem) => void;  // Called when a non-disabled item is clicked\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Layout direction\n  variant?: 'default' | 'pills' | 'underline';  // default 'default'; Visual style for active/inactive items\n}\n\n// Example:\n```tsx\n<NavigationBar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'about', label: 'About' },\n    { id: 'contact', label: 'Contact' },\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.id)}\n  orientation=\"horizontal\"\n  variant=\"pills\"\n/>\n```\n\n// FileUploader \u2014 Props for the `FileUploader` composition\ninterface FileUploaderProps {\n  files?: UploadedFile[];  // default []; Array of files currently in the upload queue, shown below the drop zone\n  onFilesSelected?: (files: File[]) => void;  // Called when the user selects files via click or drag-and-drop\n  onFileRemove?: (fileId: string) => void;  // Called when the user clicks the remove button on a file entry\n  accept?: string;  // Accepted file types passed to the hidden `<input type=\"file\" accept=\"\n  multiple?: boolean;  // default true; When true, allows selecting multiple files at once\n  maxSize?: number;  // Maximum file size in bytes\n  maxFiles?: number;  // Maximum number of files\n  disabled?: boolean;  // When true, the drop zone is visually dimmed (opacity 0\n  dragDrop?: boolean;  // default true; When true, enables drag-and-drop on the drop zone\n}\n\n// Example:\n```tsx\n<FileUploader\n  files={uploadedFiles}\n  onFilesSelected={(files) => startUpload(files)}\n  onFileRemove={(id) => removeFile(id)}\n  accept=\"image/*,.pdf\"\n  multiple\n  maxSize={5 * 1024 * 1024}\n  maxFiles={10}\n  dragDrop\n/>\n```\n\n// NotificationCenter \u2014 Props for the `NotificationCenter` composition\ninterface NotificationCenterProps {\n  notifications: Notification[];  // Array of notifications to display, in the order provided\n  onMarkAsRead?: (id: string) => void;  // Called when the user clicks \"Mark as read\" on an individual notification\n  onMarkAllAsRead?: () => void;  // Called when the user clicks the \"Mark all read\" header button\n  onDismiss?: (id: string) => void;  // Called when the user clicks the dismiss (X) button on an individual notification\n  onClearAll?: () => void;  // Called when the user clicks the \"Clear all\" header button\n  emptyText?: string;  // default 'No notifications'; Text shown when `notifications` is empty and not loading\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the notification list\n}\n\n// Example:\n```tsx\n<NotificationCenter\n  notifications={[\n    { id: '1', title: 'Deployment complete', type: 'success', timestamp: new Date(), read: false },\n    { id: '2', title: 'Build failed', type: 'error', message: 'Lint errors', timestamp: new Date() },\n  ]}\n  onMarkAsRead={(id) => markRead(id)}\n  onMarkAllAsRead={() => markAllRead()}\n  onDismiss={(id) => dismiss(id)}\n  onClearAll={() => clearAll()}\n/>\n```\n\n// Modal \u2014 Props for the `Modal` composition\ninterface ModalProps {\n  open: boolean;  // Controls modal visibility\n  onClose: () => void;  // Called to close the modal (overlay click, escape key, or close button)\n  title?: string;  // Optional title rendered in the modal header via the `Heading` primitive (leve...\n  children: ReactNode;  // Modal body content rendered in a scrollable area (`overflowY: auto`)\n  footer?: ReactNode;  // Footer content rendered below the body, right-aligned with an 8 px gap, separ...\n  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';  // default 'md'; Controls the width of the modal panel\n  closeOnOverlayClick?: boolean;  // default true; When true, clicking the semi-transparent overlay behind the modal calls `onCl...\n  closeOnEscape?: boolean;  // default true; When true, pressing the Escape key calls `onClose`\n  showCloseButton?: boolean;  // default true; When true, renders a ghost close button (X icon) in the modal header\n}\n\n// Example:\n```tsx\n<Modal\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  title=\"Confirm Action\"\n  size=\"md\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleConfirm}>Confirm</Button>\n    </>\n  }\n>\n  <p>Are you sure you want to proceed?</p>\n</Modal>\n```\n\n// CommandPalette \u2014 Props for the `CommandPalette` composition\ninterface CommandPaletteProps {\n  open: boolean;  // Controls palette visibility\n  onClose: () => void;  // Called to close the palette (overlay click, Escape key, or after command sele...\n  commands: Command[];  // Full array of available commands\n  onSelect: (command: Command) => void;  // Called when a non-disabled command is selected (Enter key or click)\n  placeholder?: string;  // default 'Search commands...'; Placeholder text for the search input\n  recentIds?: string[];  // default []; IDs of recently used commands\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the command list\n}\n\n// Example:\n```tsx\n<CommandPalette\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  commands={[\n    { id: 'new', label: 'New File', shortcut: 'Ctrl+N', group: 'File' },\n    { id: 'save', label: 'Save', shortcut: 'Ctrl+S', group: 'File' },\n    { id: 'theme', label: 'Toggle Theme', group: 'Preferences' },\n  ]}\n  onSelect={(cmd) => executeCommand(cmd.id)}\n  recentIds={['save']}\n  placeholder=\"Search commands...\"\n/>\n```\n\n// Footer \u2014 Props for the `Footer` composition\ninterface FooterProps {\n  brand?: ReactNode;  // Brand element (logo, tagline) rendered in a flexible column (`flex: 1 1 280px`)\n  columns?: FooterColumn[];  // Array of link columns rendered in a flex-wrap layout with 48 px gap\n  socialLinks?: FooterSocialLink[];  // Social media icon links rendered in the bottom bar\n  bottomText?: string;  // Text displayed at the start of the bottom bar (e\n  bottomLinks?: FooterLink[];  // Links displayed in the bottom bar after social icons (e\n  background?: string;  // default colors.gray[50]; Background color of the footer\n  bordered?: boolean;  // default true; When true, renders a 1 px top border in `colors\n}\n\n// Example:\n```tsx\n<Footer\n  brand={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  columns={[\n    { title: 'Product', links: [{ label: 'Features', href: '/features' }] },\n    { title: 'Company', links: [{ label: 'About', href: '/about' }] },\n  ]}\n  socialLinks={[\n    { label: 'Twitter', href: 'https://twitter.com/acme', icon: <TwitterIcon /> },\n  ]}\n  bottomText=\"&copy; 2026 Acme Inc.\"\n  bottomLinks={[{ label: 'Privacy', href: '/privacy' }]}\n  bordered\n/>\n```\n\n// Hero \u2014 Props for the `Hero` composition\ninterface HeroProps {\n  heading?: string;  // Main heading text rendered as an `<h1>` with bold weight and tight line-height\n  description?: string;  // Description paragraph rendered below the heading with relaxed line-height\n  primaryAction?: HeroAction;  // Primary CTA button rendered with `colors\n  secondaryAction?: HeroAction;  // Secondary CTA button rendered with a transparent background and a 1 px border\n  media?: ReactNode;  // Media element (image, video, illustration) rendered beside or below the text ...\n  align?: 'center' | 'left';  // default 'center'; Text and layout alignment\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls vertical padding and heading/description font sizes\n  background?: string;  // default colors.white (when no backgroundImage is set); Background color of the hero section\n  backgroundImage?: string;  // Background image URL applied as `background-size: cover; background-position:...\n  overlay?: boolean;  // default false; When true and `backgroundImage` is set, renders a semi-transparent black overlay\n}\n\n// Example:\n```tsx\n<Hero\n  heading=\"Build Better UIs, Faster\"\n  description=\"The universal interface layer between AI agents and humans.\"\n  primaryAction={{ label: 'Get Started', onClick: () => navigate('/signup') }}\n  secondaryAction={{ label: 'Learn More', href: '/docs' }}\n  media={<img src=\"/hero.png\" alt=\"Hero\" />}\n  align=\"left\"\n  size=\"lg\"\n/>\n```\n\n// Support types:\n// SidebarItem \u2014 A single navigation entry in a `Sidebar`\ninterface SidebarItem {\n  id: string;  // Unique identifier used for active-state matching and React keys\n  label: string;  // Display label for the item\n  icon?: ReactNode;  // Leading icon rendered before the label\n  href?: string;  // Optional URL associated with this item (not rendered as a link by default)\n  badge?: ReactNode;  // Trailing badge element (e\n  children?: SidebarItem[];  // Nested child items\n  disabled?: boolean;  // When true, the item is visually dimmed and non-interactive (`cursor: not-allo...\n}\n\n// Comment \u2014 A single comment entry in a `CommentThread`\ninterface Comment {\n  id: string;  // Unique identifier for this comment\n  author: { /** Display name of the author. */ name: string; /** URL for the author's avatar image. Passed to the `Avatar` primitive. */ avatar?: string; };  // Comment author metadata\n  content: string;  // The comment body text\n  timestamp: string | Date;  // Timestamp of the comment\n  replies?: Comment[];  // Nested reply comments\n  reactions?: { emoji: string; count: number }[];  // Emoji reactions with their aggregated counts (e\n}\n\n// DataTableColumn \u2014 Column definition for a `DataTable`\ninterface DataTableColumn {\n  key: string;  // Property key on the row object used to extract cell values\n  header: string;  // Column header text displayed in the `<thead>`\n  width?: number | string;  // Column width as a CSS value (number for pixels, string for any CSS unit)\n  sortable?: boolean;  // When true, the column header is clickable and triggers `onSort`\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n  align?: 'left' | 'center' | 'right';  // default 'left'; Text alignment for both header and body cells\n}\n\n// ChatMessage \u2014 A single message in a `ChatWindow`\ninterface ChatMessage {\n  id: string;  // Unique identifier for this message\n  content: string;  // The message body text\n  sender: { /** Unique ID of the sender. Compared to `currentUserId` to determine alignment. */ id: string; /** Display name of the sender. */ name: string; /** Avatar image URL. Only shown for non-current-user messages (xs size). */ avatar?: string; };  // Sender metadata used for avatar rendering and alignment\n  timestamp: string | Date;  // Message timestamp\n  status?: 'sending' | 'sent' | 'delivered' | 'read' | 'error';  // Delivery status indicator shown on the current user's messages\n}\n\n// NavItem \u2014 A single navigation entry in a `NavigationBar`\ninterface NavItem {\n  id: string;  // Unique identifier used for active-state matching and React keys\n  label: string;  // Display label for the navigation link\n  href?: string;  // URL for the item\n  icon?: ReactNode;  // Optional icon rendered before the label\n  children?: NavItem[];  // Nested child items (for sub-menu structures; rendering is consumer-defined)\n  disabled?: boolean;  // When true, the item is visually dimmed (opacity 0\n}\n\n// UploadedFile \u2014 A file entry in the `FileUploader` composition\ninterface UploadedFile {\n  id: string;  // Unique identifier for this file entry\n  name: string;  // Original file name\n  size: number;  // File size in bytes\n  type: string;  // MIME type of the file (e\n  progress?: number;  // Upload progress as a percentage (0-100)\n  status: 'pending' | 'uploading' | 'success' | 'error';  // Current upload lifecycle status\n  error?: string;  // Error message displayed when status is `'error'`\n  url?: string;  // The remote URL of the uploaded file after successful upload\n}\n\n// Notification \u2014 A single notification entry in the `NotificationCenter`\ninterface Notification {\n  id: string;  // Unique identifier for this notification\n  title: string;  // Notification title rendered in medium weight\n  message?: string;  // Optional body text rendered below the title in a smaller font\n  timestamp: string | Date;  // Timestamp of the notification\n  read?: boolean;  // default false; Read state\n  type?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Semantic type that controls the status dot color on unread notifications\n  icon?: ReactNode;  // Optional icon rendered alongside the notification (not used by the default im...\n  action?: { /** Button label text. */ label: string; /** Click handler for the action. */ onClick: () => void; };  // Optional inline action button rendered next to the timestamp\n}\n\n// Command \u2014 A single command entry in a `CommandPalette`\ninterface Command {\n  id: string;  // Unique identifier for this command\n  label: string;  // Display label for the command\n  description?: string;  // Optional description text shown below the label\n  icon?: ReactNode;  // Icon rendered at the start of the command row\n  shortcut?: string;  // Keyboard shortcut hint displayed at the end of the row in a `<kbd>` element\n  group?: string;  // Group name for visual sectioning\n  disabled?: boolean;  // When true, the command is visually dimmed and cannot be selected\n}\n\n// FooterLink \u2014 A single link entry in a footer column or the bottom bar\ninterface FooterLink {\n  label: string;  // Display text for the link\n  href?: string;  // URL for the link\n  onClick?: () => void;  // Click handler\n}\n\n// FooterColumn \u2014 A named column of links in the `Footer` layout\ninterface FooterColumn {\n  title?: string;  // Column heading rendered as an `<h4>` with semibold weight\n  links: FooterLink[];  // Links displayed in this column\n}\n\n// FooterSocialLink \u2014 A social media link in the `Footer` bottom bar\ninterface FooterSocialLink {\n  label: string;  // Accessible label for the social link (used as `aria-label`)\n  href: string;  // URL for the social media profile or page\n  icon: ReactNode;  // Icon element rendered inside the anchor (typically an SVG or `Icon` primitive)\n}\n\n// HeroAction \u2014 A call-to-action button definition for the `Hero` composition\ninterface HeroAction {\n  label: string;  // Button label text\n  onClick?: () => void;  // Click handler for the button\n  href?: string;  // Optional URL (not used by the default implementation; available for consumer ...\n}\n\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// System Conventions\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// Motion: render <MotionKeyframes /> once to enable keyframes.\n//   Entrance/exit: fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n//   State feedback: flash, pulse, bounce\n//   Easing: linear, easeIn, easeOut, easeInOut, spring\n//   Durations: instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n//\n// Elevation levels (shadow \u2192 z-index):\n//   0: flat          1: sm (cards)     2: md z=1000 (dropdowns, popovers)\n//   3: lg z=1200     4: xl z=1400      5: 2xl z=1800 (tooltips, toasts)\n//\n// useAnimationKey(dep) returns a key that bumps when dep changes \u2014\n// apply to <div key={...}> to replay CSS animations on data update.\n//\n// useMotion() returns { motionEnabled } \u2014 respect prefers-reduced-motion.\n";
+    PRIMITIVES_DOCUMENTATION_TS = "// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// GGUI DESIGN SYSTEM \u2014 COMPONENT REFERENCE\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// CRITICAL \u2014 Props take enum STRING LITERALS, not CSS variables:\n//   <Text size=\"sm\" weight=\"bold\" />                         \u2713\n//   <Text size=\"var(--ggui-font-size-sm)\" />                 \u2717  (breaks)\n//   The enum strings map to CSS variables internally.\n//\n// CRITICAL \u2014 onChange receives the VALUE directly, not an event:\n//   <Input value={x} onChange={setX} />                      \u2713\n//   <Input onChange={(e) => setX(e.target.value)} />         \u2717\n//\n// Imports allowed: 'react', '@ggui-ai/design', '@ggui-ai/wire'.\n//   The WHOLE design system \u2014 primitives, components, compositions,\n//   traits \u2014 is one import: import { Card, Grid, Modal, Clickable }\n//   from '@ggui-ai/design'. No subpaths. No external libs, no\n//   fetch(), no eval().\n//\n// All components accept 'style' + 'className' (omitted below).\n// Structural primitives (Box, Stack, Row, Card) also take a trait via\n// 'as': 'as={Clickable}' adds onClick + keyboard a11y; likewise\n// 'as={Hoverable}' and 'as={Pressable}'. Semantic components\n// (Button/Link/Input) are already interactive and take no 'as'.\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Primitives   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Container \u2014 Width-constrained wrapper that centers content horizontally\ninterface ContainerProps {\n  children?: ReactNode;\n  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full' | string;  // default 'lg'; Maximum width constraint\n  center?: boolean;  // default true; Whether to center the container horizontally via `margin: 0 auto`\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all sides\n}\n\n// Example:\n<Container maxWidth=\"xl\" padding=\"var(--ggui-spacing-6)\">\n  <Stack gap=\"var(--ggui-spacing-4)\">\n    <Heading level={1}>Dashboard</Heading>\n    <Card shadow=\"md\" padding=\"var(--ggui-spacing-5)\">\n      <Text>Welcome back!</Text>\n    </Card>\n  </Stack>\n</Container>\n\n// Card \u2014 Container with background, shadow, and optional border\ninterface CardProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'lg'; Padding applied to all sides\n  shadow?: 'none' | 'sm' | 'md' | 'lg' | 'xl';  // default 'sm'; Shadow elevation level\n  border?: boolean;  // default true; Whether to render a 1px border using `var(--ggui-color-outlineVariant)`\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'lg'; Corner radius\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'transparent';  // default 'default'; Semantic surface slot\n}\n\n// Example:\n<Card shadow=\"md\" padding=\"lg\" radius=\"lg\">\n  <Stack gap=\"md\">\n    <Text size=\"sm\" weight=\"medium\">Settings</Text>\n    <Input label=\"Name\" value={name} onChange={setName} />\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Card>\n\n// Stack \u2014 Flexbox layout primitive for arranging children along a single axis\ninterface StackProps {\n  children?: ReactNode;\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Main axis direction\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\n<Stack gap=\"lg\" align=\"center\">\n  <Heading level={2}>Profile</Heading>\n  <Text>Edit your account details below.</Text>\n  <Stack direction=\"horizontal\" gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\">Cancel</Button>\n    <Button variant=\"primary\">Save</Button>\n  </Stack>\n</Stack>\n\n// Grid \u2014 2-D layout primitive\ninterface GridProps {\n  children?: ReactNode;\n  columns?: number | ResponsiveColumns;  // default 2; Column count\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'md'; Gap between cells\n  minColumnWidth?: number | string;  // default undefined (use `columns`); When set, the grid becomes responsive \u2014 it fits as many equal\n}\n\n// Example:\n<Grid columns={3} gap=\"md\">\n  {items.map((it) => <Card key={it.id}>{it.name}</Card>)}\n</Grid>\n\n// Skeleton \u2014 a pulsing placeholder for content that has not loaded\ninterface SkeletonProps {\n  variant?: 'rect' | 'text' | 'circle';  // default 'rect'; Shape preset\n  width?: number | string;\n  height?: number | string;\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default 'sm'; Corner radius\n}\n\n// Example:\n{user === undefined\n  ? <Skeleton variant=\"text\" width=\"40%\" />\n  : <Text>{user.name}</Text>}\n\n// Box \u2014 Generic container with padding, margin, background, and border-radius\ninterface BoxProps {\n  children?: ReactNode;\n  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no padding); Padding applied to all four sides\n  paddingX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Horizontal (left + right) padding\n  paddingY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined; Vertical (top + bottom) padding\n  margin?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default undefined (no margin); Margin applied to all four sides\n  surface?: 'default' | 'elevated' | 'sunken' | 'accent' | 'inverted' | 'transparent';  // default undefined (transparent); Semantic surface slot\n  assetColor?: string;  // default undefined; Asset color escape \u2014 the typed valve for legitimate non-theme\n  assetSemantic?: string;  // default undefined; Human-readable semantic label that documents why\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // default undefined (no rounding); Corner radius\n}\n\n// Example:\n<Box paddingX=\"xl\" paddingY=\"lg\" surface=\"accent\" radius=\"lg\">\n  <Text size=\"sm\" tone=\"emphasized\">\n    Tip: You can customize your theme in Settings.\n  </Text>\n</Box>\n\n// Divider \u2014 A 1px line to visually separate content sections\ninterface DividerProps {\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Line direction\n  margin?: number | string;  // default 16; Spacing around the divider\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-outlineVariant)`); Semantic color slot\n}\n\n// Example:\n<Stack gap={0}>\n  <Text>Section A</Text>\n  <Divider margin=\"var(--ggui-spacing-3)\" />\n  <Text>Section B</Text>\n</Stack>\n\n// Spacer \u2014 Invisible spacing element, either fixed-size or flexible\ninterface SpacerProps {\n  size?: number | 'flex';  // default 16; Spacing amount\n}\n\n// Example:\n<Stack direction=\"horizontal\" align=\"center\">\n  <Heading level={3}>Logo</Heading>\n  <Spacer size=\"flex\" />\n  <Button variant=\"ghost\">Login</Button>\n</Stack>\n\n// Text \u2014 Versatile typography primitive for body copy, captions, and labels\ninterface TextProps {\n  children?: ReactNode;\n  size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';  // default 'base'; Font size\n  weight?: 'normal' | 'medium' | 'semibold' | 'bold';  // default 'normal'; Font weight\n  caps?: boolean;  // default false; When true, uppercases the text and adds 0\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onContainer)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n  truncate?: boolean;  // default false; When true, clips overflowing text with an ellipsis\n  is?: 'p' | 'span' | 'div' | 'label';  // default 'p'; HTML element to render\n  id?: string;  // `id` for the rendered element \u2014 anchor an in-page link, or pair\n  htmlFor?: string;  // Associates an `is=\"label\"` element with a form control by the\n}\n\n// Example:\n<Stack gap=\"var(--ggui-spacing-1)\">\n  <Text size=\"xs\" weight=\"semibold\" caps tone=\"muted\">Account</Text>\n  <Text size=\"lg\">Welcome back, Jane.</Text>\n  <Text size=\"xs\" tone=\"muted\">\n    Last login: 2 hours ago\n  </Text>\n</Stack>\n\n// Heading \u2014 Semantic heading element (h1-h6) with preset typography styles\ninterface HeadingProps {\n  children?: ReactNode;\n  level?: 1 | 2 | 3 | 4 | 5 | 6;  // default 2; Semantic heading level\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default 'default' (var(--ggui-color-onContainer)); Semantic color slot\n  align?: 'left' | 'center' | 'right';  // default undefined (inherits from parent); Horizontal text alignment\n}\n\n// Example:\n<Stack gap=\"var(--ggui-spacing-2)\">\n  <Heading level={1}>Page Title</Heading>\n  <Heading level={3} tone=\"emphasized\">\n    Subsection\n  </Heading>\n  <Text>Body content goes here.</Text>\n</Stack>\n\n// Button \u2014 A clickable button primitive with multiple visual variants and sizes\ninterface ButtonProps {\n  children?: ReactNode;\n  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';  // default 'primary'; Visual style\n  size?: 'xs' | 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and minimum height:\n  fullWidth?: boolean;  // default false; When true, sets `width: 100%` so the button fills its container\n  loading?: boolean;  // default false; When true, replaces children with a 16px `Spinner` (color: `currentColor`)\n  leftIcon?: ReactNode;  // ReactNode rendered before children, inside the flex layout with `var(--ggui-s...\n  rightIcon?: ReactNode;  // ReactNode rendered after children, inside the flex layout with `var(--ggui-sp...\n  onPress?: () => void;  // Alias for `onClick` for cross-platform compatibility (React Native convention)\n}\n\n// Example:\n<Button variant=\"primary\" size=\"md\" leftIcon={<Icon name=\"save\" />} onClick={handleSave}>\n  Save Changes\n</Button>\n\n// Input \u2014 A single-line text input with label, validation, and helper text\ninterface InputProps {\n  label?: string;  // Label rendered above the input\n  placeholder?: string;  // Placeholder text shown when the input is empty\n  value?: string;  // Controlled value of the input\n  onChange?: (value: string) => void;  // Change handler\n  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search' | 'date' | 'time' | 'datetime-local';  // default 'text'; HTML input type\n  error?: string;  // Error message displayed below the input in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the input in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\n<Input label=\"Email\" type=\"email\" value={email} onChange={setEmail} error={emailError} />\n\n// TextArea \u2014 A multiline text input with label, validation, character count, a...\ninterface TextAreaProps {\n  label?: string;  // Label rendered above the textarea\n  placeholder?: string;  // Placeholder text shown when the textarea is empty\n  value?: string;  // Controlled value of the textarea\n  onChange?: (value: string) => void;  // Change handler\n  rows?: number;  // default 4; Number of visible text rows (native `rows` attribute on `<textarea>`)\n  error?: string;  // Error message displayed below the textarea in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the textarea in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  maxLength?: number;  // Maximum character length (native `maxLength` attribute)\n  showCount?: boolean;  // default false; When true AND `maxLength` is set, displays a `{current}/{max}` character\n  autoResize?: boolean;  // default false; When true, sets CSS `resize: none` on the textarea\n}\n\n// Example:\n<TextArea label=\"Bio\" value={bio} onChange={setBio} rows={6} maxLength={500} showCount />\n\n// Select \u2014 A native dropdown selection primitive with label and validation\ninterface SelectProps {\n  label?: string;  // Label rendered above the select\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: SelectOption[];  // Array of selectable options\n  placeholder?: string;  // Placeholder text rendered as a disabled `<option value=\"\">` at the top of the\n  error?: string;  // Error message displayed below the select in `var(--ggui-color-error-500)`\n  helperText?: string;  // Helper text displayed below the select in `var(--ggui-color-onSunken)`\n  required?: boolean;  // default false; When true, appends a red asterisk (`*`) to the label and sets the native\n  disabled?: boolean;  // default false; When true, sets the native `disabled` attribute\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n}\n\n// Example:\n<Select\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  options={[\n    { value: 'us', label: 'United States' },\n    { value: 'uk', label: 'United Kingdom' },\n  ]}\n  placeholder=\"Select a country\"\n/>\n\n// Checkbox \u2014 A custom-styled checkbox with label and description\ninterface CheckboxProps {\n  label?: string;  // Primary label text rendered beside the checkbox box\n  checked?: boolean;  // Controlled checked state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  description?: string;  // Secondary description text rendered below the label in smaller, muted type\n  indeterminate?: boolean;  // default false; When true, displays a horizontal dash instead of a checkmark\n}\n\n// Example:\n<Checkbox\n  label=\"Accept terms\"\n  description=\"You agree to the Terms of Service and Privacy Policy\"\n  checked={accepted}\n  onChange={setAccepted}\n/>\n\n// Toggle \u2014 A switch/toggle input rendered as a pill-shaped track with a slidin...\ninterface ToggleProps {\n  label?: string;  // Label text rendered to the right of the toggle track\n  checked?: boolean;  // Controlled checked (on/off) state\n  onChange?: (checked: boolean) => void;  // Change handler\n  disabled?: boolean;  // default false; When true, sets `opacity: 0\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track and knob dimensions:\n}\n\n// Example:\n<Toggle label=\"Enable notifications\" checked={enabled} onChange={setEnabled} size=\"md\" />\n\n// RadioGroup \u2014 A group of mutually exclusive radio options with optional label...\ninterface RadioGroupProps {\n  label?: string;  // Group label rendered above the options\n  value?: string;  // Controlled value\n  onChange?: (value: string) => void;  // Change handler\n  options: RadioOption[];  // Array of radio options\n  direction?: 'vertical' | 'horizontal';  // default 'vertical'; Layout direction for the options container:\n  disabled?: boolean;  // default false; When true, disables ALL options (individual `RadioOption\n  error?: string;  // Error message displayed below all options in `var(--ggui-color-error-500)`\n}\n\n// Example:\n<RadioGroup\n  label=\"Plan\"\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: 'free', label: 'Free', description: 'Up to 5 projects' },\n    { value: 'pro', label: 'Pro', description: 'Unlimited projects' },\n  ]}\n/>\n\n// Slider \u2014 A range input with a custom-styled track, fill, and thumb\ninterface SliderProps {\n  label?: string;  // Label rendered above the slider track (left-aligned)\n  value?: number;  // default 0; Controlled numeric value\n  onChange?: (value: number) => void;  // Change handler\n  min?: number;  // default 0; Minimum allowed value\n  max?: number;  // default 100; Maximum allowed value\n  step?: number;  // default 1; Step increment for the slider\n  disabled?: boolean;  // default false; When true, sets `cursor: not-allowed` on the native input\n  showValue?: boolean;  // default false; When true, displays the current numeric value right-aligned in the header row\n}\n\n// Example:\n<Slider label=\"Volume\" value={volume} onChange={setVolume} min={0} max={100} step={5} showValue />\n\n// Badge \u2014 Inline label for status indicators, counts, or categories\ninterface BadgeProps {\n  children?: ReactNode;\n  variant?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'tertiary';  // default 'default'; Visual style\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding and font size:\n  pill?: boolean;  // default true; When true, uses fully rounded corners (`border-radius: 9999px`)\n}\n\n// Example:\n<Badge variant=\"success\" size=\"sm\">Active</Badge>\n\n// Spinner \u2014 Animated SVG loading indicator\ninterface SpinnerProps {\n  size?: number;  // default 24; Width and height of the SVG element in pixels\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the animated foreground arc\n}\n\n// Example:\n<Spinner size={32} tone=\"success\" />\n\n// Avatar \u2014 User or entity representation with image or auto-generated initials\ninterface AvatarProps {\n  src?: string;  // Image URL\n  name?: string;  // Name used for two purposes:\n  size?: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl';  // default 'md'; Avatar dimensions\n  shape?: 'circle' | 'square';  // default 'circle'; Container shape\n}\n\n// Example:\n<Avatar src=\"/photos/jane.jpg\" name=\"Jane Doe\" size=\"lg\" shape=\"circle\" />\n\n// Alert \u2014 Contextual message box for important information with icon and optio...\ninterface AlertProps {\n  children?: ReactNode;\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the body in semibold (`var(--ggui-font-weight-s...\n  closable?: boolean;  // default false; When true, renders a close button (X icon) in the top-right area\n  onClose?: () => void;  // Callback fired when the close button is clicked\n  icon?: ReactNode;  // Custom icon ReactNode to replace the default variant icon\n}\n\n// Example:\n<Alert variant=\"warning\" title=\"Rate limit\" closable onClose={() => setShow(false)}>\n  You have 3 requests remaining this minute.\n</Alert>\n\n// Progress \u2014 Horizontal progress bar with determinate and indeterminate modes\ninterface ProgressProps {\n  value: number;  // Current progress value\n  max?: number;  // default 100; Maximum value representing 100% progress\n  variant?: 'default' | 'success' | 'warning' | 'error';  // default 'default'; Fill bar color\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls track height in pixels:\n  label?: string;  // Accessible name describing what this bar measures, e\n  showLabel?: boolean;  // default false; When true, displays a header row above the track with the `label` text\n  indeterminate?: boolean;  // default false; When true, ignores `value` for visual width and plays a looping animation\n}\n\n// Example:\n<Progress value={65} variant=\"success\" size=\"md\" showLabel />\n\n// Image \u2014 An `<img>` element with built-in error handling and fallback support\ninterface ImageProps {\n  src: string;  // Image source URL\n  alt: string;  // Alt text for the image\n  width?: number | string;  // default '100%' (applied at render time, not on the type); Image width\n  height?: number | string;  // default 'auto' (applied at render time, not on the type); Image height\n  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';  // default 'cover'; CSS `object-fit` value controlling how the image fills its box\n  radius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | number | string;  // Corner radius applied to both the image and the error placeholder\n  fallback?: ReactNode;  // Custom ReactNode rendered when the image fails to load\n}\n\n// Example:\n<Image src=\"/hero.jpg\" alt=\"Hero banner\" width=\"100%\" height={400} objectFit=\"cover\" radius=\"md\" />\n\n// Icon \u2014 185 Lucide icons + emoji passthrough\ninterface IconProps {\n  name?: string;  // Lucide icon name (kebab-case, camelCase, or PascalCase all work)\n  size?: number;  // default 24; Icon dimensions in pixels (applied to both width and height of the wrapper\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (icon uses `currentColor`); Semantic color slot\n  children?: ReactNode;  // Custom SVG children\n  'aria-label'?: string;  // Accessible name for a standalone, meaning-bearing icon\n}\n\n// Example:\n<Icon name=\"search\" size={20} tone=\"muted\" />\n<Icon name=\"cloud-rain\" size={32} />\n<Icon name=\"\u2600\uFE0F\" size={24} />\n\n// Link \u2014 Styled anchor element with external link support\ninterface LinkProps {\n  children?: ReactNode;\n  href: string;  // Destination URL\n  external?: boolean;  // default false; When true, opens link in a new tab (`target=\"_blank\"`, `rel=\"noopener norefer...\n  tone?: | 'default' | 'muted' | 'subtle' | 'emphasized' | 'loud' | 'success' | 'warning' | 'error' | 'info' | 'inverse' | 'inherit';  // default undefined (uses `var(--ggui-color-primary-600)`); Semantic color slot for the link text\n  underline?: 'always' | 'hover' | 'none';  // default 'hover'; Underline behavior:\n}\n\n// Example:\n<Link href=\"https://docs.ggui.ai\" external>Documentation</Link>\n\n// Tooltip \u2014 Hoverable information popup positioned relative to a trigger element\ninterface TooltipProps {\n  children: ReactNode;  // Trigger element\n  content: ReactNode;  // Tooltip content\n  position?: 'top' | 'bottom' | 'left' | 'right';  // default 'top'; Tooltip placement relative to the trigger element:\n  delay?: number;  // default 200; Delay in milliseconds before the tooltip becomes visible after hover/focus\n}\n\n// Example:\n<Tooltip content=\"Copy to clipboard\" position=\"top\">\n  <Button variant=\"ghost\"><Icon name=\"copy\" /></Button>\n</Tooltip>\n\n// Table \u2014 Data table with sortable columns, striped rows, and hover highlights\ninterface TableProps {\n  columns: TableColumn<T>[];  // Array of column definitions controlling header labels, data keys, and rendering\n  data: T[];  // Array of row data objects\n  sortKey?: string;  // The `key` of the currently sorted column\n  sortDirection?: SortDirection;  // default 'asc'; Current sort direction for the column identified by `sortKey`\n  onSort?: (key: string, direction: SortDirection) => void;  // Sort change handler\n  striped?: boolean;  // default false; When true, alternating rows (odd index) get a\n  hoverable?: boolean;  // default true; When true, rows highlight with `var(--ggui-color-container)`\n  compact?: boolean;  // default false; When true, reduces cell padding:\n  bordered?: boolean;  // default false; When true, adds a 1px border around the table wrapper and between cells\n  caption?: string;  // Accessible table caption\n}\n\n// Example:\n<Table\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'role', header: 'Role' },\n    { key: 'status', header: 'Status', render: (v) => <Badge variant={v as string}>{v as string}</Badge> },\n  ]}\n  data={users}\n  sortKey={sortKey}\n  sortDirection={sortDir}\n  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}\n  striped\n/>\n\n// Tabs \u2014 Accessible tab navigation with panels and keyboard support\ninterface TabsProps {\n  items: TabItem[];  // Array of tab definitions\n  activeKey?: string;  // Controlled active tab key\n  onChange?: (key: string) => void;  // Tab change handler\n  variant?: 'line' | 'pills' | 'enclosed';  // default 'line'; Visual style of the tab bar:\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls tab button padding and font size:\n  fullWidth?: boolean;  // default false; When true, tab buttons expand equally to fill the container width\n}\n\n// Example:\n<Tabs\n  variant=\"pills\"\n  items={[\n    { key: 'overview', label: 'Overview', content: <Overview /> },\n    { key: 'settings', label: 'Settings', content: <Settings /> },\n  ]}\n  activeKey={tab}\n  onChange={setTab}\n/>\n\n// Toast \u2014 Notification banner with auto-dismiss and slide-in animation\ninterface ToastProps {\n  message: ReactNode;  // Message body content\n  variant?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Visual style\n  title?: string;  // Optional title rendered above the message in semibold\n  duration?: number;  // default 5000; Auto-dismiss delay in milliseconds\n  onClose?: () => void;  // Callback fired on auto-dismiss timeout or when the close button is clicked\n  visible?: boolean;  // default true; Controls rendering\n  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';  // Intended screen position\n}\n\n// Example:\n<Toast variant=\"success\" title=\"Saved\" message=\"Your changes have been saved.\" onClose={() => setShow(false)} />\n\n// Accordion \u2014 Collapsible content sections with chevron rotation animation\ninterface AccordionProps {\n  items: AccordionItem[];  // Array of collapsible section definitions\n  expandedKeys?: string[];  // Controlled expanded state\n  onChange?: (expandedKeys: string[]) => void;  // Expand/collapse handler\n  multiple?: boolean;  // default false; When true, multiple items can be open simultaneously\n  variant?: 'default' | 'bordered' | 'separated';  // default 'default'; Visual style controlling borders and spacing:\n}\n\n// Example:\n<Accordion\n  variant=\"separated\"\n  items={[\n    { key: 'faq1', title: 'How do I get started?', content: 'Sign up and...' },\n    { key: 'faq2', title: 'What is the pricing?', content: 'We offer...' },\n  ]}\n  expandedKeys={expanded}\n  onChange={setExpanded}\n  multiple\n/>\n\n// Row \u2014 Convenience alias for a horizontal Stack\ninterface RowProps {\n  children?: ReactNode;\n  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number | string;  // default 'sm'; Gap between children\n  align?: 'start' | 'center' | 'end' | 'stretch';  // default 'stretch'; Cross-axis alignment (maps to `align-items`)\n  justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';  // default 'start'; Main-axis content distribution (maps to `justify-content`)\n  wrap?: boolean;  // default false; Whether children wrap to the next line when they overflow\n}\n\n// Example:\n<Row gap=\"md\" align=\"center\" justify=\"between\">\n  <Text size=\"sm\" weight=\"medium\">Total</Text>\n  <Text weight=\"bold\">$42.00</Text>\n</Row>\n\n// Support types:\n// ResponsiveColumns \u2014 Explicit column count per viewport breakpoint, mobile-first\ninterface ResponsiveColumns {\n  base?: number;  // default 1; Columns below the `sm` breakpoint\n  sm?: number;  // Columns from 640px up\n  md?: number;  // Columns from 768px up\n  lg?: number;  // Columns from 1024px up\n  xl?: number;  // Columns from 1280px up\n}\n\n// SelectOption \u2014 An individual option within a `Select` dropdown\ninterface SelectOption {\n  value: string;  // The value submitted when this option is selected\n  label: string;  // The display text shown in the dropdown\n  disabled?: boolean;  // default false; When true, the option is visible but cannot be selected (grayed out by the br...\n}\n\n// RadioOption \u2014 An individual option within a `RadioGroup`\ninterface RadioOption {\n  value: string;  // The value emitted via `RadioGroupProps\n  label: string;  // Display text for this option\n  description?: string;  // Optional secondary description rendered below the label in smaller, muted type\n  disabled?: boolean;  // default false; When true, this individual option is grayed out (`opacity: 0\n}\n\n// TableColumn \u2014 Column definition for the Table component\ninterface TableColumn {\n  key: string;  // Property key in the row data object\n  header: string;  // Column header text\n  width?: number | string;  // Fixed column width\n  align?: 'left' | 'center' | 'right';  // default 'left'; Horizontal text alignment for both the header and data cells\n  sortable?: boolean;  // default false; When true, the header cell becomes clickable and shows sort direction\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n}\n\n// TabItem \u2014 Definition of a single tab within a Tabs component\ninterface TabItem {\n  key: string;  // Unique identifier for this tab\n  label: ReactNode;  // Tab button label\n  content: ReactNode;  // Panel content rendered below the tab bar when this tab is active\n  disabled?: boolean;  // default false; When true, the tab button shows `opacity: 0\n  icon?: ReactNode;  // Optional icon rendered before the label inside the tab button, with\n}\n\n// AccordionItem \u2014 Definition of a single collapsible section within an Accordion\ninterface AccordionItem {\n  key: string;  // Unique identifier for this item\n  title: ReactNode;  // Header label rendered inside the toggle button\n  content: ReactNode;  // Panel content rendered below the header when expanded\n  disabled?: boolean;  // default false; When true, the header button shows `opacity: 0\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Components   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// SearchField \u2014 A text input with a leading search icon and optional submit button\ninterface SearchFieldProps {\n  value?: string;  // Current search value\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly, not\n  onSearch?: (value: string) => void;  // Called when the user presses **Enter** or clicks the search button\n  placeholder?: string;  // default 'Search...'; Placeholder text shown when the input is empty\n  showButton?: boolean;  // default false; When `true`, renders a `Button` primitive to the right of the input\n  buttonText?: string;  // default 'Search'; Label rendered inside the submit button\n  loading?: boolean;  // When `true`, replaces the search icon with a `Spinner`, disables the\n  disabled?: boolean;  // When `true`, the input and button are visually disabled and do not\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls input height and font size\n}\n\n// Example:\n```tsx\n<SearchField\n  value={query}\n  onChange={setQuery}\n  onSearch={(q) => fetchResults(q)}\n  placeholder=\"Search products...\"\n  showButton\n  buttonText=\"Go\"\n  size=\"md\"\n/>\n```\n\n// FormField \u2014 A wrapper that adds a label, optional description, error message,\ninterface FormFieldProps {\n  label: string;  // Text rendered inside the `<label>` element above the input\n  children: ReactNode;  // The form control (typically an `Input`, `Select`, or `Textarea` primitive) re...\n  error?: string;  // Error message displayed below `children` in `colors\n  helperText?: string;  // Neutral guidance text displayed below `children` in `colors\n  required?: boolean;  // When `true`, appends a red asterisk (`*`) after the label text\n  description?: string;  // Secondary description rendered between the label and the child control\n}\n\n// Example:\n```tsx\n<FormField\n  label=\"Email address\"\n  required\n  description=\"We will never share your email.\"\n  error={errors.email}\n>\n  <Input value={email} onChange={setEmail} placeholder=\"you@example.com\" />\n</FormField>\n```\n\n// MenuItem \u2014 A full-width clickable row for menus, sidebars, and action lists\ninterface MenuItemProps {\n  label: string;  // Primary text content of the menu item\n  icon?: ReactNode;  // Icon or element rendered to the left of the label\n  rightElement?: ReactNode;  // Element rendered to the right of the label (e\n  onClick?: () => void;  // Called when the item is clicked\n  disabled?: boolean;  // When `true`, the item is non-interactive: `colors\n  active?: boolean;  // Marks this item as the current selection\n  danger?: boolean;  // Switches the item to destructive styling: `colors\n}\n\n// Example:\n```tsx\n<MenuItem\n  label=\"Delete project\"\n  icon={<Icon name=\"trash\" size={16} />}\n  danger\n  onClick={() => confirmDelete(projectId)}\n/>\n```\n\n// Tag \u2014 An inline label for categories, filters, statuses, or selections\ninterface TagProps {\n  children: ReactNode;  // Tag content -- typically a short text string\n  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';  // default 'default'; Semantic color variant applied to background, text, and border\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls padding, font size, and internal gap\n  closable?: boolean;  // When `true`, renders a small close (\"x\") button after the content\n  onClose?: () => void;  // Called when the close button is clicked\n  icon?: ReactNode;  // Icon or element rendered before the text content\n}\n\n// Example:\n```tsx\n<Tag variant=\"success\" size=\"md\" closable onClose={() => removeFilter(id)}>\n  Active\n</Tag>\n```\n\n// Dropdown \u2014 A click-triggered menu anchored to a trigger element\ninterface DropdownProps {\n  trigger: ReactNode;  // The element the user clicks to open the menu\n  options: DropdownOption[];  // Array of selectable options rendered as `MenuItem` rows\n  value?: string;  // The `value` of the currently selected option\n  onChange?: (value: string) => void;  // Called with the `value` string of the selected option (not the full\n  placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';  // default 'bottom-start'; Where to anchor the menu panel relative to the trigger\n  disabled?: boolean;  // When `true`, the trigger shows `cursor: not-allowed` and clicking\n}\n\n// Example:\n```tsx\n<Dropdown\n  trigger={<Button variant=\"outline\">Sort by</Button>}\n  options={[\n    { value: 'name', label: 'Name' },\n    { value: 'date', label: 'Date created' },\n    { value: 'delete', label: 'Delete', danger: true },\n  ]}\n  value={sortBy}\n  onChange={setSortBy}\n  placement=\"bottom-end\"\n/>\n```\n\n// Autocomplete \u2014 A text input with a filterable suggestion dropdown, keyboard navigation,\ninterface AutocompleteProps {\n  value?: string;  // default ''; Current text in the input field\n  onChange?: (value: string) => void;  // Called on every keystroke with the new input string (value directly,\n  onSelect?: (option: AutocompleteOption) => void;  // Called when the user selects an option (click or Enter on highlighted\n  options: AutocompleteOption[];  // The full list of available options\n  placeholder?: string;  // Placeholder text forwarded to the inner `Input` primitive\n  label?: string;  // Label text forwarded to the inner `Input` primitive\n  loading?: boolean;  // When `true`, the dropdown shows a centered `Spinner` instead of\n  disabled?: boolean;  // When `true`, the inner `Input` is disabled and the dropdown\n  error?: string;  // Error message forwarded to the inner `Input` primitive\n  noResultsText?: string;  // default 'No results found'; Text shown in the dropdown when filtering produces zero matches\n}\n\n// Example:\n```tsx\n<Autocomplete\n  label=\"Country\"\n  value={country}\n  onChange={setCountry}\n  onSelect={(opt) => setCountryCode(opt.value)}\n  options={countries}\n  placeholder=\"Type to search...\"\n  noResultsText=\"No countries found\"\n/>\n```\n\n// Breadcrumb \u2014 A horizontal navigation trail showing the user's location within a\ninterface BreadcrumbProps {\n  items: BreadcrumbItem[];  // Ordered array of breadcrumb segments from root to current page\n  separator?: ReactNode;  // default '/'; Separator rendered between each pair of items\n  onItemClick?: (item: BreadcrumbItem, index: number) => void;  // Called when a non-last item is clicked\n}\n\n// Example:\n```tsx\n<Breadcrumb\n  items={[\n    { label: 'Home', href: '/' },\n    { label: 'Projects', href: '/projects' },\n    { label: 'ggui' },\n  ]}\n  separator=\"/\"\n  onItemClick={(item) => router.push(item.href!)}\n/>\n```\n\n// Pagination \u2014 Page navigation controls with previous/next arrows, numbered page buttons,\ninterface PaginationProps {\n  currentPage: number;  // Current active page\n  totalPages: number;  // Total number of pages\n  onPageChange?: (page: number) => void;  // Called when the user clicks a page number, arrow, or first/last button\n  showFirstLast?: boolean;  // default true; When `true`, renders double-chevron buttons for jumping to the first\n  maxVisible?: number;  // default 5; Maximum number of page buttons visible at once (including the first\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls button dimensions and icon sizes\n  disabled?: boolean;  // When `true`, all page buttons and arrows are visually dimmed\n}\n\n// Example:\n```tsx\n<Pagination\n  currentPage={page}\n  totalPages={20}\n  onPageChange={setPage}\n  maxVisible={7}\n  size=\"md\"\n/>\n```\n\n// EmptyState \u2014 placeholder for a region with no data: empty lists,\ninterface EmptyStateProps {\n  icon?: string | ReactNode;  // A Lucide icon name (kebab-case), rendered large and subtle above\n  title: string;  // The headline, e\n  description?: string;  // Optional supporting line below the title\n  action?: ReactNode;  // Optional call-to-action, typically a `<Button>`\n}\n\n// Example:\n{results.length === 0\n  ? <EmptyState icon=\"search-x\" title=\"No matches\" description=\"Try a broader query.\" />\n  : results.map((r) => <Row key={r.id}>\u2026</Row>)}\n\n// Stat \u2014 a single KPI / metric: a label, a large value, an optional\ninterface StatProps {\n  label: string;  // The metric name, e\n  value: string | number;  // The headline value \u2014 the big number\n  delta?: string;  // Optional change indicator, pre-formatted, e\n  trend?: 'up' | 'down' | 'neutral';  // default 'neutral'; Direction of `delta` \u2014 colours it: `'up'` success, `'down'` error,\n  icon?: string | ReactNode;  // Optional Lucide icon name (kebab-case) or custom node, shown next\n}\n\n// Example:\n<Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12.5%\" trend=\"up\" icon=\"trending-up\" />\n\n// Stepper \u2014 a display-only step indicator for multi-step flows\ninterface StepperProps {\n  steps: string[];  // Ordered step labels, one per step\n  current: number;  // Zero-based index of the active step\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Flow direction\n  onStepClick?: (index: number) => void;  // When provided, each step becomes a real button and clicks receive\n}\n\n// Example:\nconst STEPS = ['Account', 'Profile', 'Review'];\n// In the component: const [step, setStep] = useState(0);\n<Stack gap=\"lg\">\n  <Stepper steps={STEPS} current={step} />\n  {step === 0 && <AccountFields />}\n  <Row gap=\"sm\" justify=\"end\">\n    <Button variant=\"ghost\" disabled={step === 0} onClick={() => setStep(step - 1)}>Back</Button>\n    <Button onClick={() => setStep(step + 1)}>Next</Button>\n  </Row>\n</Stack>\n\n// Markdown \u2014 renders markdown-formatted text as styled content:\ninterface MarkdownProps {\n  markdown: string;  // Markdown source text, passed through verbatim\n}\n\n// Example:\n<Stack gap=\"md\">\n  <Markdown markdown={recipe.instructions} />\n</Stack>\n\n// MarkdownInline \u2014 renders ONE line of inline-level markdown (bold,\ninterface MarkdownInlineProps {\n  markdown: string;  // Inline markdown source -- bold, italic, inline code, and\n}\n\n// Example:\n<Row gap=\"sm\">\n  <Badge variant=\"success\">stable</Badge>\n  <MarkdownInline markdown={release.summary} />\n</Row>\n\n// Support types:\n// DropdownOption \u2014 A single option inside a `Dropdown`\ninterface DropdownOption {\n  value: string;  // Unique identifier returned to `onChange` when this option is selected\n  label: string;  // Human-readable text shown in the menu row\n  icon?: ReactNode;  // Optional icon rendered to the left of the label via `MenuItem\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive\n  danger?: boolean;  // When `true`, the option uses destructive (red) styling via\n}\n\n// AutocompleteOption \u2014 A single option in the `Autocomplete` suggestion list\ninterface AutocompleteOption {\n  value: string;  // Unique identifier for this option\n  label: string;  // Primary display text\n  description?: string;  // Secondary description rendered below the label in `fontSize\n  icon?: ReactNode;  // Icon rendered to the left of the label/description block\n  disabled?: boolean;  // When `true`, the option is visible but non-interactive (`cursor: not-allowed`...\n}\n\n// BreadcrumbItem \u2014 A single segment in a `Breadcrumb` trail\ninterface BreadcrumbItem {\n  label: string;  // Display text for this breadcrumb segment\n  href?: string;  // URL for this segment\n  icon?: ReactNode;  // Icon rendered immediately before the label\n}\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// Compositions   (import from '@ggui-ai/design')\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n\n// Header \u2014 Props for the `Header` composition\ninterface HeaderProps {\n  logo?: ReactNode;  // Logo or brand element rendered at the start (flex-shrink: 0)\n  navigation?: ReactNode;  // Navigation content rendered in a `<nav>` element with `flex: 1` and a 32 px l...\n  actions?: ReactNode;  // Right-side action elements (buttons, avatar, etc\n  sticky?: boolean;  // default false; When true, the header becomes `position: sticky` at the top of its scroll con...\n  background?: string;  // default colors.white; Background color of the header\n  bordered?: boolean;  // default true; When true, renders a 1 px bottom border in `colors\n}\n\n// Example:\n```tsx\n<Header\n  logo={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  navigation={<a href=\"/docs\">Docs</a>}\n  actions={<Button size=\"sm\">Sign In</Button>}\n  sticky\n  bordered\n/>\n```\n\n// Sidebar \u2014 Props for the `Sidebar` composition\ninterface SidebarProps {\n  items: SidebarItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: SidebarItem) => void;  // Called when any item (including parent items with children) is clicked\n  collapsed?: boolean;  // default false; When true, hides labels and badges; only icons remain visible, centered in th...\n  header?: ReactNode;  // Content rendered above the item list, separated by a bottom border\n  footer?: ReactNode;  // Content rendered below the item list, separated by a top border\n  width?: number;  // default 256; Width in pixels when expanded\n  collapsedWidth?: number;  // default 64; Width in pixels when collapsed\n}\n\n// Example:\n```tsx\n<Sidebar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'settings', label: 'Settings', icon: <Icon name=\"settings\" />,\n      children: [\n        { id: 'profile', label: 'Profile' },\n        { id: 'billing', label: 'Billing' },\n      ]},\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.href)}\n  collapsed={false}\n  width={256}\n/>\n```\n\n// CardGrid \u2014 Props for the `CardGrid` composition\ninterface CardGridProps {\n  children: ReactNode;  // Card elements to arrange in the grid\n  columns?: number | { sm?: number; md?: number; lg?: number };  // default 3; Number of columns, or a responsive breakpoint map\n  gap?: number;  // default 16; Gap between grid items in pixels\n}\n\n// Example:\n```tsx\n<CardGrid columns={3} gap={24}>\n  <Card>A</Card>\n  <Card>B</Card>\n  <Card>C</Card>\n</CardGrid>\n```\n\n// CommentThread \u2014 Props for the `CommentThread` composition\ninterface CommentThreadProps {\n  comments: Comment[];  // Array of top-level comments to render\n  currentUser?: { /** Display name for the current user's avatar. */ name: string; /** Avatar image URL for the current user. */ avatar?: string; };  // Current user info\n  onAddComment?: (content: string, parentId?: string) => void;  // Called when the user submits a new top-level comment\n  onReply?: (commentId: string, content: string) => void;  // Called when the user submits a reply to an existing comment\n  onReaction?: (commentId: string, emoji: string) => void;  // Called when the user clicks an emoji reaction on a comment\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the comment list\n}\n\n// Example:\n```tsx\n<CommentThread\n  comments={[\n    { id: '1', author: { name: 'Alice' }, content: 'Great work!', timestamp: new Date(),\n      replies: [{ id: '2', author: { name: 'Bob' }, content: 'Thanks!', timestamp: new Date() }] }\n  ]}\n  currentUser={{ name: 'Alice', avatar: '/alice.jpg' }}\n  onAddComment={(content) => post(content)}\n  onReply={(commentId, content) => reply(commentId, content)}\n  onReaction={(commentId, emoji) => react(commentId, emoji)}\n/>\n```\n\n// DataTable \u2014 Props for the `DataTable` composition\ninterface DataTableProps {\n  columns: DataTableColumn<T>[];  // Column definitions that control header, alignment, sorting, and rendering\n  data: T[];  // Row data array\n  rowKey?: string | ((row: T) => string);  // default 'id'; Property name or function used to derive a unique key for each row\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of table body rows\n  emptyText?: string;  // default 'No data'; Text shown when `data` is empty and not loading\n  onSort?: (key: string, direction: 'asc' | 'desc') => void;  // Called when a sortable column header is clicked\n  sortKey?: string;  // The column key currently being sorted\n  sortDirection?: 'asc' | 'desc';  // The current sort direction\n  onRowClick?: (row: T, index: number) => void;  // Called when a row is clicked\n  selectable?: boolean;  // When true, adds a checkbox column at the start of each row\n  selectedKeys?: string[];  // default []; Array of currently selected row keys\n  onSelectionChange?: (keys: string[]) => void;  // Called when the set of selected row keys changes (via row checkbox or select-...\n}\n\n// Example:\n```tsx\n<DataTable\n  columns={[\n    { key: 'name', header: 'Name', sortable: true },\n    { key: 'email', header: 'Email' },\n    { key: 'role', header: 'Role', render: (v) => <Badge>{v}</Badge> },\n  ]}\n  data={users}\n  rowKey=\"id\"\n  selectable\n  selectedKeys={selected}\n  onSelectionChange={setSelected}\n  onSort={(key, dir) => sort(key, dir)}\n  sortKey=\"name\"\n  sortDirection=\"asc\"\n/>\n```\n\n// ChatWindow \u2014 Props for the `ChatWindow` composition\ninterface ChatWindowProps {\n  messages: ChatMessage[];  // Array of chat messages to display in chronological order\n  currentUserId: string;  // ID of the current user\n  onSendMessage?: (content: string) => void;  // Called when the user submits a message (Enter key or send button)\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the message list\n  typing?: { name: string } | null;  // When non-null, displays a typing indicator below the last message (e\n  placeholder?: string;  // default 'Type a message...'; Placeholder text for the message input field\n  header?: ReactNode;  // Optional header content rendered above the message area, separated by a botto...\n}\n\n// Example:\n```tsx\n<ChatWindow\n  messages={messages}\n  currentUserId=\"user-1\"\n  onSendMessage={(content) => send(content)}\n  typing={{ name: 'Alice' }}\n  placeholder=\"Type a message...\"\n  header={<h3>Chat with Alice</h3>}\n/>\n```\n\n// NavigationBar \u2014 Props for the `NavigationBar` composition\ninterface NavigationBarProps {\n  items: NavItem[];  // Array of navigation items to render\n  activeId?: string;  // ID of the currently active item\n  onItemClick?: (item: NavItem) => void;  // Called when a non-disabled item is clicked\n  orientation?: 'horizontal' | 'vertical';  // default 'horizontal'; Layout direction\n  variant?: 'default' | 'pills' | 'underline';  // default 'default'; Visual style for active/inactive items\n}\n\n// Example:\n```tsx\n<NavigationBar\n  items={[\n    { id: 'home', label: 'Home', icon: <Icon name=\"home\" /> },\n    { id: 'about', label: 'About' },\n    { id: 'contact', label: 'Contact' },\n  ]}\n  activeId=\"home\"\n  onItemClick={(item) => navigate(item.id)}\n  orientation=\"horizontal\"\n  variant=\"pills\"\n/>\n```\n\n// FileUploader \u2014 Props for the `FileUploader` composition\ninterface FileUploaderProps {\n  files?: UploadedFile[];  // default []; Array of files currently in the upload queue, shown below the drop zone\n  onFilesSelected?: (files: File[]) => void;  // Called when the user selects files via click or drag-and-drop\n  onFileRemove?: (fileId: string) => void;  // Called when the user clicks the remove button on a file entry\n  accept?: string;  // Accepted file types passed to the hidden `<input type=\"file\" accept=\"\n  multiple?: boolean;  // default true; When true, allows selecting multiple files at once\n  maxSize?: number;  // Maximum file size in bytes\n  maxFiles?: number;  // Maximum number of files\n  disabled?: boolean;  // When true, the drop zone is visually dimmed (opacity 0\n  dragDrop?: boolean;  // default true; When true, enables drag-and-drop on the drop zone\n}\n\n// Example:\n```tsx\n<FileUploader\n  files={uploadedFiles}\n  onFilesSelected={(files) => startUpload(files)}\n  onFileRemove={(id) => removeFile(id)}\n  accept=\"image/*,.pdf\"\n  multiple\n  maxSize={5 * 1024 * 1024}\n  maxFiles={10}\n  dragDrop\n/>\n```\n\n// NotificationCenter \u2014 Props for the `NotificationCenter` composition\ninterface NotificationCenterProps {\n  notifications: Notification[];  // Array of notifications to display, in the order provided\n  onMarkAsRead?: (id: string) => void;  // Called when the user clicks \"Mark as read\" on an individual notification\n  onMarkAllAsRead?: () => void;  // Called when the user clicks the \"Mark all read\" header button\n  onDismiss?: (id: string) => void;  // Called when the user clicks the dismiss (X) button on an individual notification\n  onClearAll?: () => void;  // Called when the user clicks the \"Clear all\" header button\n  emptyText?: string;  // default 'No notifications'; Text shown when `notifications` is empty and not loading\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the notification list\n}\n\n// Example:\n```tsx\n<NotificationCenter\n  notifications={[\n    { id: '1', title: 'Deployment complete', type: 'success', timestamp: new Date(), read: false },\n    { id: '2', title: 'Build failed', type: 'error', message: 'Lint errors', timestamp: new Date() },\n  ]}\n  onMarkAsRead={(id) => markRead(id)}\n  onMarkAllAsRead={() => markAllRead()}\n  onDismiss={(id) => dismiss(id)}\n  onClearAll={() => clearAll()}\n/>\n```\n\n// Modal \u2014 Props for the `Modal` composition\ninterface ModalProps {\n  open: boolean;  // Controls modal visibility\n  onClose: () => void;  // Called to close the modal (overlay click, escape key, or close button)\n  title?: string;  // Optional title rendered in the modal header via the `Heading` primitive (leve...\n  children: ReactNode;  // Modal body content rendered in a scrollable area (`overflowY: auto`)\n  footer?: ReactNode;  // Footer content rendered below the body, right-aligned with an 8 px gap, separ...\n  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';  // default 'md'; Controls the width of the modal panel\n  closeOnOverlayClick?: boolean;  // default true; When true, clicking the semi-transparent overlay behind the modal calls `onCl...\n  closeOnEscape?: boolean;  // default true; When true, pressing the Escape key calls `onClose`\n  showCloseButton?: boolean;  // default true; When true, renders a ghost close button (X icon) in the modal header\n}\n\n// Example:\n```tsx\n<Modal\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  title=\"Confirm Action\"\n  size=\"md\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleConfirm}>Confirm</Button>\n    </>\n  }\n>\n  <p>Are you sure you want to proceed?</p>\n</Modal>\n```\n\n// CommandPalette \u2014 Props for the `CommandPalette` composition\ninterface CommandPaletteProps {\n  open: boolean;  // Controls palette visibility\n  onClose: () => void;  // Called to close the palette (overlay click, Escape key, or after command sele...\n  commands: Command[];  // Full array of available commands\n  onSelect: (command: Command) => void;  // Called when a non-disabled command is selected (Enter key or click)\n  placeholder?: string;  // default 'Search commands...'; Placeholder text for the search input\n  recentIds?: string[];  // default []; IDs of recently used commands\n  loading?: boolean;  // When true, shows a centered `Spinner` instead of the command list\n}\n\n// Example:\n```tsx\n<CommandPalette\n  open={isOpen}\n  onClose={() => setOpen(false)}\n  commands={[\n    { id: 'new', label: 'New File', shortcut: 'Ctrl+N', group: 'File' },\n    { id: 'save', label: 'Save', shortcut: 'Ctrl+S', group: 'File' },\n    { id: 'theme', label: 'Toggle Theme', group: 'Preferences' },\n  ]}\n  onSelect={(cmd) => executeCommand(cmd.id)}\n  recentIds={['save']}\n  placeholder=\"Search commands...\"\n/>\n```\n\n// Footer \u2014 Props for the `Footer` composition\ninterface FooterProps {\n  brand?: ReactNode;  // Brand element (logo, tagline) rendered in a flexible column (`flex: 1 1 280px`)\n  columns?: FooterColumn[];  // Array of link columns rendered in a flex-wrap layout with 48 px gap\n  socialLinks?: FooterSocialLink[];  // Social media icon links rendered in the bottom bar\n  bottomText?: string;  // Text displayed at the start of the bottom bar (e\n  bottomLinks?: FooterLink[];  // Links displayed in the bottom bar after social icons (e\n  background?: string;  // default colors.gray[50]; Background color of the footer\n  bordered?: boolean;  // default true; When true, renders a 1 px top border in `colors\n}\n\n// Example:\n```tsx\n<Footer\n  brand={<img src=\"/logo.svg\" alt=\"Acme\" />}\n  columns={[\n    { title: 'Product', links: [{ label: 'Features', href: '/features' }] },\n    { title: 'Company', links: [{ label: 'About', href: '/about' }] },\n  ]}\n  socialLinks={[\n    { label: 'Twitter', href: 'https://twitter.com/acme', icon: <TwitterIcon /> },\n  ]}\n  bottomText=\"&copy; 2026 Acme Inc.\"\n  bottomLinks={[{ label: 'Privacy', href: '/privacy' }]}\n  bordered\n/>\n```\n\n// Hero \u2014 Props for the `Hero` composition\ninterface HeroProps {\n  heading?: string;  // Main heading text rendered as an `<h1>` with bold weight and tight line-height\n  description?: string;  // Description paragraph rendered below the heading with relaxed line-height\n  primaryAction?: HeroAction;  // Primary CTA button rendered with `colors\n  secondaryAction?: HeroAction;  // Secondary CTA button rendered with a transparent background and a 1 px border\n  media?: ReactNode;  // Media element (image, video, illustration) rendered beside or below the text ...\n  align?: 'center' | 'left';  // default 'center'; Text and layout alignment\n  size?: 'sm' | 'md' | 'lg';  // default 'md'; Controls vertical padding and heading/description font sizes\n  background?: string;  // default colors.white (when no backgroundImage is set); Background color of the hero section\n  backgroundImage?: string;  // Background image URL applied as `background-size: cover; background-position:...\n  overlay?: boolean;  // default false; When true and `backgroundImage` is set, renders a semi-transparent black overlay\n}\n\n// Example:\n```tsx\n<Hero\n  heading=\"Build Better UIs, Faster\"\n  description=\"The universal interface layer between AI agents and humans.\"\n  primaryAction={{ label: 'Get Started', onClick: () => navigate('/signup') }}\n  secondaryAction={{ label: 'Learn More', href: '/docs' }}\n  media={<img src=\"/hero.png\" alt=\"Hero\" />}\n  align=\"left\"\n  size=\"lg\"\n/>\n```\n\n// Support types:\n// SidebarItem \u2014 A single navigation entry in a `Sidebar`\ninterface SidebarItem {\n  id: string;  // Unique identifier used for active-state matching and React keys\n  label: string;  // Display label for the item\n  icon?: ReactNode;  // Leading icon rendered before the label\n  href?: string;  // Optional URL associated with this item (not rendered as a link by default)\n  badge?: ReactNode;  // Trailing badge element (e\n  children?: SidebarItem[];  // Nested child items\n  disabled?: boolean;  // When true, the item is visually dimmed and non-interactive (`cursor: not-allo...\n}\n\n// Comment \u2014 A single comment entry in a `CommentThread`\ninterface Comment {\n  id: string;  // Unique identifier for this comment\n  author: { /** Display name of the author. */ name: string; /** URL for the author's avatar image. Passed to the `Avatar` primitive. */ avatar?: string; };  // Comment author metadata\n  content: string;  // The comment body text\n  timestamp: string | Date;  // Timestamp of the comment\n  replies?: Comment[];  // Nested reply comments\n  reactions?: { emoji: string; count: number }[];  // Emoji reactions with their aggregated counts (e\n}\n\n// DataTableColumn \u2014 Column definition for a `DataTable`\ninterface DataTableColumn {\n  key: string;  // Property key on the row object used to extract cell values\n  header: string;  // Column header text displayed in the `<thead>`\n  width?: number | string;  // Column width as a CSS value (number for pixels, string for any CSS unit)\n  sortable?: boolean;  // When true, the column header is clickable and triggers `onSort`\n  render?: (value: unknown, row: T, index: number) => ReactNode;  // Custom cell renderer\n  align?: 'left' | 'center' | 'right';  // default 'left'; Text alignment for both header and body cells\n}\n\n// ChatMessage \u2014 A single message in a `ChatWindow`\ninterface ChatMessage {\n  id: string;  // Unique identifier for this message\n  content: string;  // The message body text\n  sender: { /** Unique ID of the sender. Compared to `currentUserId` to determine alignment. */ id: string; /** Display name of the sender. */ name: string; /** Avatar image URL. Only shown for non-current-user messages (xs size). */ avatar?: string; };  // Sender metadata used for avatar rendering and alignment\n  timestamp: string | Date;  // Message timestamp\n  status?: 'sending' | 'sent' | 'delivered' | 'read' | 'error';  // Delivery status indicator shown on the current user's messages\n}\n\n// NavItem \u2014 A single navigation entry in a `NavigationBar`\ninterface NavItem {\n  id: string;  // Unique identifier used for active-state matching and React keys\n  label: string;  // Display label for the navigation link\n  href?: string;  // URL for the item\n  icon?: ReactNode;  // Optional icon rendered before the label\n  children?: NavItem[];  // Nested child items (for sub-menu structures; rendering is consumer-defined)\n  disabled?: boolean;  // When true, the item is visually dimmed (opacity 0\n}\n\n// UploadedFile \u2014 A file entry in the `FileUploader` composition\ninterface UploadedFile {\n  id: string;  // Unique identifier for this file entry\n  name: string;  // Original file name\n  size: number;  // File size in bytes\n  type: string;  // MIME type of the file (e\n  progress?: number;  // Upload progress as a percentage (0-100)\n  status: 'pending' | 'uploading' | 'success' | 'error';  // Current upload lifecycle status\n  error?: string;  // Error message displayed when status is `'error'`\n  url?: string;  // The remote URL of the uploaded file after successful upload\n}\n\n// Notification \u2014 A single notification entry in the `NotificationCenter`\ninterface Notification {\n  id: string;  // Unique identifier for this notification\n  title: string;  // Notification title rendered in medium weight\n  message?: string;  // Optional body text rendered below the title in a smaller font\n  timestamp: string | Date;  // Timestamp of the notification\n  read?: boolean;  // default false; Read state\n  type?: 'info' | 'success' | 'warning' | 'error';  // default 'info'; Semantic type that controls the status dot color on unread notifications\n  icon?: ReactNode;  // Optional icon rendered alongside the notification (not used by the default im...\n  action?: { /** Button label text. */ label: string; /** Click handler for the action. */ onClick: () => void; };  // Optional inline action button rendered next to the timestamp\n}\n\n// Command \u2014 A single command entry in a `CommandPalette`\ninterface Command {\n  id: string;  // Unique identifier for this command\n  label: string;  // Display label for the command\n  description?: string;  // Optional description text shown below the label\n  icon?: ReactNode;  // Icon rendered at the start of the command row\n  shortcut?: string;  // Keyboard shortcut hint displayed at the end of the row in a `<kbd>` element\n  group?: string;  // Group name for visual sectioning\n  disabled?: boolean;  // When true, the command is visually dimmed and cannot be selected\n}\n\n// FooterLink \u2014 A single link entry in a footer column or the bottom bar\ninterface FooterLink {\n  label: string;  // Display text for the link\n  href?: string;  // URL for the link\n  onClick?: () => void;  // Click handler\n}\n\n// FooterColumn \u2014 A named column of links in the `Footer` layout\ninterface FooterColumn {\n  title?: string;  // Column heading rendered as an `<h4>` with semibold weight\n  links: FooterLink[];  // Links displayed in this column\n}\n\n// FooterSocialLink \u2014 A social media link in the `Footer` bottom bar\ninterface FooterSocialLink {\n  label: string;  // Accessible label for the social link (used as `aria-label`)\n  href: string;  // URL for the social media profile or page\n  icon: ReactNode;  // Icon element rendered inside the anchor (typically an SVG or `Icon` primitive)\n}\n\n// HeroAction \u2014 A call-to-action button definition for the `Hero` composition\ninterface HeroAction {\n  label: string;  // Button label text\n  onClick?: () => void;  // Click handler for the button\n  href?: string;  // Optional URL (not used by the default implementation; available for consumer ...\n}\n\n\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n// System Conventions\n// \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\n//\n// Motion: render <MotionKeyframes /> once to enable keyframes.\n//   Entrance/exit: fadeIn, fadeOut, slideInUp, slideInDown, scaleIn, scaleOut\n//   State feedback: flash, pulse, bounce\n//   Easing: linear, easeIn, easeOut, easeInOut, spring\n//   Durations: instant(0ms), fast(100ms), normal(200ms), slow(300ms), slower(500ms)\n//\n// Elevation levels (shadow \u2192 z-index):\n//   0: flat          1: sm (cards)     2: md z=1000 (dropdowns, popovers)\n//   3: lg z=1200     4: xl z=1400      5: 2xl z=1800 (tooltips, toasts)\n//\n// useAnimationKey(dep) returns a key that bumps when dep changes \u2014\n// apply to <div key={...}> to replay CSS animations on data update.\n//\n// useMotion() returns { motionEnabled } \u2014 respect prefers-reduced-motion.\n";
   }
 });
 
@@ -10594,20 +10874,24 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 
 | Token | CSS Variable | Default | Role |
 |-------|-------------|---------|------|
-| surface | var(--ggui-color-surface) | Main content background |
-| onSurface | var(--ggui-color-onSurface) | Primary text on surface |
-| surfaceVariant | var(--ggui-color-surfaceVariant) | Card/panel background |
-| onSurfaceVariant | var(--ggui-color-onSurfaceVariant) | Muted/secondary text |
+| ground | var(--ggui-color-ground) | The page / canvas behind everything |
+| onGround | var(--ggui-color-onGround) | Text on the canvas |
+| container | var(--ggui-color-container) | A card, a bubble, a panel \u2014 the unit of content |
+| onContainer | var(--ggui-color-onContainer) | Body text on a card |
+| elevated | var(--ggui-color-elevated) | Menus, popovers, modals, toasts \u2014 floats above a card |
+| onElevated | var(--ggui-color-onElevated) | Text on an elevated surface |
+| sunken | var(--ggui-color-sunken) | Wells, inputs at rest, code blocks \u2014 recessed inside a card |
+| onSunken | var(--ggui-color-onSunken) | Muted / secondary text |
 | container | var(--ggui-color-container) | Primary-branded containers |
 | onContainer | var(--ggui-color-onContainer) | Text on branded containers |
 | outline | var(--ggui-color-outline) | Borders, dividers |
 | outlineVariant | var(--ggui-color-outlineVariant) | Subtle borders |
 
 **Usage pattern:**
-- Page/section background \u2192 \`var(--ggui-color-surface)\`
-- Body text \u2192 \`var(--ggui-color-onSurface)\`
-- Card/panel background \u2192 \`var(--ggui-color-surfaceVariant)\`
-- Secondary/muted text \u2192 \`var(--ggui-color-onSurfaceVariant)\`
+- Page/section background \u2192 \`var(--ggui-color-ground)\`
+- Body text \u2192 \`var(--ggui-color-onContainer)\`
+- Card/panel background \u2192 \`var(--ggui-color-container)\`; recessed wells / inputs \u2192 \`var(--ggui-color-sunken)\`
+- Secondary/muted text \u2192 \`var(--ggui-color-onSunken)\`
 - Branded section/header \u2192 \`var(--ggui-color-container)\` bg + \`var(--ggui-color-onContainer)\` text
 - Borders/dividers \u2192 \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 
@@ -10624,11 +10908,11 @@ Prefer the primitives' \`tone="success|warning|error|info"\` prop over hand-writ
 - **NEVER** use rgba(), hsl(), or other CSS color functions with hardcoded values.
 - **NEVER** use raw neutral-* or gray-* scale tokens (neutral-50, neutral-900, etc.) \u2014 these are internal to the theme and break in dark mode.
 - **ALWAYS** use semantic tokens for text and backgrounds:
-  - Text: \`var(--ggui-color-onSurface)\` or \`var(--ggui-color-onSurfaceVariant)\`
-  - Backgrounds: \`var(--ggui-color-surface)\` or \`var(--ggui-color-surfaceVariant)\`
+  - Text: \`var(--ggui-color-onContainer)\` or \`var(--ggui-color-onSunken)\`
+  - Backgrounds: \`var(--ggui-color-container)\` or \`var(--ggui-color-sunken)\`
   - Borders: \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 - For branded elements use \`var(--ggui-color-primary-*)\` scale tokens \u2014 these ARE safe because primary adapts per theme.
-- For card backgrounds use \`var(--ggui-color-surfaceVariant)\` or \`var(--ggui-color-primary-50)\`
+- For card backgrounds use \`var(--ggui-color-container)\` or \`var(--ggui-color-primary-50)\`
 
 ## Spacing
 
@@ -10723,7 +11007,7 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 \`\`\`
 
 ### Color usage guide
-- **Semantic roles** (surface, onSurface, container, outline): Use for all surface/text/border decisions \u2014 these adapt to any theme
+- **Layering roles** (ground, container, elevated, sunken + their on* inks; outline): one kind of AREA each \u2014 use them for every background/text/border decision; they adapt to any theme
 - **primary-50/100**: Section backgrounds, highlight strips, card headers
 - **primary-200/300**: Borders, dividers, focus rings, input outlines
 - **primary-500/600**: Icons, links, labels, badges, buttons, CTAs
@@ -10732,7 +11016,7 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 
 The primary palette is the app's brand \u2014 use it throughout (headers, accents, borders, interactive elements), not just on the submit button.
 
-**Note:** Do NOT add fallback values to var() (e.g., var(--ggui-color-surface, #fafafa)). Just use var(--ggui-color-surface) \u2014 the theme provides all values.
+**Note:** Do NOT add fallback values to var() (e.g., var(--ggui-color-container, #fafafa)). Just use var(--ggui-color-container) \u2014 the theme provides all values.
 
 ## Motion & Animation
 
@@ -11361,7 +11645,7 @@ async function runSelfChecks(code, contract) {
         check: "hex-color",
         line: lineNum,
         message: `Hardcoded color "${hexMatch[0]}" \u2014 must use design tokens`,
-        fix: `Replace with var(--ggui-color-*, ${hexMatch[0]})`
+        fix: `Replace "${hexMatch[0]}" with a primitive variant OR a bare token reference such as var(--ggui-color-primary-500) \u2014 never a literal fallback inside var()`
       });
     }
     const colorFnMatch = line.match(/\b(rgba?|hsla?)\s*\(/);
@@ -11370,7 +11654,7 @@ async function runSelfChecks(code, contract) {
         check: "hardcoded-color-fn",
         line: lineNum,
         message: `Hardcoded ${colorFnMatch[1]}() \u2014 use design tokens instead`,
-        fix: `Replace with semantic tokens: var(--ggui-color-surface), var(--ggui-color-onSurface), var(--ggui-color-outline), etc.`
+        fix: `Replace with the layering roles: var(--ggui-color-container), var(--ggui-color-onContainer), var(--ggui-color-outline), etc.`
       });
     }
     if (/--ggui-color-neutral-50[^0-9]/.test(line) && /background/i.test(line)) {
@@ -11378,7 +11662,7 @@ async function runSelfChecks(code, contract) {
         check: "prefer-semantic",
         line: lineNum,
         message: `neutral-50 for background \u2014 prefer semantic token for dark-theme compatibility`,
-        fix: `Replace with var(--ggui-color-surface) or var(--ggui-color-surfaceVariant)`
+        fix: `Replace with var(--ggui-color-container) or var(--ggui-color-sunken)`
       });
     }
     if (/--ggui-color-neutral-900[^0-9]/.test(line) && /color/i.test(line) && !/background/i.test(line)) {
@@ -11386,7 +11670,7 @@ async function runSelfChecks(code, contract) {
         check: "prefer-semantic",
         line: lineNum,
         message: `neutral-900 for text color \u2014 prefer semantic token for dark-theme compatibility`,
-        fix: `Replace with var(--ggui-color-onSurface) or var(--ggui-color-onSurfaceVariant)`
+        fix: `Replace with var(--ggui-color-onContainer) or var(--ggui-color-onSunken)`
       });
     }
     const pxMatch = line.match(/(?:padding|margin|gap|borderRadius)\s*:\s*['"]?\d+px/);
@@ -11395,7 +11679,7 @@ async function runSelfChecks(code, contract) {
         check: "raw-pixels",
         line: lineNum,
         message: `Raw pixel value in spacing \u2014 must use design tokens`,
-        fix: `Replace with var(--ggui-spacing-*, fallback)`
+        fix: `Replace with a bare var(--ggui-spacing-*) token \u2014 no literal fallback \u2014 or the scale name on the primitive prop (gap="md", padding="lg")`
       });
     }
     if (/\beval\s*\(/.test(line)) {
@@ -12143,7 +12427,8 @@ async function runCheck(input) {
     compiledCode,
     contract,
     originalPrompt: prompt,
-    classification: harness.classification
+    classification: harness.classification,
+    designMode: harness.designMode
   };
   let axisIssueCount = 0;
   const seenAxisIds = /* @__PURE__ */ new Set();
@@ -12694,6 +12979,9 @@ function compose(classification) {
     fragments: matched
   };
 }
+
+// src/boilerplate/render.ts
+init_design_mode();
 var __dirname$1 = dirname(fileURLToPath(import.meta.url));
 var TEMPLATE_DIRS = [
   resolve(__dirname$1, "templates"),
@@ -12702,19 +12990,31 @@ var TEMPLATE_DIRS = [
   resolve(__dirname$1, "..", "..", "..", "src", "boilerplate", "templates"),
   resolve(__dirname$1, "..", "..", "..", "..", "src", "boilerplate", "templates")
 ];
-var baseCache = null;
+var BASE_TEMPLATE_FILE = {
+  constrained: "base.tsx.tmpl",
+  free: "base-free.tsx.tmpl"
+};
+var FREE_LAYOUT = [
+  "    <div style={{ width: '100%' }}>",
+  "      {/* implement your UI here */}",
+  "    </div>"
+].join("\n");
+var baseCache = /* @__PURE__ */ new Map();
 var layoutCache = /* @__PURE__ */ new Map();
-function loadBase() {
-  if (baseCache) return baseCache;
+function loadBase(designMode) {
+  const cached = baseCache.get(designMode);
+  if (cached !== void 0) return cached;
+  const file = BASE_TEMPLATE_FILE[designMode];
   for (const dir of TEMPLATE_DIRS) {
     try {
-      baseCache = readFileSync(resolve(dir, "base.tsx.tmpl"), "utf-8");
-      return baseCache;
+      const content = readFileSync(resolve(dir, file), "utf-8");
+      baseCache.set(designMode, content);
+      return content;
     } catch {
       continue;
     }
   }
-  throw new Error("No base.tsx.tmpl found");
+  throw new Error(`No ${file} found`);
 }
 function loadLayout(shellType, screen) {
   const key = `${shellType}-${screen}`;
@@ -12738,9 +13038,9 @@ function loadLayout(shellType, screen) {
   }
   throw new Error(`No layout found for ${key}`);
 }
-function renderBoilerplate(shellType, screen, markers) {
-  let template = loadBase();
-  const layout = loadLayout(shellType, screen);
+function renderBoilerplate(shellType, screen, markers, designMode = DEFAULT_DESIGN_MODE) {
+  let template = loadBase(designMode);
+  const layout = designMode === "free" ? FREE_LAYOUT : loadLayout(shellType, screen);
   template = template.replace("{{LAYOUT}}", layout);
   for (const [key, value] of Object.entries(markers)) {
     template = template.replaceAll(`{{${key}}}`, value);
@@ -12750,6 +13050,7 @@ function renderBoilerplate(shellType, screen, markers) {
 
 // src/boilerplate/generate.ts
 init_json_schema_ts();
+init_design_mode();
 var ALL_PRIMITIVES = [
   "Container",
   "Card",
@@ -12848,7 +13149,7 @@ function inferTypeFromExample(example) {
   }
   return `{ ${fields.join("; ")} }`;
 }
-function generateBoilerplate(_userPrompt, contract, shellType, screen, composedSections, appGadgets) {
+function generateBoilerplate(_userPrompt, contract, shellType, screen, composedSections, appGadgets, designMode = DEFAULT_DESIGN_MODE) {
   const propsFields = [];
   const propsProperties = contract?.propsSpec?.properties ?? {};
   for (const [key, entry] of Object.entries(propsProperties)) {
@@ -13030,7 +13331,7 @@ ${body}
     CONTEXT_HOOKS: contextHooks,
     WIRE_HOOKS: hookBody,
     AXIS_SECTIONS: composedSections ?? ""
-  });
+  }, designMode);
 }
 
 // src/boilerplate.ts
@@ -13038,6 +13339,431 @@ init_json_schema_ts();
 
 // src/boilerplate/system-prompt.ts
 init_types_public();
+init_design_mode();
+
+// src/boilerplate/free-design-prompt.ts
+init_design_mode();
+
+// src/boilerplate/hard-sections.ts
+var PROTOCOL_NOTES = `## Protocol Notes
+The boilerplate pre-declares every wire hook the contract requires (\`useAction\`, \`useStream\`, \`useGguiContext\`, plus capability hooks from \`@ggui-ai/gadgets\` when the contract declares \`clientCapabilities\`). Three rules:
+1. **Do NOT delete any pre-declared hook.** \`self_check\` fails with \`wire_preservation:<kind>:<name>\` if you remove one.
+2. **Consume every hook binding** somewhere in the component \u2014 in JSX, a callback, or an effect. Unused bindings fail lint with \`no-unused-vars\`.
+3. **Do NOT invent new wire calls.** Every \`useAction('X')\`, \`useStream('X')\`, \`useGguiContext('X')\` etc. MUST correspond to a declared entry on the contract. Calling one that isn't declared fails \`self_check\` with \`wire_undeclared:<kind>:<name>\` because the runtime has no Context/registration for it and would throw at first paint. If you need a new wire surface, that's a contract authoring step the agent owns \u2014 your job is to honor what's declared.
+
+Renaming a binding is fine \u2014 the wiring is the string-literal argument, not the identifier.`;
+var CONTRACT_SURFACE = `## Contract surface \u2014 four specs + two catalogs
+
+A \`DataContract\` declares everything a GguiSession exchanges with the outside world. **Four typed specs** for the four data-flow directions, **two reference catalogs** for tool / hook lookups:
+
+| Surface              | Direction                  | Role                                                                 |
+| -------------------- | -------------------------- | -------------------------------------------------------------------- |
+| \`propsSpec\`         | server \u2192 UI (one-shot)     | Initial render values delivered once at \`ggui_render\`              |
+| \`streamSpec\`        | agent \u2192 UI (many)          | Typed channels for live updates via \`ggui_emit\`                    |
+| \`actionSpec\`        | UI \u2192 agent (events)        | Discrete events driving the agent's next turn (consumed via \`ggui_consume\`) |
+| \`contextSpec\`       | UI \u2192 server (state mirror) | UI state the agent observes between turns                            |
+| \`agentCapabilities.tools\`     | catalog                    | Tools the contract references via \`actionSpec[*].nextStep\` and \`streamSpec[*].source.tool\` |
+| \`clientCapabilities.gadgets\` | catalog                    | Browser-capability gadget hooks the component code mounts (e.g., \`useGeolocation\`) |
+
+**Placement rule for inbound specs**: actions drive turns; context observes state. There is no third category.
+
+**Data vs behavior**: the contract describes data flow; the component code describes behavior. Scroll, focus, toast, animation, clipboard write \u2014 all component code, never contract fields.`;
+var DEFENSIVE_CODING = `## Defensive coding for absent / late-arriving data
+
+Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
+
+- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY \u2014 the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
+- **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
+- **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
+- **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
+- **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives \u2014 guard before reading \`.foo\`.
+- **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed \u2014 your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list \u2014 and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
+- **Props re-sync on repaint**: props the agent owns are the source of truth for display \u2014 prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change \u2014 \`useEffect(() => setCount(props.count ?? 0), [props.count])\` \u2014 or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
+- **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders \u2014 never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
+- **Empty state**: when a list or results array is empty, render \`<EmptyState title="\u2026" description="\u2026" />\` \u2014 a region that renders nothing when empty looks broken to the user.
+
+Unhandled \`Cannot read properties of undefined\` errors trip the iframe error boundary and the user sees "Something went wrong" \u2014 a regression class the runtime can't recover from.`;
+var GESTURE_ROUTING = `## Picking the right primitive for user gestures
+
+Choose by what the user is DOING, not where the result goes \u2014 the runtime handles the routing.
+
+| Gesture intent | LLM writes | Notes |
+| -------------- | ---------- | ----- |
+| Fire a server-side action | \`useAction(name)\` + call \`dispatch(name, payload)\` | Every action is agent-routed. The runtime emits an event on \`ggui_consume\`; the agent reacts on its next turn. If the contract entry declares \`nextStep: 'X'\`, that names the tool the agent SHOULD call next \u2014 advisory hint forwarded as event metadata. |
+| Surface state to the agent's context | the auto-generated \`setSlotName\` setter (from the boilerplate's \`useGguiContext\` line) | The runtime owns useState + Provider; the boilerplate emits one \`const [slot, setSlot] = useGguiContext<T>('slot')\` line per declared \`contextSpec\` slot. Write plain JSX, no \`useState\`, no Provider wrap. Every value change auto-flows to the host LLM (debounced). One-way client \u2192 agent \u2014 see "Observable state via \`contextSpec\`" below. |
+| Use a browser capability (camera, mic, geolocation, clipboard, file picker, notifications) | call the hook the contract declared, e.g., \`const loc = useGeolocation();\` and \`await loc.start()\` | The contract's \`clientCapabilities.gadgets\` declares which gadget exports the UI uses. The hook implementations live in \`@ggui-ai/gadgets\` (or a third-party package named in the \`Package\` column). Read \`status\` ("idle" / "prompting" / "active" / "completed" / "denied" / "error") to gate UI, and thread the resolved \`value\` into a contextSpec slot or actionSpec payload if the agent needs to see it. |
+| Open external link | Plain \`<a href="https://...">\` (or \`target="_blank"\`) | External cross-origin clicks are intercepted and routed through the host (security warnings, app-internal navigation, audit). Same-origin links and \`#fragment\` jumps stay native. |
+| Toggle fullscreen / chrome | Plain \`el.requestFullscreen()\` / \`document.exitFullscreen()\` | The native browser API is intercepted; the host adjusts iframe chrome accordingly. Returns a resolved promise so \`.then()\` / \`await\` chains don't break. |
+
+Every gesture fires a uniform server-side audit envelope (\`ggui_runtime_submit_action\`) so operators see all three patterns in RenderInspector with the same shape.
+
+**Don't import wire hooks for link / display-mode.** \`useAction\` is the only wire hook for user gestures; links and fullscreen use plain HTML / browser APIs.
+
+**All actions are agent-routed.** Every action emits an event the agent reacts to on its next turn via \`ggui_consume\`. The optional \`nextStep: '<tool>'\` field on an \`actionSpec\` entry is a HINT naming the tool the agent SHOULD call next \u2014 the contract author's recommendation, NOT a binding directive. The agent decides whether to honor it. If you want to declare a tool catalog entry the contract references, add it to \`agentCapabilities.tools[<name>]\` with input/output schemas; the cross-ref linter rejects dangling \`nextStep\` values that don't resolve to a declared catalog entry.`;
+var INTERACTIVE_TRAITS = `## Making a primitive interactive \u2014 \`as={Trait}\`
+
+Structural primitives (\`Box\`, \`Stack\`, \`Row\`, \`Card\`) have NO \`onClick\` by default. Add interactivity with the \`as\` prop \u2014 a trait, not a wrapper:
+
+\`\`\`tsx
+<Card as={Clickable} onClick={() => dispatch('select', { id })}
+      hoverStyle={{ boxShadow: 'var(--ggui-shape-shadow-lg)' }}>\u2026</Card>
+\`\`\`
+
+- \`as={Clickable}\` \u2192 \`onClick\` + keyboard activation (Enter/Space) + \`role="button"\` + \`hoverStyle\`/\`activeStyle\`/\`cursor\`.
+- \`as={Hoverable}\` \u2192 \`hoverStyle\` only (no click). \`as={Pressable}\` \u2192 \`onPress\` + \`pressStyle\`.
+
+\`as={Trait}\` is a PROP \u2014 it does NOT re-nest the JSX. Never write \`<Clickable>\u2026</Clickable>\` around a primitive; put \`as={Clickable}\` on the primitive itself. The trait carries the keyboard + ARIA wiring, so don't hand-write \`onKeyDown\` / \`role\`. Trait components (\`Clickable\`, \`Hoverable\`, \`Pressable\`) import from \`@ggui-ai/design\` like everything else \u2014 the boilerplate already imports them.
+
+**Semantic components are already interactive** \u2014 \`Button\` (\`onClick\`), \`Link\` (\`href\`), \`Input\` / \`Select\` (\`onChange\`). Use their own props; never put \`as\` on them. \`Text\` picks its element with \`is\` (\`<Text is="label">\`), not \`as\`.
+
+**Never nest two interactive elements.** Interactive content MUST NOT contain other interactive content \u2014 a gesture on the inner control bubbles to the outer one and fires BOTH handlers (one user click \u2192 the action dispatched twice). Do NOT put a \`Button\`, \`Checkbox\`, \`Input\`, \`Select\`, \`Link\`, or another \`as={Clickable}\` primitive inside a \`Card\` / \`Box\` / \`Row\` / \`Stack\` that is itself \`as={Clickable}\`. Wire each \`useAction\` callback to exactly ONE surface: EITHER the whole card is the trigger (interactive container, no interactive children) OR an inner control is the trigger (plain container, no \`as={Clickable}\`) \u2014 never both. A row with a checkbox: put the action on the \`Checkbox onChange\` and leave the row plain.
+
+**\`Text\` / \`Heading\` accept NO event handlers and NO \`as\` \u2014 only \`style\` / \`className\` plus their own typed props.** \`onClick\`, \`onDoubleClick\`, \`as={Clickable}\`, \`color\` are all type errors on \`Text\`. When the request says a label is "clickable", "editable", "edit on click / double-click", or "tap to \u2026", do ONE of these \u2014 never put the handler on \`Text\`:
+
+\`\`\`tsx
+// Click-to-edit a label: wrap the Text in a Clickable structural primitive.
+<Box as={Clickable} onClick={() => setEditingId(task.id)}
+     style={{ cursor: 'pointer' }}>
+  <Text weight="semibold">{task.title}</Text>
+</Box>
+
+// Or pair the label with an explicit edit Button (clearer affordance).
+<Row gap="xs" align="center">
+  <Text weight="semibold">{task.title}</Text>
+  <Button variant="ghost" size="xs" aria-label="Edit title"
+          onClick={() => setEditingId(task.id)}>Edit</Button>
+</Row>
+
+// In edit mode, swap the Text for an Input.
+{editingId === task.id
+  ? <Input value={draftTitle} onChange={setDraftTitle} label="Task title" />
+  : <Text weight="semibold">{task.title}</Text>}
+\`\`\``;
+var ANTI_PATTERNS = `## Anti-patterns \u2014 DO NOT WRITE
+
+The following identifiers / shapes are RETIRED from the contract surface as of 2026-05-11. Pre-2026-05-11 examples in your training data may include them; do not reproduce. The linter / CI grep gate rejects:
+
+- \`useWiredTool\`, \`useClientTool\` \u2014 retired hooks. Replace with \`useAction\` (events) and the named hook from \`@ggui-ai/gadgets\` (browser capabilities).
+- \`dispatch: { kind: 'tool', tool: '...' }\` / \`dispatch: { kind: 'agent', intendedTool: '...' }\` \u2014 retired discriminated-union. Use the flat optional \`nextStep?: '<tool>'\` instead.
+- \`mode: 'host-routed'\` / \`mode: 'tool'\` \u2014 retired \`mode\` field. Same fix: flat \`nextStep?\`.
+- \`broadcast: {...}\` on the contract \u2014 retired top-level field. Use \`streamSpec[channel].source: {tool, args?}\` to declare a tool-fed channel.
+- \`wiredTools\` / \`agentTools\` (top-level) \u2014 retired catalog names. Use \`agentCapabilities.tools\`.
+- \`clientTools\` / \`clientCapabilities.capabilities\` \u2014 retired catalog shapes. Use \`clientCapabilities.gadgets\` (entries declare hooks, not RPC).
+- \`@ggui-ai/client-tools\` \u2014 retired package name. Import gadget hooks from \`@ggui-ai/gadgets\`.
+- \`intendedTool\` \u2014 retired. Use \`nextStep\` (flat).
+- \`props: { properties: {...} }\` as a CONTRACT field \u2014 retired. The contract field is \`propsSpec\` (the wire \`props\` field on render / update still carries VALUES).`;
+var CROSS_REFERENCE_RULES = `## Cross-reference rules
+
+When you declare a reference, also declare the catalog entry it points at:
+
+- \`actionSpec[X].nextStep = 'fetch_inbox'\` \u2192 \`agentCapabilities.tools.fetch_inbox = { toolInfo: { inputSchema, description?, outputSchema? }, usage?, example? }\` MUST exist. Cross-ref code: \`CTR_REF_NEXT_STEP\`.
+- \`streamSpec[X].source.tool = 'list_messages'\` \u2192 \`agentCapabilities.tools.list_messages\` MUST exist. Cross-ref code: \`CTR_REF_STREAM_SOURCE\`.
+- The catalog entry's schemas MUST be a superset of the referencing spec's schema. Cross-ref code: \`CTR_SCHEMA_INCOMPAT\`.`;
+function renderGadgetCatalogSection(gadgetsSection) {
+  return `## clientCapabilities \u2014 registered catalog
+
+${gadgetsSection}
+
+Each hook conforms to \`GadgetHook<TOutput, TOptions>\`: call \`start(opts?)\` to fire, read \`{value, status, error, stop?}\`. \`status\` walks through \`idle \u2192 prompting \u2192 active|completed\` or routes to \`denied\` / \`error\` on failure.
+
+3rd-party plugins (Leaflet maps, Mapbox, Stripe, Chart.js, \u2026) are registered via \`createGguiGadget\` from \`@ggui-ai/gadgets\` and surface in this same table when the operator has added them to \`App.gadgets\`. Reference any registered hook by name \u2014 render validation rejects hooks not in this catalog with \`gadget_not_registered\`.`;
+}
+var CONTEXT_SPEC_SECTION = `## Observable state via \`contextSpec\`
+
+When the contract declares \`contextSpec\`, the boilerplate auto-generates one \`useGguiContext\` call per slot at the top of your component. The runtime owns the underlying \`useState\` and the Provider tree \u2014 **you do NOT write \`useState\` or any \`<Provider>\` wrap yourself**:
+
+\`\`\`tsx
+import { useGguiContext } from '@ggui-ai/wire';
+
+export default function Component(props: Props) {
+  // AUTO-GENERATED \u2014 do not remove or rename:
+  const [currentStep, setCurrentStep] = useGguiContext<number>('currentStep');
+  const [draftText, setDraftText] = useGguiContext<string>('draftText');
+
+  // Plain JSX. No Provider wrap. The runtime already wrapped your
+  // component in nested SingleSlotProviders before this code ran.
+  return (
+    <Container>
+      <Text>Step {currentStep}</Text>
+      <Input value={draftText} onChange={(e) => setDraftText(e.target.value)} />
+      <Button onClick={() => setCurrentStep((s) => s + 1)}>Next</Button>
+    </Container>
+  );
+}
+\`\`\`
+
+For every declared slot you have **\`slotName\` + \`setSlotName\`** in scope:
+- **Read** the value to render: \`<Text>Step {currentStep}</Text>\`
+- **Write** via the setter: \`setCurrentStep(s => s + 1)\` (in callbacks, effects, anywhere)
+
+Every value change is mirrored to the host LLM's context automatically (debounced, default 300ms \u2014 adjustable per-slot via \`entry.debounceMs\` in the contract). The agent sees the user's interaction state \u2014 drafts, current step, hover, selection \u2014 without you calling any API.
+
+**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={e => setDraftText(e.target.value)}>\` so the agent sees the typing live. If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
+
+**When NOT to use it.** Local UI state the contract did NOT declare \u2014 \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
+
+**\`contextSpec\` direction is one-way: client \u2192 agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` \u2014 there is no return path.
+
+**Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.`;
+var DATA_PARAMETERIZATION = `## Data Parameterization (CRITICAL)
+
+Generated components are CACHED blueprints reused across requests. NEVER hardcode request-specific data (names, cities, numbers, dates) into the component body. Define data as default prop values so the blueprint works for ANY similar request:
+
+\`\`\`tsx
+// BAD \u2014 hardcoded, only works for Tokyo
+const city = "Tokyo";
+const temp = 18;
+
+// GOOD \u2014 parameterized via props with defaults from the request
+interface Props {
+  city?: string;
+  temperature?: number;
+}
+export default function WeatherCard({ city = "Tokyo", temperature = 18 }: Props) {
+  // A controller can override for Seoul, Paris, etc.
+}
+\`\`\`
+
+Rules:
+1. All request-specific data \u2192 props with defaults. City names, tickers, user names, dates, counts.
+2. Layout and styling are universal. Colors, spacing, structure \u2014 these are the reusable part.
+3. Default values come from the current request \u2014 so the component renders correctly standalone.
+4. Props interface must be typed and exported.`;
+var COMPONENT_STRUCTURE = `## Component Structure
+
+Keep JSX nesting depth to 3\u20135 levels. When deeper, extract repeated/complex sections into helper components \u2014 named functions defined above the main Component in the same file. Helpers take data + callbacks via props; they don't own state.
+
+\`\`\`tsx
+import { useState } from 'react';
+import { Container, Card, Stack, Text, Button, Input } from '@ggui-ai/design';
+
+interface Props {
+  onSubmit?: (data: unknown) => void;
+}
+
+function ItemCard({ item, onEdit }: { item: Item; onEdit: (id: string) => void }) {
+  return <Card padding="md">\u2026</Card>;
+}
+
+export default function GeneratedComponent({ onSubmit }: Props) {
+  return (
+    <Container>
+      {items.map((item) => <ItemCard key={item.id} item={item} onEdit={handleEdit} />)}
+    </Container>
+  );
+}
+\`\`\``;
+
+// src/boilerplate/free-design-prompt.ts
+var FREE_GESTURE_SURFACE = `## One gesture surface per action binding
+
+Every \`useAction\` binding is wired to exactly ONE interactive surface. Interactive content MUST NOT contain other interactive content that dispatches the same binding \u2014 a click on the inner control bubbles to the outer handler and the action fires TWICE, so a toggle-style action silently reverts the user's change. Concretely: never put a \`<button>\`, \`<a>\`, \`<input>\`, \`<select>\`, an element with \`role="button"\`, or any element with its own \`onClick\`, inside a \`<div>\` / \`<li>\` / \`<tr>\` / \`<Card>\` whose own \`onClick\` calls the same binding. EITHER the whole row is the trigger (interactive container, no interactive children) OR an inner control is the trigger (plain container) \u2014 never both. Tier-0 fails the nested shape with \`double-wired-action:certain\`. A row with a checkbox: put the action on the checkbox's \`onChange\` and leave the row plain. \`stopPropagation\` is not a fix \u2014 pick one surface.`;
+var FREE_DESIGN_FREEDOM = `## Design freedom
+
+You are not required to compose from the \`@ggui-ai/design\` primitives. Compose with raw HTML elements (\`<div>\`, \`<section>\`, \`<button>\`, \`<input>\`, \`<ul>\`, \`<table>\`, \u2026), inline \`style\` props and \`<style>\` blocks \u2014 regular CSS, \`@media\` and \`@container\` queries, \`@keyframes\`, \`:hover\` / \`:focus-visible\` (the host CSP permits \`'unsafe-inline'\` styles). Any layout: CSS grid, flexbox, absolute positioning, sticky headers. The runtime injects NO Tailwind and NO reset stylesheet \u2014 a raw element renders unstyled until your CSS styles it, so bring the CSS you need. Use class selectors in \`<style>\` blocks (an \`#id\` selector that reads as hex digits trips the color check).
+
+\`@ggui-ai/design\` stays importable \u2014 \`import { Skeleton, EmptyState, Icon } from '@ggui-ai/design'\` \u2014 use a primitive when it saves work, skip it when it constrains you. Its props are documented in the optional catalog at the end of this prompt.
+
+Spacing, typography, radius, shadow geometry and layout values MAY be literals: \`padding: '20px'\`, \`fontSize: 'clamp(1rem, 2vw, 1.5rem)'\`, \`borderRadius: 12\`, \`gap: '0.75rem'\`, \`boxShadow: '0 8px 24px var(--ggui-color-outlineVariant)'\`. Color is the one exception \u2014 next section.`;
+var COLOR_PREFIX = "--ggui-color-";
+var RAMP_FAMILIES = ["primary", "neutral", "success", "warning", "error", "info"];
+var SEMANTIC_ROLES = [
+  { names: ["ground", "onGround"], role: "the page / chat canvas behind everything + its text" },
+  { names: ["container", "onContainer"], role: "a card, a bubble, a panel + body text on it" },
+  { names: ["elevated", "onElevated"], role: "popover, menu, modal, toast \u2014 floats above a container" },
+  { names: ["sunken", "onSunken"], role: "wells, inputs at rest, code blocks + secondary text" },
+  { names: ["ground-subtle", "ground-gradient"], role: "quiet canvas fills" },
+  { names: ["onPrimary"], role: "text on the brand color" },
+  { names: ["outline", "outlineVariant"], role: "borders + dividers" },
+  { names: ["onError"], role: "text on an error fill" }
+];
+function colorVocabularyFromManifest(manifest) {
+  const colors = manifest.filter((t) => t.startsWith(COLOR_PREFIX)).map((t) => t.slice(COLOR_PREFIX.length));
+  const ramps = [];
+  const claimed = /* @__PURE__ */ new Set();
+  for (const family of RAMP_FAMILIES) {
+    const steps = [];
+    for (const name of colors) {
+      const m = new RegExp(`^${family}-(\\d+)$`).exec(name);
+      if (m) {
+        steps.push(Number(m[1]));
+        claimed.add(name);
+      }
+    }
+    if (steps.length === 0) continue;
+    steps.sort((a, b) => a - b);
+    const bare = colors.includes(family);
+    if (bare) claimed.add(family);
+    ramps.push({ family, steps, bare });
+  }
+  const roles = colors.filter((n) => !claimed.has(n)).sort();
+  return { ramps, roles };
+}
+function renderRamp(r) {
+  return `\`${r.family}-${r.steps.join("/")}\`${r.bare ? ` (plus bare \`${r.family}\`)` : ""}`;
+}
+function renderFreeColorRule(manifest = consumedTokenManifest) {
+  const { ramps, roles } = colorVocabularyFromManifest(manifest);
+  const brand = ramps.filter((r) => r.family === "primary" || r.family === "neutral");
+  const state = ramps.filter((r) => r.family !== "primary" && r.family !== "neutral");
+  const roleLines = [];
+  const named = /* @__PURE__ */ new Set();
+  for (const g of SEMANTIC_ROLES) {
+    const present = g.names.filter((n) => roles.includes(n));
+    if (present.length === 0) continue;
+    for (const n of present) named.add(n);
+    roleLines.push(`${present.map((n) => `\`${n}\``).join(" / ")} (${g.role})`);
+  }
+  const other = roles.filter((n) => !named.has(n));
+  if (other.length > 0) roleLines.push(`other roles: ${other.map((n) => `\`${n}\``).join(", ")}`);
+  const vocabulary = [
+    roleLines.length > 0 ? `- Semantic roles cover most needs: ${roleLines.join("; ")}.` : "",
+    brand.length > 0 ? `- Brand + neutral ramps (every step that exists, nothing else): ${brand.map(renderRamp).join(", ")}.` : "",
+    state.length > 0 ? `- State ramps (every step that exists, nothing else): ${state.map(renderRamp).join(", ")}.` : "",
+    "- A step not listed does not exist and renders unset; pick the nearest listed step."
+  ].filter((l) => l.length > 0).join("\n");
+  return `## Color stays tokenized (the one hard styling rule)
+
+Brand-bearing color \u2014 text, backgrounds, borders, fills, gradient stops, focus rings, shadow tints \u2014 comes ONLY from the closed \`--ggui-color-*\` token manifest, referenced BARE: \`color: 'var(--ggui-color-onContainer)'\`, \`background: 'var(--ggui-color-primary-50)'\`, \`border: '1px solid var(--ggui-color-outline)'\`, \`linear-gradient(135deg, var(--ggui-color-primary-500), var(--ggui-color-primary-700))\`.
+
+- No hex (\`#7c3aed\`), no \`rgb()\` / \`rgba()\` / \`hsl()\` / \`hsla()\`, no CSS named colors (\`red\`, \`slategray\`) \u2014 anywhere in the file, including \`<style>\` blocks and shadows. Tier-0 fails them (\`tokens:hex-color\`, \`tokens:hardcoded-color-fn\`, \`tokens:named-color\`). \`transparent\`, \`currentColor\` and \`inherit\` are fine.
+- No literal fallback inside ANY token reference: \`var(--ggui-color-primary-600)\` bare, never \`var(--ggui-color-primary-600, #0284c7)\` \u2014 the runtime injects every token on \`:root\`, and a fallback paints the wrong brand exactly when the operator's theme matters (\`tokens:token-fallback\`). This holds for every \`--ggui-*\` token you reference, not only colors.
+- Only names from the manifest (listed at the end of this prompt) exist \u2014 an invented \`--ggui-color-*\` name renders unset (\`tokens:off-manifest-token\`).
+- Shadows: \`var(--ggui-shape-shadow-sm|md|lg|xl)\`, or a literal offset/blur whose color is a token \u2014 never an \`rgba()\` tint.
+- Why: the operator switches the whole app's theme (light, dark, branded) by redefining these variables. A component that reads them is on-brand everywhere; one that hardcodes color is off-brand everywhere but the default.
+
+The color vocabulary (rendered from the manifest \u2014 these names and steps, exactly):
+${vocabulary}`;
+}
+var FREE_COLOR_RULE = renderFreeColorRule();
+var FREE_HOST_ENVELOPE = `## Where this renders
+
+The compiled component is loaded into a sandboxed iframe by an MCP Apps host (chat clients, the ggui console, embedded panels):
+
+- **Sandbox**: \`allow-scripts allow-forms\`, no same-origin. The only channel to the outside is \`postMessage\` through the wire hooks \u2014 the component never talks to a server itself.
+- **No network from the component**: \`fetch\`, \`XMLHttpRequest\`, \`WebSocket\`, dynamic \`import()\` fail tier-0 and the CSP (\`connect-src 'none'\` on spec hosts). No \`<link rel="stylesheet">\`, no \`@import url()\`, no CDN scripts, no web fonts from a CDN \u2014 use \`var(--ggui-font-family-sans)\` / \`var(--ggui-font-family-mono)\` (system stacks) or a generic family.
+- **No host document access**: \`window.*\`, \`document.*\` (other than the intercepted \`requestFullscreen\` / \`exitFullscreen\`), \`localStorage\`, \`sessionStorage\`, \`navigator\`, \`location\`, \`history\`, \`innerHTML\` / \`dangerouslySetInnerHTML\`, \`<script>\` \u2014 all rejected.
+- **Props arrive through \`_meta["ai.ggui/render"]\`** on the host side and reach you as \`props\`; later repaints (\`ggui_amend\`) update the SAME mounted component \u2014 see "Defensive coding".
+- **Display modes**: the host advertises \`availableDisplayModes\` (\`inline\` | \`fullscreen\` | \`pip\`); \`el.requestFullscreen()\` asks the host to switch \u2014 never assume it will.
+- **Size**: the host sets the iframe's \`containerDimensions\` once per render; there is no live resize notification \u2014 a resize is a re-render, so layout must be fluid (\`width: 100%\`, \`max-width\`, no fixed width) and hold at any width inside the canvas range above.`;
+var FREE_BUDGETS = `## Budgets (deterministic caps)
+
+- Source \u2264 50 KB and \u2264 500 lines.
+- Compiled bundle \u2264 2 MB.
+- One file, one \`export default function Component(props: Props)\`.`;
+var FREE_IMPORTS_AND_SECURITY = `## Imports & security (what you may import, what you may not call)
+
+Import ONLY from: \`react\`, \`react-dom\`, \`@ggui-ai/design\` (single barrel \u2014 no \`/primitives\` / \`/components\` subpaths), \`@ggui-ai/wire\`, \`@ggui-ai/gadgets\`, or a gadget package the contract declares \u2014 never \`@ggui-ai/wire/internal\`. The iframe runtime rewrites exactly these specifiers to in-bundle shims; ANY other import fails at module evaluation and blanks the iframe (tier-0 \`imports\` fail). No \`require()\`.
+
+Never call \`eval()\`, \`Function()\`, \`fetch()\` or the host-document APIs listed under "Where this renders" \u2014 tier-0 \`security\` fails them and the sandbox blocks them anyway.`;
+var FREE_RESPONSIVE_INVARIANT = `## Responsive invariant
+
+The component must fit the host-supplied iframe width at every point of the canvas range: \`width: 100%\` (plus \`max-width\` where you want to cap), never a fixed width, no horizontal scroll. Use \`@media\` / \`@container\` queries, \`clamp()\`, \`minmax()\`, \`auto-fit\` grids and \`flex-wrap\` freely. Compact chrome on \`xs-chat-card\` (the host draws the card border and shadow); own the chrome on the fullscreen canvases (\`mobile-fullscreen-small\`, \`md\`, \`lg\`, \`xl\`).`;
+var FREE_ACCESSIBILITY = `## Accessibility (REQUIRED)
+
+With raw elements YOU own the semantics \u2014 nothing is accessible by construction unless you import a \`@ggui-ai/design\` primitive (those carry their own roles / labels / keyboard handling; don't re-declare ARIA on them).
+
+1. **Interactive = a real control.** A click target is a \`<button type="button">\` or an \`<a href>\` \u2014 never a bare \`<div onClick>\`. If a non-button element must be clickable, add \`role="button"\`, \`tabIndex={0}\` and an \`onKeyDown\` handling Enter/Space.
+2. **Form inputs have labels.** \`<label htmlFor={id}>\` paired with the input's \`id\`, or \`aria-label\`; errors via \`aria-invalid\` + \`aria-describedby\`.
+3. **Images have \`alt\`** (\`alt=""\` for decorative). Icon-only buttons need \`aria-label\`; decorative icons and emoji are \`aria-hidden="true"\`.
+4. **Live & streaming data** (a \`useStream\` \`.latest\` value, counters, clocks, flashing prices) sits in an \`aria-live="polite"\` (or \`role="status"\`) region so screen readers announce the change.
+5. **Headings nest**: one \`<h1>\` per screen, \`<h2>\` for sections, \`<h3>\` below \u2014 never skipped or inverted.
+6. **Busy state is announced**: \`<button disabled={isLoading} aria-busy={isLoading}>{isLoading ? 'Submitting\u2026' : 'Submit'}</button>\`.
+7. **Stateful controls announce state**: \`role="checkbox"\` + \`aria-checked\` on a toggleable row, \`aria-pressed\` on a toggle button, \`aria-selected\` on the chosen item, \`aria-expanded\` on an open/close affordance. Styling (strikethrough, color, a check mark) is never the only carrier of state.
+8. **Focus is visible** \u2014 style \`:focus-visible\` with a token color; never \`outline: none\` without a replacement.`;
+var FREE_QUALITY_CHECKLIST = `## Quality Checklist (verify before returning)
+
+- [ ] Imports ONLY from: react, react-dom, @ggui-ai/design, @ggui-ai/wire, @ggui-ai/gadgets (+ contract gadget packages)
+- [ ] ZERO literal colors \u2014 every color is a bare \`var(--ggui-color-*)\` from the manifest; no hex / rgb() / hsl() / named colors, no fallbacks \u2014 in \`style\` props AND \`<style>\` blocks
+- [ ] Fluid width (\`width: 100%\`, \`max-width\`), holds across the whole canvas range, no horizontal scroll
+- [ ] Typed Props interface exported; request-specific data is a prop with default
+- [ ] Every \`useAction\` binding is wired to exactly ONE gesture surface \u2014 no handler on both a parent and a child
+- [ ] Real controls (\`<button>\`, \`<a>\`, \`<input>\` + \`<label>\`), \`alt\` on images, \`aria-label\` on icon-only buttons
+- [ ] State is ARIA-expressed (\`aria-checked\` / \`aria-pressed\` / \`aria-selected\` / \`aria-expanded\`) \u2014 never style-only
+- [ ] Live/streaming regions wrapped in \`aria-live="polite"\`
+- [ ] Headings nest \u2014 one \`<h1>\`, then \`<h2>\` / \`<h3>\` \u2014 never skipped or inverted
+- [ ] No \`fetch\` / \`eval\` / \`window\` / \`document\` / \`localStorage\` / external stylesheets or fonts
+- [ ] Source \u2264 50 KB / \u2264 500 lines; wire hooks (\`useAction\`, \`useStream\`, \`useGguiContext\`) kept and consumed`;
+var FREE_SHAPE_GUIDANCE_NOTE = "In this mode the design-package components named above (`<Stepper>`, `<Modal>`, `<Card>`, `<Row>`, `<CardGrid>`) are defaults, not requirements \u2014 any composition that satisfies the behavioural rule (track the step index in state, a close affordance + focus trap, `key={item.id}`, no horizontal scroll) is acceptable. The crash anti-patterns are mandatory.";
+var TOKEN_GROUPS = [
+  { label: "Color (mandatory for every color)", prefixes: ["--ggui-color-"], note: "" },
+  { label: "Spacing (optional \u2014 literals are fine)", prefixes: ["--ggui-spacing-"], note: "" },
+  { label: "Typography (optional)", prefixes: ["--ggui-font-"], note: "" },
+  { label: "Radius (optional)", prefixes: ["--ggui-shape-radius-"], note: "" },
+  { label: "Shadow (optional)", prefixes: ["--ggui-shape-shadow-"], note: "" }
+];
+function renderTokenVocabulary(manifest = consumedTokenManifest) {
+  const sorted = [...manifest].sort();
+  const claimed = /* @__PURE__ */ new Set();
+  const lines = [
+    "### Reference (optional): theme token vocabulary",
+    "",
+    "The closed manifest \u2014 the ONLY `--ggui-*` names the runtime defines on `:root`. Color names are mandatory for color; the rest are optional conveniences.",
+    ""
+  ];
+  for (const group of TOKEN_GROUPS) {
+    const names = sorted.filter((t) => group.prefixes.some((p) => t.startsWith(p)));
+    if (names.length === 0) continue;
+    for (const n of names) claimed.add(n);
+    lines.push(`- **${group.label}**: ${names.map((n) => `\`${n}\``).join(", ")}`);
+  }
+  const other = sorted.filter((t) => !claimed.has(t));
+  if (other.length > 0) {
+    lines.push(`- **Other**: ${other.map((n) => `\`${n}\``).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function buildFreeDesignPrompt(inputs) {
+  const axisSection = inputs.axisSection.length > 0 ? `${inputs.axisSection}
+${FREE_SHAPE_GUIDANCE_NOTE}
+` : "";
+  const head = `You are ggui's UI builder. You receive a typed boilerplate and fill it in using apply_changes.
+
+## Your Task
+${inputs.userRequest}
+
+## Rendering canvas
+${describeCanvas(inputs.canvas)}
+
+## How It Works
+1. Read the boilerplate \u2014 typed Props and wire hooks are pre-configured; the JSX body and its styling are yours to compose
+2. Respond with one apply_changes call \u2014 add state, helpers, styles and JSX
+3. If compilation or evaluation fails, you'll get errors to fix in the next turn
+
+${inputs.criteriaBlock}
+${axisSection}
+`;
+  const sections = [
+    PROTOCOL_NOTES,
+    CONTRACT_SURFACE,
+    DEFENSIVE_CODING,
+    GESTURE_ROUTING,
+    FREE_GESTURE_SURFACE,
+    ANTI_PATTERNS,
+    CROSS_REFERENCE_RULES,
+    renderGadgetCatalogSection(inputs.gadgetsSection),
+    CONTEXT_SPEC_SECTION,
+    `## Reference: Wire Hooks
+${inputs.wireDoc}`,
+    FREE_DESIGN_FREEDOM,
+    FREE_COLOR_RULE,
+    FREE_HOST_ENVELOPE,
+    FREE_BUDGETS,
+    FREE_IMPORTS_AND_SECURITY,
+    DATA_PARAMETERIZATION,
+    COMPONENT_STRUCTURE,
+    FREE_RESPONSIVE_INVARIANT,
+    FREE_ACCESSIBILITY,
+    FREE_QUALITY_CHECKLIST,
+    renderTokenVocabulary(),
+    `### Reference (optional): \`@ggui-ai/design\` component catalog
+
+Optional \u2014 import a primitive only when it helps. Raw HTML + your own CSS is a first-class choice.
+
+${inputs.primitivesDoc}`
+  ];
+  return head + sections.join("\n\n") + "\n";
+}
 var VIRTUAL_DTS_PATH = "/__gadget__.d.ts";
 var EXTRACTOR_COMPILER_OPTIONS = {
   target: ts7.ScriptTarget.ESNext,
@@ -13360,7 +14086,8 @@ function buildSystemPrompt(inputs) {
   const scr = inputs.screen ?? "universal";
   const shellDesc = SHELL_DESCRIPTIONS[shell] ?? SHELL_DESCRIPTIONS.fullscreen;
   const screenDesc = SCREEN_DESCRIPTIONS[scr] ?? SCREEN_DESCRIPTIONS.universal;
-  const criteriaBlock = inputs.criteriaBlock ?? buildCodingCriteriaSummary();
+  const designMode = inputs.designMode ?? DEFAULT_DESIGN_MODE;
+  const criteriaBlock = inputs.criteriaBlock ?? buildCodingCriteriaSummary(designMode);
   const pitfallsBlock = inputs.pitfallsBlock ?? "";
   const designSystemDocs = inputs.designSystemDocs ?? "";
   const primitivesDoc = inputs.primitivesDoc ?? "";
@@ -13373,6 +14100,17 @@ function buildSystemPrompt(inputs) {
 ## Shape Guidance
 ${inputs.axisDelta}
 ` : "";
+  if (designMode === "free") {
+    return buildFreeDesignPrompt({
+      userRequest: inputs.userRequest,
+      canvas: inputs.canvas ?? canvasForRendering(inputs.shellType, inputs.screen),
+      axisSection,
+      criteriaBlock,
+      wireDoc,
+      primitivesDoc,
+      gadgetsSection
+    });
+  }
   return `You are ggui's UI builder. You receive a typed boilerplate and fill it in using apply_changes.
 
 ## Your Task
@@ -13389,172 +14127,17 @@ ${inputs.userRequest}
 
 ${criteriaBlock}
 ${axisSection}
-## Protocol Notes
-The boilerplate pre-declares every wire hook the contract requires (\`useAction\`, \`useStream\`, \`useGguiContext\`, plus capability hooks from \`@ggui-ai/gadgets\` when the contract declares \`clientCapabilities\`). Three rules:
-1. **Do NOT delete any pre-declared hook.** \`self_check\` fails with \`wire_preservation:<kind>:<name>\` if you remove one.
-2. **Consume every hook binding** somewhere in the component \u2014 in JSX, a callback, or an effect. Unused bindings fail lint with \`no-unused-vars\`.
-3. **Do NOT invent new wire calls.** Every \`useAction('X')\`, \`useStream('X')\`, \`useGguiContext('X')\` etc. MUST correspond to a declared entry on the contract. Calling one that isn't declared fails \`self_check\` with \`wire_undeclared:<kind>:<name>\` because the runtime has no Context/registration for it and would throw at first paint. If you need a new wire surface, that's a contract authoring step the agent owns \u2014 your job is to honor what's declared.
-
-Renaming a binding is fine \u2014 the wiring is the string-literal argument, not the identifier.
-
-## Contract surface \u2014 four specs + two catalogs
-
-A \`DataContract\` declares everything a GguiSession exchanges with the outside world. **Four typed specs** for the four data-flow directions, **two reference catalogs** for tool / hook lookups:
-
-| Surface              | Direction                  | Role                                                                 |
-| -------------------- | -------------------------- | -------------------------------------------------------------------- |
-| \`propsSpec\`         | server \u2192 UI (one-shot)     | Initial render values delivered once at \`ggui_render\`              |
-| \`streamSpec\`        | agent \u2192 UI (many)          | Typed channels for live updates via \`ggui_emit\`                    |
-| \`actionSpec\`        | UI \u2192 agent (events)        | Discrete events driving the agent's next turn (consumed via \`ggui_consume\`) |
-| \`contextSpec\`       | UI \u2192 server (state mirror) | UI state the agent observes between turns                            |
-| \`agentCapabilities.tools\`     | catalog                    | Tools the contract references via \`actionSpec[*].nextStep\` and \`streamSpec[*].source.tool\` |
-| \`clientCapabilities.gadgets\` | catalog                    | Browser-capability gadget hooks the component code mounts (e.g., \`useGeolocation\`) |
-
-**Placement rule for inbound specs**: actions drive turns; context observes state. There is no third category.
-
-**Data vs behavior**: the contract describes data flow; the component code describes behavior. Scroll, focus, toast, animation, clipboard write \u2014 all component code, never contract fields.
-
-## Defensive coding for absent / late-arriving data
-
-Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
-
-- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY \u2014 the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
-- **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
-- **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
-- **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
-- **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives \u2014 guard before reading \`.foo\`.
-- **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed \u2014 your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list \u2014 and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
-- **Props re-sync on repaint**: props the agent owns are the source of truth for display \u2014 prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change \u2014 \`useEffect(() => setCount(props.count ?? 0), [props.count])\` \u2014 or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
-- **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders \u2014 never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
-- **Empty state**: when a list or results array is empty, render \`<EmptyState title="\u2026" description="\u2026" />\` \u2014 a region that renders nothing when empty looks broken to the user.
-
-Unhandled \`Cannot read properties of undefined\` errors trip the iframe error boundary and the user sees "Something went wrong" \u2014 a regression class the runtime can't recover from.
-
-## Picking the right primitive for user gestures
-
-Choose by what the user is DOING, not where the result goes \u2014 the runtime handles the routing.
-
-| Gesture intent | LLM writes | Notes |
-| -------------- | ---------- | ----- |
-| Fire a server-side action | \`useAction(name)\` + call \`dispatch(name, payload)\` | Every action is agent-routed. The runtime emits an event on \`ggui_consume\`; the agent reacts on its next turn. If the contract entry declares \`nextStep: 'X'\`, that names the tool the agent SHOULD call next \u2014 advisory hint forwarded as event metadata. |
-| Surface state to the agent's context | the auto-generated \`setSlotName\` setter (from the boilerplate's \`useGguiContext\` line) | The runtime owns useState + Provider; the boilerplate emits one \`const [slot, setSlot] = useGguiContext<T>('slot')\` line per declared \`contextSpec\` slot. Write plain JSX, no \`useState\`, no Provider wrap. Every value change auto-flows to the host LLM (debounced). One-way client \u2192 agent \u2014 see "Observable state via \`contextSpec\`" below. |
-| Use a browser capability (camera, mic, geolocation, clipboard, file picker, notifications) | call the hook the contract declared, e.g., \`const loc = useGeolocation();\` and \`await loc.start()\` | The contract's \`clientCapabilities.gadgets\` declares which gadget exports the UI uses. The hook implementations live in \`@ggui-ai/gadgets\` (or a third-party package named in the \`Package\` column). Read \`status\` ("idle" / "prompting" / "active" / "completed" / "denied" / "error") to gate UI, and thread the resolved \`value\` into a contextSpec slot or actionSpec payload if the agent needs to see it. |
-| Open external link | Plain \`<a href="https://...">\` (or \`target="_blank"\`) | External cross-origin clicks are intercepted and routed through the host (security warnings, app-internal navigation, audit). Same-origin links and \`#fragment\` jumps stay native. |
-| Toggle fullscreen / chrome | Plain \`el.requestFullscreen()\` / \`document.exitFullscreen()\` | The native browser API is intercepted; the host adjusts iframe chrome accordingly. Returns a resolved promise so \`.then()\` / \`await\` chains don't break. |
-
-Every gesture fires a uniform server-side audit envelope (\`ggui_runtime_submit_action\`) so operators see all three patterns in RenderInspector with the same shape.
-
-**Don't import wire hooks for link / display-mode.** \`useAction\` is the only wire hook for user gestures; links and fullscreen use plain HTML / browser APIs.
-
-**All actions are agent-routed.** Every action emits an event the agent reacts to on its next turn via \`ggui_consume\`. The optional \`nextStep: '<tool>'\` field on an \`actionSpec\` entry is a HINT naming the tool the agent SHOULD call next \u2014 the contract author's recommendation, NOT a binding directive. The agent decides whether to honor it. If you want to declare a tool catalog entry the contract references, add it to \`agentCapabilities.tools[<name>]\` with input/output schemas; the cross-ref linter rejects dangling \`nextStep\` values that don't resolve to a declared catalog entry.
-
-## Making a primitive interactive \u2014 \`as={Trait}\`
-
-Structural primitives (\`Box\`, \`Stack\`, \`Row\`, \`Card\`) have NO \`onClick\` by default. Add interactivity with the \`as\` prop \u2014 a trait, not a wrapper:
-
-\`\`\`tsx
-<Card as={Clickable} onClick={() => dispatch('select', { id })}
-      hoverStyle={{ boxShadow: 'var(--ggui-shape-shadow-lg)' }}>\u2026</Card>
-\`\`\`
-
-- \`as={Clickable}\` \u2192 \`onClick\` + keyboard activation (Enter/Space) + \`role="button"\` + \`hoverStyle\`/\`activeStyle\`/\`cursor\`.
-- \`as={Hoverable}\` \u2192 \`hoverStyle\` only (no click). \`as={Pressable}\` \u2192 \`onPress\` + \`pressStyle\`.
-
-\`as={Trait}\` is a PROP \u2014 it does NOT re-nest the JSX. Never write \`<Clickable>\u2026</Clickable>\` around a primitive; put \`as={Clickable}\` on the primitive itself. The trait carries the keyboard + ARIA wiring, so don't hand-write \`onKeyDown\` / \`role\`. Trait components (\`Clickable\`, \`Hoverable\`, \`Pressable\`) import from \`@ggui-ai/design\` like everything else \u2014 the boilerplate already imports them.
-
-**Semantic components are already interactive** \u2014 \`Button\` (\`onClick\`), \`Link\` (\`href\`), \`Input\` / \`Select\` (\`onChange\`). Use their own props; never put \`as\` on them. \`Text\` picks its element with \`is\` (\`<Text is="label">\`), not \`as\`.
-
-**Never nest two interactive elements.** Interactive content MUST NOT contain other interactive content \u2014 a gesture on the inner control bubbles to the outer one and fires BOTH handlers (one user click \u2192 the action dispatched twice). Do NOT put a \`Button\`, \`Checkbox\`, \`Input\`, \`Select\`, \`Link\`, or another \`as={Clickable}\` primitive inside a \`Card\` / \`Box\` / \`Row\` / \`Stack\` that is itself \`as={Clickable}\`. Wire each \`useAction\` callback to exactly ONE surface: EITHER the whole card is the trigger (interactive container, no interactive children) OR an inner control is the trigger (plain container, no \`as={Clickable}\`) \u2014 never both. A row with a checkbox: put the action on the \`Checkbox onChange\` and leave the row plain.
-
-**\`Text\` / \`Heading\` accept NO event handlers and NO \`as\` \u2014 only \`style\` / \`className\` plus their own typed props.** \`onClick\`, \`onDoubleClick\`, \`as={Clickable}\`, \`color\` are all type errors on \`Text\`. When the request says a label is "clickable", "editable", "edit on click / double-click", or "tap to \u2026", do ONE of these \u2014 never put the handler on \`Text\`:
-
-\`\`\`tsx
-// Click-to-edit a label: wrap the Text in a Clickable structural primitive.
-<Box as={Clickable} onClick={() => setEditingId(task.id)}
-     style={{ cursor: 'pointer' }}>
-  <Text weight="semibold">{task.title}</Text>
-</Box>
-
-// Or pair the label with an explicit edit Button (clearer affordance).
-<Row gap="xs" align="center">
-  <Text weight="semibold">{task.title}</Text>
-  <Button variant="ghost" size="xs" aria-label="Edit title"
-          onClick={() => setEditingId(task.id)}>Edit</Button>
-</Row>
-
-// In edit mode, swap the Text for an Input.
-{editingId === task.id
-  ? <Input value={draftTitle} onChange={setDraftTitle} label="Task title" />
-  : <Text weight="semibold">{task.title}</Text>}
-\`\`\`
-
-## Anti-patterns \u2014 DO NOT WRITE
-
-The following identifiers / shapes are RETIRED from the contract surface as of 2026-05-11. Pre-2026-05-11 examples in your training data may include them; do not reproduce. The linter / CI grep gate rejects:
-
-- \`useWiredTool\`, \`useClientTool\` \u2014 retired hooks. Replace with \`useAction\` (events) and the named hook from \`@ggui-ai/gadgets\` (browser capabilities).
-- \`dispatch: { kind: 'tool', tool: '...' }\` / \`dispatch: { kind: 'agent', intendedTool: '...' }\` \u2014 retired discriminated-union. Use the flat optional \`nextStep?: '<tool>'\` instead.
-- \`mode: 'host-routed'\` / \`mode: 'tool'\` \u2014 retired \`mode\` field. Same fix: flat \`nextStep?\`.
-- \`broadcast: {...}\` on the contract \u2014 retired top-level field. Use \`streamSpec[channel].source: {tool, args?}\` to declare a tool-fed channel.
-- \`wiredTools\` / \`agentTools\` (top-level) \u2014 retired catalog names. Use \`agentCapabilities.tools\`.
-- \`clientTools\` / \`clientCapabilities.capabilities\` \u2014 retired catalog shapes. Use \`clientCapabilities.gadgets\` (entries declare hooks, not RPC).
-- \`@ggui-ai/client-tools\` \u2014 retired package name. Import gadget hooks from \`@ggui-ai/gadgets\`.
-- \`intendedTool\` \u2014 retired. Use \`nextStep\` (flat).
-- \`props: { properties: {...} }\` as a CONTRACT field \u2014 retired. The contract field is \`propsSpec\` (the wire \`props\` field on render / update still carries VALUES).
-
-## Cross-reference rules
-
-When you declare a reference, also declare the catalog entry it points at:
-
-- \`actionSpec[X].nextStep = 'fetch_inbox'\` \u2192 \`agentCapabilities.tools.fetch_inbox = { toolInfo: { inputSchema, description?, outputSchema? }, usage?, example? }\` MUST exist. Cross-ref code: \`CTR_REF_NEXT_STEP\`.
-- \`streamSpec[X].source.tool = 'list_messages'\` \u2192 \`agentCapabilities.tools.list_messages\` MUST exist. Cross-ref code: \`CTR_REF_STREAM_SOURCE\`.
-- The catalog entry's schemas MUST be a superset of the referencing spec's schema. Cross-ref code: \`CTR_SCHEMA_INCOMPAT\`.
-
-## clientCapabilities \u2014 registered catalog
-
-${gadgetsSection}
-
-Each hook conforms to \`GadgetHook<TOutput, TOptions>\`: call \`start(opts?)\` to fire, read \`{value, status, error, stop?}\`. \`status\` walks through \`idle \u2192 prompting \u2192 active|completed\` or routes to \`denied\` / \`error\` on failure.
-
-3rd-party plugins (Leaflet maps, Mapbox, Stripe, Chart.js, \u2026) are registered via \`createGguiGadget\` from \`@ggui-ai/gadgets\` and surface in this same table when the operator has added them to \`App.gadgets\`. Reference any registered hook by name \u2014 render validation rejects hooks not in this catalog with \`gadget_not_registered\`.
-
-## Observable state via \`contextSpec\`
-
-When the contract declares \`contextSpec\`, the boilerplate auto-generates one \`useGguiContext\` call per slot at the top of your component. The runtime owns the underlying \`useState\` and the Provider tree \u2014 **you do NOT write \`useState\` or any \`<Provider>\` wrap yourself**:
-
-\`\`\`tsx
-import { useGguiContext } from '@ggui-ai/wire';
-
-export default function Component(props: Props) {
-  // AUTO-GENERATED \u2014 do not remove or rename:
-  const [currentStep, setCurrentStep] = useGguiContext<number>('currentStep');
-  const [draftText, setDraftText] = useGguiContext<string>('draftText');
-
-  // Plain JSX. No Provider wrap. The runtime already wrapped your
-  // component in nested SingleSlotProviders before this code ran.
-  return (
-    <Container>
-      <Text>Step {currentStep}</Text>
-      <Input value={draftText} onChange={(e) => setDraftText(e.target.value)} />
-      <Button onClick={() => setCurrentStep((s) => s + 1)}>Next</Button>
-    </Container>
-  );
-}
-\`\`\`
-
-For every declared slot you have **\`slotName\` + \`setSlotName\`** in scope:
-- **Read** the value to render: \`<Text>Step {currentStep}</Text>\`
-- **Write** via the setter: \`setCurrentStep(s => s + 1)\` (in callbacks, effects, anywhere)
-
-Every value change is mirrored to the host LLM's context automatically (debounced, default 300ms \u2014 adjustable per-slot via \`entry.debounceMs\` in the contract). The agent sees the user's interaction state \u2014 drafts, current step, hover, selection \u2014 without you calling any API.
-
-**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={e => setDraftText(e.target.value)}>\` so the agent sees the typing live. If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
-
-**When NOT to use it.** Local UI state the contract did NOT declare \u2014 \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
-
-**\`contextSpec\` direction is one-way: client \u2192 agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` \u2014 there is no return path.
-
-**Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.
+` + [
+    PROTOCOL_NOTES,
+    CONTRACT_SURFACE,
+    DEFENSIVE_CODING,
+    GESTURE_ROUTING,
+    INTERACTIVE_TRAITS,
+    ANTI_PATTERNS,
+    CROSS_REFERENCE_RULES,
+    renderGadgetCatalogSection(gadgetsSection),
+    CONTEXT_SPEC_SECTION
+  ].join("\n\n") + `
 
 ${pitfallsBlock}
 
@@ -13570,7 +14153,7 @@ ${designSystemDocs}
 ${primitivesDoc}
 `;
 }
-var DESIGN_SYSTEM_GUIDANCE = `## Imports & Component Surface
+var DESIGN_SYSTEM_GUIDANCE_SURFACE_AND_TOKENS = `## Imports & Component Surface
 
 Import ONLY from: \`react\`, \`@ggui-ai/design\`, \`@ggui-ai/wire\`. The ENTIRE design system \u2014 every primitive, component, composition and trait \u2014 is exported from the single \`@ggui-ai/design\` entry: \`import { Card, Grid, Stack, Modal, Clickable } from '@ggui-ai/design'\`. There are NO subpaths (\`/primitives\`, \`/components\`, \u2026) \u2014 never import from them. Use the design components \u2014 DO NOT use raw HTML elements (\`<button>\`, \`<input>\`, \`<div>\` for layout) or Tailwind classes; those render unstyled in the iframe runtime.
 
@@ -13605,7 +14188,7 @@ EXACT primitive prop values (other values are silently ignored \u2014 the design
 - \`<Grid columns={N} gap="md">\` \u2014 2-D layout (rows AND columns). Reach for it for card galleries, stat grids and dashboards \u2014 NEVER hand-roll \`style={{ display: 'grid' }}\`. When the request names exact per-breakpoint counts ("3 per row on desktop, 1 on mobile"), pass a map: \`<Grid columns={{ base: 1, md: 3 }}>\` (breakpoints \`sm\`/\`md\`/\`lg\`/\`xl\`; the design system emits the media queries). For an open-ended gallery where any column count is fine, use \`<Grid minColumnWidth={220}>\` \u2014 it fits as many equal columns as the width allows. \`radius\` (Card / Box / Image) takes the scale \`none | sm | md | lg | xl\`.
 - \`<Stat label="\u2026" value="\u2026" delta="+12%" trend="up">\` \u2014 KPI display (label + big value + trend-coloured delta + optional \`icon\`). \`trend\` is \`up | down | neutral\` (delta renders green / red / muted). Reach for it for any "show a number" UI; drop several into a \`<Grid>\` for a stat grid instead of hand-building label+value pairs.
 - \`<Stepper steps={STEPS} current={step} />\` \u2014 display-only step indicator for wizards/checkouts. \`steps\` is a top-level \`const\` array of labels; \`current\` is YOUR zero-indexed \`useState\` value; \`orientation\` is \`horizontal | vertical\`; optional \`onStepClick={(i) => \u2026}\` makes steps clickable. Stepper never owns navigation state \u2014 your Next/Back handlers move \`current\`.
-- \`<Badge variant="...">\` \u2014 \`default | primary | secondary | success | warning | error | info\` for colored pills. Great for status/condition labels. There is NO \`neutral\` variant \u2014 use \`default\` (or \`secondary\`) for an un-tinted pill.
+- \`<Badge variant="...">\` \u2014 \`default | primary | secondary | tertiary | success | warning | error | info\` for colored pills. Great for status/condition labels. There is NO \`neutral\` variant \u2014 use \`default\` (or \`secondary\`) for an un-tinted pill.
 
 **Color choice rule of thumb.** Reach for typed slots first: Button \`variant\`, Badge \`variant\`, Alert \`variant\`, Text/Heading/Icon/Spinner/Link/Divider \`tone\`, Box/Card \`surface\`. NEVER hardcode hex \`#XXXXXX\`, rgba, or hsl \u2014 tier-0 self-check rejects them with \`tokens:hex-color\` / \`tokens:hardcoded-color-fn\` and the LLM must remediate. Hardcoded colors break the operator's theme switch (Indigo \u2192 Claudic \u2192 Cyberpunk preset has zero effect on a card hardcoded with \`background: '#000'\`).
 
@@ -13638,8 +14221,8 @@ MANDATORY:
 
 Token categories:
 - Brand: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
-- Text: \`var(--ggui-color-onSurface)\`, \`var(--ggui-color-onSurfaceVariant)\`
-- Backgrounds: \`var(--ggui-color-surface)\`, \`var(--ggui-color-surfaceVariant)\`
+- Text: \`var(--ggui-color-onContainer)\`, \`var(--ggui-color-onSunken)\`
+- Backgrounds: \`var(--ggui-color-container)\`, \`var(--ggui-color-sunken)\`
 - Borders: \`var(--ggui-color-outline)\`
 - Spacing: \`var(--ggui-spacing-4)\`, \`var(--ggui-spacing-6)\`
 - Typography: \`var(--ggui-font-size-sm)\`, \`var(--ggui-font-weight-semibold)\`
@@ -13660,7 +14243,7 @@ Use the FULL primary palette throughout the component \u2014 NOT only on submit
 | Buttons, CTAs, filled interactive elements | \`primary-600\` / \`primary-700\` | Primary actions |
 | Headings on light primary backgrounds | \`primary-800\` / \`primary-900\` | High-contrast branded text |
 
-Use semantic tokens (\`onSurface\`, \`onSurfaceVariant\`) for body text and secondary info. NEVER use raw \`neutral-*\` or \`gray-*\` for body text \u2014 they break in dark themes.
+Use the layering roles' inks (\`onContainer\` for body text on a card, \`onSunken\` for secondary text, captions, labels) \u2014 never raw neutrals. NEVER use raw \`neutral-*\` or \`gray-*\` for body text \u2014 they break in dark themes.
 
 ### Theme-Agnostic Design
 
@@ -13669,7 +14252,7 @@ Components MUST be theme-agnostic \u2014 they reference CSS variables but NEVER
 DO:
 - Use \`var(--ggui-color-primary-*)\` for brand elements \u2014 the theme controls what "primary" means
 - Use \`var(--ggui-shape-shadow-*)\` for depth, \`var(--ggui-shape-radius-*)\` for corners
-- Use semantic color roles: primary for brand, surface/onSurface for structure, success/error/warning for state
+- Use semantic color roles: primary for brand; the layering roles (ground / container / elevated / sunken + their on* inks) for structure; success/error/warning for state
 
 DON'T:
 - Don't assume primary is blue \u2014 could be red, green, purple
@@ -13690,59 +14273,8 @@ Generated components become reusable blueprints \u2014 the same blueprint serves
 2. Relative/fluid units \u2014 prefer \`%\`, \`em\`, \`rem\`, \`min()\`, \`max()\`, \`clamp()\` over fixed \`px\`.
 3. Fluid widths \u2014 \`max-width\` with \`width: 100%\`. Never set a fixed width.
 4. Compact padding \u2014 components are embedded in containers that provide their own chrome.
-5. No raw \`@media\` queries in component code \u2014 for a layout that must change by breakpoint, use \`<Grid columns={{ base: 1, md: 3 }}>\` (the design system emits the media queries for you) or a fluid \`minColumnWidth\` grid.
-
-## Data Parameterization (CRITICAL)
-
-Generated components are CACHED blueprints reused across requests. NEVER hardcode request-specific data (names, cities, numbers, dates) into the component body. Define data as default prop values so the blueprint works for ANY similar request:
-
-\`\`\`tsx
-// BAD \u2014 hardcoded, only works for Tokyo
-const city = "Tokyo";
-const temp = 18;
-
-// GOOD \u2014 parameterized via props with defaults from the request
-interface Props {
-  city?: string;
-  temperature?: number;
-}
-export default function WeatherCard({ city = "Tokyo", temperature = 18 }: Props) {
-  // A controller can override for Seoul, Paris, etc.
-}
-\`\`\`
-
-Rules:
-1. All request-specific data \u2192 props with defaults. City names, tickers, user names, dates, counts.
-2. Layout and styling are universal. Colors, spacing, structure \u2014 these are the reusable part.
-3. Default values come from the current request \u2014 so the component renders correctly standalone.
-4. Props interface must be typed and exported.
-
-## Component Structure
-
-Keep JSX nesting depth to 3\u20135 levels. When deeper, extract repeated/complex sections into helper components \u2014 named functions defined above the main Component in the same file. Helpers take data + callbacks via props; they don't own state.
-
-\`\`\`tsx
-import { useState } from 'react';
-import { Container, Card, Stack, Text, Button, Input } from '@ggui-ai/design';
-
-interface Props {
-  onSubmit?: (data: unknown) => void;
-}
-
-function ItemCard({ item, onEdit }: { item: Item; onEdit: (id: string) => void }) {
-  return <Card padding="md">\u2026</Card>;
-}
-
-export default function GeneratedComponent({ onSubmit }: Props) {
-  return (
-    <Container>
-      {items.map((item) => <ItemCard key={item.id} item={item} onEdit={handleEdit} />)}
-    </Container>
-  );
-}
-\`\`\`
-
-## Aesthetic Guidance (READ CAREFULLY \u2014 this is what separates "polished" from "ok")
+5. No raw \`@media\` queries in component code \u2014 for a layout that must change by breakpoint, use \`<Grid columns={{ base: 1, md: 3 }}>\` (the design system emits the media queries for you) or a fluid \`minColumnWidth\` grid.`;
+var DESIGN_SYSTEM_GUIDANCE_AESTHETICS_AND_CHECKLIST = `## Aesthetic Guidance (READ CAREFULLY \u2014 this is what separates "polished" from "ok")
 
 ### Visual hierarchy \u2014 the SCALE GAP rule
 
@@ -13764,11 +14296,11 @@ A polished UI has ONE hero that dominates. Everything else supports it. Bad layo
 ### Color discipline \u2014 the 60/30/10 rule
 
 Don't paint everything in primary. Use:
-- **60% surface** (\`var(--ggui-color-surface)\` / \`onSurface\`) \u2014 body text, default backgrounds, structure
-- **30% surfaceVariant + onSurfaceVariant** \u2014 secondary text, captions, labels, dividers
+- **60% container** (\`var(--ggui-color-container)\` / \`onContainer\`) \u2014 body text, default backgrounds, structure
+- **30% sunken + onSunken** \u2014 wells, secondary text, captions, labels, dividers
 - **10% primary** \u2014 hero number, ONE highlight element, CTAs, brand accent
 
-If your component is 100% purple text on purple backgrounds, you've lost the eye. Headings can be \`onSurface\` (dark neutral) \u2014 they'll still feel weighty. Save the primary palette for one or two STAR moments.
+If your component is 100% purple text on purple backgrounds, you've lost the eye. Headings can be \`onContainer\` (the card's ink) \u2014 they'll still feel weighty. Save the primary palette for one or two STAR moments.
 
 \`\`\`tsx
 // BAD \u2014 everything purple, eye has no anchor
@@ -13777,7 +14309,7 @@ If your component is 100% purple text on purple backgrounds, you've lost the eye
 <Text tone="emphasized">all body text</Text>
 
 // GOOD \u2014 hero pops, body is neutral, primary is reserved
-<Heading>Title</Heading>  {/* defaults to onSurface */}
+<Heading>Title</Heading>  {/* defaults to onContainer */}
 <Text size="4xl" weight="bold" tone="emphasized">42</Text>
 <Text tone="muted">all body text</Text>
 \`\`\`
@@ -13835,6 +14367,12 @@ Hero sections should feel airy. Use \`padding="xl"\` (32px) on the main card, no
 - [ ] Live/streaming regions wrapped in \`aria-live="polite"\`
 - [ ] Headings nest \u2014 one \`level={1}\`, then \`level={2}\`/\`{3}\` \u2014 never skipped or inverted
 - [ ] Wire hooks (\`useAction\`, \`useStream\`) imported from \`@ggui-ai/wire\` and consumed`;
+var DESIGN_SYSTEM_GUIDANCE = [
+  DESIGN_SYSTEM_GUIDANCE_SURFACE_AND_TOKENS,
+  DATA_PARAMETERIZATION,
+  COMPONENT_STRUCTURE,
+  DESIGN_SYSTEM_GUIDANCE_AESTHETICS_AND_CHECKLIST
+].join("\n\n");
 
 // src/tools.ts
 var APPLY_CHANGES_TOOL = {
@@ -14146,6 +14684,7 @@ function pickWorkflow(_classification) {
 
 // src/create-harness.ts
 init_policy();
+init_design_mode();
 var HARNESS_VERSION = "harness@1";
 var HOW_VERSION = "how@1";
 var WHAT_VERSION = "what@1";
@@ -14165,13 +14704,16 @@ function countCacheTiers(fragments) {
 function createHarness(input) {
   const { classification, contract, prompt, shellType, screen, overrides } = input;
   const ctx = { classification, contract, prompt };
+  const designMode = input.designMode ?? DEFAULT_DESIGN_MODE;
   const composed = compose(classification);
   const systemPromptBuilder = input.systemPromptBuilder ?? buildSystemPrompt;
   const systemPrompt = systemPromptBuilder({
     userRequest: prompt,
     shellType,
     screen,
-    axisDelta: composed.promptText
+    axisDelta: composed.promptText,
+    designMode,
+    ...input.canvas !== void 0 ? { canvas: input.canvas } : {}
   });
   const howFragments = composed.fragments.filter(
     (f) => f.promptText && f.promptText.trim().length > 0
@@ -14189,7 +14731,8 @@ function createHarness(input) {
     shellType,
     screen,
     composed.boilerplateSections,
-    input.appGadgets
+    input.appGadgets,
+    designMode
   );
   const whatFragments = composed.fragments.filter(
     (f) => f.boilerplateMarker && f.boilerplateMarker.trim().length > 0
@@ -14240,6 +14783,7 @@ function createHarness(input) {
   if (overrides?.process) overrideLabels.push("process");
   if (overrides?.label) overrideLabels.push(`label:${overrides.label}`);
   if (!isDefaultHarnessPolicy(policy)) overrideLabels.push("policy");
+  if (designMode !== DEFAULT_DESIGN_MODE) overrideLabels.push(`designMode:${designMode}`);
   const id = computeHarnessId({
     classificationHash,
     howVersion: how.version,
@@ -14267,6 +14811,7 @@ function createHarness(input) {
     id,
     name,
     classification,
+    designMode,
     how,
     what,
     check,
@@ -14410,7 +14955,7 @@ ${bullets}`;
 }
 
 // src/harness/runtime.ts
-function buildSystemPrompt2(userRequest, shellType, screen, axisDelta, appGadgets, gadgetTypes) {
+function buildSystemPrompt2(userRequest, shellType, screen, axisDelta, appGadgets, gadgetTypes, designMode, canvas) {
   return buildSystemPrompt({
     userRequest,
     shellType,
@@ -14421,7 +14966,9 @@ function buildSystemPrompt2(userRequest, shellType, screen, axisDelta, appGadget
     primitivesDoc: PRIMITIVES_DOCUMENTATION,
     wireDoc: WIRE_DOCUMENTATION,
     appGadgets,
-    gadgetTypes
+    gadgetTypes,
+    designMode,
+    canvas
     // criteriaBlock left undefined — ui-gen fills default from open CRITERIA.
   });
 }
@@ -15576,6 +16123,7 @@ var stepperAdopted = {
   values: ["multi-step"],
   run(input) {
     if (input.compiledCode === null) return [];
+    if (input.designMode === "free") return [];
     if (/<Stepper[\s/>]/.test(input.sourceCode)) return [];
     return [
       mkIssue2(
@@ -17472,6 +18020,7 @@ function getSoftWarnings(code) {
 // src/coding-agent/tools.ts
 init_check();
 init_validation();
+init_design_mode();
 function getComponentDocumentation(name) {
   const marker = `### ${name}`;
   const startIdx = PRIMITIVES_DOCUMENTATION.indexOf(marker);
@@ -17482,7 +18031,7 @@ function getComponentDocumentation(name) {
   const section = nextMarker === -1 ? PRIMITIVES_DOCUMENTATION.slice(startIdx) : PRIMITIVES_DOCUMENTATION.slice(startIdx, nextMarker);
   return section.replace(/\\n/g, "\n").replace(/\\"/g, '"').slice(0, 3e3);
 }
-async function autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes) {
+async function autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode = DEFAULT_DESIGN_MODE) {
   const commitStart = Date.now();
   const raw = workspace.read();
   if (!raw && raw !== "") {
@@ -17519,7 +18068,8 @@ async function autoCommit(workspace, commitMeta, message, contract, contextPolic
     formatted,
     contract,
     buildResult2.errors,
-    gadgetTypes
+    gadgetTypes,
+    designMode
   );
   const tier0Fails = tier0Issues.filter((i) => i.result === "fail");
   const selfCheckPassed = tier0Fails.length === 0;
@@ -17564,7 +18114,7 @@ ${errors.join("\n")}
 Fix the issues.`
   };
 }
-async function executeTool(workspace, tool, input, commitMeta, contract, applyPatch2, contextPolicy, gadgetTypes) {
+async function executeTool(workspace, tool, input, commitMeta, contract, applyPatch2, contextPolicy, gadgetTypes, designMode = DEFAULT_DESIGN_MODE) {
   switch (tool) {
     case "write":
     case "rewrite": {
@@ -17583,7 +18133,7 @@ async function executeTool(workspace, tool, input, commitMeta, contract, applyPa
       const lineCount = code.split("\n").length;
       const message = input.commit_message || `write ${lineCount} lines`;
       console.log(`[coding-agent] write: ${lineCount} lines \u2192 auto-commit`);
-      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes);
+      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode);
     }
     case "apply_changes": {
       const currentFile = workspace.read();
@@ -17758,7 +18308,7 @@ The file now reflects your latest patch. Submit a follow-up apply_changes target
       await workspace.stage();
       const message = input.commit_message || "apply changes";
       console.log(`[coding-agent] apply_changes: ${changes.length} changes applied \u2192 auto-commit`);
-      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes);
+      return autoCommit(workspace, commitMeta, message, contract, contextPolicy, gadgetTypes, designMode);
     }
     case "get_components_info": {
       const names = input.names ?? [];
@@ -18214,7 +18764,10 @@ ${iconNamesCache}`;
     // Forward the third-party wrapper `.d.ts` map so autoCommit's
     // typecheck overlays the real wrapper declarations and a generated
     // direct gadget import gets strict option/return narrowing.
-    harness.what.gadgetTypes
+    harness.what.gadgetTypes,
+    // Which tier-0 legs fire — the design-vocabulary legs stand down in
+    // `free` mode; every contract leg runs in both.
+    harness.designMode
   );
   const toolMs = Date.now() - toolStart;
   if (forceEscape && ctx.dupeBreak && call.name === "apply_changes") {
@@ -18625,7 +19178,11 @@ async function runEvalRound(ctx, input) {
         {
           sourceCode: currentSource,
           originalPrompt: userPrompt,
-          contract
+          contract,
+          // Criteria + mother prompt follow the triad that produced
+          // the source (free mode: color-only tokens, arm-neutral
+          // visual judging).
+          designMode: harness.designMode
         },
         {
           provider: mapProviderForEvaluator(evaluationAgent.provider),
@@ -18654,6 +19211,8 @@ async function runEvalRound(ctx, input) {
           passThreshold: visualThreshold,
           sampleProps: visualEvaluation?.sampleProps,
           viewport: visualEvaluation?.viewport,
+          // Per-canvas judging (arm-neutral) — absent = single shot.
+          ...visualEvaluation?.canvases !== void 0 ? { canvases: visualEvaluation.canvases } : {},
           // #484/#489 — same threading as the LLM-eval leg above:
           // the visual eval's multimodal call runs inside the same
           // concurrent generation, so it needs the same routing
@@ -18667,7 +19226,8 @@ async function runEvalRound(ctx, input) {
     ]);
     evalLlmMs = Date.now() - evalLlmStart;
     llmResult = llm;
-    visualIssues = visual;
+    visualIssues = visual?.issues ?? null;
+    const visualSummary = visual?.summary;
     if (llmResult) {
       costTracker.record(evaluationAgent.model, llmResult.inputTokens, llmResult.outputTokens);
       evalTokens = {
@@ -18684,7 +19244,11 @@ async function runEvalRound(ctx, input) {
     evalResult = {
       issues: allIssues,
       pass: allPass,
-      ...llmResult?.criteriaCoverage !== void 0 ? { criteriaCoverage: llmResult.criteriaCoverage } : {}
+      ...llmResult?.criteriaCoverage !== void 0 ? { criteriaCoverage: llmResult.criteriaCoverage } : {},
+      // Per-canvas visual summary — present only when canvases were
+      // requested and the leg ran; every later re-stamp spreads this
+      // base so it survives to the assembled result.
+      ...visualSummary !== void 0 ? { visual: visualSummary } : {}
     };
     const fails = allIssues.filter((i) => i.result === "fail");
     const warns = allIssues.filter((i) => i.result === "warn");
@@ -19328,7 +19892,8 @@ async function initSession(input) {
           sourceCode: "",
           originalPrompt: params.userPrompt,
           contract: params.contract,
-          designContext: void 0
+          designContext: void 0,
+          designMode: harness.designMode
         },
         {
           provider: mapProviderForEvaluator(evalSpec.provider),
@@ -19391,6 +19956,7 @@ async function initSession(input) {
 }
 
 // src/adapters/generation-dispatch.ts
+init_design_mode();
 function mapProviderForLLMRouter(provider) {
   return provider === "claude" ? "anthropic" : provider;
 }
@@ -19450,6 +20016,9 @@ async function dispatchGeneration(params) {
     // systemPromptBuilder closure below also captures `gadgetTypes`
     // from `params` directly for the prompt `Type:` lines.
     ...params.gadgetTypes !== void 0 ? { gadgetTypes: params.gadgetTypes } : {},
+    // Design mode + canvas — the harness carries them to every leg.
+    ...params.designMode !== void 0 ? { designMode: params.designMode } : {},
+    ...params.canvas !== void 0 ? { canvas: params.canvas } : {},
     // Policy is pre-resolved at the dispatch boundary so `createHarness`
     // stays free of experiment plumbing. `resolveHarnessPolicy` applies
     // the `GGUI_POLICY_PROFILE` experimental-profile layer and hands the
@@ -19469,13 +20038,15 @@ async function dispatchGeneration(params) {
     // prompt's gadget catalog renders a `Type:` line per third-party
     // gadget (the LLM sees a wrapper's real call shape it otherwise
     // can't know).
-    systemPromptBuilder: ({ userRequest, shellType, screen, axisDelta }) => buildSystemPrompt2(
+    systemPromptBuilder: ({ userRequest, shellType, screen, axisDelta, designMode, canvas }) => buildSystemPrompt2(
       userRequest,
       shellType,
       screen,
       axisDelta,
       params.appGadgets,
-      params.gadgetTypes
+      params.gadgetTypes,
+      designMode,
+      canvas
     ),
     // Pre-filtered axis-check registry. The `matches()` predicate
     // selects the checks relevant to this generation's axis vector.
@@ -19619,11 +20190,21 @@ Your plan is a commitment, not a design doc. Keep it tight. Do not over-plan; ju
     );
   }
   const finalSource = runResult.finalSource ?? "";
-  return assembleGenerationResult({ session, telemetry, source: finalSource });
+  const result = await assembleGenerationResult({ session, telemetry, source: finalSource });
+  return withArmRecord(result, params);
+}
+function withArmRecord(result, params) {
+  const recordedCanvas = params.canvas ?? (params.designMode === "free" ? canvasForRendering(params.shellType, params.screen) : void 0);
+  return {
+    ...result,
+    ...params.designMode !== void 0 ? { designMode: params.designMode } : {},
+    ...recordedCanvas !== void 0 ? { canvas: recordedCanvas } : {}
+  };
 }
 
 // src/contract-context.ts
 init_check();
+init_design_mode();
 var SHELL_HINTS = {
   chat: `**Chat Shell \u2014 Inline card in scrolling conversation**
 - Container: width varies (60-80% of viewport), height: auto (natural content height)
@@ -19657,6 +20238,20 @@ var DEVICE_HINTS = {
   desktop: `**Desktop:** Multi-column. Hover states. Dense layouts. Keyboard shortcuts. Pointer interactions.`,
   spatial: `**Spatial:** Fixed-size floating panel (~600x400). High contrast. Large text. No hover (gaze/hand input).`
 };
+function canvasForRenderingContext(ctx) {
+  const mode = canvasDisplayModeForShell(ctx.shell);
+  if (mode === "inline") return "xs-chat-card";
+  if (ctx.viewport) return canvasForViewportWidth(mode, ctx.viewport.width);
+  switch (ctx.device) {
+    case "mobile":
+      return "mobile-fullscreen-small";
+    case "tablet":
+    case "spatial":
+      return "md";
+    case "desktop":
+      return ctx.shell === "partial" ? "md" : "lg";
+  }
+}
 function buildRenderingContext(ctx) {
   const parts = [
     "## Rendering Context",
@@ -19856,7 +20451,7 @@ function injectVariance(userPrompt, variance) {
 // src/create-ui-generator.ts
 init_provider_router();
 var DEFAULT_TIER = "default";
-var DEFAULT_MODEL = "haiku-4-5";
+var DEFAULT_MODEL = "anthropic/claude-haiku-4-5";
 function createUiGenerator(options = {}) {
   const {
     enableRuntimeRender = false,
@@ -19865,7 +20460,9 @@ function createUiGenerator(options = {}) {
     qualityConfig,
     gadgetCatalog,
     disableEnvMutation = false,
-    onRetry
+    onRetry,
+    onGenerated,
+    designMode
   } = options;
   const identity = resolveIdentity(options);
   return {
@@ -19916,6 +20513,7 @@ function createUiGenerator(options = {}) {
         });
         const rendering = mapRendering(input.rendering);
         const promptWithRendering = rendering ? injectRenderingContext(input.request.prompt, rendering) : input.request.prompt;
+        const canvas = rendering ? canvasForRenderingContext(rendering) : void 0;
         const promptWithVariance = injectVariance(
           promptWithRendering,
           input.variance
@@ -19944,12 +20542,15 @@ function createUiGenerator(options = {}) {
           ...input.gadgetTypes !== void 0 ? { gadgetTypes: input.gadgetTypes } : {},
           enableRuntimeRender,
           ...routeOverride !== void 0 ? { routeOverride } : {},
-          ...onRetry !== void 0 ? { onRetry } : {}
+          ...onRetry !== void 0 ? { onRetry } : {},
+          ...designMode !== void 0 ? { designMode } : {},
+          ...canvas !== void 0 ? { canvas } : {}
         });
+        onGenerated?.(result);
         const metadata = {
           provider: input.llm.provider,
           generator: identity.slug,
-          model: input.llm.model,
+          model: modelRefOfRoute(input.llm),
           inputTokens: result.tokens.input,
           outputTokens: result.tokens.output,
           latencyMs: Date.now() - startedAt,
@@ -19985,7 +20586,7 @@ function createUiGenerator(options = {}) {
           metadata: {
             provider: input.llm.provider,
             generator: identity.slug,
-            model: input.llm.model,
+            model: modelRefOfRoute(input.llm),
             inputTokens: 0,
             outputTokens: 0,
             latencyMs: Date.now() - startedAt,
@@ -20003,24 +20604,24 @@ function createUiGenerator(options = {}) {
 }
 function resolveIdentity(opts) {
   const hasSlug = typeof opts.slug === "string" && opts.slug.length > 0;
-  const hasTierOrModel = opts.tier !== void 0 || opts.model !== void 0;
-  if (hasSlug && hasTierOrModel) {
+  if (hasSlug && opts.tier !== void 0) {
     throw new Error(
-      "createUiGenerator: pass either { slug } or { tier, model } \u2014 not both."
+      "createUiGenerator: pass either { slug } or { tier } \u2014 not both."
     );
   }
+  const model = opts.model ?? DEFAULT_MODEL;
   if (hasSlug) {
-    const parsed = parseGeneratorSlug(opts.slug);
-    if (!parsed) {
+    const slug2 = opts.slug;
+    const parsed = parseGeneratorSlug(slug2);
+    if (!parsed || !isGeneratorId(slug2)) {
       throw new Error(
-        `createUiGenerator: slug ${JSON.stringify(opts.slug)} is not a valid ui-gen-<tier>-<model> identifier.`
+        `createUiGenerator: slug ${JSON.stringify(slug2)} is not a valid ui-gen-<tier> identifier.`
       );
     }
-    return { slug: opts.slug, tier: parsed.tier, model: parsed.model };
+    return { slug: slug2, tier: parsed.tier, model };
   }
   const tier = opts.tier ?? DEFAULT_TIER;
-  const model = opts.model ?? DEFAULT_MODEL;
-  const slug = formatGeneratorSlug({ tier, model });
+  const slug = formatGeneratorSlug({ tier });
   if (!isValidGeneratorSlug(slug)) {
     throw new Error(
       `createUiGenerator: formatted slug ${JSON.stringify(slug)} round-trips as invalid \u2014 formatGeneratorSlug/isValidGeneratorSlug drift.`
@@ -20056,7 +20657,7 @@ function failWithoutMetadata(input, generatorSlug, startedAt, error) {
     metadata: {
       provider: input.llm.provider,
       generator: generatorSlug,
-      model: input.llm.model,
+      model: modelRefOfRoute(input.llm),
       inputTokens: 0,
       outputTokens: 0,
       latencyMs: Date.now() - startedAt,
@@ -20210,8 +20811,9 @@ function stringifyError(err) {
 }
 
 // src/index.ts
+init_design_mode();
 init_client();
 
-export { CompileComponentCodeError, buildContractsContext, buildRenderingContext, buildVarianceContext, compileComponentCode, createAnthropicClient, createUiGenerator, extractComponentCode, injectContracts, injectRenderingContext, injectVariance, withBrowserCompile };
+export { CANVAS_BREAKPOINTS, CANVAS_CLASSES, CANVAS_DESCRIPTORS, CANVAS_VIEWPORTS, CompileComponentCodeError, DEFAULT_DESIGN_MODE, DESIGN_MODES, buildContractsContext, buildRenderingContext, buildVarianceContext, canvasDisplayModeForShell, canvasForRendering, canvasForRenderingContext, canvasForViewportWidth, compileComponentCode, createAnthropicClient, createUiGenerator, describeCanvas, extractComponentCode, injectContracts, injectRenderingContext, injectVariance, withBrowserCompile };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map