@uxelle/skills 0.2.1-beta.0 → 0.2.3

package/skills/uxelle-components/NavigationSideItem.md

@@ -17,10 +17,10 @@ Destination row for a vertical side navigation rail. Shows a leading icon, label
 | trailingSlotContent | `ReactNode` | `undefined` | Content for the trailing region, typically a `LabelBadge`, short text, or a decorative icon. Rendered only when `trailingSlot` is true, and it must stay non-interactive because it sits inside the row's own link or button. |
 | subNavigationItemsSlot | `ReactNode` | `undefined` | Nested `NavigationSideSubItem` rows revealed when `accordion` is true; takes precedence over `children`. On the collapsed rail they are re-rendered as a `List` of `ListItem`s inside the flyout. |
 | children | `ReactNode` | `undefined` | Nested `NavigationSideSubItem` rows revealed when `accordion` is true, used when `subNavigationItemsSlot` is omitted. Not the row label — that is `label`. On the collapsed rail they become a `List` of `ListItem`s in the flyout. |
-| activated | `boolean` | `false` | Marks this row as the current page: filled surface plus a leading indicator bar. Destination rows also get `aria-current="page"`; accordion parents do not, so set it on the matching child instead. |
+| activated | `boolean` | `false` | Marks this row as the current page: filled surface plus a leading indicator bar. Destination rows also get `aria-current="page"`; accordion parents do not, so set it on the matching child instead. When the rail is collapsed, an accordion parent also shows this selected appearance if any nested `NavigationSideSubItem` is activated (pass the sub item directly, not wrapped in a custom component). |
 | navCollapsed | `boolean` | `false` | Icon-only rail layout: hides the label, the trailing slot, and the inline accordion panel, and shows the label in a tooltip on hover and focus. Inherited from the enclosing `NavigationSideGroup` when omitted. |
 | accordion | `boolean` | `false` | Turns the row into an expandable parent with a trailing chevron that reveals its nested rows. The control is always a button, so `href` is ignored. |
-| open | `boolean` | `undefined` | Controlled expanded state of the accordion panel (or of the collapsed-rail flyout). Pass with `onOpenChange`; omit to use `defaultOpen` instead. |
+| open | `boolean` | `undefined` | Controlled expanded state of the accordion panel (or of the collapsed-rail flyout). Pass with `onOpenChange`; omit to use `defaultOpen` instead. Collapsing the rail hides an open nested list even if this stays true; pass `true` again (or let the user open the flyout) to show it while collapsed. |
 | defaultOpen | `boolean` | `false` | Whether the accordion panel starts expanded when `open` is omitted. |
 | onOpenChange | `(open: boolean) => void` | `undefined` | Called with the next expanded state each time the accordion parent toggles. |
 | notificationBadge | `boolean` | `false` | Overlays an unread dot on the leading icon. The dot itself is decorative; the state is folded into the control name as `"{label}, notifications"`. |
@@ -48,8 +48,8 @@ Destination row for a vertical side navigation rail. Shows a leading icon, label
 - Do not use as a top or header nav link (`NavLink`). Nested accordion destinations use `NavigationSideSubItem`.
 - Compose inside `NavigationSideGroup` (a `<nav>` list). This row is a list item; other HTML attributes (`aria-*`, `data-*`, `id`) go to the interactive control, and `className` is on the row wrapper.
 - Renders as an anchor when `href` is set; otherwise a button. Accordion parents are **not** destinations: `href` is ignored and the control is always a button. Put a section landing page in a `NavigationSideSubItem` child instead.
-- Set `activated` for the current page — fill and leading indicator. Destinations also set `aria-current="page"`; accordion parents do not. When a child is the current page, set `activated` on that child, not only on the parent.
-- Set `accordion` for a parent that reveals `subNavigationItemsSlot` (or `children`): `NavigationSideSubItem` rows (`href` for destinations). Omit `open` for uncontrolled (`defaultOpen` + `onOpenChange`). The trigger is a button with `aria-expanded` / `aria-controls`; the nested list animates open and closed (inert and `aria-hidden` when collapsed). When `navCollapsed` is also true, those rows open in a disclosure flyout (`Menu` `pattern="disclosure"`, `direction="Right Top"`) as a `List` of interactive `ListItem`s. Keyboard: Enter/Space toggles; Tab moves through destinations; Tab-out and Escape close and return focus to the trigger.
+- Set `activated` for the current page — fill and leading indicator. Destinations also set `aria-current="page"`; accordion parents do not. When a child is the current page, set `activated` on that child, not only on the parent. Collapsing the rail still shows the selected appearance on that accordion parent so the section remains visible on the icon-only rail.
+- Set `accordion` for a parent that reveals `subNavigationItemsSlot` (or `children`): `NavigationSideSubItem` rows (`href` for destinations). Omit `open` for uncontrolled (`defaultOpen` + `onOpenChange`). The trigger is a button with `aria-expanded` / `aria-controls`; the nested list animates open and closed (inert and `aria-hidden` when collapsed). Collapsing the rail hides any open nested list (and moves keyboard focus to the parent if a nested row had it). Expanding restores that open state unless the flyout was dismissed while collapsed. Opening a disclosure flyout from the collapsed parent is still available. When `navCollapsed` is also true, those rows open in a disclosure flyout (`Menu` `pattern="disclosure"`, `direction="Right Top"`) as a `List` of interactive `ListItem`s. Keyboard: Enter/Space toggles; Tab moves through destinations; Tab-out and Escape close and return focus to the trigger.
 - The leading icon is always shown. Group collapsed layout with `NavigationSideGroup` (`collapsed`) or set `navCollapsed`.
 - When `navCollapsed`, the visible label is hidden; pass `label` (or `aria-label`) for the accessible name. A tooltip shows the label on hover and focus.
 - When `notificationBadge` is true, the dot stays decorative; unread state is included in the control name (`"{label}, notifications"`). Override with `aria-label` when you need a different name.

package/skills/uxelle-components/NavigationSideSubItem.md

@@ -14,7 +14,7 @@ Nested destination row under an accordion side-nav parent.
 | leadingIcon | `boolean` | `true` | Renders the leading icon before the label. Set `false` for text-only nested rows, which is the usual look under an accordion parent. |
 | leadingIconName | `string` | `"outbound"` | Material Symbol name for the leading icon. Ignored when `leadingIcon` is false. |
 | iconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the leading icon: `sharpUnfilled` for the outline glyph, `sharpFilled` for the solid one. |
-| activated | `boolean` | `false` | Marks this row as the current page: filled surface, leading indicator bar, and `aria-current="page"`. Set it here rather than on the accordion parent. |
+| activated | `boolean` | `false` | Marks this row as the current page: filled surface, leading indicator bar, and `aria-current="page"`. Set it here rather than on the accordion parent. When the rail is collapsed, that parent also shows the selected appearance. |
 | href | `string` | `undefined` | Destination URL, which renders the row as an anchor instead of a button. Omit for a button that only reports clicks through `onClick`. |
 | className | `string` | `—` |  |
 
@@ -34,6 +34,6 @@ Nested destination row under an accordion side-nav parent.
 
 - Use as a child of an accordion `NavigationSideItem`, not as a top-level rail row (`NavigationSideItem`). Compose inside `NavigationSideGroup` so this row is a list item in the side `nav`.
 - Renders as an anchor when `href` is set; otherwise a button. `className` is on the row wrapper; other HTML attributes (`aria-*`, `data-*`, `id`) go to the interactive control.
-- Set `activated` for the current page — fill, leading indicator, and `aria-current="page"`.
+- Set `activated` for the current page — fill, leading indicator, and `aria-current="page"`. When the rail is collapsed, the accordion parent also shows the selected appearance so the section remains visible on the icon-only rail.
 - Set `leadingIcon={false}` to hide the icon.
-- When the parent accordion is collapsed (`navCollapsed`), this row is presented as a `ListItem` in the disclosure flyout (a list of links, not a menu).
+- When the parent accordion is collapsed (`navCollapsed`), this row is presented as a `ListItem` in the disclosure flyout (a list of links, not a menu). Collapsing the rail hides an open nested list; the parent can still open the flyout.

package/skills/uxelle-components/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uxelle-components
-description: Reference for uxElle Generative Product Foundation (GPF) components. Use when generating UI with uxElle, implementing designs, building layouts, or when the user mentions uxElle components, design system, or enterprise UI.
+description: Reference for uxElle Generative Product Foundation (GPF) components. Use when generating UI with uxElle, implementing designs, building layouts, installing or setting up a React or Next.js app with @uxelle/components, loading theme CSS, or when the user mentions uxElle components or enterprise UI.
 ---
 
 # uxElle Components — Generative Workflow Reference
@@ -10,6 +10,7 @@ Reference for accurately using uxElle Generative Product Foundation (GPF) compon
 ## Context discipline
 
 - Load this SKILL.md when working with uxElle components.
+- New app or host without packages and CSS? Read [getting-started.md](getting-started.md) first, then [how-to-host.md](../uxelle-design-harness/how-to-host.md). Skip getting-started when the host already loads theme CSS, component CSS, and `data-*`.
 - Load individual component files (e.g. Button.md, ListItem.md) only when you need that component's props or examples.
 - Do not preload all component files.
 
@@ -220,7 +221,12 @@ Use `List` + `ListItem` for menus and lists. Prefer `centerText` / `bottomText`
 Prefer **`ListControls`** when each row has title/description plus an embedded trailing control (settings and exclusive choices). Page layout: harness [recipe-settings-page.md](../uxelle-design-harness/recipe-settings-page.md). Set **`controlType`** to **`switch`**, **`checkbox`**, or **`radio`**. Same selection roles as **`RadioGroup`** / **`CheckboxGroup`** for checkbox/radio, list layout instead of stacked form options. Use **`interactive`** **`ListItem`** rows with **`embedded`** Switch / Checkbox / Radio in **`trailing`**. Set **`dense`** on **`ListControls`** (or per **`ListItem`**) for compact row padding.
 
 ### Icon variants
-Icons use `sharpFilled` or `sharpUnfilled`. Default is `sharpUnfilled`.
+Icons use `sharpFilled` or `sharpUnfilled`. Default is `sharpUnfilled`. GPF chrome
+names always resolve from `@uxelle/components`. Any other Material Symbol requires
+`import "@uxelle/icons/register"` in the host (`@uxelle/a2ui` already does this).
+Unknown names render no glyph (empty span, production-silent) — a visual-only miss
+that a11y tests will not catch on icon-only buttons that already have `aria-label`.
+Type product names with `UxelleIconName` from `@uxelle/icons`.
 
 ### Theme tokens
 Generated app CSS uses `--uxl-color-switcher-*` and layout/page-chrome tokens. Do not use `--uxl-component-*` in app CSS (those tokens belong inside components). Focus rings on catalog controls already use `--uxl-color-switcher-interactive-icon`.
@@ -236,6 +242,7 @@ For secondary nav or brand hero bands: `data-color-switcher="brand-2"` on second
 
 ## Additional Resources
 
+- [Getting started](getting-started.md) — install `@uxelle/components` and `@uxelle/themes`, load CSS, theme provider, Next.js/SSR
 - [Design harness](../uxelle-design-harness/SKILL.md) — principles, variables, page chrome, responsiveness, WCAG AA, recipes
 - [Form field contract](../../docs/guides/form-field-contract.md) — HTML `value` / `checked` (not Figma `Selected` / `Activated`)
 - [Design variables (`--uxl-*`)](../uxelle-design-harness/tokens.md) — spacing, radius, elevation, color switcher, type

package/skills/uxelle-components/Select.md

@@ -34,6 +34,7 @@ Single-select dropdown with label, design tokens, optional `FieldMessage`, and l
 | readOnly | `boolean` | `false` | Shows the current selection but blocks opening the listbox and hides the trailing chevron; the trigger stays focusable and reports `aria-readonly`. |
 | required | `boolean` | `—` | Adds the asterisk to `Label` and `aria-required` on the trigger. Advisory only — no native constraint validation runs on the hidden input. |
 | name | `string` | `—` | Form field name for the hidden input that posts the selected value. No input is rendered while nothing is selected, so an empty selection is never submitted. |
+| onClick | `MouseEventHandler<HTMLDivElement>` | `—` | Fired on the field chrome. `currentTarget` is the trigger wrapper, not the combobox input. |
 | disabled | `boolean` | `false` | Blocks interaction, removes the trigger from the tab order, and applies disabled styling; a `name` hidden input still submits the current value. |
 
 <!-- prettier-ignore-end -->
@@ -51,5 +52,5 @@ Single-select dropdown with label, design tokens, optional `FieldMessage`, and l
 - **Simple API** — pass `options` with `value` / `onChange` for controlled usage; optional `leadingIcon` / `leadingIconName`.
 - **Composable API** — pass `children` to render custom `ListItem` rows in the listbox; pass `leading` for a custom leading slot. Each row should spread `listboxOptionProps()` plus selection handlers (see dev console when the list opens).
 - **Accessibility**: Visible label uses `<Label htmlFor>`; the combobox name uses `aria-labelledby` on the label text only (not `fieldDescription`, which is linked via `aria-describedby`). `FieldMessage` uses `aria-describedby` (info) or `aria-errormessage` (error). Pass `id` for stable ids; use `aria-label` when `label={false}`.
-- **Focus**: Tab focuses the combobox trigger only; **Arrow** keys move the active option (`aria-activedescendant`) while open. **Enter** commits the active option; **Escape** closes the list. Options use `tabIndex={-1}` and are not separate tab stops.
+- **Focus**: The combobox is a readonly `<input>` (not a `<button>`) so Safari's default Tab cycle — text fields, not buttons — can land on it, and a click actually focuses the control. **Arrow** keys move the active option (`aria-activedescendant`) while open. **Enter** commits the active option; **Escape** closes the list. Options use `tabIndex={-1}` and are not separate tab stops.
 - **Forms**: With `name`, a hidden input posts the selected value; when nothing is selected, no hidden input is rendered.

package/skills/uxelle-components/StatTile.md

@@ -10,11 +10,11 @@ Card-styled readout for a headline figure with a label, optional qualifier, info
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| order | `"labelFirst" \| "valueFirst"` | `"labelFirst" as StatTileOrder` | Vertical order of the label row and the value row. |
-| label | `ReactNode` | `—` | Label in the label row. Occupies remaining width beside the info control. Pass a `string` (or `number`) to render with the default label typography (`Text type="Body Medium"`), or pass a `ReactNode` for full control. When you pass a `ReactNode` you own its accessibility: use meaningful text (not color or icon alone) and keep it non-interactive so it can name the group. |
-| value | `ReactNode` | `—` | Headline figure in the value row. Pass a `string` (or `number`) to render with the default value typography (`Text type="Display Medium"` as `<p>`), or pass a `ReactNode` for full control. A library `Text` node is rendered as `<p>` so a grid of StatTiles does not become a heading outline. When you pass any other `ReactNode`, make sure the figure reads as text and is not conveyed through color or an icon alone (WCAG 1.4.1). |
+| order | `"labelFirst" \| "valueFirst"` | `"labelFirst"` | Vertical order of the label row and the value row. |
+| label | `ReactNode` | `—` | Label in the label row. Occupies remaining width beside the info control and stays on one line: overflow ellipsizes. Hover or focus a truncated label to read the full name in a tooltip. A string (or number) is wrapped in **Text** with `type="Body Medium"`; pass a `Text` node for a different type (truncation is still applied). When you pass a `Text` or other `ReactNode` you own its accessibility: use meaningful text (not color or icon alone) and keep it non-interactive so it can name the group. |
+| value | `ReactNode` | `—` | Headline figure in the value row. A string (or number) is wrapped in **Text** with `type="Display Small"` as `<p>`; pass a `Text` node for a different type. A `Text` keeps its `type` and is rendered as `<p>` so a grid of StatTiles does not become a heading outline. Any other `ReactNode` is allowed; make sure the figure reads as text and is not conveyed through color or an icon alone (WCAG 1.4.1). |
 | qualifier | `boolean` | `true` | When true, allows the qualifier to render when content is present. |
-| qualifierContent | `ReactNode` | `—` | Qualifier beside the value. Pass a `string` (or `number`) to render with the default qualifier typography (`Text type="Body Medium"`), or a `ReactNode` for full control. Only rendered when `qualifier` is true and content is present. When you pass a `ReactNode`, ensure it reads as text; do not rely on color alone to distinguish comparison periods. |
+| qualifierContent | `ReactNode` | `—` | Qualifier beside the value. A string (or number) is wrapped in **Text** with `type="Body Medium"`; pass a `Text` node for a different type. Only rendered when `qualifier` is true and content is present. When you pass a `Text` or other `ReactNode`, ensure it reads as text; do not rely on color alone to distinguish comparison periods. |
 | tooltipSlot | `boolean` | `true` | When true, allows the tooltip slot to render when content is present. |
 | tooltipContent | `ReactNode` | `—` | Info control at the end of the label row (typically `Tooltip` wrapping `IconButton`). Only rendered when `tooltipSlot` is true and content is present. Icon-only triggers within this slot must carry an accessible name via `aria-label` on the interactive element (e.g. `<IconButton aria-label="More information" />`). |
 | trailingSlot | `boolean` | `false` | When true, allows the trailing region to render when content is present. The slot accepts any content. |
@@ -70,7 +70,7 @@ Card-styled readout for a headline figure with a label, optional qualifier, info
 // ReactNode override — caller owns accessibility (semantic element, text)
 <StatTile
   label={<Text type="Body Medium" width={false}>Fill rate</Text>}
-  value={<Text type="Display Medium" as="p">94%</Text>}
+  value={<Text type="Display Small" as="p">94%</Text>}
 />
 ```
 
@@ -78,7 +78,7 @@ Card-styled readout for a headline figure with a label, optional qualifier, info
 // Polling dashboard — aria-live on the value announces only the change
 <StatTile
   label="Active sessions"
-  value={<Text type="Display Medium" as="p" aria-live="polite">{count}</Text>}
+  value={<Text type="Display Small" as="p" aria-live="polite">{count}</Text>}
 />
 ```
 
@@ -111,40 +111,11 @@ Card-styled readout for a headline figure with a label, optional qualifier, info
 
 ## Notes
 
-- Pass a `string` (or `number`) to `label`, `value`, and `qualifierContent` to
-- render with each region's default typography — no `Text` wrapper needed. Pass
-- a `ReactNode` instead when you need full control (e.g. truncation, a custom
-- element); in that case you own its accessibility (see each prop). A library
-- `Text` passed as `value` is rendered as `<p>`.
-- Pass a library `Tooltip` (typically wrapping `IconButton`) through
-- `tooltipContent`. Toggle regions with `qualifier`, `tooltipSlot`, and
-- `trailingSlot`; empty content is not rendered. `trailingSlotContent` is an
-- open slot — any content is allowed. Surface, elevation, radius, and
-- padding come from `Card`. StatTile is a standalone tile: place it next to
-- other StatTiles in a grid. Do not wrap it in `Card`. A figure inside a chart
-- card or table cell is a different surface — compose `Text` there.
-- **Accessibility.** The root is a `role="group"` region. It is named
-- automatically from `label` (via `aria-labelledby`), so the group is announced
-- with context in both orders — including `"valueFirst"`, where the value
-- precedes the label in the DOM. Supply your own `aria-label` or
-- `aria-labelledby` to override the derived name; this is **required** when
-- there is no `label` (e.g. `aria-label="Median first response time, 1 day 12
-- hours"`) so the figure is not announced without context. In development,
-- StatTile warns when content is present but the group has no name. The trailing
-- slot is open, so its accessibility is the caller's responsibility — see
-- `trailingSlotContent`.
-- **Navigation.** Do not put `onClick` on StatTile — the root is a named group,
-- not a control, and a wrapped link would nest interactives when a tooltip is
-- present. Put the destination in `trailingSlotContent` as a `Link` or
-- `IconButton`.
+- `label`, `value`, and `qualifierContent` each accept a string (or number) or a **Text** node. A string is wrapped in that region's default `Text` type — no wrapper needed. Pass a `Text` when you need a different `type` or a live region. A `Text` passed as `value` keeps its `type` and is rendered as `<p>`. The label always truncates to one line so a row of tiles stays scannable; hover or focus a truncated label to read the full name (`Text` Body Small). This overflow tooltip is separate from `tooltipContent` (the info control).
+- Pass a library `Tooltip` (typically wrapping `IconButton`) through `tooltipContent`. Toggle regions with `qualifier`, `tooltipSlot`, and `trailingSlot`; empty content is not rendered. `trailingSlotContent` is an open slot — any content is allowed. Surface, elevation, radius, and padding come from `Card`. StatTile is a standalone tile: place it next to other StatTiles in a grid. Do not wrap it in `Card`. A figure inside a chart card or table cell is a different surface — compose `Text` there.
+- **Accessibility.** The root is a `role="group"` region. It is named automatically from `label` (via `aria-labelledby`), so the group is announced with context in both orders — including `"valueFirst"`, where the value precedes the label in the DOM. Supply your own `aria-label` or `aria-labelledby` to override the derived name; this is **required** when there is no `label` (e.g. `aria-label="Median first response time, 1 day 12 hours"`) so the figure is not announced without context. In development, StatTile warns when content is present but the group has no name. The trailing slot is open, so its accessibility is the caller's responsibility — see `trailingSlotContent`.
+- **Navigation.** Do not put `onClick` on StatTile — the root is a named group, not a control, and a wrapped link would nest interactives when a tooltip is present. Put the destination in `trailingSlotContent` as a `Link` or `IconButton`.
 - Set `order` to `"valueFirst"` to put the value row above the label row.
-- The root fills its parent by default (`fullWidth`). Set `fullWidth={false}`
-- to hug contents. Long label, value, and qualifier copy wrap inside the tile.
-- While data is loading, replace the tile with a `Skeleton` sized to the card
-- (full-width rectangle) inside `SkeletonGroup`. Do not pass a skeleton as
-- `value`.
-- For polling dashboards where the value updates in place, prefer putting
-- `aria-live="polite"` on the **value** node so only the changing figure is
-- announced (a root-level `aria-live` also works but re-announces the whole
-- group). When using a `string` `value`, wrap it yourself to place the live
-- region precisely.
+- The root fills its parent by default (`fullWidth`). Set `fullWidth={false}` to hug contents. Long value and qualifier copy wrap inside the tile; the label ellipsizes instead of wrapping.
+- While data is loading, replace the tile with a `Skeleton` sized to the card (full-width rectangle) inside `SkeletonGroup`. Do not pass a skeleton as `value`.
+- For polling dashboards where the value updates in place, prefer putting `aria-live="polite"` on the **value** node so only the changing figure is announced (a root-level `aria-live` also works but re-announces the whole group). When using a `string` `value`, wrap it yourself to place the live region precisely.

package/skills/uxelle-components/Table.md

@@ -11,7 +11,7 @@ Composable table shell and semantic grid for tabular data. Columns support resiz
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | topSlot | `ReactNode` | `—` | Band rendered above the table and outside its horizontal scrollport — typically a title, toolbar, filters, or search. Omitted entirely when unset. |
-| bottomSlot | `ReactNode` | `—` | Band rendered below the table and outside its horizontal scrollport — typically pagination or bulk actions. Omitted entirely when unset. |
+| bottomSlot | `ReactNode` | `—` | Band rendered below the table and outside its horizontal scrollport — typically **Pagination** or bulk actions. Omitted entirely when unset. |
 | tableSlot | `ReactNode` | `—` | The table itself: one **TableGrid** with its head, body, rows, and cells, placed in the scroll region that drives the horizontal scroll hint. Same slot as `children`, and it wins when both are passed. |
 | children | `ReactNode` | `—` | Alias for `tableSlot`, ignored when `tableSlot` is also passed. Compose one `TableGrid` (give it `aria-label` and `gridTemplateColumns`) holding a `TableHead` with a `TableRow` of `TableHeaderCell` children, then a `TableBody` with one `TableRow` of `TableCell` children per record — all exported from `@uxelle/components`. |
 
@@ -23,7 +23,7 @@ Extends `HTMLAttributes` — supports standard HTML attributes.
 
 ```tsx
 const columns = [
-  { flex: 0.5, minWidth: 48 },
+  { flex: 0, minWidth: 48, maxWidth: 72 },
   { flex: 1, minWidth: 120 },
 ] as const;
 
@@ -44,12 +44,15 @@ function OrdersGrid() {
       <OrdersGrid />
     </TableColumnSizingProvider>
   }
+  bottomSlot={
+    <Pagination totalItems={100} defaultItemsPerPage={10} aria-label="Orders pagination" />
+  }
 />
 ```
 
 
 ## Notes
 
-- Optional top and bottom slots frame the table region; a horizontal scroll hint appears when the grid is wider than its container. Fixed columns are implemented as sticky cells inside one `TableGrid`—not as a separate grid—so each row stays a single unit for assistive technology. Use **TableColumnPinProvider** or `pinned="start"` on **TableHeaderCell** and **TableCell** with **usePinnedStartOffsets** to keep leading columns visible during horizontal scroll.
-- Horizontal scroll and the trailing-edge hint appear automatically when content overflows the container. Define column proportions with **TableColumnSizingProvider** and **useColumnGridTemplate**.
+- Optional top and bottom slots frame the table region; pass **Pagination** in `bottomSlot` when the dataset is paged. A horizontal scroll hint appears when the grid is wider than its container. Fixed columns are implemented as sticky cells inside one `TableGrid`—not as a separate grid—so each row stays a single unit for assistive technology. Use **TableColumnPinProvider** or `pinned="start"` on **TableHeaderCell** and **TableCell** with **usePinnedStartOffsets** to keep leading columns visible during horizontal scroll.
+- Horizontal scroll and the trailing-edge hint appear automatically when content overflows the container. Define column proportions with **TableColumnSizingProvider** and **useColumnGridTemplate**. Set `flex: 0` and `maxWidth` on compact columns (selection, icons) so leftover `fr` space does not stretch them on a wide viewport. `flex: 0` without a pixel `minWidth` or `maxWidth` sizes the track to content (`max-content`) instead of collapsing. `maxWidth` on a growing column (`flex > 0`) is a resize ceiling only. Cell copy wraps and the row height follows the tallest cell. Header titles stay on one line and ellipsize when the column is narrower than the name. Pass `truncation` on **Text** in a body cell only when that column must stay single-line. Resizing a column persists every column as a pixel track at the widths on screen, so siblings are not stretched or shrunk to fit the container. Call **useResetTableColumnWidths** to restore every column to its template.
 - Layout is left-to-right only; right-to-left document direction is not supported yet.

package/skills/uxelle-components/getting-started.md

@@ -0,0 +1,85 @@
+<!-- Generated from README.md (getting-started region). Do not edit. -->
+
+# Getting started
+
+New app or host without uxElle packages and CSS? Read this file first, then set up page chrome in [how-to-host.md](../uxelle-design-harness/how-to-host.md). Component APIs live in [SKILL.md](SKILL.md). Optional A2UI runtime: [a2ui.md](../uxelle-design-harness/a2ui.md). Do not preload every component file.
+
+## Quick Start
+
+Peer dependencies: React 18 or 19.
+
+```bash
+npm install @uxelle/components @uxelle/themes
+```
+
+Import the two stylesheets:
+
+```tsx
+import "@uxelle/components/base.css";
+import "@uxelle/themes/open-source.css";
+
+import { Button } from "@uxelle/components";
+
+function App() {
+  return <Button emphasis="high">Get Started</Button>;
+}
+```
+
+Then set the theme attributes on `<html>`:
+
+```html
+<html data-open-source="light" data-color-switcher="default"></html>
+```
+
+Both attributes are required. Every `--uxl-*` token is declared under
+`[data-open-source="light"]` or `[data-open-source="dark"]`, so components render
+unstyled without them. See [Themes](#themes) to switch modes at runtime.
+
+`base.css` is the single component stylesheet. `@uxelle/components/styles.css`
+(global baseline) and `@uxelle/components/index.css` (component rules)
+stay exported if you need to load them separately.
+
+### Next.js / SSR
+
+- Import both stylesheets in `app/layout.tsx` (or a top-level provider). JS side effects will not style App Router.
+- Published `@uxelle/components` JS is prefixed with `"use client"`. Importing any component places that file in the client graph.
+- Pass `mobile={true}` or `mobile={false}` on `NavigationSide` so server and client markup match. Omit `mobile` only in client-only surfaces.
+
+Optional: for an agent-driven UI surface, also install `@uxelle/a2ui`.
+
+### Icons
+
+`@uxelle/components` ships GPF chrome glyphs (`close`, `chevron_*`, `check`, and other names the library itself uses). For any other Material Symbol Sharp name, install `@uxelle/icons` and register once before the first `Icon` render:
+
+```bash
+npm install @uxelle/icons
+```
+
+```tsx
+import "@uxelle/icons/register";
+```
+
+`@uxelle/a2ui` registers the full catalog when you import it. Unknown names render no glyph (an empty span). Development warns; production is silent, so an icon-only control with `aria-label` can still pass a11y tests while showing nothing. Register `@uxelle/icons` before the first render, or type names with `UxelleIconName` from `@uxelle/icons`.
+
+## Themes
+
+Theme CSS is published as `@uxelle/themes` and generated from design tokens. Quick Start covers the import and the two required attributes; this section covers changing them.
+
+- `data-open-source` — `"light"` or `"dark"`
+- `data-color-switcher` — `"default"`, `"default-subtle"`, `"success"`, `"warning"`, `"danger"`, or `"info"`
+
+To drive both from React instead of hardcoding them, wrap the app with `UXelleThemeProvider`, which sets the attributes on `document.documentElement`:
+
+```tsx
+import { UXelleThemeProvider } from "@uxelle/themes/react";
+
+function AppShell({ children }: { children: React.ReactNode }) {
+  return (
+    <UXelleThemeProvider theme="open-source" darkMode={false} colorSwitcher="default">
+      {children}
+    </UXelleThemeProvider>
+  );
+}
+```
+
+Open Source uses **Open Sans** (self-hosted in the theme package). Do not set `font-family` in app CSS — `Text` uses theme tokens.

package/skills/uxelle-design-harness/SKILL.md

@@ -37,29 +37,38 @@ palette. The full mapping of principles to uxElle mechanisms lives in
 1. Load this `SKILL.md`. The foundations below always apply.
 2. Read the variable foundation once: [tokens.md](tokens.md) and
    [spacing-steps.md](spacing-steps.md).
-3. Creating an app shell? [how-to-host.md](how-to-host.md). Building a page body?
-   [how-to-page-layout.md](how-to-page-layout.md) (layout **and** responsiveness),
-   [how-to-color.md](how-to-color.md), and [how-to-accessibility.md](how-to-accessibility.md).
-4. Prefer an existing component. Link its doc at point of use, e.g.
+3. Pick the **density mode** for the experience — `compact` (data-dense product),
+   `standard` (task product, the default), `spacious` (marketing). One mode per
+   experience, chosen before any layout: [density.md](density.md).
+4. Creating a **new** app/host? Install and load CSS from
+   [getting-started.md](../uxelle-components/getting-started.md), then the
+   shell in [how-to-host.md](how-to-host.md). Building a page body in an
+   existing host? [how-to-page-layout.md](how-to-page-layout.md) (layout
+   **and** responsiveness), [how-to-color.md](how-to-color.md), and
+   [how-to-accessibility.md](how-to-accessibility.md).
+5. Prefer an existing component. Link its doc at point of use, e.g.
    `Table` -> `../uxelle-components/Table.md`. Import from `@uxelle/components`.
-5. Otherwise follow a recipe (see the index). If nothing fits, compose `Layout` +
+6. Otherwise follow a recipe (see the index). If nothing fits, compose `Layout` +
    `Text` + primitives on the grid.
-6. Building a runtime surface? Read [a2ui.md](a2ui.md) and each recipe's **A2UI** note.
-7. Before you finish, run the quality checklist below.
+7. Building a runtime surface? Read [a2ui.md](a2ui.md) and each recipe's **A2UI** note.
+8. Before you finish, run the quality checklist below.
 
 ## Decision tree
 
-- **New app/host** (loads theme CSS, `data-*`, skip link, `main`) -> [how-to-host.md](how-to-host.md).
-  Composing inside an existing host -> skip host setup; do not set theme `data-*` on `<html>`.
+- **New app/host** (packages not installed, or CSS / `data-*` not loaded) ->
+  [getting-started.md](../uxelle-components/getting-started.md), then
+  [how-to-host.md](how-to-host.md) for skip link, `main`, and column chrome.
+  Composing inside an existing host -> skip both; do not set theme `data-*` on `<html>`.
 - **Product experience** (signed-in app):
   app frame -> [recipe-app-chrome.md](recipe-app-chrome.md);
-  landing/overview -> [recipe-dashboard-overview.md](recipe-dashboard-overview.md);
-  records list -> [recipe-data-table-page.md](recipe-data-table-page.md);
+  landing/overview -> [recipe-dashboard-overview.md](recipe-dashboard-overview.md) (`compact`);
+  records list -> [recipe-data-table-page.md](recipe-data-table-page.md) (`compact`);
   one record -> [recipe-record-detail.md](recipe-record-detail.md);
   settings -> [recipe-settings-page.md](recipe-settings-page.md);
   wizard/checkout -> [recipe-multi-step-flow.md](recipe-multi-step-flow.md);
   generic body -> [recipe-page-shell.md](recipe-page-shell.md).
-- **Marketing experience** (public): whole page -> [recipe-landing-page.md](recipe-landing-page.md),
+  Unmarked product recipes default to `standard` ([density.md](density.md)).
+- **Marketing experience** (public, `spacious`): whole page -> [recipe-landing-page.md](recipe-landing-page.md),
   composed from the marketing pieces below.
 - **A piece** (part of an experience): page intro -> [recipe-page-header.md](recipe-page-header.md);
   filter/search toolbar -> [recipe-query-bar.md](recipe-query-bar.md);
@@ -79,6 +88,11 @@ palette. The full mapping of principles to uxElle mechanisms lives in
   padding / margin. Page chrome (inset, column cap, `fr` gaps) uses
   `--uxl-breakpoints-margin` / `-max-container-width` / `-gutter`. See
   [spacing-steps.md](spacing-steps.md) and [how-to-page-layout.md](how-to-page-layout.md).
+- **Density**: choose the step by **role** (Flush / Tight / Control / Group /
+  Section / Band) and the heading type by **rank**, both resolved through one
+  **mode** for the whole experience — `compact` | `standard` | `spacious`. Page
+  chrome and component internals are density-invariant. Never mix modes or tighten
+  one role alone. See [density.md](density.md).
 - **Color**: style via `--uxl-color-switcher-*` roles; apply a palette with
   `data-color-switcher` on a **region** (never invent switcher names). See
   [how-to-color.md](how-to-color.md).
@@ -86,10 +100,12 @@ palette. The full mapping of principles to uxElle mechanisms lives in
   never use `--uxl-component-*` in app/recipe CSS (those belong inside components).
 - **No hardcoded values**: no hex, no font-family, no breakpoint px. Read
   breakpoint bounds from theme variables when JS is unavoidable
-  ([how-to-page-layout.md](how-to-page-layout.md)). Exception: one-column reading
-  content (a form/settings page, or a form / FAQ / prose section on a wider page)
-  may cap at the `maxWidth="600px"` **reading measure** — always centered with
-  `mh="auto"` ([how-to-page-layout.md](how-to-page-layout.md#reading-measure)).
+  ([how-to-page-layout.md](how-to-page-layout.md)). Two exceptions: one-column
+  reading content (a form/settings page, or a form / FAQ / prose section on a wider
+  page) may cap at the `maxWidth="600px"` **reading measure**, always centered with
+  `mh="auto"` ([how-to-page-layout.md](how-to-page-layout.md#reading-measure)); and
+  **intrinsic sizes** — `minmax()` mins and a bounded search field — use `rem`
+  ([how-to-page-layout.md](how-to-page-layout.md#intrinsic-sizes-in-rem)).
 - **Components first**: prefer a catalog component over bespoke markup; link its
   doc at point of use (`../uxelle-components/<Name>.md`); do not open package source.
 - **Recipes are patterns, not exports**: never add `PageShell` / `AppChrome` /
@@ -104,14 +120,21 @@ Every generated screen must pass this. It is the definition of done.
 
 - **Grid & rhythm**: content sits on the grid; one capped content column via
   `--uxl-breakpoints-max-container-width` / `-gutter` / `-margin`; section spacing
-  from the ramp (page sections use `medium-12`). One-column reading sections
+  from the ramp at the experience's **Section** step. One-column reading sections
   (form / FAQ / prose) share the `600px` reading measure and are centered
   (`mh="auto"`); a decision cluster (form actions) is separated from its fields by
-  `medium-12`, not the field gap.
+  the **Section** step, not the field gap.
+- **Density**: one mode declared for the surface and applied to every role; the gap
+  roles (Tight -> Control -> Group -> Section) stay ~1.5x apart; page chrome and
+  component internals unchanged; no breakpoint logic added for density
+  ([density.md](density.md)).
 - **Tokens only**: spacing from `--uxl-theme-layout-spacing-*`; color from
   `--uxl-color-switcher-*`; no hardcoded hex or px, no invented `--uxl-*`, no
   `--uxl-component-*` in app CSS, no `var(--x, fallback)`.
-- **Hierarchy**: exactly one `h1`; heading ranks unbroken; few `Text` type roles.
+- **Hierarchy**: exactly one `h1`; heading ranks unbroken; each rank resolved to a
+  **distinct** `Text` type through the density mode — consecutive ranks never share
+  a type (an `h1` and `h2` both on `Display Extra Small` flatten the page), and
+  headings inside a `Card` step down one stop ([density.md](density.md)).
 - **Responsive**: reflows mobile -> up with no px literals; clusters stack, `Table`
   scrolls, nav collapses; touch targets stay >= 24 CSS px.
 - **Color discipline**: at most one dominant brand band per view; status palettes
@@ -126,9 +149,10 @@ Every generated screen must pass this. It is the definition of done.
 
 **Foundations** (always apply): [principles.md](principles.md) ·
 [tokens.md](tokens.md) · [spacing-steps.md](spacing-steps.md) ·
+[density.md](density.md) ·
 [how-to-page-layout.md](how-to-page-layout.md) · [how-to-color.md](how-to-color.md) ·
 [how-to-accessibility.md](how-to-accessibility.md) · [how-to-host.md](how-to-host.md) ·
-[a2ui.md](a2ui.md)
+[getting-started](../uxelle-components/getting-started.md) · [a2ui.md](a2ui.md)
 
 **Experiences** — product: [app-chrome](recipe-app-chrome.md) ·
 [page-shell](recipe-page-shell.md) · [dashboard-overview](recipe-dashboard-overview.md) ·

package/skills/uxelle-design-harness/a2ui.md

@@ -13,12 +13,20 @@ Hosts inject `uxelleCatalogSchema` (and optionally a recipe's messages) into the
 agent prompt and render the result. Do not open package source to "discover" props —
 use the catalog schema the host provides.
 
+Importing `@uxelle/a2ui` registers the full Material Symbols Sharp catalog. React
+hosts that do not use A2UI must `import "@uxelle/icons/register"` themselves if
+generated UI uses icon names beyond GPF chrome.
+
 ## Hard constraints
 
 - **Catalog adapters only.** No raw HTML, no custom components.
 - **No `className` / `style`.** Styling comes from the theme and adapter props.
 - **Layout-spacing tokens only.** `A2uiLayout` accepts `0` or
   `var(--uxl-theme-layout-spacing-*)`; never emit page-chrome breakpoint tokens.
+- **`standard` or `compact` density only.** Chat surfaces are narrow and have no
+  full-bleed bands, so `spacious` never applies and the **Band** role has no
+  meaning. Use `standard` by default, `compact` for data-heavy runtime output
+  ([density.md](density.md)).
 - **No responsive JS.** There is no `matchMedia`. Default to a single, narrow
   column (chat is mobile-like) and stack action clusters (`"direction": "column"`).
 - **Host owns theme.** Never set theme `data-*` or a skip link from adapters; the
@@ -45,12 +53,32 @@ recipe JSON into the customer app.
 Most catalog components map 1:1 to an `A2ui<Name>` adapter (e.g. `Button` ->
 `A2uiButton`, `Textfield` -> `A2uiTextfield`, `Textarea` -> `A2uiTextarea`,
 `Table` -> `A2uiTable`, `Sheet` -> `A2uiSheet`, `Hero` -> `A2uiHero`,
-`Stepper` -> `A2uiStepper` + `A2uiStepperItem`, `ListControls` -> `A2uiListControls`,
+`Image` -> `A2uiImage`, `Stepper` -> `A2uiStepper` + `A2uiStepperItem`,
+`ListControls` -> `A2uiListControls`,
 `Banner` -> `A2uiBanner`, `LabelBadge` -> `A2uiLabelBadge`, `StatTile` -> `A2uiStatTile`,
+`ChoiceChip` -> `A2uiChoiceChip`, `ChoiceChipGroup` -> `A2uiChoiceChipGroup`,
+`FilterChip` -> `A2uiFilterChip`, `FilterChipGroup` -> `A2uiFilterChipGroup`,
 `DynamicAngle*` -> `A2uiDynamicAngle*`). `Table` has the full family (`A2uiTableGrid`,
 `A2uiTableHead`, `A2uiTableBody`, `A2uiTableRow`, `A2uiTableCell`,
 `A2uiTableHeaderCell`, `A2uiTableColumnSizingProvider`).
 
+`A2uiImage` box size (`width`, `height`, `minWidth`, `maxWidth`, `minHeight`,
+`maxHeight`) is `number|string` — numbers are pixels, strings pass through as CSS
+(including `var(--uxl-…)`). `aspectRatio` crops and computes the missing axis.
+Omit size and `aspectRatio` on an `A2uiImage` nested in `A2uiHero`.
+
+`A2uiChoiceChip` / `A2uiFilterChip` take a `label` string. Do not nest `A2uiText`
+inside a chip. Choice-chip labels use Condensed when unchecked and Condensed Alt
+when checked; filter-chip labels use Condensed. `A2uiFilterChipGroup` wraps whole
+chips; a chip wider than its container ellipsizes so dismiss stays visible.
+Exclusive `A2uiChoiceChip` selection is one checked value in host state (toggles,
+not radios). Use `A2uiRadioGroup` or `A2uiSegmentedControl` for radio semantics.
+
+`A2uiStatTile` labels stay on one line and ellipsize; hover or focus a truncated
+label to read the full name. Pass `label` as a string — do not wrap it in
+`A2uiText` or set truncation. Value and qualifier copy wrap. The overflow tooltip
+is automatic and separate from `tooltipContent`.
+
 Known gaps — substitute rather than invent:
 
 | React | A2UI |
@@ -66,7 +94,8 @@ If a design needs a gap component as its backbone, say so in the recipe's
 
 ## Translating a React recipe
 
-1. Keep the same region order and layout-spacing values.
+1. Keep the same region order. Keep the layout-spacing values too, unless the React
+   surface was `spacious` — then re-resolve its roles at `standard`.
 2. Swap each component for its adapter; expand `Lockup` to stacked `A2uiText`.
 3. Replace `useBreakpointUp` switches with a single narrow column.
 4. Replace React state with host bindings.