@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: uxelle-components
+description: Reference for uxElle Generative Product Foundation (GPF) components. Use when generating UI with uxElle, implementing designs, building layouts, or when the user mentions uxElle components, design system, or enterprise UI.
+---
+
+# uxElle Components — Generative Workflow Reference
+
+Reference for accurately using uxElle Generative Product Foundation (GPF) components in generative workflows. Import from `@uxelle/components`.
+
+## Context discipline
+
+- Load this SKILL.md when working with uxElle components.
+- Load individual component files (e.g. Button.md, ListItem.md) only when you need that component's props or examples.
+- Do not preload all component files.
+
+## Reading a component file
+
+Each component file leads with its import and a one-line summary, then a Props table of `Prop | Type | Default | Description`.
+
+- A prop marked **`(required)`** must be passed — the component will not render correctly without it.
+- The Default column shows the value the component applies when the prop is omitted; `—` means there is no default.
+- Props tables list the supported public surface. Prefer these over spreading arbitrary HTML attributes.
+
+## Quick Import Reference
+
+```tsx
+import {
+  Accordion,
+  AccordionGroup,
+  Banner,
+  BannerAnnouncement,
+  Breadcrumb,
+  Breadcrumbs,
+  Bubble,
+  Button,
+  ButtonGroup,
+  Card,
+  Checkbox,
+  CheckboxGroup,
+  ChoiceChip,
+  ChoiceChipGroup,
+  DatePicker,
+  DatePickerRange,
+  Dialog,
+  Divider,
+  DynamicAngleLine,
+  DynamicAngleLineCombo,
+  DynamicAngleShape,
+  DynamicAngleShapeSurface,
+  DynamicAngleTexture,
+  DynamicAngleTextureText,
+  FieldMessage,
+  FileUpload,
+  FilterChip,
+  FilterChipGroup,
+  Footer,
+  Hero,
+  Icon,
+  IconButton,
+  Image,
+  Label,
+  LabelBadge,
+  LanguageSelector,
+  LanguageSelectorButton,
+  Layout,
+  LinearProgress,
+  Link,
+  List,
+  ListControls,
+  ListItem,
+  Lockup,
+  Logo,
+  Menu,
+  MultiSelect,
+  NavLink,
+  Navigation,
+  NavigationSide,
+  NavigationSideGroup,
+  NavigationSideItem,
+  NavigationSideSubItem,
+  NotificationBadge,
+  Pagination,
+  PaginationComplex,
+  PaginationSimple,
+  ProductCard,
+  Quantity,
+  Radio,
+  RadioGroup,
+  Select,
+  SegmentedControl,
+  Scrim,
+  Sheet,
+  Skeleton,
+  SkeletonGroup,
+  Spinner,
+  StatTile,
+  Stepper,
+  Switch,
+  Tab,
+  Table,
+  TabsCompact,
+  TabsStretch,
+  Textarea,
+  Textfield,
+  Tooltip,
+  Text,
+} from "@uxelle/components";
+```
+
+## Component Index
+
+| Component | File | Use when |
+|-----------|------|----------|
+| **Accordion** | [Accordion.md](Accordion.md) | Expandable sections, FAQs |
+| **AccordionGroup** | [AccordionGroup.md](AccordionGroup.md) | Multiple elevated accordions |
+| **Banner** | [Banner.md](Banner.md) | In-page contextual notices with optional actions and dismiss |
+| **BannerAnnouncement** | [BannerAnnouncement.md](BannerAnnouncement.md) | System-wide bar above nav that displaces layout |
+| **Breadcrumb** | [Breadcrumb.md](Breadcrumb.md) | Single crumb in a trail; compose inside `Breadcrumbs` |
+| **Breadcrumbs** | [Breadcrumbs.md](Breadcrumbs.md) | Nav landmark trail of `Breadcrumb` children with optional overflow |
+| **Bubble** | [Bubble.md](Bubble.md) | Compact icon or text chips, inline labels |
+| **Button** | [Button.md](Button.md) | Primary actions, CTAs |
+| **ButtonGroup** | [ButtonGroup.md](ButtonGroup.md) | Layout group for related `Button` actions (not segmented control) |
+| **Card** | [Card.md](Card.md) | Elevated surface for arbitrary content |
+| **Checkbox** | [Checkbox.md](Checkbox.md) | Single checkbox inputs in forms |
+| **CheckboxGroup** | [CheckboxGroup.md](CheckboxGroup.md) | Fieldset-backed groups; nested **`Checkbox`** children share **`name`** and group **`value`** |
+| **ChoiceChip** | [ChoiceChip.md](ChoiceChip.md) | Toggle pill for multi-select choice sets (facets, sort, view) |
+| **ChoiceChipGroup** | [ChoiceChipGroup.md](ChoiceChipGroup.md) | Groups multi-select choice toggles under an optional label |
+| **DatePicker** | [DatePicker.md](DatePicker.md) | Single calendar date field (ISO `YYYY-MM-DD`); type or pick from a month grid |
+| **DatePickerRange** | [DatePickerRange.md](DatePickerRange.md) | Start and end calendar dates (ISO `YYYY-MM-DD`); type or pick from a month grid |
+| **Dialog** | [Dialog.md](Dialog.md) | Centered modal confirmations and forms with scrim and focus trap |
+| **Divider** | [Divider.md](Divider.md) | Visual separation, section boundaries |
+| **DynamicAngleLine** | [DynamicAngleLine.md](DynamicAngleLine.md) | Decorative diagonal brand accent for hero and section layouts |
+| **DynamicAngleLineCombo** | [DynamicAngleLineCombo.md](DynamicAngleLineCombo.md) | Decorative paired diagonal accents for hero layouts |
+| **DynamicAngleShape** | [DynamicAngleShape.md](DynamicAngleShape.md) | Decorative angled shard for hero bands and section accents |
+| **DynamicAngleShapeSurface** | [DynamicAngleShapeSurface.md](DynamicAngleShapeSurface.md) | Decorative angled surface for hero and section backgrounds |
+| **DynamicAngleTexture** | [DynamicAngleTexture.md](DynamicAngleTexture.md) | Decorative repeating diagonal texture strip |
+| **DynamicAngleTextureText** | [DynamicAngleTextureText.md](DynamicAngleTextureText.md) | Texture strip paired with a tagline for hero layouts |
+| **FieldMessage** | [FieldMessage.md](FieldMessage.md) | Field validation, helper text |
+| **FileUpload** | [FileUpload.md](FileUpload.md) | File picker with button or drag-and-drop, file list, validation |
+| **FilterChip** | [FilterChip.md](FilterChip.md) | Removable pill for an applied filter |
+| **FilterChipGroup** | [FilterChipGroup.md](FilterChipGroup.md) | Groups dismissible applied-filter chips under an optional label |
+| **Footer** | [Footer.md](Footer.md) | Page footer, legal, branding |
+| **Hero** | [Hero.md](Hero.md) | Full-bleed marketing band with overlaid copy and actions |
+| **Icon** | [Icon.md](Icon.md) | Material Symbols icons |
+| **IconButton** | [IconButton.md](IconButton.md) | Icon-only actions |
+| **Image** | [Image.md](Image.md) | Responsive images with controlled aspect ratios |
+| **Label** | [Label.md](Label.md) | Form field labels, required indicator |
+| **LabelBadge** | [LabelBadge.md](LabelBadge.md) | Status pills, emphasis labels, badges |
+| **LanguageSelector** | [LanguageSelector.md](LanguageSelector.md) | Locale switching |
+| **LanguageSelectorButton** | [LanguageSelectorButton.md](LanguageSelectorButton.md) | Language selector menu button |
+| **Layout** | [Layout.md](Layout.md) | Flex/grid containers, spacing |
+| **LinearProgress** | [LinearProgress.md](LinearProgress.md) | Progress bars; determinate/indeterminate; optional label and field message slots |
+| **Link** | [Link.md](Link.md) | Navigation links, hyperlinks |
+| **List** | [List.md](List.md) | Vertical list container |
+| **ListControls** | [ListControls.md](ListControls.md) | Settings/choice list with embedded Switch, Checkbox, or Radio (`controlType`) |
+| **ListItem** | [ListItem.md](ListItem.md) | List items with slots |
+| **Lockup** | [Lockup.md](Lockup.md) | Stacked eyebrow, heading, and supporting copy for section intros |
+| **Logo** | [Logo.md](Logo.md) | Brand logo slot for navigation, footer, and marketing surfaces |
+| **Menu** | [Menu.md](Menu.md) | Dropdown menus |
+| **MultiSelect** | [MultiSelect.md](MultiSelect.md) | Multi-value combobox with chip overflow |
+| **NavLink** | [NavLink.md](NavLink.md) | Primary/secondary nav links (optional menu) |
+| **Navigation** | [Navigation.md](Navigation.md) | Header/nav bar |
+| **NavigationSide** | [NavigationSide.md](NavigationSide.md) | Side-rail chrome (`<aside>`) or compact top bar; SSR hosts pass `mobile`; omit only in client-only surfaces |
+| **NavigationSideGroup** | [NavigationSideGroup.md](NavigationSideGroup.md) | Side-nav landmark (`<nav>`) grouping destination rows with optional end divider and collapsed layout |
+| **NavigationSideItem** | [NavigationSideItem.md](NavigationSideItem.md) | Destination row for a vertical side rail — icon, label, activated indicator, accordion, collapsed flyout |
+| **NavigationSideSubItem** | [NavigationSideSubItem.md](NavigationSideSubItem.md) | Nested destination under an accordion side-rail parent |
+| **NotificationBadge** | [NotificationBadge.md](NotificationBadge.md) | Dot or counter overlays on icons and avatars |
+| **Pagination** | [Pagination.md](Pagination.md) | Numbered page footer with optional summary (items-per-page menu + range) |
+| **PaginationComplex** | [PaginationComplex.md](PaginationComplex.md) | Full footer with items-per-page menu, range, page-jump menu, prev/next |
+| **PaginationSimple** | [PaginationSimple.md](PaginationSimple.md) | Compact prev/next with optional item-range label |
+| **ProductCard** | [ProductCard.md](ProductCard.md) | Product tile with top, center, and bottom content regions |
+| **Quantity** | [Quantity.md](Quantity.md) | Numeric stepper (minus/plus, spinbutton); enforces `min`/`max`; optional `FieldMessage` |
+| **Radio** | [Radio.md](Radio.md) | Single radio option (`<label>` + native `input type="radio"`) |
+| **RadioGroup** | [RadioGroup.md](RadioGroup.md) | Fieldset-backed groups; nested **`Radio`** children share **`name`** and group **`value`** |
+| **Select** | [Select.md](Select.md) | Single-select combobox with listbox options |
+| **SegmentedControl** | [SegmentedControl.md](SegmentedControl.md) | Exclusive multi-segment view/mode switcher |
+| **Scrim** | [Scrim.md](Scrim.md) | Semi-transparent backdrop behind modal overlays (Sheet, Dialog) |
+| **Sheet** | [Sheet.md](Sheet.md) | Slide-over panels and edge sheets |
+| **Skeleton** | [Skeleton.md](Skeleton.md) | Layout loading placeholders; compose with `SkeletonGroup` |
+| **Spinner** | [Spinner.md](Spinner.md) | Loading / success / error async status beside optional label |
+| **StatTile** | [StatTile.md](StatTile.md) | KPI readout with label, value, optional qualifier, info tooltip, and trailing region |
+| **Stepper** | [Stepper.md](Stepper.md) | Multi-step progress; includes **`StepperItem`** composition |
+| **Switch** | [Switch.md](Switch.md) | Toggle controls, on/off states |
+| **Tab** | [Tab.md](Tab.md) | Tab labels for tab navigation |
+| **Table** | [Table.md](Table.md) | Data tables with sort, reorder, resize, and pinning |
+| **TabsCompact** | [TabsCompact.md](TabsCompact.md) | Intrinsic tab widths, optional scroll |
+| **TabsStretch** | [TabsStretch.md](TabsStretch.md) | Equal-width tabs |
+| **Textarea** | [Textarea.md](Textarea.md) | Multi-line text fields with optional character counter, auto-grow, and soft overflow |
+| **Textfield** | [Textfield.md](Textfield.md) | Single-line text input fields, forms |
+| **Tooltip** | [Tooltip.md](Tooltip.md) | Contextual hints on hover or focus |
+| **Text** | [Text.md](Text.md) | Text, headings, labels |
+
+## Core Patterns
+
+### Button labels
+Pass the label as plain `children`. `Button` wraps it in `<Text type="Button">` for you — adding your own `Text` nests one inside another:
+
+```tsx
+<Button emphasis="high">Click me</Button>
+```
+
+`IconButton` has no visible label, so give it an `aria-label` instead.
+
+### List structure
+Use `List` + `ListItem` for menus and lists. Prefer `centerText` / `bottomText` / `topText`:
+
+```tsx
+<List>
+  <ListItem divider centerText={<Text type="Body Small Alt">Header</Text>} />
+  <ListItem
+    interactive
+    trailingSlot
+    trailingIconName="outbound"
+    centerText={<Text type="Body Small Alt">Item</Text>}
+  />
+</List>
+```
+
+### List controls
+Prefer **`ListControls`** when each row has title/description plus an embedded trailing control (settings and exclusive choices). Page layout: harness [recipe-settings-page.md](../uxelle-design-harness/recipe-settings-page.md). Set **`controlType`** to **`switch`**, **`checkbox`**, or **`radio`**. Same selection roles as **`RadioGroup`** / **`CheckboxGroup`** for checkbox/radio, list layout instead of stacked form options. Use **`interactive`** **`ListItem`** rows with **`embedded`** Switch / Checkbox / Radio in **`trailing`**. Set **`dense`** on **`ListControls`** (or per **`ListItem`**) for compact row padding.
+
+### Icon variants
+Icons use `sharpFilled` or `sharpUnfilled`. Default is `sharpUnfilled`.
+
+### Theme tokens
+Generated app CSS uses `--uxl-color-switcher-*` and layout/page-chrome tokens. Do not use `--uxl-component-*` in app CSS (those tokens belong inside components). Focus rings on catalog controls already use `--uxl-color-switcher-interactive-icon`.
+
+### Radio groups
+Use **`RadioGroup`** for a shared **`name`** and selection state; each option is a **`Radio`** with a stable **`value`** and **`Text`** (or similar) as **`children`**. Wire **`value`** / **`onChange`** for controlled mode (`onChange` receives the next string). Without a visible **`legend`** (**`label`** + **`labelText`**), set **`aria-label`** or **`aria-labelledby`** on **`RadioGroup`** (the **`fieldset`**).
+
+### Checkbox groups
+Use **`CheckboxGroup`** for related multi-select options under one legend; each option is a **`Checkbox`** with a stable **`value`** and **`Text`** (or similar) as **`children`**. **`value`** / **`defaultValue`** are **`string[]`**. Without a visible **`legend`**, set **`aria-label`** or **`aria-labelledby`** on **`CheckboxGroup`**.
+
+### Color switcher
+For secondary nav or brand hero bands: `data-color-switcher="brand-2"` on secondary nav (or `brand-1` on hero regions); use `NavLink` with `navigationLevel="Secondary"` in that band.
+
+## Additional Resources
+
+- [Design harness](../uxelle-design-harness/SKILL.md) — principles, variables, page chrome, responsiveness, WCAG AA, recipes
+- [Form field contract](../../docs/guides/form-field-contract.md) — HTML `value` / `checked` (not Figma `Selected` / `Activated`)
+- [Design variables (`--uxl-*`)](../uxelle-design-harness/tokens.md) — spacing, radius, elevation, color switcher, type
+- Do not import `InternalDialog` or `InternalImageOverlay` in generated UI — use `Dialog` and `Image`.

package/skills/uxelle-components/Scrim.md

@@ -0,0 +1,28 @@
+# Scrim
+
+Import: `import { Scrim } from "@uxelle/components";`
+
+Semi-transparent backdrop that dims page content behind modal overlays.
+
+## Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `className` | `string` | Optional class names merged onto the scrim surface. |
+
+Parent overlays own open/close state, motion, positioning, and dismiss behavior.
+
+## Usage
+
+```tsx
+<div className="overlay" data-state={open ? "open" : "closed"}>
+  <Scrim className="overlay__scrim" />
+  <DialogPanel />
+</div>
+```
+
+## Notes
+
+- **Visual only**: Themed semi-transparent background — no state, motion, or dismiss logic.
+- **Decorative**: Always `aria-hidden`; the parent dialog or sheet owns modal semantics and focus management.
+- **Composition**: Parent sets positioning on `className`, plus `data-state`, fade animations, and click handling as needed. `Sheet` passes `className="uxl-sheet__scrim"` and dismisses on overlay clicks outside the panel.

package/skills/uxelle-components/SegmentedControl.md

@@ -0,0 +1,118 @@
+# SegmentedControl
+
+Import: `import { SegmentedControl } from "@uxelle/components";`
+
+Compact single-select control for switching related views or modes (list vs grid, chart period, toolbar filters). Suitable for forms with optional **FieldMessage**, `required` / `invalid`, and a form `name`.
+
+## Props — SegmentedControl
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| name | `string` | `""` | Form field name for a hidden input carrying the selected segment value. Omit when the control is not submitted with a native form. |
+| label | `boolean` | `true` | Renders a `<legend>` when true and `labelText` (or `labelSlot`) is set; the legend names the group. When false, name the group with `aria-label` or `aria-labelledby` — `fieldDescription` is not rendered without a legend. |
+| labelText | `string` | `""` | Visible group name rendered in the legend (Body Medium Alt). Leave it empty to drop the legend entirely, then name the group with `aria-label`. |
+| fieldDescription | `string` | `""` | Supporting copy below the legend, wired to the fieldset through `aria-describedby`. Rendered only while the legend is visible. |
+| labelSlot | `ReactNode` | `—` | Custom legend content replacing the default `Label` + `Text`, and with them the `required` asterisk and `fieldDescription`. Setting it also shows the legend when `labelText` is empty. |
+| segments | `readonly SegmentedControlSegmentConfig[]` | `—` | Segment definitions for A2UI, codegen, or simple configs. Prefer **SegmentedControlSegment** children for hand-written React. When both are set, `children` wins. |
+| children | `ReactNode` | `—` | Compose 2–5 `SegmentedControlSegment` children (preferred for React apps). Fragments are unwrapped; any other child is skipped with a development warning. |
+| controlType | `"Button" \| "Icon Button"` | `"Button"` | Layout mode applied to every segment: `Button` shows a text label with optional leading and trailing icons, `Icon Button` shows `iconName` alone and needs each segment's `aria-label`. |
+| value | `string` | `undefined` | Selected segment value; controlled whenever this is a non-empty string. Pair it with `onValueChange`, and omit it entirely (never `""`) to fall back to index-based `activated`. |
+| defaultValue | `string` | `""` | Initially selected segment value while `value` is omitted, after which the component owns selection. Falls back to `defaultActivated` when empty or unmatched. |
+| onValueChange | `(value: string) => void` | `—` | Called with the newly selected segment's value on click or keyboard selection. Preferred over `onActivatedChange`; both fire when both are set. |
+| activated | `number` | `undefined` | Selected segment as a 1-based index, controlled and clamped to the segment count. Read only while `value` is omitted; prefer `value` in application code so selection survives reordered or localized options. |
+| defaultActivated | `number` | `1` | Initially selected segment as a 1-based index while `value` and `defaultValue` are both omitted; clamped to the segment count. Prefer `defaultValue` when segment identity matters. |
+| onActivatedChange | `(activated: number) => void` | `—` | Called with the newly selected segment's 1-based index. Prefer `onValueChange` when segment identity matters; both fire when both are set. |
+| disabled | `boolean` | `false` | Locks the group as non-interactive while keeping options perceivable (`aria-disabled` on the group and segments). The hidden `name` input is disabled too, so nothing is submitted. |
+| fieldMessage | `ReactNode` | `—` | Shown below the control; plain string or number uses `fieldMessageType` with **FieldMessage**. Its region `id` is merged into fieldset `aria-describedby` (or `aria-errormessage` when the type is Danger). |
+| fieldMessageType | `"Info" \| "Danger" \| "Warning" \| "Success"` | `SEGMENTED_CONTROL_DEFAULTS.fieldMessageType` | Style applied to `FieldMessage` when `fieldMessage` is a string or number. Forced to `Danger` while `invalid` is true. |
+| required | `boolean` | `false` | Maps to `aria-required` on the radiogroup, and shows the `Label` asterisk while a legend is visible. Announces that a selection is mandatory before any option is chosen. |
+| invalid | `boolean` | `false` | Sets `aria-invalid="true"` and shows a Danger field message (uses `fieldMessage` when set, otherwise a default error string). Also wires `aria-errormessage` and announces the message politely. |
+| width | `string` | `""` | Width of the control. Numbers and bare numeric strings become px; other strings pass through as CSS (`100%`, `16rem`, `var(--uxl-…)`). Omit to size from the segments, which truncate long labels and reveal the full text in a tooltip. |
+| "aria-label" | `string` | `""` | Accessible name for the radiogroup when no legend is visible. Prefer `label` + `labelText` when a visible group name exists. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that name the group. Ignored while a legend is visible, since the legend already names the fieldset. |
+| "aria-describedby" | `string` | `""` | Space-separated ids of helper or instruction copy. Merged with the `fieldDescription` id and the id of a non-error field message. |
+| "aria-errormessage" | `string` | `""` | Id of the element holding the error text. Defaults to the field message region id once the resolved message type is Danger, and is only announced while `aria-invalid` is true. |
+| "aria-invalid" | `boolean` | `false` | Explicit `aria-invalid` on the radiogroup, overriding what `invalid` would set. Marking it true also triggers the Danger field message. |
+| "aria-required" | `boolean` | `false` | Explicit `aria-required` on the radiogroup, overriding what `required` would set. Omit it to let `required` drive the announcement. |
+
+<!-- prettier-ignore-end -->
+
+## Props — SegmentedControlSegment
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | `""` | Stable segment identity matched against the parent's `value` and reported by `onValueChange`. When empty it falls back to the visible label — or, for `Icon Button` segments, to `aria-label` then `iconName` — and finally to a positional `segment-N`. |
+| text | `string` | `""` | Visible label when the parent `controlType` is `Button`. Prefer `children` when composing in React; `text` is the string form for configs and codegen. |
+| children | `ReactNode` | `—` | Label content when the parent `controlType` is `Button`. Wins over `text`, and long labels truncate with the full text shown in a tooltip on hover or focus. |
+| leadingIcon | `boolean` | `false` | Renders `leadingIconName` before the label. Ignored when the parent `controlType` is `Icon Button`. |
+| trailingIcon | `boolean` | `false` | Renders `trailingIconName` after the label. Ignored when the parent `controlType` is `Icon Button`. |
+| leadingIconName | `string` | `"chevron_left"` | Material Symbol drawn before the label. Only read when `leadingIcon` is true, and falls back to `chevron_left` when omitted. |
+| trailingIconName | `string` | `"chevron_right"` | Material Symbol drawn after the label. Only read when `trailingIcon` is true, and falls back to `chevron_right` when omitted. |
+| leadingIconVariant | `"sharpFilled" \| "sharpUnfilled"` | `"sharpFilled"` | Fill style of the leading icon: `sharpFilled` (solid) or `sharpUnfilled` (outline). |
+| trailingIconVariant | `"sharpFilled" \| "sharpUnfilled"` | `"sharpFilled"` | Fill style of the trailing icon: `sharpFilled` (solid) or `sharpUnfilled` (outline). |
+| iconName | `string` | `"add"` | Material Symbol shown in place of a label when the parent `controlType` is `Icon Button`. Falls back to `add` when omitted; pair it with `aria-label`. |
+| iconVariant | `"sharpFilled" \| "sharpUnfilled"` | `"sharpFilled"` | Fill style of the icon-only glyph: `sharpFilled` (solid) or `sharpUnfilled` (outline). |
+| disabled | `boolean` | `false` | Blocks selection of this one segment while keeping it visible and announced (`aria-disabled`). Arrow, Home, and End navigation skips it. |
+| "aria-label" | `string` | `""` | Accessible name for the segment. Required for `Icon Button` segments, which have no visible text, and useful when a visible label is too terse on its own. |
+
+<!-- prettier-ignore-end -->
+
+
+## Usage
+
+```tsx
+<SegmentedControl
+  name="chartType"
+  controlType="Button"
+  label
+  labelText="Chart Type"
+  fieldDescription="Choose how your data is displayed in the chart."
+  value={chart}
+  onValueChange={setChart}
+  fieldMessage={error}
+  fieldMessageType="Danger"
+  invalid={Boolean(error)}
+  required
+>
+  <SegmentedControl.Segment value="bar">Bar</SegmentedControl.Segment>
+  <SegmentedControl.Segment value="line">Line</SegmentedControl.Segment>
+  <SegmentedControl.Segment value="area">Area</SegmentedControl.Segment>
+</SegmentedControl>
+```
+
+```tsx
+<SegmentedControl
+  controlType="Icon Button"
+  label={false}
+  aria-label="View mode"
+  value={view}
+  onValueChange={setView}
+>
+  <SegmentedControl.Segment value="list" iconName="view_list" aria-label="List" />
+  <SegmentedControl.Segment value="grid" iconName="grid_view" aria-label="Grid" />
+</SegmentedControl>
+```
+
+```tsx
+<SegmentedControl label={false} aria-label="View mode" value={view} onValueChange={setView}>
+  <SegmentedControl.Segment value="list" leadingIcon leadingIconName="list">
+    List
+  </SegmentedControl.Segment>
+  <SegmentedControl.Segment value="grid">Grid</SegmentedControl.Segment>
+</SegmentedControl>
+```
+
+
+## Notes
+
+- Compose 2–5 `SegmentedControl.Segment` children, or pass a `segments` array for generated configs. Exactly one segment is active at a time. Not a ButtonGroup for independent actions or Choice Chips for multi-select.
+- **Selection**: Prefer `value` / `defaultValue` / `onValueChange` in application code, with a `value` on each segment. Omit `value` entirely (do not pass `""`) only when you need index-based `activated` / `defaultActivated` / `onActivatedChange` (e.g. Code Connect). A non-empty `value` is controlled.
+- **Keyboard**: Arrow keys, Home, and End move focus and selection together (radiogroup pattern). Space and Enter also select the focused segment.
+- **Segments**: Each option renders a `SegmentedControl.Segment`. Set `controlType` on this parent (`Button` with optional leading/trailing icons + label, or `Icon Button` with `iconName` + `aria-label`); it applies to every segment.
+- **Forms**: Optional `name` submits the selected segment value via a hidden input. Use `Label` (via `label` + `labelText` + `required`) for a visible required marker, plus `fieldMessage`, `fieldMessageType`, and `invalid`. When `invalid` is true, a Danger field message is shown (author `fieldMessage` when provided, otherwise a default error string).
+- **Accessibility**: Root is a **`fieldset`** with **`role="radiogroup"`**. Native **`<legend>`** names the group when shown (do not also point `aria-labelledby` at that legend). Segments are `role="radio"` with `aria-checked`. Arrow keys (RTL-aware), Home, and End move focus and selection and skip disabled segments. Group `disabled` uses `aria-disabled` so options stay perceivable. When `label` is false, set `aria-label` or `aria-labelledby`. Icon-only segments require `aria-label`.
+- **Width**: Numbers map to pixels; strings accept `%`, lengths, or `var(--uxl-…)`. Narrow the width to verify label truncation; truncated Button labels show the full text in a tooltip on hover or focus.

package/skills/uxelle-components/Select.md

@@ -0,0 +1,55 @@
+# Select
+
+Import: `import { Select } from "@uxelle/components";`
+
+Single-select dropdown with label, design tokens, 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 no option 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 value in controlled mode. Pass it with `onChange`; omit it to let the component track the selection itself. |
+| defaultValue | `string` | `—` | Starting selection for uncontrolled usage; ignored once `value` is set. |
+| onChange | `(value: string) => void` | `—` | Called with the chosen option's `value` after the user commits a selection; the listbox closes and focus returns to the trigger. |
+| options | `SelectOption[]` | `SELECT_DEFAULT_OPTIONS` | Options rendered as listbox rows, and the lookup that resolves the label shown in the trigger — 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 an activate handler such as `onClick`. The trigger still resolves the selected label 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 current selection but blocks opening the listbox and hides the trailing chevron; the trigger stays focusable and reports `aria-readonly`. |
+| required | `boolean` | `—` | Adds the asterisk to `Label` and `aria-required` on the trigger. Advisory only — no native constraint validation runs on the hidden input. |
+| name | `string` | `—` | Form field name for the hidden input that posts the selected value. No input is rendered while nothing is selected, so an empty selection is never submitted. |
+| disabled | `boolean` | `false` | Blocks interaction, removes the trigger from the tab order, and applies disabled styling; a `name` hidden input still submits the current value. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Select>
+  {/* Content */}
+</Select>
+```
+
+## Notes
+
+- **Simple API** — pass `options` with `value` / `onChange` for controlled usage; optional `leadingIcon` / `leadingIconName`.
+- **Composable API** — pass `children` to render custom `ListItem` rows in the listbox; pass `leading` for a custom leading slot. Each row should spread `listboxOptionProps()` plus selection handlers (see dev console when the list opens).
+- **Accessibility**: Visible label uses `<Label htmlFor>`; the combobox name uses `aria-labelledby` on the label text only (not `fieldDescription`, which is linked via `aria-describedby`). `FieldMessage` uses `aria-describedby` (info) or `aria-errormessage` (error). Pass `id` for stable ids; use `aria-label` when `label={false}`.
+- **Focus**: Tab focuses the combobox trigger only; **Arrow** keys move the active option (`aria-activedescendant`) while open. **Enter** commits the active option; **Escape** closes the list. Options use `tabIndex={-1}` and are not separate tab stops.
+- **Forms**: With `name`, a hidden input posts the selected value; when nothing is selected, no hidden input is rendered.

package/skills/uxelle-components/Sheet.md

@@ -0,0 +1,31 @@
+# Sheet
+
+Import: `import { Sheet } from "@uxelle/components";`
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| direction | `"Right" \| "Left" \| "Bottom"` | `"Right"` | Edge the panel slides in from. `Right` / `Left` give a side sheet with a header and close button; `Bottom` gives a bottom sheet with a drag handle that can be swiped down to dismiss. |
+| open | `boolean` | `—` | Controlled visibility. Pass it with `onOpenChange` and update it yourself; omit it to let the sheet track its own state from `defaultOpen`. |
+| defaultOpen | `boolean` | `false` | Whether the sheet starts open on first render. Ignored afterwards, and whenever `open` is passed. |
+| onOpenChange | `(open: boolean) => void` | `—` | Called with the requested visibility when the trigger is clicked, Escape or the scrim dismisses the sheet, or a bottom sheet is dragged down. Required when `open` is controlled. |
+| trigger | `ReactElement` | `—` | Single element that toggles the sheet; it is cloned to receive `onClick`, `aria-expanded`, `aria-haspopup`, and `aria-controls`, and takes focus back on close. Omit it and control `open` yourself when the opener lives elsewhere. |
+| title | `string` | `"Title"` | Heading text for the default top slot: visible on `Left` / `Right` sheets and screen-reader-only on `Bottom`. It also becomes the sheet's accessible name unless `topSlot`, `aria-label`, or `aria-labelledby` is supplied. |
+| closeLabel | `string` | `"Close"` | Text shared by both default dismiss affordances — the `aria-label` on the header close button and the visible label on the footer button. Blank falls back to `Close`. |
+| topSlot | `ReactNode` | `—` | Replaces the entire default top region: the side header with its close button, or the bottom sheet's drag handle. `title` is then dropped, so supply your own heading and dismiss affordance. |
+| bottomSlot | `ReactNode` | `—` | Replaces the default footer close button — use it for the sheet's real actions. Keep a dismiss control among them, since Escape and the scrim are otherwise the only way out. |
+| initialFocusRef | `RefObject<HTMLElement \| null>` | `—` | Ref to the element that should take focus when the sheet opens — typically the first input or the primary action. Omit it to focus the panel itself, which announces the sheet's accessible name and lets Tab walk the content in DOM order; a target outside the panel or one that refuses focus falls back there too. Focus always enters the panel: the sheet is a modal dialog (`aria-modal`). |
+| children | `ReactNode` | `—` | Main body of the sheet, rendered between the top and bottom slots and scrolled independently once it overflows. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Sheet>
+  {/* Content */}
+</Sheet>
+```

package/skills/uxelle-components/Skeleton.md

@@ -0,0 +1,35 @@
+# Skeleton
+
+Import: `import { Skeleton } from "@uxelle/components";`
+
+Decorative loading placeholder for a single shape. Use with **SkeletonGroup** so assistive technology hears one loading announcement for the region. Individual shapes are `aria-hidden`.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| type | `"circle" \| "square" \| "rectangle" \| "textLoader"` | `"circle"` | Placeholder geometry: `circle` for avatars, `square` for thumbnails, `rectangle` for image and block placeholders, `textLoader` for stacked text lines. |
+| size | `"extraSmall" \| "small" \| "medium" \| "large"` | `"small"` | Token-backed footprint preset, and for `textLoader` the height of each line. `width` / `height` override the dimensions it produces. |
+| width | `string` | `""` | Explicit width in place of the `size` preset: numbers are pixels, strings take any CSS length (e.g. `100%`, `4rem`). `rectangle` and `textLoader` already fill the parent width when this is omitted. |
+| height | `string` | `""` | Explicit height in place of the `size` preset: numbers are pixels, strings take any CSS length. For `textLoader` this sizes the whole block — per-line height still follows `size`. |
+| motion | `boolean` | `true` | Runs the shimmer sweep on this shape. A `SkeletonGroup` with `motion` false suppresses it regardless, as does `prefers-reduced-motion`. |
+| contentSlot | `ReactNode` | `—` | Replaces the three default lines of a `textLoader` with your own shapes — nest **Skeleton** instances to mirror a specific text layout. Ignored by every other `type`. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Skeleton>
+  {/* Content */}
+</Skeleton>
+```
+
+## Notes
+
+- For async operation feedback (save, submit), use **Spinner** or **LinearProgress**instead. Provide a fallback if loading exceeds ~5 seconds.
+- Use `size` for token-backed presets. Set `width` and/or `height` to mirror specific content dimensions; those props override preset footprint sizing. Rectangle and text-loader shapes default to 100% parent width when `width` is omitted.

package/skills/uxelle-components/Spinner.md

@@ -0,0 +1,33 @@
+# Spinner
+
+Import: `import { Spinner } from "@uxelle/components";`
+
+Status indicator that communicates loading, success, or error state.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| status | `"loading" \| "success" \| "error"` | `"loading"` | Which indicator and default message the live region shows: `loading` spins and sets `aria-busy`, `success` shows a filled check, `error` a filled error glyph. Default copy per status comes from `SPINNER_STATUS_MESSAGES`. |
+| label | `boolean` | `true` | Shows text beside the indicator — `children` when supplied, otherwise the default message for `status`. With `label` false the same message becomes the root `aria-label` instead, and `size` starts applying. Avoid setting `aria-label` alongside a visible label; it duplicates the announcement. |
+| size | `number` | `SPINNER_ICON_ONLY_DEFAULT_PX` | Icon box in px, honoured only when `label` is false; values are clamped to 8–128. Omit it to inherit `--uxl-spinner-icon-box` from CSS or a parent. With a label the icon size follows the composed `Text` type instead. |
+| inheritColor | `boolean` | `false` | Drops the loading indicator's info color switcher so the parent's tokens supply its color — this is how the `Button` and `IconButton` loaders are styled. Standalone spinners should keep the switcher. |
+| children | `ReactNode` | `—` | Status label shown beside the indicator when `label` is true. When omitted, the default message for `status` is used. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Spinner>
+  {/* Content */}
+</Spinner>
+```
+
+## Notes
+
+- Uses a live region (`role="status"`, `aria-live`, `aria-busy` while loading); icons are `aria-hidden`. Use `aria-describedby` for related context — do not override `role`, `aria-live`, `aria-busy`, or `aria-atomic` via forwarded props (they’re applied last and are part of this component contract). While loading, disable the triggering control; this component does not add an overlay or manage focus. With `label` + **Text**, icon size follows the type’s line-height via a root modifier class (`.uxl-spinner--text-*`). With `label` false, pass `size` (px) or omit it so `--uxl-spinner-icon-box` from CSS / a parent applies.