@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/AccordionGroup.md

@@ -0,0 +1,39 @@
+# AccordionGroup
+
+Import: `import { AccordionGroup } from "@uxelle/components";`
+
+Vertical stack of `Accordion` sections spaced by theme gap.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | `Accordion` sections stacked in a vertical column with theme gap between them. Each child keeps its own expanded state — the group does not enforce one-open-at-a-time. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<AccordionGroup>
+  <Accordion>
+    <Text type="Body Medium Alt">Section 1</Text>
+    <Accordion.Panel>
+      <Text type="Body Small">Content...</Text>
+    </Accordion.Panel>
+  </Accordion>
+  <Accordion>
+    <Text type="Body Medium Alt">Section 2</Text>
+  </Accordion>
+</AccordionGroup>
+```
+
+
+## Notes
+
+- **Slot**: Accepts Accordion children
+- **Layout**: Vertical stack with gap between elevated accordion cards

package/skills/uxelle-components/Banner.md

@@ -0,0 +1,73 @@
+# Banner
+
+Import: `import { Banner } from "@uxelle/components";`
+
+In-page messaging for contextual updates—section notices, task feedback, and supplemental copy with optional actions.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| alert | `boolean` | `false` | Marks the message as urgent for assistive technology: the root becomes role="alert" with aria-live="assertive" so it is announced as soon as it appears, unless you override `role` or `aria-live`. Nothing changes visually. |
+| open | `boolean` | `true` | Whether the banner is present. Setting it false plays the leave animation and then removes the banner from layout, so keep the component mounted and toggle this instead of conditionally rendering it. |
+| inline | `boolean` | `true` | Layout of copy and actions: true puts them on one row inside a max-width content region, false stacks actions under the copy and anchors trailing content to the top-right. |
+| dismissible | `boolean` | `true` | Adds the close control and an elevated surface, suited to a banner floating under navigation; false renders a flat banner in document flow. Dismiss only calls `onDismiss`, so set `open` to false there to animate the banner away. |
+| trailingSlot | `boolean` | `false` | Renders the trailing region holding `trailing` — after the actions when `inline` is true, at the top-right otherwise. Ignored while `dismissible` is true, because the close control owns the trailing edge. |
+| trailing | `ReactNode` | `—` | Content for the trailing region, such as a **Link** or a timestamp. Rendered only when `trailingSlot` is true and `dismissible` is false. |
+| children | `ReactNode` | `—` | Message copy for the banner. A string is wrapped in `Text` with `type=\"Body Medium Alt\"`; pass composed `Text` nodes for a title plus supporting copy. Omitting it renders an empty copy region — there is no placeholder. |
+| onDismiss | `() => void` | `—` | Fires when the close control is activated. The banner never hides itself, so set `open` to false here to start the leave animation. |
+| onExitComplete | `() => void` | `—` | Fires once the leave animation has finished and the banner is out of the layout. Use it to move keyboard focus somewhere sensible after a dismissal. |
+| dismissLabel | `string` | `"Dismiss"` | Accessible name for the close `IconButton`, which has no visible text. Localize it for non-English UIs. |
+| dataColorSwitcher | `string` | `"info"` | Status palette for the banner surface, text, and icon colors — for example `info`, `success`, `warning`, or `danger`. Sets `data-color-switcher` on the root. |
+| "data-color-switcher" | `string` | `—` | Attribute spelling of `dataColorSwitcher`, for call sites that spread DOM props. Wins over `dataColorSwitcher` when both are set. |
+| leadingSlot | `boolean` | `true` | Reserves the leading region and renders `leadingSlotContent`, which becomes required. Set false to drop the region entirely. |
+| leadingSlotContent | `ReactNode` | `null` | Content for the leading region, typically a decorative `Icon` marked `aria-hidden`. Required when `leadingSlot` is true and ignored when it is false. |
+| actionsSlot | `boolean` | `true` | Renders the actions region holding `actionsSlotContent`, which becomes required. Set false when the banner is copy-only. |
+| actionsSlotContent | `ReactNode` | `null` | Content for the actions region, typically a `ButtonGroup` of `Button` children. Required when `actionsSlot` is true and ignored when it is false. |
+| "aria-label" | `string` | `""` | Names the banner's region, which turns it into a landmark; leave it unset for ordinary in-page notices so the copy is not announced twice. Ignored when `aria-labelledby` is set. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that name the region and turn it into a landmark. Takes precedence over `aria-label`. |
+| "aria-live" | `"polite" \| "assertive" \| "off"` | `""` | How the banner is announced while it is present. Leave it unset for static copy and use `polite` when a non-alert banner appears in response to something the user did; setting `alert` already implies `assertive`. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+const [open, setOpen] = useState(true);
+
+return (
+  <Banner
+    open={open}
+    leadingSlotContent={
+      <Icon iconName="info" size={24} variant="sharpUnfilled" aria-hidden />
+    }
+    actionsSlotContent={
+      <ButtonGroup direction="row">
+        <Button emphasis="high" size="medium">
+          <Text type="Button" width>Continue</Text>
+        </Button>
+      </ButtonGroup>
+    }
+    onDismiss={() => setOpen(false)}
+    dismissLabel="Dismiss notice"
+  >
+    <Text type="Body Medium Alt" width>Schedule updated.</Text>
+  </Banner>
+);
+```
+
+
+## Notes
+
+- Usually sits within the content area when `dismissible` is false (flat, in-flow). When `dismissible` is true, elevation supports placement under navigation floating above content without pushing layout down. Prefer `BannerAnnouncement` when a system-wide bar should displace the page by its height in document flow.
+- **Presence**: Controlled with `open`. Leave animates then unmounts from layout (respects `prefers-reduced-motion`). Keep mounted and toggle `open` for exit motion.
+- **Copy**: Pass `children` (string or composed `Text`). Empty children render an empty copy region — there is no built-in placeholder copy.
+- **Leading**: Pass `leadingSlotContent` when `leadingSlot` is true (typically an `Icon`).
+- **Actions**: Pass `actionsSlotContent` when `actionsSlot` is true (typically `ButtonGroup` with `Button` children). Set `actionsSlot={false}` to hide the region.
+- **Layout**: Use `inline` for a single-row max-width layout; turn it off to stack copy above actions with trailing content top-right.
+- **Trailing**: `trailingSlot` is ignored when `dismissible` is true; dismiss owns the trailing edge. Pass `trailing` only when `trailingSlot` is true and not dismissible.
+- **Dismissible**: When true, shows the close control and elevated surface. Set `open={false}` in `onDismiss`; use `onExitComplete` to restore focus after leave.
+- **Alert**: Accessibility only. When `alert` is true, uses `role="alert"` and `aria-live="assertive"`. Otherwise the banner is a `region` with no `aria-live`, so static in-page copy is not announced as a live region. Pass `aria-live="polite"` when a non-alert banner is shown dynamically. Override `role` / `aria-live` as needed.
+- **Accessibility**: The `region` is unnamed by default, so an in-page banner is not exposed as a landmark and its copy is announced once (never auto-named from copy). Pass `aria-label` / `aria-labelledby` only when the banner should be a named landmark. Alerts announce their message when they appear and are likewise never named from copy. Localize `dismissLabel` for non-English UIs.

package/skills/uxelle-components/BannerAnnouncement.md

@@ -0,0 +1,63 @@
+# BannerAnnouncement
+
+Import: `import { BannerAnnouncement } from "@uxelle/components";`
+
+Compact system announcement bar for product-wide messaging above navigation.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| alert | `boolean` | `false` | Marks the announcement as urgent for assistive technology: the root becomes role="alert" with aria-live="assertive" so it is announced as soon as it appears, unless you override `role` or `aria-live`. Nothing changes visually. |
+| open | `boolean` | `true` | Whether the bar is present. Setting it false animates height and opacity closed and then removes the bar from layout, reflowing the page, so keep the component mounted and toggle this instead of conditionally rendering it. |
+| dismissible | `boolean` | `true` | Shows the close control at the far edge of the bar. It only calls `onDismiss`, so set `open` to false there to animate the bar away; a missing `onDismiss` warns in development. |
+| trailingSlot | `boolean` | `true` | Renders the trailing region after the message inside the centered content row. Independent of `dismissible`, whose close control is positioned separately at the far edge. |
+| trailing | `ReactNode` | `null` | Content for the trailing region, typically a `Link` that continues the announcement. Rendered only when `trailingSlot` is true. |
+| children | `ReactNode` | `—` | Announcement message; a string is wrapped in `Text` with `type=\"Body Medium Alt\"`. The rendered message also names the landmark region unless you pass `aria-label` or `aria-labelledby`, and leaving it empty warns in development. |
+| onDismiss | `() => void` | `—` | Fires when the close control is activated. The bar never hides itself, so set `open` to false here to start the leave animation. |
+| onExitComplete | `() => void` | `—` | Fires once the leave animation has finished and the bar is out of the layout. Use it to move keyboard focus somewhere sensible, such as the main landmark. |
+| dismissLabel | `string` | `"Dismiss"` | Accessible name for the close `IconButton`, which has no visible text. Localize it for non-English UIs. |
+| dataColorSwitcher | `string` | `"success"` | Status palette for the bar surface, text, and icon colors — for example `success`, `info`, `warning`, or `danger`. Sets `data-color-switcher` on the root. |
+| "data-color-switcher" | `string` | `—` | Attribute spelling of `dataColorSwitcher`, for call sites that spread DOM props. Wins over `dataColorSwitcher` when both are set. |
+| leadingSlot | `boolean` | `true` | Reserves the leading region and renders `leadingSlotContent`, which becomes required. Set false to drop the region entirely. |
+| leadingSlotContent | `ReactNode` | `null` | Content for the leading region, typically a decorative `Icon` marked `aria-hidden`. Required when `leadingSlot` is true and ignored when it is false. |
+| "aria-label" | `string` | `""` | Names the bar's landmark region, overriding the name generated from the message copy. Usually unnecessary, and ignored when `aria-labelledby` is set. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that name the landmark region. Takes precedence over both `aria-label` and the name generated from the message copy. |
+| "aria-live" | `"polite" \| "assertive" \| "off"` | `"off"` | How the bar is announced while it is present. It stays `off` for a bar rendered with the page; use `polite`, or set `alert` for `assertive`, when the bar mounts later in response to an event. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+const [open, setOpen] = useState(true);
+const mainRef = useRef<HTMLElement>(null);
+
+return (
+  <BannerAnnouncement
+    open={open}
+    leadingSlotContent={<Icon iconName="campaign" size={24} variant="sharpUnfilled" aria-hidden />}
+    trailing={<Link href="/whats-new">Take a look</Link>}
+    onDismiss={() => setOpen(false)}
+    onExitComplete={() => mainRef.current?.focus()}
+    dismissLabel="Dismiss announcement"
+    aria-live="polite"
+  >
+    Something new is here.
+  </BannerAnnouncement>
+);
+```
+
+
+## Notes
+
+- Sits above navigation and pushes page content down by its height. Prefer `Banner` for in-page contextual notices that should not displace the whole layout.
+- **Placement**: Above navigation; not a page heading — do not substitute for `h1`.
+- **Presence**: Controlled with `open`. Leave animates height/opacity then unmounts from layout (respects `prefers-reduced-motion`). Keep the component in the tree and toggle `open` — conditional render skips exit motion.
+- **Leading**: Pass `leadingSlotContent` when `leadingSlot` is true (typically an `Icon`).
+- **Copy**: Pass a string, `Text`, or composed message as `children`. Message copy names the landmark automatically unless you pass `aria-label` or `aria-labelledby`.
+- **Trailing**: Pass `trailing` when `trailingSlot` is true (typically a `Link`).
+- **Dismiss**: Calls `onDismiss` only — set `open={false}` there. Use `onExitComplete` to restore focus after leave.
+- **Accessibility**: Defaults to `role="region"` named from the message. Defaults to `aria-live="off"`; set `alert` (or `aria-live`) when mounting dynamically after load.

package/skills/uxelle-components/Breadcrumb.md

@@ -0,0 +1,38 @@
+# Breadcrumb
+
+Import: `import { Breadcrumb } from "@uxelle/components";`
+
+Single breadcrumb item. Compose multiple instances inside `Breadcrumbs` for a full trail. Can also render standalone as a list item when building custom layouts.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` | `"Page"` | Crumb text for link and current-page crumbs. Required unless `collapse` is true — a blank label skips the item and logs a development warning. |
+| href | `string` | `""` | Destination URL for an ancestor crumb, rendered through `Link`. Omit it and the crumb falls back to current-page text. Ignored when `currentPage` or `collapse` is true. |
+| currentPage | `boolean` | `false` | Renders the crumb as non-interactive bold text instead of a link. Inside `Breadcrumbs` this is set automatically on the last child. |
+| collapse | `boolean` | `false` | Replaces the crumb with the overflow menu control that lists `collapseItems`. `Breadcrumbs` inserts this crumb itself when a trail collapses, so set it only when hand-building a trail. |
+| collapseItems | `BreadcrumbCollapseItem[]` | `—` | Ancestor crumbs listed in the overflow menu when `collapse` is true, each `{ label, href? }`. Entries without `href` render as non-interactive rows. |
+| expandLabel | `string` | `"Show hidden breadcrumbs"` | Accessible name for the icon-only overflow menu trigger, which has no visible text. Localize for your locale; you may include the hidden crumb count. |
+| chevron | `boolean` | `true` | Renders the leading chevron separator before this crumb. `Breadcrumbs` manages it — `false` on the first visible crumb, `true` on the rest. |
+
+<!-- prettier-ignore-end -->
+
+Extends `React.LiHTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Breadcrumb>
+  {/* Content */}
+</Breadcrumb>
+```
+
+## Notes
+
+- Compose inside `Breadcrumbs` for a full trail with the correct `nav` landmark. Ancestors use `Link`; the current page is plain text.
+- With `href` (and not `currentPage` / `collapse`): interactive link.
+- With `currentPage`: non-interactive bold text.
+- With `collapse`: overflow menu for hidden ancestor crumbs.

package/skills/uxelle-components/Breadcrumbs.md

@@ -0,0 +1,32 @@
+# Breadcrumbs
+
+Import: `import { Breadcrumbs } from "@uxelle/components";`
+
+Compose `Breadcrumb` children for the route.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children (required) | `ReactNode` | `—` | `Breadcrumb` children in route order, root first, rendered into an `<ol>`. The last one is always shown as the current page. Other element types are dropped with a development warning. |
+| overflow | `boolean` | `true` | Collapses middle crumbs into an overflow menu once the trail is longer than the root plus its tail (the last crumb for trails of three or fewer, the last two above that). Set `false` to keep every crumb visible. |
+| expandLabel | `string` | `"Show hidden breadcrumbs"` | Accessible name for the icon-only overflow menu trigger, which has no visible text. Localize for your locale; you may include the hidden crumb count. |
+| "aria-label" | `string` | `"Breadcrumb"` | Accessible name for the `<nav>` landmark wrapping the trail. Localize for your locale (e.g. `Fil d'Ariane`). |
+
+<!-- prettier-ignore-end -->
+
+Extends `React.HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Breadcrumbs>
+  {/* React.ReactNode */}
+</Breadcrumbs>
+```
+
+## Notes
+
+- Pass `href` for ancestors; the last child is always treated as the current page. Ancestor links use the shared `Link` component. When `overflow` is enabled, the bar shows **Home**, the overflow trigger, the **parent level**, and **Current Page**; ancestors between them are listed in `collapseItems`. Middle segments collapse into an overflow menu after the root crumb.

package/skills/uxelle-components/Bubble.md

@@ -0,0 +1,34 @@
+# Bubble
+
+Import: `import { Bubble } from "@uxelle/components";`
+
+Non-interactive circular marker. Nest Text as children, or set `icon` with `iconName` for a glyph.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `boolean` | `false` | Switches the bubble to a single glyph from `iconName` and ignores `children`. When false, `children` are rendered instead and development builds warn if there are none. |
+| iconName | `string` | `"add"` | Material Symbol glyph shown while `icon` is true. It is `aria-hidden`, so convey the meaning through `aria-label` or nearby copy. |
+| iconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the glyph while `icon` is true: `sharpFilled` solid, `sharpUnfilled` outlined. |
+| children | `ReactNode` | `—` | Content shown while `icon` is false — typically one or two initials in `Text` (`<Text type=\"Body Small Alt\" width inline>Aa</Text>`). Nothing renders when this is empty. |
+| "aria-label" | `string` | `""` | Accessible name for the bubble, needed when it is the only indicator of a category and its initials or glyph do not convey that on their own. |
+| "aria-hidden" | `"true" \| "false"` | `""` | Hides the bubble from assistive technology. Set it when the marker is purely decorative or repeats copy that sits next to it. |
+
+<!-- prettier-ignore-end -->
+
+Extends `React.HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Bubble>
+  {/* Content */}
+</Bubble>
+```
+
+## Notes
+
+- Use for decoration or category—initials, type glyphs, or a single icon. Not a button, link, or actionable control. Do not use as a button or link. When decorative, set `aria-hidden={true}`; when the sole category indicator, expose meaning on a parent or via `aria-label`.

package/skills/uxelle-components/Button.md

@@ -0,0 +1,54 @@
+# Button
+
+Import: `import { Button } from "@uxelle/components";`
+
+Standard action control for forms, dialogs, and toolbars. Label with `children`; Use `IconButton` for icon-only actions.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| emphasis | `"high" \| "medium" \| "low"` | `"high"` | Visual weight: `high` is a filled surface for the one primary action in a view, `medium` an outlined surface for secondary actions, `low` text-only for tertiary or inline actions. |
+| size | `"extraSmall" \| "small" \| "medium" \| "large"` | `"medium"` | Padding and gap scale — the label `Text` type and icon size stay fixed. Use `extraSmall` for dense toolbars (it matches the `IconButton` box height) and `large` for prominent page-level actions. |
+| leadingIcon | `boolean` | `false` | Renders `leadingIconName` before the label. The icon is `aria-hidden`, so its meaning must also live in `children` or `aria-label`. |
+| trailingIcon | `boolean` | `false` | Renders `trailingIconName` after the label. The icon is `aria-hidden`, so its meaning must also live in `children` or `aria-label`. |
+| leadingIconName | `string` | `"chevron_forward"` | Material Symbol glyph used by `leadingIcon`; ignored while `leadingIcon` is false. |
+| trailingIconName | `string` | `"chevron_forward"` | Material Symbol glyph used by `trailingIcon`; ignored while `trailingIcon` is false. |
+| leadingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the leading icon: `sharpFilled` solid, `sharpUnfilled` outlined. |
+| trailingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the trailing icon: `sharpFilled` solid, `sharpUnfilled` outlined. |
+| fullWidth | `boolean` | `false` | Stretches the button to 100% of its parent width instead of sizing to its label. Use it for card and form actions that should fill their column. |
+| loading | `boolean` | `false` | Shows a centered spinner while the label and icons stay in layout at opacity 0 so the width does not jump. Blocks activation including form submit, sets `aria-busy` / `aria-disabled`, and keeps enabled visuals even when `disabled` is also true. Set `aria-label` to change what is announced while loading. |
+| "aria-label" | `string` | `""` | Accessible name that overrides the visible label; set it when `children` is empty or too terse to describe the action. For icon-only actions reach for `IconButton` with its own `aria-label` instead. |
+| children | `ReactNode` | `—` | Visible label, always rendered with `Text` `type=\"Button\"`. Provide meaningful label text; when it is empty or too terse, set `aria-label` or `aria-labelledby`. |
+| disabled | `boolean` | `false` | Blocks activation and applies disabled styling through the native `disabled` attribute. For work in progress use `loading` instead — it keeps enabled visuals and overrides this prop. |
+
+<!-- prettier-ignore-end -->
+
+Extends `ButtonHTMLAttributes` — supports `disabled`, `onClick`, `className`, etc.
+
+## Usage
+
+```tsx
+<Button emphasis="high" size="medium">
+  Click me
+</Button>
+<Button emphasis="medium" trailingIcon trailingIconName="chevron_right" trailingIconVariant="sharpUnfilled">
+  Button
+</Button>
+<Button emphasis="low">Text button</Button>
+<Button leadingIcon trailingIcon>With both icons</Button>
+<Button fullWidth emphasis="medium">Full width</Button>
+<Button loading>Saving</Button>
+```
+
+
+## Notes
+
+- The visible label is always rendered with `Text` `type="Button"` (from `children`).
+- **Accessible name**: Provide meaningful label text via `children`. When visible text is not descriptive enough, set `aria-label` or `aria-labelledby`. For icon-only actions, use `IconButton` with `aria-label` instead of `Button` without children.
+- **Loading**: Set `loading` while an action is in progress. Label/icons remain in the layout at opacity 0 so width is stable; a centered spinner is shown. The control sets `aria-busy` / `aria-disabled`, keeps enabled visuals (including when `disabled` is also true), and blocks activation (click, keyboard, and form submit) until loading ends. Prefer `loading` alone for pending work — do not rely on `disabled` for that state. The accessible name stays the label (or `aria-label`); set `aria-label` to customize what assistive tech announces while loading.
+- **Full width**: Set `fullWidth` when the button should span its parent (e.g. card actions).
+- **Focus**: Native outline on `:focus-visible` (keyboard only)
+- **Keyboard**: Native `<button>` supports Enter and Space

package/skills/uxelle-components/ButtonGroup.md

@@ -0,0 +1,43 @@
+# ButtonGroup
+
+Import: `import { ButtonGroup } from "@uxelle/components";`
+
+Groups related Button components with consistent spacing. Set `aria-label` when the group needs an accessible name.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | One `Button` per action, listed in the tab order you want. Any other node is dropped from the output (with a development warning), so wrap other controls in `Button` first. |
+| direction | `"row" \| "row-reverse" \| "column" \| "column-reverse"` | `"row"` | Main-axis flow of the buttons. `row` and `column` follow DOM order, while `row-reverse` and `column-reverse` flip the visual order only — focus still moves through the children in the order you pass them. |
+| fullWidth | `boolean` | `false` | Stretches the group to the full width of its container and gives every button an equal share of the main axis. Left unset, the group hugs its content and each button keeps its intrinsic size. |
+| "aria-label" | `string` | `""` | Accessible name announced for the whole group, for example `Form actions`. Set this or `aria-labelledby` — otherwise the component logs a development warning, since the group role alone announces nothing. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<ButtonGroup aria-label="Form actions">
+  <Button emphasis="medium">Cancel</Button>
+  <Button emphasis="high">Save</Button>
+</ButtonGroup>
+```
+
+
+## Notes
+
+- **What this is**
+- A **layout group** for multiple independent actions (e.g. Cancel + Save).
+- Compose only `Button` children; each button keeps its own action and focus ring.
+- **What this is not**
+- Not a **segmented control** or **toggle group** (no single selection, no `aria-pressed` roving pattern).
+- For mutually exclusive options, use **SegmentedControl** or a radio group.
+- Control how many buttons appear by **which `Button` children you pass** (two or three, etc.).
+- **Accessibility**
+- Uses `role="group"` by default. When buttons are related actions, set `aria-label` or `aria-labelledby`.
+- Tab order follows **DOM order** of `Button` children. Order children for the intended keyboard sequence (e.g. secondary before primary left-to-right) even when `direction` is `row-reverse` (visual-only reversal).

package/skills/uxelle-components/Card.md

@@ -0,0 +1,35 @@
+# Card
+
+Import: `import { Card } from "@uxelle/components";`
+
+Elevated surface container for arbitrary content.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| cardContentSlot | `ReactNode` | `null` | Everything rendered inside the card surface — any layout, media, or controls. This is the only content prop: `Card` takes no `children`. Empty or whitespace-only content renders no inner wrapper, so the card stays blank. |
+| padding | `"Default" \| "None"` | `"Default"` | Inner spacing around the content region. `Default` applies theme spacing; `None` removes it so media can bleed to the edges. The card keeps its stroke and elevation either way. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Card
+  cardContentSlot={
+    <Text type="Body Medium">Any content fits here.</Text>
+  }
+/>
+```
+
+```tsx
+<Card padding="None" cardContentSlot={<Image src="/hero.jpg" alt="" aspectRatio="16:9" />} />
+```
+
+
+## Notes
+
+- Use for generic grouped content that needs a bordered, elevated surface. Pass composed children through `cardContentSlot`. Empty content is not rendered. Set `padding="None"` when media or layout should bleed to the edges. Remaining HTML attributes—including `aria-*`, `id`, and `className`— are forwarded to the root element. Prefer `ProductCard` when the layout needs fixed top, center, and bottom regions.

package/skills/uxelle-components/Checkbox.md

@@ -0,0 +1,57 @@
+# Checkbox
+
+Import: `import { Checkbox } from "@uxelle/components";`
+
+Native checkbox built as `<label>` + `<input type="checkbox">`.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| checked | `boolean` | `false` | Checked state — controlled when paired with `onChange`, otherwise only the initial value. Ignored inside CheckboxGroup, where the group's `value` decides which options are checked. |
+| value | `string` | `""` | Value submitted with the form, and the identity this option is matched against in CheckboxGroup `value`. An empty string is valid; inside a group without one, a generated fallback is used that will never match your data. |
+| indeterminate | `boolean` | `false` | Tri-state dash for partial selection, mapped to the native `indeterminate` property so assistive tech reports `mixed`. Independent of `checked` — a select-all uses `checked={allSelected}` with `indeterminate={someSelected && !allSelected}`. |
+| disabled | `boolean` | `false` | Blocks interaction, applies disabled styling, and removes the control from the tab order. The native `disabled` attribute is set, so the value is not submitted. |
+| embedded | `boolean` | `false` | Indicator-only mode for a checkbox 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. |
+| onChange | `ChangeEventHandler<HTMLInputElement>` | `—` | Native change handler receiving the input event; read `event.target.checked` for the next state. Supplying it is what makes `checked` controlled, and inside **CheckboxGroup** it runs after the group's own handler. |
+| label | `boolean` | `true` | Renders `children` beside the box and points `aria-labelledby` at that text. With `false` there is no visible name, so set `aria-label` or `aria-labelledby` on `inputProps` or the option is left unnamed. |
+| children | `ReactNode` | `—` | Label content beside the box, 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 | `CheckboxInputProps` | `—` | Attributes spread onto the `<input>` before the component's own; put form semantics here (`required`, `name`, `value`, `form`, `autoComplete`, ARIA). `type`, `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 CheckboxGroup 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
+<Checkbox>
+  {/* Content */}
+</Checkbox>
+```
+
+## Notes
+
+- **Accessibility (WCAG 2.x AA baseline)**
+- **Keyboard** — Native `<input type="checkbox">` (implicit **`role="checkbox"`**; **`checked`** exposes state—do not set **`aria-checked`**). **Enter** / **Space** toggle 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** — Sets HTML **`disabled`** and **`aria-disabled`**; the control is removed from the tab order.
+- **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 and indeterminate state are exposed via the native control (not only icon color). The icon is **decorative / redundant** with that state and is marked **`aria-hidden`**. Do not set **`aria-checked`** manually—the browser maps **`indeterminate`** to **`mixed`**. 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.
+- **Indeterminate** — Pass **`indeterminate`** for tri-state visuals (e.g. “select all” with partial selection). Uses the native **`HTMLInputElement.indeterminate`** property. On user activation, the browser clears indeterminate before **`onChange`**; when **`indeterminate`** is controlled, set it to **`false`** in **`onChange`** (or derive it from selection state).
+- **Form / validation** — Pass **`required`**, **`aria-invalid`**, **`aria-describedby`**, **`aria-errormessage`**, and **`autoComplete`** on **`inputProps`**.
+- **`labelProps` vs `inputProps`**
+- Spread **`labelProps`** on the root `<label>`. Spread **`inputProps`** on the `<input>` **first**, then the component applies authoritative props (`type`, `checked`, `disabled`, `onChange`, `id`), so those always win.
+- Put **form and control** semantics on **`inputProps`**, not on **`labelProps`**: `aria-describedby`, `autoComplete`, `form`, `name`, `value`. When **not** **`embedded`**, you may pass **`tabIndex`** on **`inputProps`**; disabled options always use **`tabIndex={-1}`**.
+- **Controlled vs uncontrolled**
+- **Controlled**: use **`checked`** with **`onChange`**. Pass **`indeterminate`** when tri-state is driven by the parent; clear or recompute it in **`onChange`** after the user toggles the control.
+- **Uncontrolled**: omit **`onChange`**; internal state is seeded from **`checked`** when it is defined, otherwise the option starts unchecked and toggles on interaction. Initial **`indeterminate`** is cleared automatically on user interaction when **`indeterminate`** is not controlled.
+- **Inside CheckboxGroup** — Group **`value`** / **`defaultValue`** own checked state; option **`checked`** is ignored. Set **`value`** on each option for a stable native value (group **`optionValues`** is a deprecated fallback).
+- **Embedded mode**
+- The checkbox 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.

package/skills/uxelle-components/CheckboxGroup.md

@@ -0,0 +1,47 @@
+# CheckboxGroup
+
+Import: `import { CheckboxGroup } from "@uxelle/components";`
+
+Fieldset-backed checkbox group; semantics and a11y rules are documented on **CheckboxGroupProps**.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | The `Checkbox` options for this group, in DOM order. The group owns checked state 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` | `—` | Shared form field `name` applied to every nested **Checkbox**, so each checked option is submitted as a separate entry under that one name. |
+| value | `readonly string[]` | `—` | `value` of every checked option, which makes the group controlled. Pair with `onChange`; omit it to let the group track its own selection from `defaultValue`. |
+| defaultValue | `readonly string[]` | `[] as readonly string[]` | Values checked on first render when uncontrolled. Read only on mount — later changes are ignored, so remount with a `key` or switch to controlled `value` to reset. |
+| onChange | `(value: string[]) => void` | `—` | Receives the full next array of checked values whenever any option toggles, not just the one that changed. Required for controlled use alongside `value`. |
+| label | `boolean` | `false` | Renders the `<legend>` that names the fieldset for assistive technology. Needs non-empty `labelText`; with `false`, name the group with `aria-label` or `aria-labelledby` instead or it is left unnamed. |
+| labelText | `string` | `""` | Text inside the `<legend>`. Blank or whitespace-only text hides it 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 fieldset automatically. |
+| fieldMessageType | `"Info" \| "Danger" \| "Warning" \| "Success"` | `CHECKBOX_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 fieldset so at least one selection is announced as mandatory. Nothing is enforced natively — validate the selected values 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. |
+| "aria-label" | `string` | `""` | Accessible name used when no `<legend>` is rendered. Ignored while `label` and `labelText` show one, since the native legend names the fieldset. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that name the group when no `<legend>` is rendered. Dropped entirely while a legend is shown, to avoid a double announcement. |
+| "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 fieldset, 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 fieldset, overriding what `required` would set. Use it when the requirement is conditional and `required` cannot express it. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<CheckboxGroup
+  name="notifications"
+  label
+  labelText="Notification preferences"
+  defaultValue={["email"]}
+  onChange={(next) => setSelected(next)}
+>
+  <Checkbox value="email"><Text type="Body Medium" width>Email updates</Text></Checkbox>
+  <Checkbox value="product"><Text type="Body Medium" width>Product announcements</Text></Checkbox>
+</CheckboxGroup>
+```
+

package/skills/uxelle-components/ChoiceChip.md

@@ -0,0 +1,44 @@
+# ChoiceChip
+
+Import: `import { ChoiceChip } from "@uxelle/components";`
+
+Toggle pill for choice sets (facets, sort, view options).
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label (required) | `string` | `"Choice Chip"` | Visible chip text, and the accessible name unless `aria-label` overrides it. Whitespace is trimmed, and an empty result renders no chip at all. |
+| disabled | `boolean` | `false` | Blocks toggling and applies disabled styling. Clicks fire no handlers, `onClick` included. |
+| checked | `boolean` | `false` | Selected state when controlled — sets `aria-pressed` and swaps the leading icon for a check. Pass with `onChange`; omit it to let the chip track its own state from `defaultChecked`. |
+| defaultChecked | `boolean` | `false` | Selected state on first render when `checked` is omitted. Read only on mount, so later changes to it are ignored. |
+| leadingIcon | `boolean` | `false` | Adds a decorative icon before the label while the chip is unchecked. A checked chip always shows a check instead, whatever this is set to. |
+| leadingIconName | `string` | `"add"` | Material Symbol drawn as the leading icon while unchecked. Ignored unless `leadingIcon` is `true`, and always replaced by `check` once the chip is checked. |
+| leadingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Glyph weight of the leading icon: `sharpFilled` is the solid form, `sharpUnfilled` the outlined one. The check on a checked chip is always filled. |
+| trailingIcon | `boolean` | `false` | Adds a decorative icon after the label, for affordances such as a dropdown caret. It is not a separate control — the whole chip is one button. |
+| trailingIconName | `string` | `"add"` | Material Symbol drawn after the label. Ignored unless `trailingIcon` is `true`. |
+| trailingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpFilled"` | Glyph weight of the trailing icon: `sharpFilled` is the solid form, `sharpUnfilled` the outlined one. |
+| onChange | `(checked: boolean) => void` | `—` | Fires on click with the next selected value (the inverse of the current one). Use this rather than `onClick` to drive `checked` and app selection state. |
+| onClick | `MouseEventHandler<HTMLButtonElement>` | `—` | Native click handler, called after `onChange` with the raw mouse event. Reach for it only for side effects such as analytics; use `onChange` for selection. |
+| "aria-label" | `string` | `""` | Overrides `label` as the accessible name, for cases where the visible text is abbreviated. Leave it unset when `label` already reads well on its own. |
+| "aria-labelledby" | `string` | `""` | IDs of elements that name the chip instead of `label`, space-separated. Use it when the name already exists elsewhere on the page. |
+| "aria-describedby" | `string` | `""` | IDs of elements holding supplementary description read after the name, space-separated. For hints, not for the chip's own name. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<ChoiceChip label="Relevance" onChange={() => {}} />
+```
+
+```tsx
+<ChoiceChip label="Newest" checked trailingIcon onChange={() => {}} />
+```
+
+
+## Notes
+
+- Uses `checked` / `defaultChecked` with `aria-pressed`. Checked chips show a leading check. Selection policy (single vs multi) is owned by the app — this control only toggles itself. Compose in **ChoiceChipGroup**. For exclusive single-select, keep one checked value in app state and set `role="radiogroup"` on the group. Use **FilterChip** for dismissible applied filters. There is no InputChip — compose entry (e.g. Textfield) with FilterChips for removable values. Controlled: set `checked` from `onChange` (next pressed value). Uncontrolled: `defaultChecked` is mount-only.