@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/NavigationSideGroup.md

@@ -0,0 +1,36 @@
+# NavigationSideGroup
+
+Import: `import { NavigationSideGroup } from "@uxelle/components";`
+
+Landmark list of destination rows in a vertical side rail, with an optional end divider.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | `NavigationSideItem` rows, rendered as list items inside this group's `<ul>`. Accordion parents keep their own `NavigationSideSubItem` rows as children, so sub-items are never direct children of the group. |
+| endDivider | `boolean` | `true` | Adds a low-emphasis `Divider` below the last row to separate this group from the next. Set `false` on the last group in the rail. |
+| collapsed | `boolean` | `false` | Icon-only layout for every row in the group: labels hide and each row falls back to a tooltip. A row can opt out with its own `navCollapsed`, and a parent `NavigationSide` with `expanded={false}` turns this on for its groups. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<NavigationSideGroup aria-label="Product">
+  <NavigationSideItem label="Overview" href="/overview" leadingIconName="dashboard" />
+  <NavigationSideItem label="Timing" href="/timing" leadingIconName="schedule" />
+</NavigationSideGroup>
+```
+
+
+## Notes
+
+- Renders a named `<nav>` containing a `<ul>` of `NavigationSideItem` children (including accordion parents with `NavigationSideSubItem` rows). This is the side navigation for the experience — not a nested landmark inside another `nav`. Compose groups in `NavigationSide` `centerSlotContent`; that chrome is an `<aside>` (or a `<header>` when `mobile`), not a `nav`.
+- Pass `aria-label` (or `aria-labelledby`) when more than one group is on the page so each landmark has a unique name. The default name is “Side navigation”.
+- Set `collapsed` for the icon-only rail layout, or place the group in `NavigationSide` with `expanded={false}` so child rows inherit collapsed spacing unless they set `navCollapsed` themselves.
+- Set `endDivider` to show a low-emphasis horizontal rule after the last row.

package/skills/uxelle-components/NavigationSideItem.md

@@ -0,0 +1,56 @@
+# NavigationSideItem
+
+Import: `import { NavigationSideItem } from "@uxelle/components";`
+
+Destination row for a vertical side navigation rail. Shows a leading icon, label, and optional trailing slot.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` | `"Label"` | Row text shown beside the leading icon. Also the accessible name: on the collapsed rail the text is hidden, applied as `aria-label`, and surfaced in a tooltip on hover and focus. |
+| leadingIconName | `string` | `"outbound"` | Material Symbol name for the leading icon. Shown at both rail widths — it is the only visible content once the rail collapses. |
+| iconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the leading icon: `sharpUnfilled` for the outline glyph, `sharpFilled` for the solid one. |
+| trailingSlot | `boolean` | `false` | Reveals `trailingSlotContent` at the end of the row. Ignored when `accordion` is true (the chevron owns that spot) or when the rail is collapsed. |
+| 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. |
+| 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. |
+| 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"`. |
+| href | `string` | `undefined` | Destination URL, which renders the row as an anchor instead of a button. Ignored when `accordion` is true — put a section landing page in a `NavigationSideSubItem` child instead. |
+| className | `string` | `—` |  |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<NavigationSideItem label="Dashboard" href="/dashboard" leadingIconName="dashboard" />
+```
+
+```tsx
+<NavigationSideItem accordion label="Products">
+  <NavigationSideSubItem leadingIcon={false} label="Overview" href="/products" />
+  <NavigationSideSubItem leadingIcon={false} label="Catalog" href="/products/catalog" />
+</NavigationSideItem>
+```
+
+
+## Notes
+
+- 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.
+- 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.
+- Trailing slot content must be non-interactive (no nested buttons or links). Use a badge, text, or decorative icon.

package/skills/uxelle-components/NavigationSideSubItem.md

@@ -0,0 +1,39 @@
+# NavigationSideSubItem
+
+Import: `import { NavigationSideSubItem } from "@uxelle/components";`
+
+Nested destination row under an accordion side-nav parent.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` | `"Label"` | Text for this nested destination, indented under its accordion `NavigationSideItem` parent. It is the row's accessible name, and becomes the `ListItem` center text in the collapsed-rail flyout. |
+| 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. |
+| 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` | `—` |  |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<NavigationSideItem accordion label="Products">
+  <NavigationSideSubItem leadingIcon={false} label="Overview" href="/products" />
+  <NavigationSideSubItem leadingIcon={false} label="Catalog" href="/products/catalog" />
+</NavigationSideItem>
+```
+
+
+## Notes
+
+- 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 `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).

package/skills/uxelle-components/NotificationBadge.md

@@ -0,0 +1,62 @@
+# NotificationBadge
+
+Import: `import { NotificationBadge } from "@uxelle/components";`
+
+Notification indicator on a corner of its child (typically `Icon` or `IconButton`). Toggle `counter` and `count` for a numeric pill.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| position | `"top-left" \| "top-right"` | `"top-right"` | Corner of the wrapped child the indicator sits on. Use `top-left` when the child's own content or a neighbouring control would collide with the usual top-right placement. |
+| overlap | `"rectangular" \| "circular"` | `—` | Shape of the wrapped child, which sets how far the indicator is pulled toward its center: `circular` tightens the offset for round hosts such as an avatar, `rectangular` suits square icons and buttons. Omit to follow the theme's overlay prop-control (the Open Source theme resolves to circular, the others to rectangular). |
+| counter | `boolean` | `false` | When true the indicator becomes a numeric pill showing `count`; when false it stays a small dot with no text. |
+| count | `number` | `—` | Number shown in the counter pill. Values above 99 render as `99+`, an omitted count is treated as `0`, and the value is ignored while `counter` is false. |
+| dataColorSwitcher | `"neutral" \| "neutral-alt" \| "primary" \| "secondary" \| "tertiary" \| "ancillary" \| "success" \| "warning" \| "danger" \| "info"` | `"danger"` | Palette for the dot or counter fill and its text. Applied as `data-color-switcher` on the indicator only, so the ring separating it from the child keeps the page palette even when the app or a toolbar sets a different one on `:root`. |
+| "data-color-switcher" | `string` | `—` | Attribute spelling of `dataColorSwitcher`, for call sites that spread DOM props. Wins over `dataColorSwitcher` when both are set. |
+| indicatorAriaHidden | `boolean` | `true` | Keeps the dot or counter out of the accessibility tree so it is not announced separately from the control it decorates; instead carry unread state on that control. Set false only when the indicator itself should be read, and pair it with `indicatorLabel` or `indicatorId`. |
+| indicatorId | `string` | `""` | Id placed on the indicator element so the focusable child can point at it with `aria-describedby` and have the count read as part of that control's description. |
+| indicatorAriaLive | `"off" \| "polite" \| "assertive"` | `""` | How count changes are announced once the indicator is exposed with `indicatorAriaHidden={false}`: `polite` waits for a pause, `assertive` interrupts. Ignored while the indicator is hidden from assistive technology. |
+| indicatorLabel | `string` | `""` | Accessible name for a dot-only indicator exposed with `indicatorAriaHidden={false}`, such as "Unread". Ignored when `counter` is true because the visible number names it, and a missing value warns in development. |
+| children (required) | `ReactNode` | `—` | Element the badge decorates, typically an **Icon** or **IconButton**. The wrapper sizes itself to this node and overlays the indicator on its corner, so set icon or control dimensions on the child rather than on the badge. |
+| "aria-label" | `string` | `""` | Accessible name for the wrapper span. Rarely the right place — name the focusable child such as an `IconButton` instead, so unread state is announced with the control. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that name the wrapper span. As with `aria-label`, prefer naming the focusable child. |
+| "aria-describedby" | `string` | `""` | Space-separated ids of elements that describe the wrapper span. To tie the count to the control instead, set `indicatorId` and reference it from the focusable child. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<NotificationBadge position="top-right">
+  <Icon iconName="mail" variant="sharpUnfilled" />
+</NotificationBadge>
+```
+
+```tsx
+<NotificationBadge position="top-right" counter count={3}>
+  <Icon iconName="mail" variant="sharpUnfilled" />
+</NotificationBadge>
+```
+
+```tsx
+<NotificationBadge dataColorSwitcher="success" position="top-right">
+  <Icon iconName="mail" variant="sharpUnfilled" />
+</NotificationBadge>
+```
+
+```tsx
+<NotificationBadge overlap="circular">
+  <Avatar … />
+</NotificationBadge>
+```
+
+
+## Notes
+
+- The wrapper sizes to `children`; set icon / control dimensions on the child you pass in.
+- **Accessibility (WCAG-aligned):** By default the indicator is `aria-hidden` so assistive tech does not hear the dot/counter separately from the control it decorates. Reflect unread state on the **focusable** child (`aria-label`, or `aria-describedby` pointing at `indicatorId` when `indicatorAriaHidden={false}`). For dot-only badges with `indicatorAriaHidden={false}`, set `indicatorLabel`. Use `indicatorAriaLive` when counts update and the indicator stays visible to AT. Contrast uses mapped tokens (AA text / non-text pairs from the theme).
+- **Overlap:** Omit `overlap` to follow the theme overlay prop-control (`Rectangular` or `Circular`; unread tokens fall back to rectangular). Pass `rectangular` or `circular` to override that theme default.
+- **Color:** The outer ring uses the page (inherited) `data-color-switcher` surface (`--uxl-color-switcher-background`). Fill and counter text follow `dataColorSwitcher` on the dot only. Storybook’s toolbar palette affects the ring; the prop still scopes danger/success/etc. for the pill.

package/skills/uxelle-components/Pagination.md

@@ -0,0 +1,49 @@
+# Pagination
+
+Import: `import { Pagination } from "@uxelle/components";`
+
+Numbered pagination footer for tables, lists, and card grids.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| currentPage | `number` | `PAGINATION_DEFAULTS.defaultCurrentPage` | Active page when controlled, 1-based and clamped to the available range. Pass with `onChange`; omit it to let the component track its own page from `defaultCurrentPage`. |
+| defaultCurrentPage | `number` | `1` | Page shown on first render when `currentPage` is omitted, 1-based. Read only on mount — after that the component owns the value and reports moves through `onChange`. |
+| onChange | `(page: number) => void` | `—` | Fires with the new 1-based page number, already clamped to the available range. Also fires when a `totalItems` or `itemsPerPage` change forces the current page back into range. |
+| disabled | `boolean` | `false` | Blocks interaction on every control — previous/next, the page numbers, and the items-per-page menu. Labels and the item range stay visible. |
+| summary | `boolean` | `true` | When `true`, renders the leading region with the items-per-page menu and live item-range text. When `false`, only the page controls render. |
+| totalItems | `number` | `100` | Size of the full data set. Drives the item-range label and the page count (`ceil(totalItems / itemsPerPage)`, minimum one page). |
+| itemsPerPage | `number` | `PAGINATION_DEFAULTS.defaultItemsPerPage` | Page size when controlled. Pass with `onItemsPerPageChange`; a value larger than `totalItems` falls back to the largest entry in `itemsPerPageOptions` that fits. |
+| defaultItemsPerPage | `number` | `10` | Page size on first render when `itemsPerPage` is omitted. After mount the component owns the value and reports changes through `onItemsPerPageChange`. |
+| onItemsPerPageChange | `(itemsPerPage: number) => void` | `—` | Fires with the newly selected page size, already clamped. When the new size pushes the current page past the last page, `onChange` also fires with the corrected page. |
+| itemsPerPageOptions | `readonly number[]` | `PAGINATION_DEFAULT_ITEMS_PER_PAGE_OPTIONS` | Page sizes offered in the items-per-page menu, in display order. Also the candidate set when the active size has to shrink to fit `totalItems`. |
+| itemsPerPageLabel | `(itemsPerPage: number) => string` | `—` | Builds the items-per-page trigger text from the active page size; the result is also that button's accessible name. Defaults to `Items per page: 10`. |
+| rangeLabel | `(start: number, end: number, total: number) => string` | `—` | Builds the item-range text from the 1-based `start` and `end` of the current page plus `totalItems`. Rendered in a polite live region; defaults to `11-20 of 100`. |
+| previousLabel | `string` | `"Previous page"` | Accessible name for the icon-only previous-page button — its only label. Translate for non-English locales. |
+| nextLabel | `string` | `"Next page"` | Accessible name for the icon-only next-page button — its only label. Translate for non-English locales. |
+| pagesLabel | `string` | `"Pages"` | Accessible name for the group wrapping previous, the page numbers, and next. Translate for non-English locales. |
+| "aria-label" | `string` | `"Pagination"` | Accessible name for the root `nav` landmark; give each pagination region on a page a distinct value. Translate for non-English locales. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Pagination
+  currentPage={page}
+  onChange={setPage}
+  totalItems={100}
+  itemsPerPage={10}
+  onItemsPerPageChange={setItemsPerPage}
+/>
+```
+
+
+## Notes
+
+- **Summary** — Optional leading region with an items-per-page menu and live range text.
+- **Pages** — Circular page controls with ellipsis for long ranges; previous/next disable on first and last page.
+- **State** — Supports controlled and uncontrolled `currentPage` and `itemsPerPage`.

package/skills/uxelle-components/PaginationComplex.md

@@ -0,0 +1,51 @@
+# PaginationComplex
+
+Import: `import { PaginationComplex } from "@uxelle/components";`
+
+Full data-view pagination with items-per-page and page-jump menus.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| currentPage | `number` | `PAGINATION_COMPLEX_DEFAULTS.defaultCurrentPage` | Active page when controlled, 1-based and clamped to the available range. Pass with `onChange`; omit it to let the component track its own page from `defaultCurrentPage`. |
+| defaultCurrentPage | `number` | `1` | Page shown on first render when `currentPage` is omitted, 1-based. Read only on mount — after that the component owns the value and reports moves through `onChange`. |
+| onChange | `(page: number) => void` | `—` | Fires with the new 1-based page number, already clamped to the available range. Also fires when a `totalItems` or `itemsPerPage` change forces the current page back into range. |
+| disabled | `boolean` | `false` | Blocks interaction on every control — previous/next, the page-jump menu, and the items-per-page menu. Labels and the item range stay visible. |
+| totalItems | `number` | `100` | Size of the full data set. Drives the item-range label and the page count (`ceil(totalItems / itemsPerPage)`, minimum one page). |
+| itemsPerPage | `number` | `PAGINATION_COMPLEX_DEFAULTS.defaultItemsPerPage` | Page size when controlled. Pass with `onItemsPerPageChange`; a value larger than `totalItems` falls back to the largest entry in `itemsPerPageOptions` that fits. |
+| defaultItemsPerPage | `number` | `10` | Page size on first render when `itemsPerPage` is omitted. After mount the component owns the value and reports changes through `onItemsPerPageChange`. |
+| onItemsPerPageChange | `(itemsPerPage: number) => void` | `—` | Fires with the newly selected page size, already clamped. When the new size pushes the current page past the last page, `onChange` also fires with the corrected page. |
+| itemsPerPageOptions | `readonly number[]` | `PAGINATION_DEFAULT_ITEMS_PER_PAGE_OPTIONS` | Page sizes offered in the items-per-page menu, in display order. Also the candidate set when the active size has to shrink to fit `totalItems`. |
+| itemsPerPageLabel | `(itemsPerPage: number) => string` | `—` | Builds the items-per-page trigger text from the active page size; the result is also that button's accessible name. Defaults to `Items per page: 10`. |
+| rangeLabel | `(start: number, end: number, total: number) => string` | `—` | Builds the item-range text from the 1-based `start` and `end` of the current page plus `totalItems`. Rendered in a polite live region; defaults to `11-20 of 100`. |
+| currentPageLabel | `(page: number) => string` | `—` | Builds the page-jump trigger text from the active 1-based page; the result is also that button's accessible name. Defaults to `Page 3`. |
+| pageCountLabel | `(totalPages: number) => string` | `—` | Builds the total-page-count text beside the page-jump trigger, which also describes that button through `aria-describedby`. Defaults to `of 120`. |
+| previousLabel | `string` | `"Previous page"` | Accessible name for the icon-only previous-page button — its only label. Translate for non-English locales. |
+| nextLabel | `string` | `"Next page"` | Accessible name for the icon-only next-page button — its only label. Translate for non-English locales. |
+| pagesLabel | `string` | `"Pages"` | Accessible name for the group wrapping the page-jump menu, the page count, and previous/next. Translate for non-English locales. |
+| "aria-label" | `string` | `"Pagination"` | Accessible name for the root `nav` landmark; give each pagination region on a page a distinct value. Translate for non-English locales. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<PaginationComplex
+  currentPage={page}
+  onChange={setPage}
+  totalItems={1200}
+  itemsPerPage={10}
+  onItemsPerPageChange={setItemsPerPage}
+/>
+```
+
+
+## Notes
+
+- **Left** — Items-per-page menu and live item-range text.
+- **Right** — Page-jump menu, total page count, and previous/next controls.
+- **Page jump** — Lists every page up to 100 entries; larger totals window around the current page and always include first and last.
+- **State** — Supports controlled and uncontrolled `currentPage` and `itemsPerPage`.

package/skills/uxelle-components/PaginationSimple.md

@@ -0,0 +1,44 @@
+# PaginationSimple
+
+Import: `import { PaginationSimple } from "@uxelle/components";`
+
+Compact previous/next pagination with an optional item-range label.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| currentPage | `number` | `PAGINATION_SIMPLE_DEFAULTS.defaultCurrentPage` | Active page when controlled, 1-based and clamped to the available range. Pass with `onChange`; omit it to let the component track its own page from `defaultCurrentPage`. |
+| defaultCurrentPage | `number` | `1` | Page shown on first render when `currentPage` is omitted, 1-based. Read only on mount — after that the component owns the value and reports moves through `onChange`. |
+| onChange | `(page: number) => void` | `—` | Fires with the new 1-based page number, already clamped to the available range. Also fires when a `totalItems` or `itemsPerPage` change forces the current page back into range. |
+| disabled | `boolean` | `false` | Blocks interaction on the previous and next buttons. The item-range label stays visible. |
+| label | `boolean` | `true` | When `true`, the item-range text sits between the previous and next buttons. When `false`, it stays in the DOM as a visually hidden polite live region. |
+| totalItems | `number` | `2000` | Size of the full data set. Drives the item-range label and the page count (`ceil(totalItems / itemsPerPage)`, minimum one page). |
+| itemsPerPage | `number` | `25` | Fixed page size used to derive the item range and the page count. There is no items-per-page menu here, so it only changes when you change the prop. |
+| rangeLabel | `(start: number, end: number, total: number) => string` | `—` | Builds the item-range text from the 1-based `start` and `end` of the current page plus `totalItems`. Defaults to `1-25 of 2,000 Items`, and is still exposed to assistive tech when `label` is `false`. |
+| previousLabel | `string` | `"Previous page"` | Accessible name for the icon-only previous-page button — its only label. Translate for non-English locales. |
+| nextLabel | `string` | `"Next page"` | Accessible name for the icon-only next-page button — its only label. Translate for non-English locales. |
+| pagesLabel | `string` | `"Pages"` | Accessible name for the group wrapping previous, the item range, and next. Translate for non-English locales. |
+| "aria-label" | `string` | `"Pagination"` | Accessible name for the root `nav` landmark; give each pagination region on a page a distinct value. Translate for non-English locales. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<PaginationSimple
+  currentPage={page}
+  onChange={setPage}
+  totalItems={2000}
+  itemsPerPage={25}
+/>
+```
+
+
+## Notes
+
+- **Label** — When `label` is true, shows the current item range between chevrons. When false, the range stays in a polite live region for assistive technologies.
+- **Boundaries** — Previous disables on the first page; next disables on the last page.
+- **State** — Supports controlled and uncontrolled `currentPage`.

package/skills/uxelle-components/ProductCard.md

@@ -0,0 +1,46 @@
+# ProductCard
+
+Import: `import { ProductCard } from "@uxelle/components";`
+
+Product-oriented card with stacked top, center, and bottom content regions.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| topSlot | `boolean` | `true` | Gate for the first stacked region. Set `false` to suppress it even when `topSlotContent` is set; the region is skipped anyway when that content is empty, so no gap is left behind. |
+| topSlotContent | `ReactNode` | `null` | Content for the first stacked region, typically a `LabelBadge`, a title, and supporting copy. Rendered only when `topSlot` is true and this is non-empty. `ProductCard` takes no `children` — use these slots. |
+| centerSlot | `boolean` | `true` | Gate for the middle stacked region. Set `false` to suppress it even when `centerSlotContent` is set; the region is skipped anyway when that content is empty, so no gap is left behind. |
+| centerSlotContent | `ReactNode` | `null` | Content for the middle stacked region, typically an `Image`. Rendered only when `centerSlot` is true and this is non-empty. |
+| bottomSlot | `boolean` | `true` | Gate for the last stacked region. Set `false` to suppress it even when `bottomSlotContent` is set; the region is skipped anyway when that content is empty, so no gap is left behind. |
+| bottomSlotContent | `ReactNode` | `null` | Content for the last stacked region, typically a `Button` or action group. Rendered only when `bottomSlot` is true and this is non-empty. |
+| padding | `"Default" \| "None"` | `"Default"` | Inner spacing and stroke around the card. `Default` applies theme spacing and a 1px stroke; `None` removes both so media can bleed to the edges. Elevation stays either way. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<ProductCard
+  topSlotContent={
+    <>
+      <LabelBadge label="Category" emphasis="low" />
+      <Text type="Display Extra Small">Your product name looks great here</Text>
+      <Text type="Body Medium">Describe something here</Text>
+    </>
+  }
+  centerSlotContent={<Image src="/product.jpg" alt="" aspectRatio="1:1" />}
+  bottomSlotContent={
+    <Button fullWidth emphasis="medium">
+      Learn more
+    </Button>
+  }
+/>
+```
+
+
+## Notes
+
+- Compose category metadata and titles in `topSlotContent`, media in `centerSlotContent`, and actions in `bottomSlotContent`. Toggle regions with `topSlot`, `centerSlot`, and `bottomSlot`; empty content is not rendered, so unused regions do not add gap. Set `padding="None"` when content should bleed to the edges without stroke. Remaining HTML attributes—including `aria-*`, `id`, and `className`—are forwarded to the root element. Prefer `Card` for a single unconstrained content surface.

package/skills/uxelle-components/Quantity.md

@@ -0,0 +1,45 @@
+# Quantity
+
+Import: `import { Quantity } from "@uxelle/components";`
+
+Numeric quantity control with decrement and increment actions and an editable value field.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `boolean` | `true` | Renders the label row above the stepper. The row also needs non-empty `labelText`; once it is hidden, `aria-label` or `aria-labelledby` are forwarded to the input so the field still has a name. |
+| labelText | `string` | `"Quantity"` | Visible label text tied to the numeric input through `htmlFor`. An empty string hides the whole label row even when `label` is true, so supply `aria-label` in that case. |
+| fieldMessage | `boolean` | `false` | Renders a helper FieldMessage under the stepper and links it to the input with `aria-describedby`. Falls back to a min/max hint when `fieldMessageContent` is empty. |
+| fieldMessageContent | `string` | `""` | Helper copy shown while `fieldMessage` is on. Leave it empty to use the generated hint that reads out the current `min` and `max`. |
+| value | `number` | `QUANTITY_DEFAULT_VALUE` | Current quantity, which makes the field controlled. Pair with `onChange` or the stepper cannot update, and note the value is clamped into `min`–`max` before display. |
+| defaultValue | `number` | `QUANTITY_DEFAULT_VALUE` | Starting quantity when `value` is omitted. Read once on mount and clamped into `min`–`max`; later changes to it are ignored. |
+| min | `number` | `QUANTITY_VALUE_MIN` | Lowest quantity the field accepts. Decrement is disabled here, typed input clamps up to it, and Home jumps straight to it. |
+| max | `number` | `QUANTITY_VALUE_MAX` | Highest quantity the field accepts. Increment is disabled here, typed input clamps down to it, and End jumps straight to it. |
+| onChange | `(value: number) => void` | `—` | Receives the committed, clamped quantity — from the stepper buttons, arrow keys, Home / End, or when typed input commits on Enter or blur. Typing on its own does not fire it. |
+| decrementDisabled | `boolean` | `false` | Forces the decrement button off even away from `min`, where it is already disabled automatically. While off, typed input cannot be clamped below the current quantity. |
+| incrementDisabled | `boolean` | `false` | Forces the increment button off even away from `max`, where it is already disabled automatically. While off, typed input cannot be clamped above the current quantity. |
+| required | `boolean` | `false` | Marks the field mandatory: required indicator on the label plus `required` and `aria-required` on the input. Enforcement is left to the surrounding form. |
+| decrementAriaLabel | `string` | `"Decrease quantity"` | Accessible name announced for the minus button, which has no visible text. Localize it alongside `labelText`. |
+| incrementAriaLabel | `string` | `"Increase quantity"` | Accessible name announced for the plus button, which has no visible text. Localize it alongside `labelText`. |
+| name | `string` | `""` | Form field name on the numeric input, so the quantity is submitted with the surrounding form. Omit it for a standalone stepper. |
+| id | `string` | `"qty-field"` | Id for the numeric input and the `htmlFor` target of the built-in label. Omit it for a generated id; set it when external `aria-describedby` copy or tests need a stable hook. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Quantity labelText="Quantity" min={0} max={99} defaultValue={1} fieldMessage />
+```
+
+
+## Notes
+
+- Enforces `min` and `max` in code and disables the bound stepper at limits.
+- **Form libraries**: `onChange` emits the committed, clamped number (not a DOM event), which is the shape controlled wrappers expect. With react-hook-form, use `Controller` and pass `field.value` to `value` and `field.onChange` to `onChange` — it receives the number directly. Forward `field.ref`, `field.onBlur`, and `field.name` so focus-on-error, touched state, and submission work. Avoid `register`, which expects a native input event.
+- **Accessibility**: `role="spinbutton"` with `aria-valuemin`, `aria-valuemax`, and `aria-valuenow`. Stepper buttons have accessible names; associate helper copy via `aria-describedby`.
+- **Ref**: Forwarded to the `<input>` for focus and form-library integration.
+- **Unlabeled usage**: When `label={true}` (default) but `labelText` is empty, pass `aria-label` or `aria-labelledby`.

package/skills/uxelle-components/Radio.md

@@ -0,0 +1,55 @@
+# Radio
+
+Import: `import { Radio } from "@uxelle/components";`
+
+Native radio built as `<label>` + `<input type="radio">`.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| checked | `boolean` | `false` | Selected state for a standalone radio — controlled when paired with `onChange`, otherwise only the initial value. Ignored inside RadioGroup, where the group's `value` decides which option is selected. |
+| value | `string` | `""` | Value submitted with the form, and the identity this option is matched against in RadioGroup `value`. Standalone radios fall back to an empty string, and grouped options without one get a generated value that will never match your data. |
+| disabled | `boolean` | `false` | Blocks interaction and applies disabled styling. Grouped options report `aria-disabled` so they stay discoverable, and standalone radios also set the native `disabled` attribute; a disabled RadioGroup does the same to every option. |
+| embedded | `boolean` | `false` | Indicator-only mode for a radio nested in a larger target such as a ListItem row: no hover, active, or focus ring, and `tabIndex={-1}`. The parent must own focus, the accessible name, and keyboard activation. |
+| name | `string` | `—` | Native `name` that groups standalone radios so the browser enforces a single selection. Ignored inside **RadioGroup**, which leaves options unnamed on purpose so Tab reaches each one and submits through a hidden input instead. |
+| onChange | `ChangeEventHandler<HTMLInputElement>` | `—` | Native change handler for a standalone radio; read `event.target.value`. Inside **RadioGroup** the group's own `onChange` runs first and is the one to wire. |
+| label | `boolean` | `true` | Renders `children` beside the dot and points `aria-labelledby` at that text. With `false` there is no visible name, so set `aria-label` or `aria-labelledby` on `inputProps`; a RadioGroup name covers the group, never the option. |
+| children | `ReactNode` | `—` | Label content beside the dot, usually a `Text` node; it becomes the accessible name through `aria-labelledby`. Not rendered when `label` is `false` or `embedded` is set. |
+| id | `string` | `—` | Id applied to the `<input>` and matched by the wrapping label's `htmlFor`. Omit it for a generated id; set it when other elements or tests need a stable hook. |
+| className | `string` | `—` | Class names merged onto the root `<label>`, applied before `labelProps.className` so both survive. The `<input>` keeps its own classes. |
+| labelProps | `Omit<LabelHTMLAttributes<HTMLLabelElement>, "htmlFor" \| "children">` | `—` | Extra attributes spread onto the root `<label>` wrapper — use it for layout hooks, `data-*`, and pointer handlers, not form semantics. `htmlFor` and `children` are managed for you, so they cannot be passed. |
+| inputProps | `RadioInputProps` | `—` | Attributes spread onto the `<input>` before the component's own; put form semantics here (`required`, `form`, `autoComplete`, ARIA). `type`, `name`, `value`, `checked`, `disabled`, `defaultChecked`, `onChange`, and `ref` are managed for you. |
+| "inputProps.aria-describedby" | `string` | `""` | Space-separated ids of elements describing this one option, such as a price or caveat under the label. Group-level helper copy belongs on RadioGroup instead. |
+| "inputProps.aria-label" | `string` | `""` | Accessible name for the option when `label` is false and no visible text exists. Skip it whenever visible label `children` can name the control instead. |
+| "inputProps.aria-labelledby" | `string` | `""` | Space-separated ids of elements naming this option. Merged after the id generated for visible label `children`, so both are announced. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Radio>
+  {/* Content */}
+</Radio>
+```
+
+## Notes
+
+- **Accessibility (WCAG 2.x AA baseline)**
+- **Keyboard** — Native `<input type="radio">` (implicit **`role="radio"`**; **`checked`** exposes state—do not set **`aria-checked`**). **Inside **RadioGroup****, each enabled option uses **`tabIndex={0}`** so **Tab** visits every radio; **arrow keys** move focus and selection. **Enter** / **Space** activate while focused. **`embedded`** uses **`tabIndex={-1}`**.
+- **Option naming** — Visible label text is referenced with **`aria-labelledby`**. Per-option helper copy via **`inputProps`** **`aria-describedby`**.
+- **Disabled** — In a group, **`aria-disabled`** is used (options stay discoverable); standalone radios also set the HTML **`disabled`** attribute for form semantics.
+- **Focus visible** — Keyboard focus is shown with a **`:focus-visible`** outline on the **root `<label>`** (the full hit target), using the design-system focus ring token. **`embedded`** omits the ring; the embedding control must expose a single clear focus indicator.
+- **Name and state** — Checked state is exposed via the native control (not only icon color). The icon is **decorative / redundant** with that state and is marked **`aria-hidden`**. Provide an **accessible name** with visible **`children`**, **`inputProps`** (**`aria-label`** / **`aria-labelledby`**), or **`labelProps`** as appropriate. When **`label={false}`** (no visible label text in this component), set a name on **`inputProps`** so the control is not unnamed.
+- **Form / validation** — Pass **`required`**, **`aria-invalid`**, **`aria-describedby`**, **`aria-errormessage`**, and **`autoComplete`** on **`inputProps`**. Inside **`RadioGroup`**, helper or error text is often associated with the **`fieldset`**; if you describe a specific option, point **`aria-describedby`** at stable **`id`s** on the describing elements.
+- **`labelProps` vs `inputProps`**
+- Spread **`labelProps`** on the root `<label>`. Spread **`inputProps`** on the `<input>` **first**, then the component applies authoritative props (`type`, `name`, `checked`, `disabled`, `value`, `onChange`, `id`), so those always win.
+- Put **form and control** semantics on **`inputProps`**, not on **`labelProps`**: `aria-describedby`, `autoComplete`, `form`. Group-level **`aria-required`**, **`aria-invalid`**, and **`aria-errormessage`** belong on **RadioGroup**. When **not** **`embedded`** and **not** inside **RadioGroup**, you may pass **`tabIndex`** on **`inputProps`**; **inside **RadioGroup****, **`tabIndex`** is **`0`** per enabled option (**`inputProps.tabIndex`** is ignored).
+- **Grouped vs standalone**
+- **Inside **RadioGroup****: selection is owned by the group’s **`value`** / **`defaultValue`**. The **`checked`** prop does **not** control **`checked`** state on the input.
+- **Standalone**: use **`checked`** with **`onChange`** for controlled mode; without **`onChange`**, internal state is seeded from **`checked`** when it is defined; otherwise the option toggles on interaction.
+- **Embedded mode**
+- The radio is not in the tab order (`tabIndex={-1}`). The **embedding parent** must be focusable, have an accessible name, handle keyboard activation, and must not duplicate this control in the tab order ([APG radiobutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton/)).

package/skills/uxelle-components/RadioGroup.md

@@ -0,0 +1,49 @@
+# RadioGroup
+
+Import: `import { RadioGroup } from "@uxelle/components";`
+
+Fieldset-backed radio group; semantics and a11y rules are documented on **RadioGroupProps**.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | The `Radio` options for this group, in DOM order. The group owns selection through `value` / `defaultValue`, so each child only needs its own `value` and its label content; nesting them in fragments or wrapper elements is fine. |
+| name (required) | `string` | `—` | Form field `name` submitted with the selected value through a hidden input. Nested **Radio** controls deliberately omit `name` so Tab reaches every option while the form still sees a single field. |
+| value | `string` | `—` | `value` of the selected option, which makes the group controlled. Pair with `onChange`; omit it to let the group track selection itself from `defaultValue`. |
+| defaultValue | `string` | `—` | `value` selected on first render when uncontrolled. Changing it later resets the uncontrolled selection, so derive it from state that does not churn. |
+| onChange | `(value: string, event: ChangeEvent<HTMLInputElement>) => void` | `—` | Receives the next selected value plus the originating change event. Clicking the already-selected option clears the group, so the handler can be called with an empty string. |
+| label | `boolean` | `false` | Shows the group's visible name above the options and wires it as the accessible name via `aria-labelledby`. Needs non-empty `labelText`; with `false`, name the group with `aria-label` or `aria-labelledby` instead or it is left unnamed. |
+| labelText | `string` | `""` | Text of the visible group name. Blank or whitespace-only text hides the row entirely, leaving the group unnamed unless you pass `aria-label` or `aria-labelledby`. |
+| fieldMessage | `ReactNode` | `—` | Helper or validation content rendered below the options. Strings and numbers are wrapped in a **FieldMessage** styled by `fieldMessageType`; any other node renders as-is, and its container id is linked to the group automatically. |
+| fieldMessageType | `"Info" \| "Danger" \| "Warning" \| "Success"` | `RADIO_GROUP_DEFAULTS.fieldMessageType` | Tone and icon for a string or number `fieldMessage`. `Danger` also marks the group invalid, links the message with `aria-errormessage`, and announces it politely; other types link it with `aria-describedby`. |
+| required | `boolean` | `false` | Sets `aria-required` on the radiogroup so a selection is announced as mandatory. Nothing is enforced natively — validate the group value yourself and report the failure through `fieldMessage`. |
+| invalid | `boolean` | `false` | Marks the group invalid with `aria-invalid` unless `aria-invalid` is passed explicitly. Redundant when `fieldMessageType` is `Danger`, which already implies it. |
+| disabled | `boolean` | `false` | Locks the group: every option reports `aria-disabled` and stops responding, and the hidden submit input is disabled so nothing is sent. The fieldset itself is never natively disabled, so assistive tech can still read the options. |
+| role | `string` | `"radiogroup"` | Role placed on the fieldset, `radiogroup` unless overridden. Change it only for exceptional composition patterns, since arrow-key navigation looks for that role. |
+| "aria-label" | `string` | `""` | Accessible name used when no visible group name is rendered. Ignored while `label` and `labelText` show one, which takes precedence. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that name the group. Merged with the id generated for the visible group name when `label` and `labelText` are set. |
+| "aria-describedby" | `string` | `""` | Space-separated ids of helper or instruction copy. Merged with the field message region id for non-error messages (Info, Warning, Success). |
+| "aria-errormessage" | `string` | `""` | Id of the element holding the error text. Defaults to the field message region id when `fieldMessageType` is `Danger`, and is only announced while the group is also marked invalid. |
+| "aria-invalid" | `boolean` | `false` | Explicit `aria-invalid` on the radiogroup, overriding whatever the component would infer. Omit it to let `invalid` or a `Danger` field message drive the state. |
+| "aria-required" | `boolean` | `false` | Explicit `aria-required` on the radiogroup, overriding what `required` would set. Use it when the requirement is conditional and `required` cannot express it. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<RadioGroup
+  name="plan"
+  label
+  labelText="Plan"
+  defaultValue="a"
+  onChange={(next) => setPlan(next)}
+>
+  <Radio value="a"><Text type="Body Medium">Plan A</Text></Radio>
+  <Radio value="b"><Text type="Body Medium">Plan B</Text></Radio>
+</RadioGroup>
+```
+