@gradeui/ui 3.1.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/combobox.md

@@ -0,0 +1,46 @@
+---
+name: Combobox
+import: "@gradeui/ui"
+props:
+  - options: { value, label, icon?, keywords?, disabled? }[] — the selectable pool
+  - value?: string | null — controlled selection (wire onValueChange)
+  - defaultValue?: string | null — uncontrolled initial selection
+  - onValueChange?: (next: string | null) => void — fired with the next value, or null when cleared
+  - placeholder?: string — trigger text when nothing is selected
+  - searchPlaceholder?: string — search-input placeholder
+  - emptyMessage?: string — shown when search returns no rows
+  - searchable?: boolean — show the search input (default true)
+  - clearable?: boolean — add a Clear row so the value can return to unset
+  - triggerVariant?: "default" | "inline" — default = form-control surface (like Select); inline = chrome-free token trigger
+  - renderValue?: (option) => ReactNode — render the selected value yourself (e.g. a Badge); falls back to icon + label
+  - hideChevron?: boolean — drop the trailing chevron (inline token look)
+  - disabled?: boolean — lock to a read-only display of the current value
+  - align?: "start" | "center" | "end" — popover alignment
+when_to_use: Single-pick searchable picker — the single-select sibling of MultiSelect and the Linear "selectable badge" pattern (status / priority / assignee). Use triggerVariant="inline" with renderValue returning a Badge to make a value read as a clickable token that opens a command menu. For multiple selection use MultiSelect; for a small fixed list with no search use Select; for free-form command palettes use Command directly. Pass disabled (driven by a permission check) to show the value without letting the user edit it.
+composes_with: [Popover, Command, Badge, Avatar, PropertyList, Table, Field]
+aliases: [combobox, single select, searchable select, picker, status picker, priority picker, assignee picker, command select, autocomplete, dropdown select, selectable badge, inline select, token select, linear combobox]
+---
+
+```jsx
+<Combobox
+  options={[
+    { value: "low", label: "Low" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High" },
+  ]}
+  defaultValue="low"
+  placeholder="Set priority"
+/>
+```
+
+```jsx
+// Linear-style: the value IS the trigger.
+<Combobox
+  triggerVariant="inline"
+  hideChevron
+  options={priorityOptions}
+  value={priority}
+  onValueChange={setPriority}
+  renderValue={(opt) => <Badge variant="warning-soft">{opt.label}</Badge>}
+/>
+```

package/components/ui/data-view.md

@@ -0,0 +1,59 @@
+---
+name: DataView
+import: "@gradeui/ui"
+props:
+  - data: T[] — the rows
+  - columns: { key, header, type?, options?, cell?, role?, sortable?, pinned?, width?, align?, hideable?, defaultHidden? }[] — the schema; one list drives table, cards, and grid
+  - getRowId?: (row, i) => string — defaults to row.id
+  - view? / defaultView? / onViewChange?: "table" | "cards" | "grid" — controlled or uncontrolled view
+  - views?: ("table" | "cards" | "grid")[] — allowed views; one entry = single view, no toggle
+  - activeId? / defaultActiveId? / onActiveChange?: string | null — the selected row; click emits it
+  - sorting? / defaultSorting? / onSortingChange? — TanStack SortingState
+  - columnVisibility? / defaultColumnVisibility? / onColumnVisibilityChange? — which fields show
+  - stickyHeader?: boolean — freeze the header row on scroll
+  - toolbar?: boolean — render the built-in columns menu + view toggle above the view
+  - renderCard?: (row, { active }) => ReactNode — override card / grid tiles
+  - emptyMessage?: ReactNode
+when_to_use: One dataset, drawn as a table, a list of cards, or a grid — without re-typing the TanStack boilerplate (sortable headers, flexRender, selection, view switch) on every page. Hand it data + a columns schema; columns declare a `type` (badge/tags/number/currency/percent/date/boolean/url/text) that DataView renders, with a `cell` override for bespoke cells (avatars, relations). The view toggle can live anywhere — `useDataView()` holds the state so a `<DataViewToggle>` or `<DataViewColumns>` in a page header drives a `<DataView>` lower down. Mark a column `pinned="left"` (with a `width`) for a fixed column and `stickyHeader` to freeze the header. For a single record's fields use PropertyList; for the raw table primitive use Table.
+composes_with: [Table, Card, Badge, Avatar, ToggleGroup, DropdownMenu, PropertyList, Combobox]
+aliases: [data view, data table, datatable, data grid, dataview, table view, card view, grid view, list view, gallery, records list, master list, tanstack table, sortable table, column visibility, pinned column, frozen column, sticky header, view switcher]
+---
+
+```jsx
+const dv = useDataView({ defaultView: "table", defaultActiveId: rows[0].id });
+
+// The toggle / columns menu can live anywhere — they just read dv.
+<Row justify="between">
+  <h1>Alerts</h1>
+  <Row gap="sm">
+    <DataView.Columns columns={columns} visibility={dv.columnVisibility} onVisibilityChange={dv.setColumnVisibility} />
+    <DataView.Toggle value={dv.view} onChange={dv.setView} views={dv.views} />
+  </Row>
+</Row>
+
+<DataView
+  data={rows}
+  columns={columns}
+  view={dv.view}
+  activeId={dv.activeId}
+  onActiveChange={dv.setActiveId}
+  sorting={dv.sorting}
+  onSortingChange={dv.setSorting}
+  columnVisibility={dv.columnVisibility}
+  onColumnVisibilityChange={dv.setColumnVisibility}
+  stickyHeader
+/>
+```
+
+```jsx
+// Self-contained: built-in toolbar, single column pinned, table only.
+<DataView
+  data={rows}
+  toolbar
+  columns={[
+    { key: "name", header: "Name", role: "title", pinned: "left", width: 220 },
+    { key: "status", header: "Status", type: "badge", options: statusOptions, sortable: true },
+    { key: "arr", header: "ARR", type: "currency", align: "end", sortable: true },
+  ]}
+/>
+```

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/map.md

@@ -90,3 +90,9 @@ ANTI-PATTERNS — don't do these:
 - DO NOT render >500 markers without clustering. The component warns in dev. For larger datasets, drop to `.instance` and use the provider's clustering layer.
 
 Markers are DOM — children inherit `--gds-*` tokens. Drop a `<Card>`, `<Badge>`, `<Avatar>`, or anything else inside `<MapMarker>` and it themes correctly.
+
+Stacking inside a marker follows normal DOM order on every provider — you do NOT need `z-index` hacks to layer content (e.g. a count label sitting on top of an inline pin-shield `<svg>`). The DS neutralizes Leaflet's vendor rule that sets `z-index: 200` on map `<svg>` elements (via `[data-gds-part="map-marker-content"] svg { z-index: auto }` in `globals.css`); without it, an inline SVG would paint above later siblings on Leaflet (the default provider) but not on Mapbox/MapLibre/Google, making the same marker markup look provider-dependent. If you nest an inline SVG behind text in a marker, just rely on source order.
+
+For a floating text label over busy tiles, add the `gds-map-label` class — it applies a mode-aware halo (`--gds-map-label-halo`: white stroke on light tiles, near-black on dark) so the label never washes out. Don't hard-code a white `-webkit-text-stroke`.
+
+Note: `<Map>` carries no border-radius or border of its own — it's an unopinionated primitive (the container clips with `overflow: hidden`). Round or frame it from the call site with `className` (e.g. `rounded-xl border`).

package/components/ui/property-list.md

@@ -0,0 +1,43 @@
+---
+name: PropertyList
+import: "@gradeui/ui"
+props:
+  - layout?: "row" | "stack" — row (default): label column beside value; stack: label above value for narrow panels
+  - density?: "compact" | "default" | "relaxed" — row rhythm
+  - align?: "start" | "center" — default vertical alignment of label vs value; use start when values wrap (tag groups, multi-line)
+  - divider?: boolean — hairline rule between rows
+  - labelWidth?: string — override the label column width (any CSS length); sets --gds-property-list-label-width
+  - children: PropertyList.Row[]
+when_to_use: Read-only display of the properties of a SINGLE item — detail panels, inspectors, "about this" cards, order/record summaries. It is a Table row transposed (schema vertical, one record). The value side is a polymorphic slot, so the same renderers that fill a Table cell (text, Badge, tag group, Avatar stack, date, link) drop straight into a row. For an EDITABLE field (label + control) use Field instead; a panel that flips between read and edit swaps a PropertyList for a stack of Fields.
+composes_with: [Badge, Avatar, Table, Field, Separator, Card]
+aliases: [property list, properties, property panel, description list, definition list, detail list, key value, key-value, data list, field list, attributes, metadata list, record summary, detail panel, inspector fields, spec list]
+---
+
+```jsx
+<PropertyList>
+  <PropertyList.Row label="Status" icon={<Activity />}>
+    <Badge variant="warning-soft">Low</Badge>
+  </PropertyList.Row>
+  <PropertyList.Row label="Published">2026-06-18</PropertyList.Row>
+  <PropertyList.Row label="Owner">
+    <Avatar className="h-5 w-5"><AvatarFallback>EO</AvatarFallback></Avatar>
+  </PropertyList.Row>
+</PropertyList>
+```
+
+```jsx
+<PropertyList density="compact" divider align="start">
+  <PropertyList.Row label="Topics">
+    <Row gap="xs" wrap>
+      <Badge variant="secondary">Pricing</Badge>
+      <Badge variant="secondary">Onboarding</Badge>
+    </Row>
+  </PropertyList.Row>
+  <PropertyList.Row label="Business profiles">
+    <Row gap="xs" wrap>
+      <Badge variant="outline">Acme</Badge>
+      <Badge variant="outline">Kite</Badge>
+    </Row>
+  </PropertyList.Row>
+</PropertyList>
+```

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>
+```