@gradeui/ui 2.1.0 → 3.1.0

package/README.md

@@ -27,23 +27,16 @@ export default function Example() {
 }
 ```
 
-### Tailwind preset
+### Styles
 
-If you're using Tailwind in your consuming app, extend the Grade preset so brand tokens and OKLCH semantic colors resolve correctly:
+Import the compiled stylesheet once (e.g. in your root layout). It is fully self-contained — design tokens, the native Tailwind v4 `@theme` bridge, and every utility the components use are baked in; there is no JS Tailwind config to extend (the old `@gradeui/ui/tailwind-preset` export was retired with the v4 native-@theme migration):
 
 ```ts
-// tailwind.config.ts
-import gradePreset from "@gradeui/ui/tailwind-preset";
-
-export default {
-  presets: [gradePreset],
-  content: [
-    "./app/**/*.{ts,tsx,mdx}",
-    "./node_modules/@gradeui/ui/dist/**/*.{js,mjs}",
-  ],
-};
+import "@gradeui/ui/styles.css";
 ```
 
+If your app runs its own Tailwind v4 build alongside Grade, add a `@source` for `node_modules/@gradeui/ui/dist` so your scan picks up the library's class names — the brand and semantic tokens themselves already ship in the stylesheet as CSS variables (`--gds-*`, OKLCH role triplets).
+
 ## Theme engine
 
 `@gradeui/ui` ships an OKLCH-based theme generator. Wrap your app in `GradeThemeProvider` (currently still named `GradeThemeProvider` pending rename — see upstream TODO) to get runtime theme switching.

package/components/ui/button.md

@@ -4,12 +4,13 @@ import: "@gradeui/ui"
 variants: [default, destructive, outline, secondary, ghost, link, raised]
 sizes: [sm, md, lg, icon]
 props:
-  - variant? (default | destructive | outline | secondary | ghost | link | raised)
+  - variant? (default | destructive | outline | secondary | ghost | link | raised) — `raised` here is a back-compat alias (the raised TRAIT on a neutral key surface); prefer the `raised` prop
+  - raised?: boolean — presence TRAIT: tactile elevation (bevel + drop + hover glow + pressed sink) layered onto ANY variant — raised primary, raised outline, etc. Glow tone reads --btn-glow → --accent-glow → --selected-glow; override per-button via style={{ "--btn-glow": "var(--warning)" }}
   - size? (sm | md | lg | icon) — t-shirt scale aligned with Tabs/ToggleGroup heights (sm=h-7, md=h-8, lg=h-10). `default` still works as an alias for `md`.
   - asChild?: boolean — renders as the child element (use to wrap <a>/<Link>)
   - disabled?: boolean
   - All native button HTML attrs (onClick, type, etc.)
-when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button, variant="raised" for high-commitment / weighty actions where the chrome can afford a tactile "physical key" treatment. A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
+when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button, the `raised` prop for high-commitment / weighty actions where the chrome can afford a tactile "physical key" treatment (composes with any variant; variant="raised" remains the neutral-key alias). A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
 composes_with: [Dialog, DropdownMenu, Tooltip, Card (in CardFooter), Row, Form controls]
 aliases: [button, push button, plain button, bordered button, destructive button, capsule button, link button, action button, cta, raised button, pill button, key button]
 ---
@@ -32,16 +33,19 @@ aliases: [button, push button, plain button, bordered button, destructive button
 ```
 
 ```jsx
-// Raised variant — tactile bevel + drop shadow + ambient hover glow.
+// Raised TRAIT — tactile bevel + drop shadow + ambient hover glow,
+// layered onto any variant (raised primary, raised outline, ...).
 // Composed from the Presence elevation tokens (--elevation-3 rest,
 // --elevation-hot hover, --elevation-pressed active). Tone is driven
 // by --btn-glow, which defaults to --selected-glow (blue). Override
 // per-button for "traffic light" semantics:
 <Row gap="sm">
-  <Button variant="raised" style={{ "--btn-glow": "var(--warning)" }}>
+  <Button raised>Raised primary</Button>
+  <Button variant="outline" raised>Raised outline</Button>
+  <Button raised style={{ "--btn-glow": "var(--warning)" }}>
     Iterate
   </Button>
-  <Button variant="raised" style={{ "--btn-glow": "var(--success)" }}>
+  <Button raised style={{ "--btn-glow": "var(--success)" }}>
     Ship it
   </Button>
 </Row>
@@ -51,13 +55,13 @@ aliases: [button, push button, plain button, bordered button, destructive button
 // data-state="on" / aria-pressed="true" gives the held-down "key
 // pressed" look — picks up the --selected blue stroke + heat-inner
 // glow. Works as a Toggle/ToggleGroupItem child via asChild.
-<Button variant="raised" data-state="on">Locked</Button>
+<Button raised data-state="on">Locked</Button>
 ```
 
 ```jsx
 // Combine with Aura for AI-attention states. The three Aura styles
 // (ring/gradient/shimmer) stack independently of the variant.
-<Button variant="raised" className="gds-aura-ring">
+<Button raised className="gds-aura-ring">
   Studio is reviewing this
 </Button>
 ```

package/components/ui/dropdown-menu.md

@@ -13,6 +13,7 @@ props:
   - DropdownMenuItem: onSelect?, disabled?, asChild?, inset?
   - DropdownMenuCheckboxItem / DropdownMenuRadioItem: checked? / value, onCheckedChange? / onValueChange? (radio is on the group)
   - DropdownMenuSub / DropdownMenuSubTrigger / DropdownMenuSubContent: nested menu — sub-trigger shows children, sub-content holds the deeper items
+  - DropdownMenuSub: open?, defaultOpen?, onOpenChange? — nested-menu open state (Radix passthrough); pass `open` to compose a pre-opened submenu in static screens and captures
   - DropdownMenuShortcut: children — right-aligned kbd hint
 when_to_use: A small action menu attached to a trigger — overflow "…" buttons on cards, user-avatar menus in headers, "Insert" menus in editors. For a full searchable list, use Command. For ONE primary action plus a secondary, use a Button next to a smaller ghost Button instead of a dropdown.
 composes_with: [Button (as trigger asChild), Avatar (user menu), Card (overflow on a tile), Tooltip (on the trigger)]

package/components/ui/logo.md

@@ -3,12 +3,14 @@ name: Logo
 import: "@gradeui/ui"
 subcomponents: []
 props:
-  - sources?: LogoSources — artwork keyed by lockup then appearance:
-      { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }.
-      Each slot is any node (inline <svg>, <img>, component). OMIT ENTIRELY
-      and the GRADE MARK renders (the square G-arrow, painted with
-      currentColor so it sits correctly on any surface). A bare <Logo /> is
-      always correct branding.
+  - sources?: LogoSources — artwork keyed by lockup then appearance: { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }. Each slot is any node (inline <svg>, <img>, component). OMIT ENTIRELY and the GRADE MARK renders (the square G-arrow, painted with currentColor so it sits correctly on any surface). A bare <Logo /> is always correct branding.
+  - size? ("sm" | "md" | "lg" | "xl") — height of the mark: 20 / 28 / 40 / 56px (a raw pixel number also works). Width is intrinsic (square/icon 1:1, horizontal keeps its ratio). Default "md"; use "sm" in dense rails and toolbars.
+  - lockup? ("square" | "horizontal" | "icon") — which shape to show; falls back to the next-best available artwork. Default "horizontal".
+  - mode? ("light" | "dark") — the background the logo SITS ON, selecting light/dark artwork. Explicit, not theme-coupled. Default "light".
+  - mono?: boolean — render the single-colour treatment; inherits currentColor from the parent. Default false.
+  - label?: string — accessible name (aria-label + role="img"); pair with decorative when the brand name is already beside it.
+  - decorative?: boolean — aria-hidden, no role; use when text nearby names the brand.
+  - href?: string — renders the logo as a link (logo-links-home).
   - lockup?: "square" | "horizontal" | "icon" (default "horizontal")
   - mode?: "light" | "dark" (default "light") — the background the logo sits on
   - mono?: boolean (default false) — use the single-colour artwork (inherits currentColor)

package/components/ui/map.md

@@ -10,7 +10,10 @@ props:
   - Map: bounds — `[[swLng, swLat], [neLng, neLat]]`. When set, takes precedence over center+zoom.
   - Map: appearance — "light" | "dark" | "satellite" | "auto" (default "auto", follows GradeThemeProvider mode).
   - Map: hoveredId — controlled string id, pairs with onHoveredIdChange. The matching MapMarker gets `data-gds-state="hovered"` automatically. This is how you build list ↔ map two-way sync.
+  - Map: onHoveredIdChange — `(id: string | null) => void`. The other half of the controlled hover pair: fires when the pointer enters/leaves a marker so the sibling list can highlight in step. Without this entry in the contract, screens using the documented two-way sync fail save validation.
   - Map: interactive — false freezes pan/zoom, useful for static cards.
+  - Map: tools — "auto" (default, zoom buttons follow `interactive`) | "zoom" (force zoom buttons) | "none" (chrome-free map; attribution always stays — license). One vocabulary across all providers.
+  - Map: toolsPosition — "top-left" (default) | "top-right" | "bottom-left" | "bottom-right". Corner the tools dock to; use when a search bar or legend sits over the default corner.
   - Map: onLoad(handle) / onError(error) — handle exposes flyTo, panTo, fitBounds, getCenter, getZoom, getBounds, instance.
   - Map: tilerKey? — MapLibre only (provider="maplibre"). Optional everywhere: omit on `gradeui.com`/`localhost` and the referrer-locked demo key is used; set it only when embedding off-domain. The contract never requires it.
   - Map: accessToken? — Mapbox only. Pass it whenever provider="mapbox" — the component itself enforces this at runtime (throws a clear `provider="mapbox" requires an accessToken prop` error via onError if missing). It is OPTIONAL in the contract on purpose, so the validator never demands it from maplibre/google maps.

package/components/ui/media-surface.md

@@ -8,6 +8,7 @@ props:
   - loading?: boolean — renders the muted skeleton overlay
   - hint?: "album" | "portrait" | "landscape" | "poster" | "product" | "food" | "video" | "audio" | "embed" | "3d" | "generic" (default "generic") — picks the placeholder glyph + the default aspect + the future generation provider
   - alt?: string — becomes the eventual `<img alt>`; also drives the placeholder caption and small-tier initials
+  - instanceId?: string — stable per-instance id stamped as `data-gds-instance-id`. Use when rendering MediaSurfaces from a data array (`.map(item => <MediaSurface instanceId={item.id} …/>)`): it's how Studio's selection + Fill flows tell one card apart from its siblings and patch only that entry's data
   - source?: { kind, …per-kind fields } — structured metadata for the generation pipeline. Shapes per kind — album: { artist, title, year? } · poster: { title, year? } · portrait: { name?, role? } · landscape: { location?, mood? } · product: { name?, brand? } · food: { dish?, cuisine? } · generic: { prompt } · video/audio/embed/3d: no fields
   - src?: string — when set, renders an `<img>` filling the slot via object-cover; the wrapper keeps its chrome
   - glyph?: ReactNode — per-instance override of the hint-derived placeholder glyph (escape hatch for unusual slots)

package/components/ui/sidebar.md

@@ -11,7 +11,8 @@ props:
   - SidebarHeader: any children — brand / logo / org switcher; hides nothing when collapsed (centred)
   - SidebarContent: any children — scrollable body
   - SidebarFooter: any children — user block, settings link, pinned chrome
-  - SidebarSection: title?: ReactNode — group label; **uppercase tracking-wide muted** styling auto-applied (Notion / Linear / Slack-style "GAMES", "FAVORITES", "WORKSPACE" headers); hidden when sidebar is collapsed
+  - SidebarSection: title?: ReactNode — group label, tracking-wide muted styling; hidden when sidebar is collapsed. CASE: static (non-collapsible) headers historically render UPPERCASE (Notion / Linear / Slack-style "GAMES", "FAVORITES"); collapsible headers render the authored case. Control it explicitly with titleTransform.
+  - SidebarSection: titleTransform? ("uppercase" | "none") — title casing for BOTH header variants. "none" renders the authored case (sentence-case headers like a "Recents" list); "uppercase" forces the shouty group label. Unset = the per-variant legacy default above.
   - SidebarSection: icon?: ReactNode — optional icon beside the title
   - SidebarSection: trailing?: ReactNode — **action(s) on the right edge of the header** — the canonical "+" / "..." slot (Notion's "+ Add page" next to Pages, Linear's "+" next to Favorites, Slack's "+" next to Channels). Pointer events isolated so a Button here doesn't toggle collapse.
   - SidebarSection: collapsible?: boolean — title acts as expand/collapse trigger with a **chevron indicator** (default true). Set `false` for a static, non-clickable header.

package/components/ui/swatch.md

@@ -0,0 +1,88 @@
+---
+name: Swatch
+import: "@gradeui/ui"
+subcomponents: [SwatchGroup]
+sizes: [xs, sm, md, lg, xl]
+props:
+  - color?: string — any raw CSS colour (`#1f6feb`, `oklch(...)`, `rgb(...)`, or `var(--x)`). Takes precedence over `token`. Use for one-off or external colours.
+  - token?: string — a Grade colour token NAME with no `--` and no `oklch()` wrap; resolved internally to `oklch(var(--<token>))`. THE design-system path — e.g. `token="brand-3"`, `token="primary"`, `token="chart-2"`. Re-voices live when the theme changes.
+  - size? (xs | sm | md | lg | xl) — t-shirt scale, 20px → 56px; default md (32px). Prefer over h-*/w-* utilities.
+  - shape? (square | rounded | circle) — default rounded (rides `--radius`); circle for dot pickers; square for a hard tile.
+  - selected?: boolean — draws the shared selection ring (`--selected`). For palette / accent pickers.
+  - onSelect?: () => void — makes the swatch a pickable <button> (adds aria-pressed, focus ring, hover lift). Omit for a static display chip.
+  - onColorChange?: (value: string) => void — makes the swatch an editable colour well: hosts a native `<input type="color">` (the OS picker) behind the DS chip and fires with the new `#rrggbb`. Presentation stays the chip, interaction stays native. Use for inspector / control-panel colour fields instead of styling a raw colour input. Takes precedence over `onSelect`.
+  - label?: ReactNode — caption rendered beneath the chip; also becomes the accessible name + tooltip.
+  - SwatchGroup: layout? (row | stack) — `row` (default) spaces chips out; `stack` overlaps them into a coin-stack (the theme-picker / "key colours" treatment, where each chip's ring reads as the separating edge).
+  - SwatchGroup: size? / shape? — cascade to every child Swatch so a strip stays consistent without repeating the prop.
+  - SwatchGroup: gap? (xs | sm | md | lg) — spacing between chips in `row` layout; default sm.
+when_to_use: Showing a colour as a small chip — brand-pop strips, palette / accent pickers, theme previews, token galleries, "pick a colour" rows. Reach for `token` to bind to a live theme variable; `color` for raw values. A transparency checkerboard sits behind the fill so semi-transparent values read honestly.
+composes_with: [Row (strip of swatches), Stack, Grid (palette wall), Field (as a colour-picker trailing slot), Card (in a theme-preview), RadioGroup (selectable accent set), Label]
+aliases: [colour swatch, color swatch, colour chip, color chip, palette swatch, token swatch, brand pop, accent swatch, colour tile, color tile, paint chip, react native colour swatch]
+notes: |
+  Anti-patterns to avoid:
+
+  - DO NOT hand-roll a colour chip as a bare `<div className="h-10 w-10 rounded">`
+    with an inline `style={{ background: ... }}`. That is exactly what
+    <Swatch> is — use it so the chip is selectable in Studio, sizes on
+    tokens, and gets the transparency checkerboard + selection ring for free.
+  - DO NOT wrap a token in oklch() yourself for the `token` prop —
+    pass the bare name. `token="brand-3"`, NOT `token="oklch(var(--brand-3))"`.
+    (If you already have a wrapped string, pass it as `color` instead.)
+  - DO NOT size with h-*/w-* utilities — use `size` so the scale stays on
+    the t-shirt tokens.
+  - DO NOT use Swatch for an avatar, status dot, or icon background. It is
+    specifically a COLOUR specimen. A status dot is a tiny Badge/indicator;
+    a person is an Avatar.
+---
+
+```jsx
+// Brand-pop strip — eight live theme accents.
+<SwatchGroup size="lg">
+  {[1, 2, 3, 4, 5, 6, 7, 8].map((n) => (
+    <Swatch key={n} token={`brand-${n}`} />
+  ))}
+</SwatchGroup>
+```
+
+```jsx
+// Theme-picker "key colours" — overlapping coin-stack of circles.
+<SwatchGroup layout="stack" shape="circle" size="md">
+  <Swatch token="background" />
+  <Swatch token="muted" />
+  <Swatch token="primary" />
+  <Swatch token="accent" />
+</SwatchGroup>
+```
+
+```jsx
+// Captioned token chips.
+<Row gap="md" wrap>
+  <Swatch token="primary" label="Primary" />
+  <Swatch token="accent" label="Accent" />
+  <Swatch token="muted" label="Muted" />
+</Row>
+```
+
+```jsx
+// Pickable accent set — selection ring + button semantics.
+<Row gap="sm">
+  {["brand-1", "brand-2", "brand-3", "brand-4"].map((t) => (
+    <Swatch
+      key={t}
+      token={t}
+      shape="circle"
+      selected={t === selectedToken}
+      onSelect={() => setSelectedToken(t)}
+    />
+  ))}
+</Row>
+```
+
+```jsx
+// Raw colour, including a semi-transparent value over the checkerboard.
+<Row gap="sm">
+  <Swatch color="#1f6feb" />
+  <Swatch color="oklch(0.7 0.18 30)" />
+  <Swatch color="rgb(16 185 129 / 0.4)" />
+</Row>
+```