@gradeui/ui 3.2.0 → 3.3.0

package/components/ui/button.md

@@ -2,15 +2,16 @@
 name: Button
 import: "@gradeui/ui"
 variants: [default, destructive, outline, secondary, ghost, link, raised]
-sizes: [sm, md, lg, icon]
+sizes: [2xs, xs, sm, md, lg]
 props:
   - 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`.
+  - size? (2xs | xs | sm | md | lg) — t-shirt scale aligned with Tabs/ToggleGroup heights (2xs=h-5, xs=h-6, sm=h-7, md=h-8, lg=h-10). 2xs/xs are the dense tool-panel sizes (match Figma Button size=2xs/xs). `default` still works as an alias for `md`.
+  - iconOnly?: boolean — squares the button at the current `size` height (w = h, no horizontal padding) for icon-only buttons; the icon child is centered. This is THE way to make a square icon button at any density (sm→28², 2xs→20²).
   - 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, 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.
+when_to_use: Any clickable action. Use `iconOnly` for square icon-only buttons (at any size), 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]
 ---
@@ -18,7 +19,8 @@ aliases: [button, push button, plain button, bordered button, destructive button
 ```jsx
 <Button>Save</Button>
 <Button variant="outline" size="sm">Cancel</Button>
-<Button size="icon" variant="ghost"><Mail /></Button>
+<Button iconOnly variant="ghost"><Mail /></Button>
+<Button size="sm" iconOnly variant="outline"><Plus /></Button>
 ```
 
 ```jsx

package/components/ui/color-picker.md

@@ -0,0 +1,34 @@
+---
+name: ColorPicker
+import: "@gradeui/ui"
+props:
+  - value?: string | null — a Grade colour token NAME ("action/primary"), the literal "transparent", or null when nothing is picked
+  - onValueChange?: (value: string | null) => void — fired with the next value (token name, "transparent", or null)
+  - tokens?: { group, tokens }[] — token families offered in the list; defaults to the Grade semantic set (surface / action / status)
+  - searchable?: boolean — show the search input (default true)
+  - triggerVariant? (default | inline) — default = form-control surface (swatch + name); inline = just a clickable swatch for inspector / fill-row use
+  - placeholder?: string — trigger text when nothing is selected
+  - searchPlaceholder?: string — search-input placeholder
+  - emptyMessage?: string — shown when search returns no rows
+  - allowTransparent?: boolean — include a Transparent option at the top (default true)
+  - align? (start | center | end) — popover alignment (default start)
+  - disabled?: boolean — lock to a read-only display of the current value
+when_to_use: The token-led single-select colour picker — the focused "pick one colour token" sibling of FillPicker's solid tab. Use it anywhere a value is ONE Grade colour token (a fill colour, a border colour, an accent override) rather than a full paint. Composes Popover + Command exactly like Combobox, but each row is a Swatch + the token's short name, grouped by family and searchable. triggerVariant="inline" reduces the trigger to a single clickable swatch — reach for that inside inspectors and the FillSection fill rows. For a full paint (gradient / image / shader) use FillPicker; for a list of fills use FillSection; for a multi-stop gradient use GradientEditor.
+composes_with: [Popover, Command, Swatch, FillSection, GradientEditor, Field, PropertyList]
+aliases: [color picker, colour picker, token picker, colour token picker, color token picker, swatch picker, paint colour, fill colour picker, accent picker, colour dropdown]
+---
+
+```jsx
+// Token-led colour field.
+<ColorPicker value={color} onValueChange={setColor} />
+```
+
+```jsx
+// Inline swatch trigger — the inspector / fill-row affordance.
+<ColorPicker
+  triggerVariant="inline"
+  value={stopColor}
+  onValueChange={setStopColor}
+  aria-label="Stop colour"
+/>
+```

package/components/ui/fill-picker.md

@@ -1,12 +1,16 @@
 ---
 name: FillPicker
 import: "@gradeui/ui"
+subcomponents: [FillSection]
 props:
   - value: FillValue — current paint ({ type, color?, gradient?, src?, fit?, repeat?, tileSize?, preset?, palette?, postPreset?, opacity? }) (required)
   - onChange: (value: FillValue) => void — called on any change (required)
-when_to_use: Grade's paint picker — the control for choosing a frame's background fill, modelled on Figma's fill popover. A fill-type icon row (solid · gradient · image · pattern · video · shader) switches the panel below; a global opacity sits at the foot. Emits a FillValue that maps 1:1 onto BackgroundFill props. This is a Studio/inspector chrome control — pair it with BackgroundFill, which renders the chosen paint. Not for app content.
-composes_with: [BackgroundFill (renders the FillValue), Popover (host it in a popover), ShaderPresetPicker (the shader tab), the inspector Fill section]
-aliases: [fill picker, paint picker, background picker, fill chooser, fill popover]
+  - FillSection: value — FillValue[] — the ordered list of fills to stack as rows
+  - FillSection: onChange — (value: FillValue[]) => void — fired with the next list on add / edit / remove / visibility toggle
+  - FillSection: title?: string — section heading (default "Fills")
+when_to_use: Grade's paint picker — the control for choosing a frame's background fill, modelled on Figma's fill popover. A fill-type icon row (solid · gradient · image · pattern · video · shader) switches the panel below; a global opacity sits at the foot. Emits a FillValue that maps 1:1 onto BackgroundFill props. This is a Studio/inspector chrome control — pair it with BackgroundFill, which renders the chosen paint. Not for app content. Use the FillSection subcomponent to edit a LIST of fills (the Figma "Fill" inspector section): each row is a Solid/Gradient/Image toggle, the matching value control (ColorPicker / GradientEditor popover / image URL), an opacity %, a visibility eye, and a remove button, with an add button in the header.
+composes_with: [BackgroundFill (renders the FillValue), Popover (host it in a popover), ColorPicker (the solid value), GradientEditor (the gradient value), ShaderPresetPicker (the shader tab), the inspector Fill section]
+aliases: [fill picker, paint picker, background picker, fill chooser, fill popover, fill section, fill list, fills inspector, paint section]
 notes: |
   Grade is token-led, so the solid + gradient tabs lead with theme-token
   swatches (`primary`, `accent`, `secondary`, `muted`, `card`,

package/components/ui/gradient-editor.md

@@ -0,0 +1,30 @@
+---
+name: GradientEditor
+import: "@gradeui/ui"
+props:
+  - value: { type, angle?, stops } — the structured gradient (type linear/radial/angular, optional angle in deg, ordered stops). NOT a CSS string — render the string via gradientToCss(value).
+  - onChange: (value) => void — fired with the next structured gradient on any edit
+when_to_use: Edit a multi-stop CSS gradient with token-led stops. A type Select (Linear / Radial / Angular) with reverse + rotate actions, a live full-width preview bar (a Swatch type="gradient"), then a Stops list where each stop is a position %, a colour (ColorPicker token or raw), an opacity %, and a remove button; an add button appends a stop. Token stops resolve to oklch(var(--<token>)) so the preview re-voices with the theme. Emits the structured GradientValue (kept editable + serialisable); the caller turns it into CSS with the exported gradientToCss(value). Use inside a Popover from a FillSection gradient row, or standalone in a theme builder. For a single solid colour use ColorPicker; for a full paint (solid / gradient / image / shader) use FillPicker.
+composes_with: [Select, Button, Input, ColorPicker, Swatch, Popover, FillSection]
+aliases: [gradient editor, gradient picker, gradient builder, css gradient editor, stop editor, gradient stops, linear gradient editor, conic gradient editor]
+---
+
+```jsx
+<GradientEditor
+  value={{
+    type: "linear",
+    angle: 90,
+    stops: [
+      { id: "a", position: 0, token: "action/primary", opacity: 1 },
+      { id: "b", position: 100, token: "action/accent", opacity: 1 },
+    ],
+  }}
+  onChange={setGradient}
+/>
+```
+
+```jsx
+// Render the CSS string for a background.
+import { gradientToCss } from "@gradeui/ui";
+<div style={{ background: gradientToCss(gradient) }} />
+```

package/components/ui/section.md

@@ -0,0 +1,52 @@
+---
+name: Section
+import: "@gradeui/ui"
+subcomponents: [Container, SectionEyebrow, SectionTitle, SectionSubtitle, SectionDescription, SectionActions, SectionMedia]
+props:
+  - Section: scope? (default | inverse | brand | accent | muted | card) — colour SUBTHEME; applies the `scope-*` class so the whole band re-tones (bg/fg/card/muted/border) while action colours stay vivid. Unset = the page surface. See STUDIO-COLOR.md.
+  - Section: background?: ReactNode — visual band background slot: image / video / gradient / shader (drop a <BackgroundFill> here). Renders BEHIND the content; Section owns the relative/overflow/z plumbing. Works with `scope` (which re-tones the content tokens so text stays legible over the media).
+  - Section: pad? (none | sm | md | lg | xl) — vertical rhythm (responsive py); default lg. Section is ALWAYS full width — it never sets a max width.
+  - Section: as? (section | header | footer | div) — semantic element; default section.
+  - Container: maxW? (sm | md | lg | xl | prose | full) — centred max width + gutters; default lg. The MEASURE.
+  - Container: grid?: boolean — snap children to a 12-column grid (use `col-span-*` on children); default false.
+  - Container: as? (div | section) — semantic element; default div.
+when_to_use: THE page scaffold. A page is an ordered stack of Sections — every distinct band (hero, logos, features, pricing, testimonial, CTA, footer) gets its OWN Section so each is independently themeable. `Section` is the full-width band (scope + vertical rhythm); drop a `Container` inside it for a measure, or omit the Container for a full-bleed band. Reach for Section/Container instead of hand-rolling `<section className="py-20"><div className="max-w-7xl mx-auto px-6">`. The content inside is free — use the parts (SectionEyebrow/Title/Subtitle/Description/Actions/Media) for the common heading+copy+CTA+media shape, or drop any JSX. SectionMedia is a slot for any media (MediaSurface image, Carousel, VideoPlayer, embed, or a whole app UI). Don't use Section for app chrome — that's AppShell.
+composes_with: [Container, MediaSurface, Carousel, VideoPlayer, Button, Badge, Card, Grid, Stack]
+aliases: [section, band, hero section, page section, content section, marketing section, landing section, full bleed, container, max width wrapper, page band, section block]
+---
+
+```jsx
+// A page is a stack of Sections. Each band picks a scope; a Container
+// holds the measure (omit it to let the band bleed full-width).
+<Section scope="inverse" pad="xl">
+  <Container maxW="lg">
+    <SectionEyebrow>New</SectionEyebrow>
+    <SectionTitle>Use the agent you prefer.</SectionTitle>
+    <SectionSubtitle>Own the components. Ship on your subscription.</SectionSubtitle>
+    <SectionActions>
+      <Button size="lg">Open Studio</Button>
+      <Button size="lg" variant="outline">Docs</Button>
+    </SectionActions>
+  </Container>
+</Section>
+```
+
+```jsx
+// Full-bleed media band — no Container, so the media spans edge to edge.
+// The scope re-tones the band; the media frames itself.
+<Section scope="card" pad="lg">
+  <SectionMedia>
+    <MediaSurface hint="Studio canvas" alt="A generated screen" className="aspect-[21/9] w-full" />
+  </SectionMedia>
+</Section>
+```
+
+```jsx
+// Contained content on a grid — children snap to the 12-col Container grid.
+<Section pad="lg">
+  <Container grid>
+    <div className="col-span-12 md:col-span-7">{/* lead */}</div>
+    <div className="col-span-12 md:col-span-5">{/* aside */}</div>
+  </Container>
+</Section>
+```

package/components/ui/swatch.md

@@ -2,11 +2,14 @@
 name: Swatch
 import: "@gradeui/ui"
 subcomponents: [SwatchGroup]
-sizes: [xs, sm, md, lg, xl]
+sizes: [2xs, 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.
+  - type? (solid | gradient | image) — fill kind; default solid (or inferred from `image` / `gradient`). Determines what the chip renders in place.
+  - gradient?: string — CSS gradient for `type="gradient"`, e.g. `linear-gradient(135deg,#6366f1,#ec4899)`.
+  - image?: string — image URL for `type="image"`; rendered cover-fit behind the chip.
+  - size? (2xs | xs | sm | md | lg | xl) — t-shirt scale, 16px → 56px; default md (32px). 2xs (16px) suits dense colour lists. 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.

package/components/ui/toggle-group.md

@@ -2,15 +2,15 @@
 name: ToggleGroup
 import: "@gradeui/ui"
 subcomponents: [ToggleGroupItem]
-variants: [default, outline]
-sizes: [sm, md, lg]
+variants: [default, outline, segmented]
+sizes: [2xs, xs, sm, md, lg]
 props:
   - ToggleGroup: type: "single" | "multiple" — single picks one, multiple picks any number
   - ToggleGroup: value?: string | string[] — controlled; matches `type` (string for single, string[] for multiple)
   - ToggleGroup: defaultValue?: string | string[] — uncontrolled initial
   - ToggleGroup: onValueChange?: (value: string | string[]) => void
-  - ToggleGroup: size? (sm | md | lg, default md) — cascades to every ToggleGroupItem via context, matches Tabs/Button heights
-  - ToggleGroup: variant? (default | outline)
+  - ToggleGroup: size? (2xs | xs | sm | md | lg, default md) — cascades to every ToggleGroupItem via context, matches Tabs/Button heights; 2xs/xs are the dense tool-panel sizes (2xs also drops text to text-2xs and icons to size-3 so labelled items read at panel density)
+  - ToggleGroup: variant? (default | outline | segmented) — segmented sits the items in a muted track with the active item as a soft raised pill, so it reads like a TabsList; reach for it in dense property panels (e.g. a Row/Stack direction toggle)
   - ToggleGroupItem: value: string — what the group reports when this item is pressed
   - ToggleGroupItem: tooltip?: ReactNode — when set, wraps the item in a Tooltip; required for icon-only items where the visible chrome doesn't carry a label
   - ToggleGroupItem: tooltipSide? ("top" | "right" | "bottom" | "left", default "top") — side the tooltip renders on
@@ -41,3 +41,20 @@ aliases: [toggle group, segmented control, segmented buttons, button group, pill
   <ToggleGroupItem value="underline" aria-label="Underline"><Underline /></ToggleGroupItem>
 </ToggleGroup>
 ```
+
+```jsx
+// Segmented variant + 2xs — a dense property-panel toggle. Reads like a
+// tab strip (muted track, active pill) but emits a value, so it's a form
+// control, not panel-switching. This is the Studio Row/Stack control.
+<ToggleGroup
+  type="single"
+  variant="segmented"
+  size="2xs"
+  value={direction}
+  onValueChange={(v) => v && setDirection(v)}
+  className="w-full"
+>
+  <ToggleGroupItem value="row" className="flex-1"><Columns3 /> Row</ToggleGroupItem>
+  <ToggleGroupItem value="col" className="flex-1"><Rows3 /> Stack</ToggleGroupItem>
+</ToggleGroup>
+```