@uxelle/skills 0.2.2 → 0.2.3

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/manifest.generated.ts
 var manifest = {
   "schemaVersion": 1,
-  "version": "0.2.2",
+  "version": "0.2.3",
   "skills": [
     {
       "name": "uxelle-components",
@@ -154,8 +154,8 @@ var manifest = {
         },
         {
           "path": "getting-started.md",
-          "size": 2276,
-          "hash": "sha256:c40148458f76df3bdd9a0cf85732cd09bbe621c5625d20c4251aa7f4bd808a90"
+          "size": 3387,
+          "hash": "sha256:5aa1009aaf71d2d45d8f57198ee52942d4220d031948357c646b799b19ffd34f"
         },
         {
           "path": "Hero.md",
@@ -164,8 +164,8 @@ var manifest = {
         },
         {
           "path": "Icon.md",
-          "size": 2218,
-          "hash": "sha256:bfde859f04937c40b1ce2f3b386e9b059e3781878b1bb91471e688de605ccf1b"
+          "size": 2948,
+          "hash": "sha256:c467d672c13c5d52120618d5f932454e5f3a8dbd5f8bdd2e1498b26f676d523d"
         },
         {
           "path": "IconButton.md",
@@ -254,8 +254,8 @@ var manifest = {
         },
         {
           "path": "NavigationSide.md",
-          "size": 5005,
-          "hash": "sha256:32386fd82517e9d74561b4c05b8a7b0951532fcf1ab80b038fe7bde376b96752"
+          "size": 5474,
+          "hash": "sha256:ffe9e9a88ade7c6cef99c1953e4e265afce446d616af366fd4b63206517396bf"
         },
         {
           "path": "NavigationSideGroup.md",
@@ -264,13 +264,13 @@ var manifest = {
         },
         {
           "path": "NavigationSideItem.md",
-          "size": 5839,
-          "hash": "sha256:a57473d0c207155e48e34e495a9a8b195357442871132c04e3a51b0130044cc9"
+          "size": 6595,
+          "hash": "sha256:3e7f51a9eabb5bf144022064b14416cebbc4d7d9eb87ee9c82299c5ecbb50e34"
         },
         {
           "path": "NavigationSideSubItem.md",
-          "size": 2350,
-          "hash": "sha256:f3da7ff70aac2a0568ff6831efd18bd2849d459f88ba41a76006432a33245b02"
+          "size": 2649,
+          "hash": "sha256:3edf70cb4a3cb43abd112cbae73d83385481f004d8e48513ab455596388d221e"
         },
         {
           "path": "NavLink.md",
@@ -344,8 +344,8 @@ var manifest = {
         },
         {
           "path": "SKILL.md",
-          "size": 14408,
-          "hash": "sha256:de312111538d710c822a0212af2188584591d594d4f99ba7f3efb7a4435e9021"
+          "size": 14816,
+          "hash": "sha256:a15ed6eb6c149096d9cb6376ee47e17700cbf36ed498edd176232ff87f78d94b"
         },
         {
           "path": "Spinner.md",
@@ -354,8 +354,8 @@ var manifest = {
         },
         {
           "path": "StatTile.md",
-          "size": 7820,
-          "hash": "sha256:e9330341336d46ab38724a17e76548d8cd4081b06b1a483bfea6be642718ea9e"
+          "size": 8042,
+          "hash": "sha256:76a99c8ea47082659e625c59030d0cef527bd19d8d6cabd635e71016be13754d"
         },
         {
           "path": "Stepper.md",
@@ -415,8 +415,8 @@ var manifest = {
       "files": [
         {
           "path": "a2ui.md",
-          "size": 4779,
-          "hash": "sha256:e557e7caba1471f250a651f6449aa4b8e73b40e05c331dcbda25892b958ecd99"
+          "size": 5279,
+          "hash": "sha256:9ebad576e8878251c6ce2210a7cab70066b30d04f0b38e1963b5eeb9f5c820e3"
         },
         {
           "path": "density.md",
@@ -425,8 +425,8 @@ var manifest = {
         },
         {
           "path": "how-to-accessibility.md",
-          "size": 3554,
-          "hash": "sha256:c19043086e302c1681ae462efa9f7282a9e227aeb78dfe93bf66f6c4f4710bf7"
+          "size": 3732,
+          "hash": "sha256:c66c97e67182cb444fb9ff6f1b02db8da663f928a79bf31517008b9dc3f7a82e"
         },
         {
           "path": "how-to-color.md",
@@ -435,8 +435,8 @@ var manifest = {
         },
         {
           "path": "how-to-host.md",
-          "size": 2647,
-          "hash": "sha256:bdab3b08e77adaabcd582dff4b64838e0723ade66d5c9416be9111f9dc9b49cd"
+          "size": 2856,
+          "hash": "sha256:05187f27fb791bc18c613354635d5d68a044454c166dfce0925116adca3a6cba"
         },
         {
           "path": "how-to-page-layout.md",
@@ -465,8 +465,8 @@ var manifest = {
         },
         {
           "path": "recipe-dashboard-overview.md",
-          "size": 4708,
-          "hash": "sha256:a6a581ca179595535d9d3df0469d362d8e7175e5595bea3222a32733c66c4615"
+          "size": 4857,
+          "hash": "sha256:4fe4573d6eb09730c1737875c835ca9b939cd3d8e8587ecae09ba7331b2ff8d7"
         },
         {
           "path": "recipe-data-table-page.md",
@@ -540,8 +540,8 @@ var manifest = {
         },
         {
           "path": "recipe-stat-callouts.md",
-          "size": 4017,
-          "hash": "sha256:fb3857880f691fd016cb1414ee788e3a9fdfc49f7e61376442965aa018896f6e"
+          "size": 4207,
+          "hash": "sha256:ef84f56f302f623b990dff4e5051256642a41cf2dabab0e102ddf030bff4f61c"
         },
         {
           "path": "recipe-states.md",

package/index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.2.2",
+  "version": "0.2.3",
   "skills": [
     {
       "name": "uxelle-components",
@@ -153,8 +153,8 @@
         },
         {
           "path": "getting-started.md",
-          "size": 2276,
-          "hash": "sha256:c40148458f76df3bdd9a0cf85732cd09bbe621c5625d20c4251aa7f4bd808a90"
+          "size": 3387,
+          "hash": "sha256:5aa1009aaf71d2d45d8f57198ee52942d4220d031948357c646b799b19ffd34f"
         },
         {
           "path": "Hero.md",
@@ -163,8 +163,8 @@
         },
         {
           "path": "Icon.md",
-          "size": 2218,
-          "hash": "sha256:bfde859f04937c40b1ce2f3b386e9b059e3781878b1bb91471e688de605ccf1b"
+          "size": 2948,
+          "hash": "sha256:c467d672c13c5d52120618d5f932454e5f3a8dbd5f8bdd2e1498b26f676d523d"
         },
         {
           "path": "IconButton.md",
@@ -253,8 +253,8 @@
         },
         {
           "path": "NavigationSide.md",
-          "size": 5005,
-          "hash": "sha256:32386fd82517e9d74561b4c05b8a7b0951532fcf1ab80b038fe7bde376b96752"
+          "size": 5474,
+          "hash": "sha256:ffe9e9a88ade7c6cef99c1953e4e265afce446d616af366fd4b63206517396bf"
         },
         {
           "path": "NavigationSideGroup.md",
@@ -263,13 +263,13 @@
         },
         {
           "path": "NavigationSideItem.md",
-          "size": 5839,
-          "hash": "sha256:a57473d0c207155e48e34e495a9a8b195357442871132c04e3a51b0130044cc9"
+          "size": 6595,
+          "hash": "sha256:3e7f51a9eabb5bf144022064b14416cebbc4d7d9eb87ee9c82299c5ecbb50e34"
         },
         {
           "path": "NavigationSideSubItem.md",
-          "size": 2350,
-          "hash": "sha256:f3da7ff70aac2a0568ff6831efd18bd2849d459f88ba41a76006432a33245b02"
+          "size": 2649,
+          "hash": "sha256:3edf70cb4a3cb43abd112cbae73d83385481f004d8e48513ab455596388d221e"
         },
         {
           "path": "NavLink.md",
@@ -343,8 +343,8 @@
         },
         {
           "path": "SKILL.md",
-          "size": 14408,
-          "hash": "sha256:de312111538d710c822a0212af2188584591d594d4f99ba7f3efb7a4435e9021"
+          "size": 14816,
+          "hash": "sha256:a15ed6eb6c149096d9cb6376ee47e17700cbf36ed498edd176232ff87f78d94b"
         },
         {
           "path": "Spinner.md",
@@ -353,8 +353,8 @@
         },
         {
           "path": "StatTile.md",
-          "size": 7820,
-          "hash": "sha256:e9330341336d46ab38724a17e76548d8cd4081b06b1a483bfea6be642718ea9e"
+          "size": 8042,
+          "hash": "sha256:76a99c8ea47082659e625c59030d0cef527bd19d8d6cabd635e71016be13754d"
         },
         {
           "path": "Stepper.md",
@@ -414,8 +414,8 @@
       "files": [
         {
           "path": "a2ui.md",
-          "size": 4779,
-          "hash": "sha256:e557e7caba1471f250a651f6449aa4b8e73b40e05c331dcbda25892b958ecd99"
+          "size": 5279,
+          "hash": "sha256:9ebad576e8878251c6ce2210a7cab70066b30d04f0b38e1963b5eeb9f5c820e3"
         },
         {
           "path": "density.md",
@@ -424,8 +424,8 @@
         },
         {
           "path": "how-to-accessibility.md",
-          "size": 3554,
-          "hash": "sha256:c19043086e302c1681ae462efa9f7282a9e227aeb78dfe93bf66f6c4f4710bf7"
+          "size": 3732,
+          "hash": "sha256:c66c97e67182cb444fb9ff6f1b02db8da663f928a79bf31517008b9dc3f7a82e"
         },
         {
           "path": "how-to-color.md",
@@ -434,8 +434,8 @@
         },
         {
           "path": "how-to-host.md",
-          "size": 2647,
-          "hash": "sha256:bdab3b08e77adaabcd582dff4b64838e0723ade66d5c9416be9111f9dc9b49cd"
+          "size": 2856,
+          "hash": "sha256:05187f27fb791bc18c613354635d5d68a044454c166dfce0925116adca3a6cba"
         },
         {
           "path": "how-to-page-layout.md",
@@ -464,8 +464,8 @@
         },
         {
           "path": "recipe-dashboard-overview.md",
-          "size": 4708,
-          "hash": "sha256:a6a581ca179595535d9d3df0469d362d8e7175e5595bea3222a32733c66c4615"
+          "size": 4857,
+          "hash": "sha256:4fe4573d6eb09730c1737875c835ca9b939cd3d8e8587ecae09ba7331b2ff8d7"
         },
         {
           "path": "recipe-data-table-page.md",
@@ -539,8 +539,8 @@
         },
         {
           "path": "recipe-stat-callouts.md",
-          "size": 4017,
-          "hash": "sha256:fb3857880f691fd016cb1414ee788e3a9fdfc49f7e61376442965aa018896f6e"
+          "size": 4207,
+          "hash": "sha256:ef84f56f302f623b990dff4e5051256642a41cf2dabab0e102ddf030bff4f61c"
         },
         {
           "path": "recipe-states.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxelle/skills",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "uxElle generate-UI agent skills: component API reference and design harness, as versioned markdown with a machine-readable manifest",
   "type": "module",
   "repository": {

package/skills/uxelle-components/Icon.md

@@ -2,7 +2,7 @@
 
 Import: `import { Icon } from "@uxelle/components";`
 
-Renders Material Symbols icons.
+Inline Material Symbols Sharp pictogram.
 
 ## Props
 
@@ -10,13 +10,13 @@ Renders Material Symbols icons.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| iconName | `string` | `"add"` | Material Symbols ligature name to render, e.g. `home`, `close`, or `settings`. Names outside that set render as literal text. |
+| iconName | `string` | `"add"` | Material Symbols Sharp name to render, e.g. `home`, `close`, or `settings`. GPF chrome names always resolve. Any other name needs `import "@uxelle/icons/register"` (or `registerIcons`) before render. Unknown names render no glyph (an empty span — a visual-only miss that a11y tests will not catch). Type names with `UxelleIconName` from `@uxelle/icons` to catch typos at compile time. |
 | size | `number` | `24` | Glyph size in pixels, applied as an inline `font-size`. Valid range is 8–128 and out-of-range values warn in development; leaving it at the default emits no inline size, so CSS or a parent token can drive it. |
 | style | `CSSProperties` | `—` | Inline styles merged onto the icon `span`, applied after the `size`-derived `font-size` — a `fontSize` here therefore overrides `size`. |
 | "aria-label" | `string` | `""` | Accessible name for an icon that carries meaning. Setting it also suppresses the automatic `aria-hidden`, so the icon becomes visible to assistive technology. |
 | "aria-hidden" | `"auto" \| "true" \| "false"` | `undefined` | Explicitly includes or excludes the icon from the accessibility tree. Leave it unset for the default: hidden when there is no `aria-label`, exposed once there is one. |
 | role | `string` | `""` | Role placed on the icon `span`. Pair `img` with `aria-label` when the glyph is meaningful content; leave it unset for decorative icons. |
-| variant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Glyph weight: `sharpFilled` renders the solid form through font-variation settings, `sharpUnfilled` the outlined form. |
+| variant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Glyph weight: `sharpFilled` renders the solid SVG, `sharpUnfilled` the outlined form. |
 
 <!-- prettier-ignore-end -->
 
@@ -40,4 +40,4 @@ Renders Material Symbols icons.
 
 ## Notes
 
-- Uses the material-symbols sharp font; updates instantly when `iconName` changes. By default, icons are hidden from screen readers (`aria-hidden="true"`) as they are typically decorative. Provide an `aria-label` when the icon conveys meaningful information.
+- Looks up a Sharp SVG from `iconName` and `variant`. `@uxelle/components` ships the GPF chrome set; register the full catalog with `import "@uxelle/icons/register"` or **registerIcons** before the first render. Unknown names render no glyph and warn in development — treat that as an authoring error, not UI copy. Production is silent: an icon-only control with `aria-label` still has an accessible name, so this is a visual-only failure that a11y tests will not catch. Import `@uxelle/icons/register` in the host, or type names with `UxelleIconName` from `@uxelle/icons`. By default, icons are hidden from screen readers (`aria-hidden="true"`) as they are typically decorative. Provide an `aria-label` when the icon conveys meaningful information.

package/skills/uxelle-components/NavigationSide.md

@@ -10,9 +10,9 @@ App chrome for a vertical side rail, or a compact top bar on small layouts.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| expanded | `boolean` | `—` | Controlled rail width: wide labeled rail when true, icon-only rail when false. Pass with `onExpandedChange`; omit to let `defaultExpanded` and the built-in toggle own the width. Ignored when the mobile layout is shown. |
+| expanded | `boolean` | `—` | Controlled rail width: wide labeled rail when true, icon-only rail when false. Pass with `onExpandedChange`; omit to let `defaultExpanded` and the built-in toggle own the width. Ignored when the mobile layout is shown. Collapsing hides open nested destination lists; accordion parents of the current nested page show the selected appearance. |
 | defaultExpanded | `boolean` | `true` | Whether the rail starts wide and labeled (true) or icon-only (false) when `expanded` is omitted. The built-in toggle owns the width after mount. |
-| onExpandedChange | `(expanded: boolean) => void` | `—` | Called with the next width state each time the expand/collapse control is activated. Required to track the width when `expanded` is set. |
+| onExpandedChange | `(expanded: boolean) => void` | `—` | Called with the next width state each time the expand/collapse control is activated. Required to track the width when `expanded` is set. Collapsing hides open nested destination lists on accordion rows. |
 | mobile | `boolean` | `—` | Top-bar chrome when true; side rail when false. SSR hosts must pass `true` or `false` so server and client markup match. Omit only in client-only surfaces to follow the theme mobile range (`--uxl-theme-layout-mobile-screen-width-max`). The menu opens a right sheet with the same center and bottom slots as the rail. |
 | logoSlot | `boolean` | `true` | Renders the logo region on the expanded rail and the mobile top bar. Set `false` to leave it empty; the collapsed rail never shows the logo. |
 | logoSlotContent | `ReactNode` | `undefined` | Content for the logo region, typically a decorative **Logo**. Rendered only when `logoSlot` is true; omit for a neutral placeholder block. |
@@ -45,7 +45,7 @@ Extends `HTMLAttributes` — supports standard HTML attributes.
 ## Notes
 
 - **Rail**: Logo, expand/collapse control, `centerSlotContent` (`NavigationSideGroup` rows), and `bottomSlotContent`. Renders an `<aside>`. Groups remain named `<nav>` landmarks — do not wrap this chrome in another `nav`.
-- **Width**: Set `expanded` for the labeled rail and `expanded={false}` for the icon-only rail. Hosts own when to pass those values (tablet-and-up). This component does not hard-code those widths.
+- **Width**: Set `expanded` for the labeled rail and `expanded={false}` for the icon-only rail. Hosts own when to pass those values (tablet-and-up). This component does not hard-code those widths. Collapsing hides any open accordion nested lists (focus moves to the parent if a nested row had it) and shows the selected appearance on an accordion parent when a nested row is the current page. Expanding restores that open state unless the flyout was dismissed while collapsed.
 - **Mobile**: Pass `mobile` (`true` or `false`) in SSR so the first paint matches hydration. The server snapshot for an omitted `mobile` is always the rail, so a phone viewport would swap to the top bar on the client. Omit `mobile` only in client-only surfaces (for example Storybook) to follow the theme mobile range (`--uxl-theme-layout-mobile-screen-width-max`). When the mobile layout is shown, the menu control opens a right `Sheet` (no visible title, labeled Menu for assistive tech) with the same `centerSlotContent` and `bottomSlotContent` as the rail (labeled rows, not the collapsed icon rail). The logo stays on the top bar. Use `menuOpen` / `onMenuOpenChange` to control the sheet (for example to close it after navigation). `onMenuClick` still fires on the menu control.
 - **Slots**: Omit a slot to fill demo content. Pass `false` to leave a region empty. `logoSlot={false}` hides the logo on the expanded rail and the mobile bar.
 - **Bottom slot**: Typical account rows use `List` + `ListItem`. List item text stays on one line during the rail width transition (same as destination labels) so it is revealed horizontally instead of wrapping.

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

@@ -221,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`.

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/getting-started.md

@@ -12,10 +12,11 @@ Peer dependencies: React 18 or 19.
 npm install @uxelle/components @uxelle/themes
 ```
 
+Import the two stylesheets:
+
 ```tsx
-import "@uxelle/components/styles.css";
-import "@uxelle/components/index.css";
-import "@uxelle/themes/themes/open-source/open-source.css";
+import "@uxelle/components/base.css";
+import "@uxelle/themes/open-source.css";
 
 import { Button } from "@uxelle/components";
 
@@ -24,22 +25,52 @@ function App() {
 }
 ```
 
-`styles.css` loads Material Symbols and the global baseline. `index.css` ships the bundled component rules. Load both stylesheets in the host app — the package JS does not import CSS automatically.
+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 the three stylesheets in `app/layout.tsx` (or a top-level provider). JS side effects will not style App Router.
+- 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. Apply a theme by importing one CSS file. Set `data-open-source="light"` or `data-open-source="dark"` on `<html>`, plus `data-color-switcher="default"`. Optional: wrap the app with `UXelleThemeProvider` so those attributes stay in sync.
+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 "@uxelle/themes/themes/open-source/open-source.css";
 import { UXelleThemeProvider } from "@uxelle/themes/react";
 
 function AppShell({ children }: { children: React.ReactNode }) {

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

@@ -13,6 +13,10 @@ 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.
@@ -70,6 +74,11 @@ 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 |

package/skills/uxelle-design-harness/how-to-accessibility.md

@@ -26,7 +26,7 @@ This file covers **composition**: landmarks, heading ranks, names, and live regi
 - `aria-describedby` — extra help, not the name (`fieldDescription`, instructions).
 - `aria-hidden="true"` — decorative / redundant graphics (default `Icon`).
 - `aria-live="polite"` — status that appears without moving focus. `assertive` only for urgent interruptions.
-- `aria-current="page"` — current item in nav (`NavLink`, or `activated` on `NavigationSideItem` / `NavigationSideSubItem` destinations — not accordion parents).
+- `aria-current="page"` — current item in nav (`NavLink`, or `activated` on `NavigationSideItem` / `NavigationSideSubItem` destinations — not accordion parents). When the side rail is collapsed, an accordion parent of an activated nested row still shows the selected appearance so the current section remains visible on the icon-only rail.
 - `aria-expanded` — only on a real disclosure control, not on every section.
 - `aria-pressed` — toggle buttons (`IconButton` `activated`); `Switch` uses `checked` instead.
 

package/skills/uxelle-design-harness/how-to-host.md

@@ -14,6 +14,10 @@ Load component and theme CSS as in
 [getting-started.md](../uxelle-components/getting-started.md). Do not set
 `font-family` in app CSS — `Text` uses theme tokens.
 
+If generated UI uses Material Symbol names beyond GPF chrome (`home`, `mail`,
+`campaign`, …), add `import "@uxelle/icons/register"` once at the app entry.
+`@uxelle/a2ui` already registers the full catalog.
+
 On `<html>`:
 
 - Theme mode (host-owned): `data-open-source="light" | "dark"` (other themes use

package/skills/uxelle-design-harness/recipe-dashboard-overview.md

@@ -32,7 +32,8 @@ sections
 
 KPI and card grids reflow with `auto-fit` / `minmax` (no JS); the header stacks and
 its actions go `fullWidth` below tablet; the primary `Table` scrolls horizontally
-when narrow. See [how-to-page-layout.md](how-to-page-layout.md#responsiveness).
+when narrow. StatTile labels ellipsize on one line so a KPI row stays scannable.
+See [how-to-page-layout.md](how-to-page-layout.md#responsiveness).
 
 ## Spacing
 
@@ -49,7 +50,8 @@ KPIs rather than a dense monitoring surface — but pick one mode and hold it.
 ## A11y
 
 One `main`, one `h1`. Name each region (KPIs `aria-label="Key metrics"`, the primary
-surface by its heading). KPI deltas pair color with a sign or word. Loading and empty
+surface by its heading). KPI deltas pair color with a sign or word. Truncated KPI
+labels keep the full name on the group; hover or focus reveals it. Loading and empty
 for the primary surface follow [states](recipe-states.md). See
 [how-to-accessibility.md](how-to-accessibility.md).
 

package/skills/uxelle-design-harness/recipe-stat-callouts.md

@@ -24,6 +24,8 @@ A small set of headline numbers — revenue, active users, uptime, "10k+ teams."
 - Do not put `onClick` on StatTile — put a `Link` or `IconButton` in
   `trailingSlotContent`.
 - Do not signal a delta with color alone — pair it with a sign or word.
+- Do not wrap StatTile labels yourself. The label stays on one line and
+  ellipsizes; hover or focus a truncated label to read the full name.
 
 ## Regions
 
@@ -50,10 +52,10 @@ band on a `spacious` page it adds breathing with the **Band** step (`large-15`)
 ## A11y
 
 Each figure and its label read together. StatTile names the group from `label`
-automatically (including `valueFirst`). If there is no label, set `aria-label`
-that combines the figure and its meaning. If the trailing slot holds a delta,
-keep the meaning in text, not color alone. See
-[how-to-accessibility.md](how-to-accessibility.md).
+automatically (including `valueFirst`), including when the visible label is
+ellipsized. If there is no label, set `aria-label` that combines the figure and
+its meaning. If the trailing slot holds a delta, keep the meaning in text, not
+color alone. See [how-to-accessibility.md](how-to-accessibility.md).
 
 ## Color