@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/Link.md

@@ -0,0 +1,52 @@
+# Link
+
+Import: `import { Link } from "@uxelle/components";`
+
+Standalone hyperlink for use outside navigation contexts.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| href (required) | `string` | `—` | Destination for the underlying `a` — absolute URL, root-relative path, `mailto:`, or `#fragment`. Triggers a full page navigation; for client-side routing, render your router's link with `className="uxl-link"` instead. |
+| icon | `ReactNode` | `—` | Node rendered after the link text, typically an **Icon** such as `outbound` for external destinations. Its wrapper is `aria-hidden`, so keep the meaning in the link text rather than the icon. |
+| children | `ReactNode` | `—` | Link text. A string or number is wrapped in `Text` `type="Link"`; pass a `Text` node or other custom content when needed. |
+
+<!-- prettier-ignore-end -->
+
+Extends `React.AnchorHTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+// Link component with optional icon
+<Link
+  href="#"
+  icon={<Icon iconName="outbound" variant="sharpUnfilled" aria-hidden />}
+>
+  Documentation
+</Link>
+```
+
+```tsx
+// Bare anchor + Link text style
+<a href="/docs" className="uxl-link">
+  <Text type="Link" inline>Documentation</Text>
+</a>
+```
+
+```tsx
+// Inline link inside body copy (styled via Text.css)
+<Text type="Body Medium">
+  <>Email: <a href="mailto:hello@example.com">hello@example.com</a></>
+</Text>
+```
+
+
+## Notes
+
+- String children render with `Text` `type="Link"`. Pass custom nodes when needed.
+- **Accessibility**: Uses semantic <a> with proper href. Add rel="noopener noreferrer" for external links.
+- **States**: Underline at rest; thicker underline on hover per design tokens.

package/skills/uxelle-components/List.md

@@ -0,0 +1,35 @@
+# List
+
+Import: `import { List } from "@uxelle/components";`
+
+Vertical stack of `ListItem` children, rendered as a semantic `ul` or `ol`.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | `ListItem` elements, each rendering its own `li` row. Any other node is rendered as-is, so wrap raw content in an `li` to keep the list valid. |
+| ordered | `boolean` | `false` | Renders an `ol` instead of a `ul`, so the sequence is announced as ordered. Semantics only — markers stay hidden, so put any visible numbering in the `ListItem` content. |
+| role | `AriaRole` | `—` | Overrides the ARIA role of the list element. Inside a **Menu** the list already falls back to `presentation` so the menu's own semantics apply; set this only to force a different role. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<List>
+  <ListItem centerText="Item" />
+  <ListItem interactive centerText="Clickable item" />
+</List>
+```
+
+
+## Notes
+
+- **Slot**: Accepts ListItem children (renders as li)
+- **Layout**: Vertical stack
+- **Semantic**: Uses ul/ol for list structure

package/skills/uxelle-components/ListControls.md

@@ -0,0 +1,100 @@
+# ListControls
+
+Import: `import { ListControls } from "@uxelle/components";`
+
+Settings or choice list: optional **Label**, **List** of interactive **ListItem** rows with an embedded Switch, Checkbox, or Radio in the trailing slot.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | Rows of the list — `ListItem` elements marked `interactive` with an `embedded` Switch, Checkbox, or Radio in their `trailing` slot. Activating a row toggles or selects that control. |
+| label | `boolean` | `false` | When true and `labelText` is non-empty, renders a `Label` above the list and names the group with it. When false, name the group with `aria-label` or `aria-labelledby` instead. |
+| labelText | `string` | `""` | Text shown in the visible `Label`. Rendered only when `label` is true and this is non-empty after trimming. |
+| dense | `boolean` | `false` | Applies compact vertical padding to every nested `ListItem`. An individual row can still override it by setting its own `dense`. |
+| controlType | `"switch" \| "checkbox" \| "radio"` | `"switch"` | Control rendered in each row and the selection model it uses: `switch` for independent toggles with no shared value, `checkbox` for multi-select where the value is a `string[]`, `radio` for exclusive single-select where the value is a `string`. The checkbox and radio modes also require `name`. |
+| name (required) | `string` | `—` | Form field name applied to every nested **Checkbox** so the rows submit as one multi-valued field. |
+| value | `readonly string[] \| string` | `—` | Selected option values for controlled use. Pass it with `onChange`; omit it to let the group track selection itself starting from `defaultValue`. |
+| defaultValue | `readonly string[] \| string` | `[] as readonly string[]` | Initial selection for uncontrolled use, read once on mount. Later changes are ignored, so remount with a `key` or switch to controlled `value` to reset the group. |
+| optionValues | `readonly string[]` | `—` | Native `value` for each embedded **Checkbox**, matched to children in **ListItem** order. Omit it to fall back to generated ids, which are not meaningful in submitted data or in `value` / `defaultValue`. |
+| onChange | `(value: string[]) => void \| (value: string, event: ChangeEvent<HTMLInputElement>) => void` | `—` | Called with the complete next selection, not just the row that changed. |
+| fieldMessage | `ReactNode` | `—` | Message rendered below the list. A string or number is wrapped in a **FieldMessage** styled by `fieldMessageType`; any other node renders as-is. |
+| fieldMessageType | `"Info" \| "Danger" \| "Warning" \| "Success"` | `LIST_CONTROLS_DEFAULTS.fieldMessageType` | Tone for a string or number `fieldMessage` below the list (checkbox and radio only). `Danger` also exposes the message as `aria-errormessage` and announces changes politely, while the other tones expose it through `aria-describedby`. |
+| required | `boolean` | `false` | Sets `aria-required` on the group so a selection is announced as mandatory (checkbox and radio only). It does not block form submission. |
+| invalid | `boolean` | `false` | Sets `aria-invalid="true"` on the group unless `aria-invalid` is passed explicitly. Pair it with a `Danger` field message so the reason is visible. |
+| disabled | `boolean` | `false` | Marks the group non-interactive with `aria-disabled` on the radiogroup and its options so they stay readable, and disables the hidden input so no value is submitted. Radio mode only. |
+| "aria-label" | `string` | `""` | Accessible name for the group when no visible label is rendered. Prefer `label` with `labelText` whenever the name belongs on screen. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that name the group. Appended after the visible `Label` id when `label` is on. |
+| "aria-describedby" | `string` | `""` | Space-separated ids of helper copy for the group. The field message region id is appended automatically for every tone except `Danger`. |
+| "aria-errormessage" | `string` | `""` | Id of the element holding the error text, which defaults to the field message region when `fieldMessageType` is `Danger`. Assistive technology only exposes it while the group is also invalid. |
+| "aria-invalid" | `boolean` | `false` | Explicit invalid state on the group, which takes precedence over `invalid`. Leave it unset to let `invalid` drive the state; a `Danger` field message on its own does not mark the group invalid. |
+| "aria-required" | `boolean` | `false` | Explicit `aria-required` on the group, which takes precedence over `required`. Leave it unset to let `required` drive the value. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<ListControls controlType="switch" label labelText="Notification Type">
+  <ListItem
+    interactive
+    trailingSlot
+    trailing={<Switch embedded defaultChecked aria-label="Direct Messages" />}
+    centerText="Direct Messages"
+    bottomText="Instant push notifications for new direct messages."
+  />
+</ListControls>
+```
+
+```tsx
+<ListControls
+  controlType="checkbox"
+  name="privacy"
+  label
+  labelText="Privacy Settings"
+  defaultValue={["public"]}
+  optionValues={["public", "activity"]}
+>
+  <ListItem
+    interactive
+    trailingSlot
+    trailing={<Checkbox embedded inputProps={{ "aria-label": "Public Profile" }} />}
+    centerText="Public Profile"
+    bottomText="Allow others to find and view your profile"
+  />
+</ListControls>
+```
+
+```tsx
+<ListControls
+  controlType="radio"
+  name="delivery"
+  label
+  labelText="Delivery Options"
+  defaultValue="standard"
+  optionValues={["standard", "express"]}
+>
+  <ListItem
+    interactive
+    trailingSlot
+    trailing={<Radio embedded inputProps={{ "aria-label": "Standard" }} />}
+    centerText="Standard"
+    bottomText="Get in a week"
+  />
+</ListControls>
+```
+
+
+## Notes
+
+- **`controlType`** selects the row control and selection model:
+- **`switch`** — independent immediate toggles (no shared value).
+- **`checkbox`** — multi-select (**`value`** as **`string[]`**), same model as **CheckboxGroup**.
+- **`radio`** — exclusive single-select, same model as **RadioGroup**.
+- Compose **ListItem** with **`interactive`** and an **`embedded`** control in **`trailing`**. Row activation toggles or selects that control. Use **`centerText`** / **`bottomText`** for the title and optional supporting copy. Set **`dense`** for compact row padding (rows inherit unless they set **`dense`** themselves).
+- **Accessibility (WCAG 2.x AA baseline)**
+- **Group** — Visible **Label** or **`aria-label`** / **`aria-labelledby`**. Radio uses **`role="radiogroup"`**; switch/checkbox use **`role="group"`**. **`aria-describedby`**, **`aria-required`**, **`aria-invalid`**, and **`aria-errormessage`** wire helper/error copy where applicable.
+- **Rows** — Each interactive **ListItem** owns focus and activates its embedded control. Prefer naming the option from the row title (**`aria-label`** / **`aria-labelledby`**).
+- **Keyboard** — **Tab** visits each row; **Space** / **Enter** activate; radio rows also use **Arrow** keys to move selection.

package/skills/uxelle-components/ListItem.md

@@ -0,0 +1,69 @@
+# ListItem
+
+Import: `import { ListItem } from "@uxelle/components";`
+
+Row for **List** with leading, center content, and trailing regions.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | Legacy fallback used as the center line when `centerText` is omitted. Prefer `topText` / `centerText` / `bottomText`, which apply the right `Text` type per line. |
+| leading | `ReactNode` | `—` | Node rendered in the leading region at the start of the row, typically an `Icon` or avatar. Needs `leadingSlot`; without it the region falls back to an `Icon` built from `leadingIconName` and `leadingIconVariant`. |
+| trailing | `ReactNode` | `—` | Node rendered in the trailing region at the end of the row — an `Icon`, a badge, or an embedded `Switch` / `Checkbox` / `Radio`. Needs `trailingSlot`; without it the region falls back to an `Icon` built from `trailingIconName` and `trailingIconVariant`. |
+| topContentSlot | `ReactNode` | `—` | Node rendered above the text stack inside the center region, typically a `LabelBadge` or chip. Needs `topSlot`; nothing renders unless both are set. |
+| leadingSlot | `boolean` | `false` | Renders the leading region at the start of the row. Ignored while `reserved` is on, which claims that space for the activation check icon instead. |
+| trailingSlot | `boolean` | `false` | Renders the trailing region at the end of the row, holding `trailing` or the default `trailingIconName` icon. |
+| topSlot | `boolean` | `false` | Renders `topContentSlot` above the text stack. Both this and `topContentSlot` are required for anything to appear. |
+| topText | `ReactNode` | `""` | Eyebrow line above `centerText`, for category or status copy. Strings are wrapped in a Text node with the Overline type; omit or pass an empty string to hide it. |
+| centerText | `ReactNode` | `"List Item"` | Primary line of the row. Strings are wrapped in a Text node with the Body Small Alt type; an empty string hides the line, and omitting it falls back to `children`. |
+| bottomText | `ReactNode` | `"List Item"` | Supporting line below `centerText`, for secondary detail. Strings are wrapped in a Text node with the Condensed type; omit or pass an empty string to hide it. |
+| divider | `boolean` | `false` | Draws a low-emphasis hairline pinned to the bottom edge of the row, separating it from the next one. Set it per row rather than on the list. |
+| interactive | `boolean` | `false` | Makes the row activatable: it renders as a `<button>`, or an `<a>` when `href` is set, and gains hover and pressed styling. Inside ListControls the row stays an `<li>` that owns focus and toggles the embedded control. |
+| href | `string` | `undefined` | Destination for a navigational row. With `interactive`, the row renders as an `<a>` inside the `<li>` and `activated` adds `aria-current="page"`; inside a Menu it also takes `role="menuitem"`. |
+| leadingIconName | `string` | `"outbound"` | Material Symbol drawn in the leading region when `leading` is not supplied. Only reaches the DOM while `leadingSlot` is on and `reserved` is off. |
+| trailingIconName | `string` | `"outbound"` | Material Symbol drawn in the trailing region when `trailing` is not supplied. Only reaches the DOM while `trailingSlot` is on. |
+| leadingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the default leading icon: `sharpUnfilled` is outlined, `sharpFilled` is solid. No effect when `leading` supplies its own node. |
+| trailingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the default trailing icon: `sharpUnfilled` is outlined, `sharpFilled` is solid. No effect when `trailing` supplies its own node. |
+| disabled | `boolean` | `false` | Blocks activation and applies disabled styling. Button rows get the native `disabled` attribute; plain, ListControls, and anchor (`href`) rows expose `aria-disabled` instead so they stay readable. |
+| activated | `boolean` | `false` | Marks the row as the current selection: activated background plus `aria-selected`, or `aria-current="page"` on `href` rows. Turns the row interactive on its own, and shows the check icon when paired with `reserved`. |
+| reserved | `boolean` | `false` | Reserves the leading space for the activation check icon so text does not shift as selection changes. Overrides `leadingSlot`, and the check appears only while `activated`. |
+| dense | `boolean` | `false` | Compact vertical padding for denser lists. Inside ListControls, inherits the group’s `dense` when this prop is omitted. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<ListItem centerText={<Text type="Body Small Alt">Item label</Text>} />
+<ListItem dense centerText={<Text type="Body Small Alt">Compact row</Text>} />
+<ListItem divider centerText={<Text type="Body Small Alt">Header</Text>} />
+<ListItem
+  interactive
+  trailingSlot
+  trailingIconName="outbound"
+  centerText={<Text type="Body Small Alt">Item with icon</Text>}
+/>
+<ListItem
+  topSlot
+  topContentSlot={<LabelBadge label="New" />}
+  centerText={<Text type="Body Small Alt">Title</Text>}
+  bottomText={<Text type="Condensed">Supporting copy</Text>}
+/>
+// Strings also work: <ListItem centerText="Item label" />
+```
+
+
+## Notes
+
+- **Center content**: Optional top content slot plus a center text stack driven by `topText`, `centerText`, and `bottomText` (omit or empty string to hide a line). Prefer **Text** nodes (Overline / Body Small Alt / Condensed); plain strings are accepted and wrapped the same way.
+- **Children**: Fallback for `centerText` when that prop is omitted (legacy).
+- **Props**: `leading` / `trailing` for icons; `leadingSlot` / `trailingSlot` / `topSlot` to show/hide
+- **States**: disabled (via disabled prop); interactive items use CSS :hover/:active
+- **Interactive**: When true, renders as button for keyboard/click support
+- **Dense**: Compact vertical padding; inside **ListControls**, inherits group `dense` when omitted
+- **List controls**: Inside **ListControls**, an interactive row owns focus and activates the embedded trailing Switch / Checkbox / Radio (no nested button around the control).

package/skills/uxelle-components/Lockup.md

@@ -0,0 +1,50 @@
+# Lockup
+
+Import: `import { Lockup } from "@uxelle/components";`
+
+Stacked eyebrow, heading, and supporting copy used for section and hero intros.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| overline | `ReactNode` | `—` | Eyebrow content above the title, typically a `Text` of type `Overline` or a fragment mixing a `LabelBadge` with that text. Rendered only when `topSlot` is true and this is non-empty. |
+| title | `ReactNode` | `—` | Heading content between `overline` and `body`, rendered as-is. Pass a `Text` with `as="h1"`–`"h6"` for the outline — `Lockup` adds no heading element of its own. This slot replaces the HTML `title` attribute on the root. |
+| body | `ReactNode` | `—` | Supporting copy under the title, typically a `Text` of type `Body Medium`. Omit it and nothing is rendered, so the stack gap collapses. |
+| topSlot | `boolean` | `true` | Gate for the overline region. Set `false` to suppress it even when `overline` has content; `title` and `body` are unaffected. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Lockup
+  overline={<Text type="Overline" width={false}>Our mission</Text>}
+  title={<Text type="Display Medium" as="h2" width={false}>Health for all, Hunger for none</Text>}
+  body={
+    <Text type="Body Medium" width={false}>
+      Advancing access to health and nutrition worldwide.
+    </Text>
+  }
+/>
+```
+
+```tsx
+// Badge beside overline text
+<Lockup
+  overline={
+    <>
+      <LabelBadge label="New" />
+      <Text type="Overline" width={false}>Our mission</Text>
+    </>
+  }
+  title={<Text type="Display Medium" as="h1" width={false}>Health for all, Hunger for none</Text>}
+/>
+```
+
+
+## Notes
+
+- Each region accepts composed content—typically `Text` for typography, or a fragment mixing badges and overline text in `overline`. Empty regions are not rendered. Set `topSlot={false}` to hide the top region. Remaining HTML attributes—including `aria-*`, `id`, and `className`—are forwarded to the root element.

package/skills/uxelle-components/Logo.md

@@ -0,0 +1,39 @@
+# Logo
+
+Import: `import { Logo } from "@uxelle/components";`
+
+Brand logo slot for navigation, footer, and marketing surfaces.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| name | `"generic"` | `"generic"` | Which mark to render from the logo set bundled in this build. It picks the asset file together with `color` and `background`, and fixes the aspect ratio that `width` scales. |
+| background | `"default" \| "onDark"` | `"default"` | Surface the mark sits on. `onDark` swaps in the on-dark full-color asset for the brands that ship one, and only applies while `color` is `fullColor`. |
+| color | `"fullColor" \| "black" \| "white" \| "colorSwitcherIcon"` | `"fullColor"` | Color treatment: `fullColor` for the brand palette, `black` or `white` for the monochrome mark, `colorSwitcherIcon` to tint the black mark with `--uxl-color-switcher-icon` from the nearest color-switcher context. Anything but `fullColor` overrides `background`. |
+| interactive | `boolean` | `false` | Fades the mark to 80% opacity on hover. `Logo` is not a control on its own, so set this only when it sits inside a link or button. |
+| width | `string` | `""` | Width of the logo container. A number or bare numeric string becomes pixels (`56`); any other string passes through as CSS (`100%`, `var(--uxl-logo-size)`). Height follows the brand aspect ratio; omit to use the mark's intrinsic width. |
+| "aria-label" | `string` | `""` | Accessible name for a meaningful (non-decorative) logo, applied as the image `alt`. Ignored while the logo is decorative — that is, when `aria-hidden` is true or when neither this nor `aria-hidden={false}` is set. |
+| "aria-hidden" | `"auto" \| "true" \| "false"` | `undefined` | Forces decorative (`true`, empty `alt`) or announced (`false`) treatment. Omit to derive it: the logo is decorative unless `aria-label` is set. |
+| role | `string` | `""` | ARIA role on the wrapper element. Prefer leaving it unset and naming the mark through the image `alt` or a parent **Link**; `role="img"` on the wrapper while the image already has `alt` can confuse assistive technology. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Logo>
+  {/* Content */}
+</Logo>
+```
+
+## Notes
+
+- Set `width` (pixels, percentage, or theme variable) so the image scales to the full width of the container; height follows each brand's aspect ratio. Not a control by itself — wrap with **Link** when it should navigate. Set `interactive` for the hover opacity treatment when the mark is inside a control.
+- **Decorative (default)** — Nav with visible site title beside the mark: omit `aria-label`; the logo stays decorative (`aria-hidden`, empty `alt`).
+- **Meaningful** — Home control where the logo is the only visible label: `aria-label="My Company Logo"` (or `aria-hidden={false}` with a label) so `alt` names the logo; put the control name on the parent link (`aria-label` / visible text), not duplicated on both link and image without intent.
+- **Avoid** `role="img"` on the wrapper when the image already has a non-empty `alt` — some assistive technologies expose redundant structure. Prefer `aria-hidden` on the mark beside visible text (see navigation examples).

package/skills/uxelle-components/Menu.md

@@ -0,0 +1,48 @@
+# Menu
+
+Import: `import { Menu } from "@uxelle/components";`
+
+Popover surface that pairs a trigger with a floating content panel.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| direction | `"Top Right" \| "Top Center" \| "Top Left" \| "Right Top" \| "Right Center" \| "Right Bottom" \| "Bottom Right" \| "Bottom Center" \| "Bottom Left" \| "Left Bottom" \| "Left Center" \| "Left Top"` | `"Top Right"` | Preferred panel position: the first word is the trigger edge the panel sits on, the second is its alignment along that edge. Flips to the opposite edge and shifts back inside the viewport when it would overflow. |
+| disableFlip | `boolean` | `—` | Pins the panel to `direction` exactly, turning off both the edge flip and the viewport clamping. Use it when a predictable position matters more than the panel staying fully visible. |
+| open | `boolean` | `—` | Controlled visibility. Pass it with `onOpenChange` and update it yourself; omit it to let the menu track its own state from `defaultOpen`. |
+| defaultOpen | `boolean` | `false` | Whether the panel starts open on first render. Ignored afterwards, and whenever `open` is passed. |
+| onOpenChange | `(open: boolean) => void` | `—` | Called with the requested visibility on trigger toggle, outside click, page scroll, Escape, or Tab-out. Required when `open` is controlled. |
+| pattern | `MenuPattern` | `"menu"` | `menu` (default): application menu (`role="menu"`, menuitems, arrow keys, Tab dismisses). `disclosure`: popup list of links or buttons. Tab moves through destinations; Tab-out and Escape close and return focus to the trigger. |
+| trigger | `ReactElement` | `—` | Single element that opens the panel, normally a `Button`. It is cloned to receive `onClick`, arrow-key handling, `aria-expanded` / `aria-haspopup` / `aria-controls`, and — in the `menu` pattern — a chevron `trailingIconName`. Without it the menu renders an inert placeholder. |
+| children | `ReactNode` | `—` | Contents of the floating panel, usually a `List` of `ListItem`s. In the `menu` pattern only `menuitem` children join arrow-key navigation; in `disclosure` any links or buttons are walked with Tab. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Menu
+  direction="Top Right"
+  trigger={<Button emphasis="low" size="large" trailingIcon trailingIconName="keyboard_arrow_down">Open Menu</Button>}
+>
+  <List>
+    <ListItem divider centerText="Header" />
+    <ListItem interactive trailingSlot trailingIconName="call_made" centerText="Item" />
+  </List>
+</Menu>
+```
+
+
+## Notes
+
+- **Trigger**: Pass a Button (required). Clicking toggles the menu open/close.
+- **Children**: Pass List with ListItems or custom content for the menu panel.
+- **Direction**: Twelve placements (Top/Right/Bottom/Left × alignment), matching Tooltip. Flips to the opposite edge when space is tight.
+- While open, the panel tracks the trigger if it moves (e.g. layout or column resize).
+- **pattern**: Default `menu` is an application menu (`role="menu"`, arrow keys, Tab dismisses). Use `disclosure` for a popup list of destinations (side-nav flyout): no menu role, Tab moves through links, Tab-out and Escape close and return focus to the trigger.
+- **Accessibility**: Default `menu` panels use `role="menu"` and are named by the trigger (`aria-labelledby`). Pass `id` on the trigger when you need a stable association. `disclosure` panels stay unnamed (destination list, no menu role).

package/skills/uxelle-components/MultiSelect.md

@@ -0,0 +1,54 @@
+# MultiSelect
+
+Import: `import { MultiSelect } from "@uxelle/components";`
+
+Multi-select dropdown with removable chips, label, optional `FieldMessage`, and listbox options.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `boolean` | `true` | When false, the label row is not rendered; pass `aria-label` so the combobox keeps an accessible name. |
+| labelText | `string` | `"Department"` | Visible label text, rendered as Body Medium Alt inside `Label`; ignored when `labelSlot` is set, and an empty string hides the label row. |
+| labelSlot | `ReactNode` | `—` | Replaces `labelText` with custom content inside `Label`, which keeps `htmlFor` and the required asterisk. Reach for it when the label needs a link or badge. |
+| fieldDescription | `string` | `""` | Helper copy rendered under the label and linked to the combobox with `aria-describedby`; only rendered while the label row is visible. |
+| fieldMessage | `boolean` | `false` | Renders a `FieldMessage` row below the control; `validation` set to `error` shows the row as well, so use this flag for neutral helper copy. |
+| fieldMessageContent | `string` | `""` | Content for the `FieldMessage` row; when omitted, the row falls back to built-in copy for the current `validation` state. |
+| validation | `"none" \| "error"` | `"none"` | Validation state: `error` switches the field message to the danger style, sets `aria-invalid`, and forces the message row; `none` leaves the field neutral. |
+| placeholder | `string` | `""` | Text shown in the trigger while nothing is selected; nothing is rendered when it is an empty string. |
+| leadingIcon | `boolean` | `false` | When true, renders the built-in leading `Icon` from `leadingIconName` inside the trigger; `leadingSlot` is the identical alias and `leading` overrides both. |
+| leadingSlot | `boolean` | `false` | Alias of `leadingIcon`: either flag turns the leading region on, matching the Textfield leading-slot naming. |
+| leadingIconName | `string` | `"add"` | Material Symbol rendered in the leading region; used only when `leadingIcon` (or `leadingSlot`) is true and `leading` is unset. An empty string falls back to `add`. |
+| leadingIconVariant | `"sharpFilled" \| "sharpUnfilled"` | `"sharpUnfilled"` | Icon style for the built-in leading icon — `sharpUnfilled` (outlined) or `sharpFilled` (solid); ignored when `leading` supplies its own icon. |
+| leading | `ReactNode` | `—` | Custom node rendered in the leading region instead of the built-in icon, with no need for `leadingIcon`. The wrapper is `aria-hidden`, so keep it decorative. |
+| value | `string[]` | `—` | Selected option values in controlled mode. Pass it with `onChange`; omit it to let the component track the selection itself. |
+| defaultValue | `string[]` | `[] as string[]` | Starting selection for uncontrolled usage; ignored once `value` is set. |
+| onChange | `(value: string[]) => void` | `—` | Called with the complete next array of values each time an option is toggled or a chip is removed. |
+| options | `MultiSelectOption[]` | `MULTI_SELECT_DEFAULT_OPTIONS` | Options rendered as listbox rows, and the lookup that resolves the trigger chip labels — still used when `children` replaces the rows. Omitting it falls back to three placeholder department options. |
+| children | `ReactNode` | `—` | Custom listbox rows (usually `ListItem`) replacing the rows built from `options`; each row must spread `listboxOptionProps()` plus a handler that toggles the value. The trigger still builds its chips from `options`, so keep the two in sync. |
+| open | `boolean` | `—` | Controlled open state of the listbox. Pass it with `onOpenChange`; omit it to let the component manage its own. `disabled` and `readOnly` keep the list closed. |
+| defaultOpen | `boolean` | `false` | Whether the listbox starts open when uncontrolled; ignored once `open` is set. |
+| onOpenChange | `(open: boolean) => void` | `—` | Called with the next open state whenever the listbox opens or closes, including outside clicks, Escape, and Tab. |
+| readOnly | `boolean` | `false` | Shows the selection as comma-separated text instead of chips, blocks opening the listbox, and hides the trailing chevron; the trigger stays focusable. |
+| required | `boolean` | `—` | Adds the asterisk to `Label` and `aria-required` on the trigger. Advisory only — no native constraint validation runs on the hidden inputs. |
+| name | `string` | `—` | Form field name for the hidden inputs that post the selection — one input per selected value, and none at all while nothing is selected. |
+| disabled | `boolean` | `false` | Blocks interaction, collapses chips to comma-separated text, and removes the trigger from the tab order; a `name` hidden input still submits each selected value. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<MultiSelect>
+  {/* Content */}
+</MultiSelect>
+```
+
+## Notes
+
+- Chips stay on one row when interactive; overflowed chips collapse to “and N more”. Read-only and disabled states show comma-separated text with truncation.
+- **Accessibility**: Visible label uses `<Label htmlFor>`; selected values render as Filter Chip–styled tags inside the combobox (standard tag-in-input pattern). Remove controls use `tabIndex={-1}` and are omitted from the accessibility tree; toggle selections via the listbox. Overflowed labels are included in a screen-reader-only summary on the combobox. Composable list rows should use `listboxOptionProps()`. `FieldMessage` uses `aria-describedby` (info) or `aria-errormessage` (error). Pass `id` for stable ids; use `aria-label` when `label={false}`.
+- **Focus**: Tab focuses the combobox trigger; **Arrow** keys move the active option while open. **Enter** / **Space** toggle the active option; **Escape** closes the list.
+- **Forms**: With `name`, one hidden input is rendered per selected value.

package/skills/uxelle-components/NavLink.md

@@ -0,0 +1,44 @@
+# NavLink
+
+Import: `import { NavLink } from "@uxelle/components";`
+
+Primary or secondary navigation item with Navigation Link typography.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` | `"Nav Link"` | Link text, rendered with Navigation Link typography. It is the control's accessible name — `children` holds the dropdown panel, not the label. |
+| leadingIcon | `boolean` | `false` | Renders `leadingIconName` before the label. |
+| leadingIconName | `string` | `"add"` | Material Symbol name for the leading icon. Ignored when `leadingIcon` is false. |
+| trailingIcon | `boolean` | `false` | Renders `trailingIconName` after the label. Forced on when `withMenu` is true, which supplies its own chevron. |
+| trailingIconName | `string` | `"keyboard_arrow_down"` | Material Symbol name for the trailing icon. Ignored when `trailingIcon` is false, and overridden by the menu chevron when `withMenu` is true. |
+| iconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style shared by both icons: `sharpUnfilled` for the outline glyph, `sharpFilled` for the solid one. |
+| navigationLevel | `"Primary" \| "Secondary"` | `"Primary"` | Which `Navigation` band the link sits in, so its colors match that surface: `Primary` for the main bar, `Secondary` for the sub-navigation bar. |
+| withMenu | `boolean` | `false` | Wraps the link in a `Menu` that opens `children` as a dropdown panel. The trigger stays a button (so `href` is ignored) and always shows a trailing `keyboard_arrow_down` that rotates 180° when open. |
+| href | `string` | `undefined` | Destination URL, which renders the link as an anchor instead of a button. Ignored when `withMenu` is true. |
+| children | `ReactNode` | `undefined` | Dropdown panel content — typically a `List` of `ListItem`s — shown when `withMenu` is true. Ignored otherwise; the visible text comes from `label`. |
+| className | `string` | `—` |  |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<NavLink label="Products" href="/products" />
+```
+
+```tsx
+<NavLink label="More" withMenu>
+  <List>...</List>
+</NavLink>
+```
+
+
+## Notes
+
+- Renders as an anchor when `href` is set; otherwise a button.
+- Set `withMenu` and pass panel `children` for dropdown overflow items. `href` is ignored while `withMenu` is true so the trigger stays a button. A trailing `keyboard_arrow_down` icon is shown and rotates 180° when open.
+- Use `navigationLevel="Secondary"` in the secondary nav band so colors follow that surface.

package/skills/uxelle-components/Navigation.md

@@ -0,0 +1,61 @@
+# Navigation
+
+Import: `import { Navigation } from "@uxelle/components";`
+
+Two-tier navigation bar for enterprise applications.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| leadingSlot | `ReactNode \| null` | `undefined` | Start of the primary bar, typically a menu `IconButton`, a **Logo**, and a title lockup. Pass `null` to drop the region; omit to render the built-in placeholder branding. |
+| centerSlot | `ReactNode \| null` | `undefined` | Middle of the primary bar between the leading and trailing regions — typically a row of `NavLink`s. Pass `null` to drop the region; omit to render placeholder links. |
+| trailingSlot | `ReactNode \| null` | `undefined` | End of the primary bar, for utilities such as a search `IconButton`, a `LanguageSelector`, and a log-in `Button`. Pass `null` to drop the region; omit for the built-in utility set. |
+| bottomSlot | `ReactNode \| null` | `undefined` | Contents of the secondary bar below the primary bar, typically `NavLink`s with `navigationLevel="Secondary"`. Pass `null` to drop the secondary bar entirely; omit to render placeholder links. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Navigation
+  leadingSlot={
+    <>
+      <IconButton emphasis="low" size="medium" iconName="menu" iconVariant="sharpUnfilled" />
+      <Logo name="generic" className="uxl-navigation__logo" width={48} aria-hidden />
+      <Text type="Condensed Alt" truncation>Votre espace dédié</Text>
+    </>
+  }
+  centerSlot={
+    <>
+      <NavLink label="Menu Link" href="#" />
+      <NavLink label="Menu Link" href="#" />
+    </>
+  }
+  trailingSlot={
+    <>
+      <IconButton iconName="search" aria-label="Search" emphasis="low" size="small" />
+      <LanguageSelector value="EN" />
+      <Divider orientation="vertical" emphasis="low" />
+      <Button emphasis="low" size="small" trailingIcon trailingIconName="keyboard_arrow_down" trailingIconVariant="sharpUnfilled">Log In</Button>
+    </>
+  }
+  bottomSlot={
+    <>
+      <NavLink label="Menu Link" href="#" navigationLevel="Secondary" />
+      <NavLink label="Menu Link" href="#" navigationLevel="Secondary" />
+    </>
+  }
+/>
+```
+
+
+## Notes
+
+- **Primary nav**: Leading, center, and trailing regions. Use slots for branding, main links, and utilities.
+- **Secondary nav**: Optional bottom bar for sub-navigation.
+- **Slots**: Pass `leadingSlot`, `centerSlot`, `trailingSlot`, and `bottomSlot` to customize each region. Omit a slot for the built-in placeholder; pass `null` to drop that region.

package/skills/uxelle-components/NavigationSide.md

@@ -0,0 +1,51 @@
+# NavigationSide
+
+Import: `import { NavigationSide, DefaultLogoSlotContent, DefaultCenterSlotContent, DefaultBottomSlotContent } from "@uxelle/components";`
+
+App chrome for a vertical side rail, or a compact top bar on small layouts.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| 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. |
+| 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. |
+| 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. |
+| centerSlotContent | `ReactNode` | `undefined` | Main destination region: one or more `NavigationSideGroup` elements, each wrapping `NavigationSideItem` rows. Rendered in the rail and, on the mobile layout, in the menu sheet. Omit for demo groups; pass `false` to leave empty. |
+| bottomSlotContent | `ReactNode` | `undefined` | Trailing region under the destinations, typically an account row built from `List` + `ListItem`. Sits at the bottom of the rail and is pinned to the bottom of the mobile menu sheet. Pass `false` to leave it empty. |
+| menuOpen | `boolean` | `—` | Controlled open state of the mobile menu sheet. Pass with `onMenuOpenChange` (for example to close the sheet after navigation); omit to let `defaultMenuOpen` and the menu control own it. No effect on the side rail. |
+| defaultMenuOpen | `boolean` | `false` | Whether the mobile menu sheet starts open when `menuOpen` is omitted. |
+| onMenuOpenChange | `(open: boolean) => void` | `—` | Called with the next open state whenever the mobile menu sheet opens or closes, including dismissals from inside the sheet. |
+| onMenuClick | `MouseEventHandler<HTMLButtonElement>` | `—` | Click handler on the mobile menu button itself. Fires in addition to the sheet opening — use `onMenuOpenChange` to track sheet state. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<NavigationSide
+  expanded
+  logoSlotContent={<Logo name="generic" width={48} aria-hidden />}
+  centerSlotContent={
+    <NavigationSideGroup aria-label="Product">
+      <NavigationSideItem label="Overview" href="/overview" leadingIconName="view_quilt" />
+    </NavigationSideGroup>
+  }
+/>
+```
+
+
+## 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.
+- **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.