@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/StatTile.md

@@ -0,0 +1,150 @@
+# StatTile
+
+Import: `import { StatTile } from "@uxelle/components";`
+
+Card-styled readout for a headline figure with a label, optional qualifier, info control, and trailing region.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| order | `"labelFirst" \| "valueFirst"` | `"labelFirst" as StatTileOrder` | Vertical order of the label row and the value row. |
+| label | `ReactNode` | `—` | Label in the label row. Occupies remaining width beside the info control. Pass a `string` (or `number`) to render with the default label typography (`Text type="Body Medium"`), or pass a `ReactNode` for full control. When you pass a `ReactNode` you own its accessibility: use meaningful text (not color or icon alone) and keep it non-interactive so it can name the group. |
+| value | `ReactNode` | `—` | Headline figure in the value row. Pass a `string` (or `number`) to render with the default value typography (`Text type="Display Medium"` as `<p>`), or pass a `ReactNode` for full control. A library `Text` node is rendered as `<p>` so a grid of StatTiles does not become a heading outline. When you pass any other `ReactNode`, make sure the figure reads as text and is not conveyed through color or an icon alone (WCAG 1.4.1). |
+| qualifier | `boolean` | `true` | When true, allows the qualifier to render when content is present. |
+| qualifierContent | `ReactNode` | `—` | Qualifier beside the value. Pass a `string` (or `number`) to render with the default qualifier typography (`Text type="Body Medium"`), or a `ReactNode` for full control. Only rendered when `qualifier` is true and content is present. When you pass a `ReactNode`, ensure it reads as text; do not rely on color alone to distinguish comparison periods. |
+| tooltipSlot | `boolean` | `true` | When true, allows the tooltip slot to render when content is present. |
+| tooltipContent | `ReactNode` | `—` | Info control at the end of the label row (typically `Tooltip` wrapping `IconButton`). Only rendered when `tooltipSlot` is true and content is present. Icon-only triggers within this slot must carry an accessible name via `aria-label` on the interactive element (e.g. `<IconButton aria-label="More information" />`). |
+| trailingSlot | `boolean` | `false` | When true, allows the trailing region to render when content is present. The slot accepts any content. |
+| trailingSlotContent | `ReactNode` | `—` | Trailing region. Open slot — any content is allowed (a delta `LabelBadge`, sparkline, action, or custom composition). Only rendered when `trailingSlot` is true and content is present. Because it is an open slot the component cannot guarantee its accessibility: this slot commonly holds a trend/delta indicator, so do not convey direction with color or an icon alone (WCAG 1.4.1) — include text (e.g. `"+25%"`) or an accessible name on the indicator, and give any interactive content a clear accessible name. |
+| fullWidth | `boolean` | `true` | When true, the root fills the parent width. When false, the root hugs its contents. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Label First (default) — string shorthand renders default typography
+<StatTile
+  label="Median first response time"
+  value="1d 12h"
+  qualifierContent="Last 7 days"
+  tooltipContent={
+    <Tooltip
+      direction="Top Right"
+      content={<Text type="Body Small">How this figure is calculated.</Text>}
+    >
+      <IconButton
+        emphasis="low"
+        size="extraSmall"
+        iconName="info"
+        aria-label="More information"
+      />
+    </Tooltip>
+  }
+/>
+```
+
+```tsx
+// Value First — named automatically from the label
+<StatTile
+  order="valueFirst"
+  trailingSlot
+  trailingSlotContent={
+    // Direction is carried by text ("25%"), not color/icon alone.
+    <LabelBadge label="25%" leadingIcon leadingIconName="arrow_upward_alt" data-color-switcher="success" />
+  }
+  label="Median first response time"
+  value="1d 12h"
+/>
+```
+
+```tsx
+// Value First without a label — supply an explicit accessible name
+<StatTile order="valueFirst" aria-label="Uptime, 99.9 percent" value="99.9%" />
+```
+
+```tsx
+// ReactNode override — caller owns accessibility (semantic element, text)
+<StatTile
+  label={<Text type="Body Medium" width={false}>Fill rate</Text>}
+  value={<Text type="Display Medium" as="p">94%</Text>}
+/>
+```
+
+```tsx
+// Polling dashboard — aria-live on the value announces only the change
+<StatTile
+  label="Active sessions"
+  value={<Text type="Display Medium" as="p" aria-live="polite">{count}</Text>}
+/>
+```
+
+```tsx
+// Hug contents instead of filling the parent
+<StatTile fullWidth={false} label="Uptime" value="99.9%" />
+```
+
+```tsx
+// Loading — replace the tile with a Skeleton that fills the same cell
+<SkeletonGroup loading={isLoading} aria-label="Loading median first response time">
+  {isLoading ? (
+    <Skeleton type="rectangle" size="large" />
+  ) : (
+    <StatTile label="Median first response time" value="1d 12h" />
+  )}
+</SkeletonGroup>
+```
+
+```tsx
+// Drill-through — destination lives in the trailing slot, not on the root
+<StatTile
+  label="Monthly revenue"
+  value="$1.24M"
+  trailingSlot
+  trailingSlotContent={<Link href="/reports/revenue">View report</Link>}
+/>
+```
+
+
+## Notes
+
+- Pass a `string` (or `number`) to `label`, `value`, and `qualifierContent` to
+- render with each region's default typography — no `Text` wrapper needed. Pass
+- a `ReactNode` instead when you need full control (e.g. truncation, a custom
+- element); in that case you own its accessibility (see each prop). A library
+- `Text` passed as `value` is rendered as `<p>`.
+- Pass a library `Tooltip` (typically wrapping `IconButton`) through
+- `tooltipContent`. Toggle regions with `qualifier`, `tooltipSlot`, and
+- `trailingSlot`; empty content is not rendered. `trailingSlotContent` is an
+- open slot — any content is allowed. Surface, elevation, radius, and
+- padding come from `Card`. StatTile is a standalone tile: place it next to
+- other StatTiles in a grid. Do not wrap it in `Card`. A figure inside a chart
+- card or table cell is a different surface — compose `Text` there.
+- **Accessibility.** The root is a `role="group"` region. It is named
+- automatically from `label` (via `aria-labelledby`), so the group is announced
+- with context in both orders — including `"valueFirst"`, where the value
+- precedes the label in the DOM. Supply your own `aria-label` or
+- `aria-labelledby` to override the derived name; this is **required** when
+- there is no `label` (e.g. `aria-label="Median first response time, 1 day 12
+- hours"`) so the figure is not announced without context. In development,
+- StatTile warns when content is present but the group has no name. The trailing
+- slot is open, so its accessibility is the caller's responsibility — see
+- `trailingSlotContent`.
+- **Navigation.** Do not put `onClick` on StatTile — the root is a named group,
+- not a control, and a wrapped link would nest interactives when a tooltip is
+- present. Put the destination in `trailingSlotContent` as a `Link` or
+- `IconButton`.
+- Set `order` to `"valueFirst"` to put the value row above the label row.
+- The root fills its parent by default (`fullWidth`). Set `fullWidth={false}`
+- to hug contents. Long label, value, and qualifier copy wrap inside the tile.
+- While data is loading, replace the tile with a `Skeleton` sized to the card
+- (full-width rectangle) inside `SkeletonGroup`. Do not pass a skeleton as
+- `value`.
+- For polling dashboards where the value updates in place, prefer putting
+- `aria-live="polite"` on the **value** node so only the changing figure is
+- announced (a root-level `aria-live` also works but re-announces the whole
+- group). When using a `string` `value`, wrap it yourself to place the live
+- region precisely.

package/skills/uxelle-components/Stepper.md

@@ -0,0 +1,73 @@
+# Stepper
+
+Import: `import { Stepper, StepperItem, STEPPER_AMOUNT_MIN } from "@uxelle/components";`
+
+Ordered step list for multi-step flows. Use **`steps`** with **`currentStep`**, or compose **`StepperItem`** children (children take precedence). **`amount`** generates placeholder ordinal copy for demos only.
+
+## Props — Stepper
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | Composed `StepperItem` children, which take precedence over `steps` and `amount`. Each item owns its own `status`, so `currentStep` is not applied to children. |
+| horizontal | `boolean` | `true` | When true, steps run in a row; when false, they stack against a vertical rail with the labels beside it. |
+| amount | `number` | `3` | Number of placeholder steps generated when neither `children` nor `steps` is set; the value is floored and clamped to at least `STEPPER_AMOUNT_MIN` (2). The generated ordinal copy is for demos — pass `steps` or `StepperItem` children in product UI. |
+| currentStep | `number` | `1` | 1-based index of the active step, which drives complete / current / upcoming status for `steps` and `amount`. Floored and clamped into range, and ignored once `StepperItem` children are supplied. |
+| showLabel | `boolean` | `true` | When false, only the indicator row renders — no titles or descriptions. Inherited by every `StepperItem` through context and overridable per item. |
+| interactive | `boolean` | `true` | When true, each indicator is a focusable `button` (or `a` when the step sets `href`) with hover and focus styling; when false, indicators are static progress markers outside the tab order. |
+| onStepClick | `(stepIndex: number) => void` | `—` | Called with the activated step's 1-based index when an interactive indicator is clicked or keyboard-activated. Skipped for disabled steps and when a per-item `onClick` calls `preventDefault()`. |
+| required | `boolean` | `false` | Default asterisk state for steps that do not set their own `required`, including composed `StepperItem` children. A per-step `required` always wins. |
+| steps | `StepperStepDefinition[]` | `—` | Declarative step definitions (**StepperStepDefinition**) — label, description, and optional `required` / `disabled` / `href`. Its length sets the step count and `currentStep` drives status; ignored when `children` is provided. |
+| statusLabels | `Partial<StepperStatusLabels>` | `—` | Localized fragments (**StepperStatusLabels**) appended to each step's accessible name for the completed, current, and required states. Merged over the English defaults, so partial objects are fine. |
+| className | `string` | `""` | Extra class names appended to the root `<ol>` after the built-in `uxl-stepper` layout classes. |
+
+<!-- prettier-ignore-end -->
+
+Extends `OlHTMLAttributes` — supports standard HTML attributes.
+
+## Props — StepperItem
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label (required) | `string` | `"Step"` | Step title, rendered as Body Medium Alt while labels are visible and always part of the indicator's accessible name. |
+| description | `string` | `""` | Supporting line under the title in Condensed type, also appended to the step's accessible name; omit it or pass an empty string to hide it. |
+| status | `"complete" \| "current" \| "upcoming"` | `"upcoming"` | Indicator state: `complete` shows a filled check and a high-emphasis connector, `current` shows a filled dot and sets `aria-current`, `upcoming` shows `stepIndex`. |
+| stepIndex | `number` | `1` | 1-based position: displayed inside an `upcoming` indicator and passed to the parent `Stepper` `onStepClick`. Derived from child order inside a `Stepper`, so set it only for standalone items. |
+| lastStep | `boolean` | `false` | When true, the connector after the indicator is omitted. Derived from child order inside a `Stepper`. |
+| layout | `StepperLayout` | `—` | Orientation for this step only, overriding the row / rail layout inherited from the parent `Stepper`. |
+| showLabel | `boolean` | `true` | Shows or hides this step's title and description, overriding the parent `Stepper` `showLabel`. |
+| required | `boolean` | `false` | When true, an asterisk precedes the title and “required” joins the accessible name; overrides the parent `Stepper` `required` default. |
+| disabled | `boolean` | `false` | Blocks activation of this step's indicator while the parent `Stepper` is interactive, so `onStepClick` does not fire; a link step also drops its `href` and tab stop. |
+| href | `string` | `""` | Renders the interactive indicator as an `a` pointing here instead of a `button`. Applies only while the parent `Stepper` is interactive; an empty string keeps the button. |
+| onClick | `MouseEventHandler<HTMLButtonElement \| HTMLAnchorElement>` | `—` | Fired when the interactive indicator is activated, before the parent `Stepper` `onStepClick`. Call `preventDefault()` to stop `onStepClick` from running. |
+| anchorProps | `Omit< AnchorHTMLAttributes<HTMLAnchorElement>, "href" \| "onClick" \| "children" >` | `—` | Extra anchor attributes (e.g. `target`, `rel`) merged onto the link rendered for `href`; ignored on button steps. |
+| className | `string` | `""` | Extra class names appended to the `<li>` after the built-in `uxl-stepper-item` status classes. |
+
+<!-- prettier-ignore-end -->
+
+
+## Usage
+
+```tsx
+<Stepper
+  steps={[
+    { label: "Shipping", description: "Address" },
+    { label: "Payment", description: "Card" },
+    { label: "Review", description: "Confirm" },
+  ]}
+  currentStep={2}
+  aria-label="Checkout"
+  onStepClick={(step) => setStep(step)}
+/>
+```
+
+
+## Notes
+
+- Renders as an ordered list (`<ol>`). Prefer wrapping in `<nav aria-label="…">` when the stepper is a page landmark. Pass **`aria-label`** / **`aria-labelledby`** on the root when it is not inside a labeled `nav`.
+- **Interactive** (default): each indicator is a native `<button>` (or `<a>` when **`href`** is set) in the tab order with a `:focus-visible` ring. Use **`onStepClick`** (1-based) or per-item **`onClick`**. Set **`interactive={false}`** for progress-only UI.
+- **`statusLabels`**: localize “completed” / “current” / “required” in accessible names.
+- **`stepIndex`** / **`lastStep`** are derived from child order when omitted.

package/skills/uxelle-components/Switch.md

@@ -0,0 +1,41 @@
+# Switch
+
+Import: `import { Switch } from "@uxelle/components";`
+
+Toggle switch using design tokens. Renders a native checkbox with `role="switch"` for forms and assistive technologies.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| checked | `boolean` | `—` | On/off state when controlled. Pass it with `onChange` to drive the switch from app state; omit it and the switch tracks its own state from `defaultChecked`. |
+| defaultChecked | `boolean` | `false` | Starting on/off state when `checked` is omitted. Unusually for a `default*` prop, changing it later re-syncs the uncontrolled state; it is ignored entirely while `checked` is set. |
+| disabled | `boolean` | `false` | Blocks toggling and applies disabled styling. The underlying input is disabled, so its value is left out of form submission. |
+| embedded | `boolean` | `false` | Turns the switch into a display-only indicator: `pointer-events: none`, `tabIndex={-1}`, and no hover/active/focus ring, so an enclosing row or cell owns pointer and focus. That parent must then supply the accessible name. |
+| label | `boolean` | `true` | Renders `children` beside the track as the switch's visible name. With `false` there is no visible name, so set `aria-label` or `aria-labelledby` on the component or the switch is left unnamed. |
+| onChange | `ChangeEventHandler<HTMLInputElement>` | `—` | Fires on every toggle with the native change event; read the new state from `event.target.checked`. Required in controlled mode to keep `checked` in sync. |
+| name | `string` | `—` | Form field name on the underlying checkbox input. Without it the switch submits no value. |
+| value | `string` | `—` | Value submitted alongside `name` while the switch is on. Browsers fall back to `on` when omitted. |
+| form | `string` | `—` | `id` of the form this switch belongs to, for when it renders outside that form's markup. |
+| required | `boolean` | `—` | Marks the underlying input required, so native validation blocks submission while the switch is off. |
+| children | `ReactNode` | `—` | Label content to the right of the track, usually a `Text` node; the wrapping `label` element makes it the switch's accessible name. Not rendered when `label` is `false` — set `aria-label` instead. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Switch defaultChecked>
+  <Text type="Body Medium" width>Notifications</Text>
+</Switch>
+```
+
+
+## Notes
+
+- Optional `children` render as label text to the right of the track.
+- **Accessibility**: Provide a visible label (`children`) or an accessible name with `aria-label` / `aria-labelledby`. Control ARIA (`aria-invalid`, `aria-errormessage`, `aria-describedby`, `aria-required`) is applied to the `role="switch"` input, not the wrapping label. Keyboard: Space toggles when the input is focused. **`embedded`** uses **`tabIndex={-1}`**.
+- **Embedded**: When `embedded` is set, the switch is removed from the tab order (`tabIndex={-1}`), does not draw its own focus ring, and uses **`pointer-events: none`** so the parent row or cell owns pointer and focus; that parent should expose a single clear `:focus-visible` indicator.
+- **Controlled**: Pass `checked` and `onChange`; omit `defaultChecked`.

package/skills/uxelle-components/Tab.md

@@ -0,0 +1,41 @@
+# Tab
+
+Import: `import { Tab } from "@uxelle/components";`
+
+Selectable control that switches between panels in a tabbed interface.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label (required) | `string` | `"Tab 1"` | Visible text naming the panel this tab switches to. Rendered with `Text`, so keep it to a couple of words; add `aria-label` when the panel needs a fuller name. |
+| activated | `boolean` | `false` | Marks this tab as the selected one: sets `aria-selected`, applies the activated styling, and makes it the single tab-order stop. `TabsCompact` / `TabsStretch` set it from their own selection state, so pass it only on a standalone `Tab`. |
+| fullWidth | `boolean` | `false` | Switches to full-width spacing tokens and lets the tab grow to fill its share of the row. `TabsStretch` sets it for every tab. |
+| leadingSlot | `boolean` | `false` | Reveals the region before the label. With no `leading` content, the `leadingIconName` icon fills it. |
+| trailingSlot | `boolean` | `false` | Reveals the region after the label. With no `trailing` content, the `trailingIconName` icon fills it. |
+| leading | `ReactNode` | `—` | Custom content for the region before the label, replacing the default icon. Rendered only when `leadingSlot` is true. |
+| trailing | `ReactNode` | `—` | Custom content for the region after the label, replacing the default icon. Rendered only when `trailingSlot` is true. |
+| leadingIconName | `string` | `"add"` | Material Symbol drawn in the leading region when `leadingSlot` is on and no `leading` content is supplied. |
+| trailingIconName | `string` | `"add"` | Material Symbol drawn in the trailing region when `trailingSlot` is on and no `trailing` content is supplied. |
+| leadingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the default leading icon: `sharpFilled` solid, `sharpUnfilled` outlined. |
+| trailingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the default trailing icon: `sharpFilled` solid, `sharpUnfilled` outlined. |
+| textWidth | `boolean` | `true` | When true the label shrinks to its text; when false it fills the tab so the text centres. `TabsStretch` sets it to false for its equal-width tabs. |
+| "aria-label" | `string` | `""` | Accessible name that replaces `label` for assistive technology; use it when the visible label is too terse to identify the panel. Blank strings are dropped. |
+| "aria-controls" | `string` | `""` | Id of the `tabpanel` this tab controls. Set it only when you render panels yourself — `TabsCompact` / `TabsStretch` wire their own `panel` / `panels` content automatically. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Tab label="…">
+  {/* Content */}
+</Tab>
+```
+
+## Notes
+
+- The visible label uses `Text` `type="Body Medium"` when inactive and `type="Body Medium Alt"` when activated.
+- **Slots**: `leading` / `trailing` accept any composable content; `leadingSlot` / `trailingSlot` show the side regions. When a slot is on and no custom content is passed, the default Material Symbol icon (`add`) is shown — same pattern as ListItem and Textfield.

package/skills/uxelle-components/Table.md

@@ -0,0 +1,55 @@
+# Table
+
+Import: `import { Table } from "@uxelle/components";`
+
+Composable table shell and semantic grid for tabular data. Columns support resize, reorder, and sort; horizontal scroll activates when widths exceed the container.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| topSlot | `ReactNode` | `—` | Band rendered above the table and outside its horizontal scrollport — typically a title, toolbar, filters, or search. Omitted entirely when unset. |
+| bottomSlot | `ReactNode` | `—` | Band rendered below the table and outside its horizontal scrollport — typically pagination or bulk actions. Omitted entirely when unset. |
+| tableSlot | `ReactNode` | `—` | The table itself: one **TableGrid** with its head, body, rows, and cells, placed in the scroll region that drives the horizontal scroll hint. Same slot as `children`, and it wins when both are passed. |
+| children | `ReactNode` | `—` | Alias for `tableSlot`, ignored when `tableSlot` is also passed. Compose one `TableGrid` (give it `aria-label` and `gridTemplateColumns`) holding a `TableHead` with a `TableRow` of `TableHeaderCell` children, then a `TableBody` with one `TableRow` of `TableCell` children per record — all exported from `@uxelle/components`. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+const columns = [
+  { flex: 0.5, minWidth: 48 },
+  { flex: 1, minWidth: 120 },
+] as const;
+
+function OrdersGrid() {
+  const columnOrder = useColumnOrder() ?? [0, 1];
+  const gridTemplateColumns =
+    useColumnGridTemplate(columnOrder) ?? tableColumnTracksTemplate(columns);
+  return (
+    <TableGrid aria-label="Orders" gridTemplateColumns={gridTemplateColumns}>
+      …
+    </TableGrid>
+  );
+}
+
+<Table
+  tableSlot={
+    <TableColumnSizingProvider columns={columns}>
+      <OrdersGrid />
+    </TableColumnSizingProvider>
+  }
+/>
+```
+
+
+## Notes
+
+- Optional top and bottom slots frame the table region; a horizontal scroll hint appears when the grid is wider than its container. Fixed columns are implemented as sticky cells inside one `TableGrid`—not as a separate grid—so each row stays a single unit for assistive technology. Use **TableColumnPinProvider** or `pinned="start"` on **TableHeaderCell** and **TableCell** with **usePinnedStartOffsets** to keep leading columns visible during horizontal scroll.
+- Horizontal scroll and the trailing-edge hint appear automatically when content overflows the container. Define column proportions with **TableColumnSizingProvider** and **useColumnGridTemplate**.
+- Layout is left-to-right only; right-to-left document direction is not supported yet.

package/skills/uxelle-components/TabsCompact.md

@@ -0,0 +1,37 @@
+# TabsCompact
+
+Import: `import { TabsCompact, Tab } from "@uxelle/components";`
+
+Tabs sized to their content width, with optional scroll controls when they overflow.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | `Tab` elements in display order — the normal way to build a tab list. Selection, ids, and `aria-controls` are injected into each one. Omit them only to fall back to the placeholder tabs generated from `amount`. |
+| amount | `number` | `7` | Tab count, clamped to 2–8. Without `children` it generates that many placeholder tabs labelled from `tabLabels` (or `Tab 1`…`Tab N`) for previews; with real `Tab` children — preferred in product code — it only caps how many of them render. |
+| tabLabels | `string[]` | `—` | Labels for the tabs generated by `amount`, indexed in order; missing entries fall back to `Tab 1`, `Tab 2`, … Ignored once `children` are supplied. |
+| panel | `ReactNode` | `—` | One body rendered below the tab list and reused for every tab. Passing this (or `panels`) is what creates the `tabpanel` and its `aria-controls` wiring. |
+| panels | `ReactNode[]` | `—` | Body content per tab, indexed in tab order. Takes precedence over `panel`; inactive panels stay mounted with `hidden`. |
+| activeTab | `number` | `undefined` | Selected tab as a 1-based index, clamped to the tab count. Pass it with `onChange` to control selection; omit it to let the group track its own from `defaultActiveTab`. |
+| defaultActiveTab | `number` | `1` | Selected tab as a 1-based index on first render only; later changes are ignored. Use it for uncontrolled selection — pair `activeTab` with `onChange` to drive it. |
+| onChange | `(activeTab: number) => void` | `—` | Called with the newly selected tab's 1-based index on click or arrow-key navigation. Required to react to selection when `activeTab` is controlled. |
+| scrollLeft | `boolean` | `false` | Shows a chevron control before the tablist that scrolls it left by roughly three-quarters of its visible width. `compact` layouts only. |
+| scrollRight | `boolean` | `false` | Shows a chevron control after the tablist that scrolls it right by roughly three-quarters of its visible width. `compact` layouts only. |
+| "aria-label" | `string` | `—` | Accessible name for the tablist. Set this or `aria-labelledby` — development builds warn when neither is present, and an unnamed tablist is ambiguous once a page has more than one. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<TabsCompact>
+  {/* Content */}
+</TabsCompact>
+```
+
+## Notes
+
+- Renders `TabGroup` with `variant="compact"`. Scroll controls appear when tabs exceed the container width. Use **TabsStretch** when tabs should share width equally. Tab and panel ids are unique per instance. Pass `aria-label` or `aria-labelledby` so the tablist has an accessible name, especially when more than one tablist is on the page.

package/skills/uxelle-components/TabsStretch.md

@@ -0,0 +1,35 @@
+# TabsStretch
+
+Import: `import { TabsStretch, Tab } from "@uxelle/components";`
+
+Equal-width tabs that stretch to fill the available space; no scroll controls.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | `Tab` elements in display order — the normal way to build a tab list. Selection, ids, and `aria-controls` are injected into each one. Omit them only to fall back to the placeholder tabs generated from `amount`. |
+| amount | `number` | `7` | Tab count, clamped to 2–8. Without `children` it generates that many placeholder tabs labelled from `tabLabels` (or `Tab 1`…`Tab N`) for previews; with real `Tab` children — preferred in product code — it only caps how many of them render. |
+| tabLabels | `string[]` | `—` | Labels for the tabs generated by `amount`, indexed in order; missing entries fall back to `Tab 1`, `Tab 2`, … Ignored once `children` are supplied. |
+| panel | `ReactNode` | `—` | One body rendered below the tab list and reused for every tab. Passing this (or `panels`) is what creates the `tabpanel` and its `aria-controls` wiring. |
+| panels | `ReactNode[]` | `—` | Body content per tab, indexed in tab order. Takes precedence over `panel`; inactive panels stay mounted with `hidden`. |
+| activeTab | `number` | `undefined` | Selected tab as a 1-based index, clamped to the tab count. Pass it with `onChange` to control selection; omit it to let the group track its own from `defaultActiveTab`. |
+| defaultActiveTab | `number` | `1` | Selected tab as a 1-based index on first render only; later changes are ignored. Use it for uncontrolled selection — pair `activeTab` with `onChange` to drive it. |
+| onChange | `(activeTab: number) => void` | `—` | Called with the newly selected tab's 1-based index on click or arrow-key navigation. Required to react to selection when `activeTab` is controlled. |
+| "aria-label" | `string` | `—` | Accessible name for the tablist. Set this or `aria-labelledby` — development builds warn when neither is present, and an unnamed tablist is ambiguous once a page has more than one. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<TabsStretch>
+  {/* Content */}
+</TabsStretch>
+```
+
+## Notes
+
+- Renders `TabGroup` with `variant="stretch"` so each tab shares width equally. Use **TabsCompact** when tabs should size to their content. Tab and panel ids are unique per instance. Pass `aria-label` or `aria-labelledby` so the tablist has an accessible name, especially when more than one tablist is on the page.

package/skills/uxelle-components/Text.md

@@ -0,0 +1,56 @@
+# Text
+
+Import: `import { Text } from "@uxelle/components";`
+
+Typographic primitive for rendering text with variant styles and responsive sizing.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| type (required) | `TextType` | `"Body Medium"` | Type ramp entry applied to the text: it sets the font family, size, weight, line height, and letter spacing, and picks the default element when `as` is omitted. The full set of values is exported as **TEXT_TYPES** — Display, Component, Body, Condensed, Overline, Button, Link, and Navigation Link entries. |
+| width | `boolean` | `true` | When true the text box hugs its content; when false it spans the full width of its container, which is what lets long copy wrap or `truncation` clip to a stable width. |
+| children (required) | `ReactNode` | `—` | Text to render inside the styled element — a string, or inline nodes such as a `Link` or emphasis markup. Omit it when `as` is `\"input\"`, which renders no children. |
+| as | `TextAsTag \| "input"` | `—` | Element tag to render. Omit it for a semantic default derived from `type` — `h1`, `h2`, `h3` for Display Large, Medium, and Small, `p` for Body and Component types, and `span` for everything else. Pass `"input"` to switch to input mode, which renders a native input styled with the same type ramp. |
+| role | `string` | `—` | ARIA role placed on the rendered text element itself, not the wrapper. Set it only to override the implicit role of the tag `as` produces, for example `heading` on a `span`. |
+| "aria-label" | `string` | `—` | Accessible name for the rendered text element, for when the visible characters are not meaningful on their own. `Overline` and `Overline Alt` fall back to their string content as a name when neither this nor `aria-hidden` is set. |
+| "aria-describedby" | `string` | `—` | Space-separated ids of elements that describe this text; applied to the rendered text element rather than the wrapper. |
+| "aria-hidden" | `boolean` | `—` | When true, removes the text from the accessibility tree. Use it for decorative copy, or copy a labelled parent already announces, so it is not read twice. |
+| truncation | `boolean` | `false` | Clips overflow to a single line ending in an ellipsis instead of wrapping. Needs a bounded width, so pair it with `width={false}` or a sized parent. |
+| uppercase | `boolean` | `—` | Forces `text-transform`: true uppercases the text, false cancels an inherited uppercase style. Omit it to leave the transform to the type ramp (Button applies the theme's uppercase prop-control to its own label only). |
+| inline | `boolean` | `false` | Renders the wrapper inline instead of as its own block, so the text can sit inside a sentence or in another component's row (for example `FieldMessage`). |
+| className | `string` | `—` | Classes merged onto the outer wrapper element; the inner text element keeps its own type ramp classes. |
+| inputClassName | `string` | `—` | Classes merged onto the `input` element alongside its type ramp classes. Applies only in input mode. |
+| inputHtmlType | `HTMLInputElement["type"]` | `"text"` | Value for the native `type` attribute on the input, such as `email` or `password`. `type` stays the type ramp entry. |
+
+<!-- prettier-ignore-end -->
+
+## TextType values
+
+- **Display**: `"Display Large"`, `"Display Medium"`, `"Display Small"`, `"Display Extra Small"`
+- **Component**: `"Component Medium"`, `"Component Medium Alt"`
+- **Body**: `"Body Medium"`, `"Body Medium Alt"`, `"Body Small"`, `"Body Small Alt"`
+- **Condensed**: `"Condensed"`, `"Condensed Alt"`
+- **Overline**: `"Overline"`, `"Overline Alt"`
+- **Button**: `"Button"`
+
+
+## Usage
+
+```tsx
+// Display heading
+<Text type="Display Large">Main Heading</Text>
+```
+
+```tsx
+// Body text with full width
+<Text type="Body Medium" width={false}>This is body text that wraps to full width</Text>
+```
+
+```tsx
+// Native input with Body Small (e.g. Textfield — long values scroll in the field wrapper, not ellipsis)
+<Text type="Body Small" as="input" width inputHtmlType="email" />
+```
+

package/skills/uxelle-components/Textarea.md

@@ -0,0 +1,77 @@
+# Textarea
+
+Import: `import { Textarea } from "@uxelle/components";`
+
+Multi-line text input with a label, optional helper copy, validation message, character counter, and CSS-driven height.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `boolean` | `true` | Show label row (Label + Text) |
+| labelText | `string` | `"Label"` | Label text (Body Medium Alt); ignored if labelSlot is set |
+| labelSlot | `ReactNode` | `—` | Composable label: replaces the default `Text` inside `Label` while keeping `htmlFor` / `required` / `fieldDescription` on `Label`. Pass `id` on `Textarea` when you need a stable association. |
+| fieldDescription | `string` | `""` | Helper text below the label; associated with the textarea via aria-describedby |
+| required | `boolean` | `false` | Required field (asterisk on Label, native required on the textarea) |
+| fieldMessage | `boolean` | `false` | Show field message row (also shown automatically when validation is success or error, or when soft overflow is over the limit and softOverflowMessage is set) |
+| fieldMessageContent | `string` | `""` | Message when fieldMessage is true (optional; else defaults by validation) |
+| validation | `"none" \| "success" \| "error"` | `"none" as TextareaValidation` | Field message and validation state |
+| height | `string` | `""` | Explicit field height (px number or CSS length). Overrides rows when set |
+| maxHeight | `string` | `""` | Maximum height while resizing or auto-growing (px number or CSS length) |
+| resize | `"vertical" \| "none"` | `"vertical" as TextareaResize` | Height-only resize; width never changes. Forced to none when disabled, read-only, or autoGrow |
+| counter | `boolean` | `false` | Show character count (requires maxLength) |
+| autoGrow | `boolean` | `false` | Grow height with content; rows/height are the minimum, maxHeight caps. Forces resize none |
+| softOverflow | `boolean` | `false` | Allow typing past maxLength; warning color-switcher on the counter when over the limit. Pass softOverflowMessage for warning FieldMessage copy |
+| softOverflowMessage | `string` | `""` | Warning FieldMessage when softOverflow content exceeds maxLength; omit for chrome only |
+| placeholder | `string` | `""` | Native textarea placeholder |
+| disabled | `boolean` | `false` | Disabled state |
+| readOnly | `boolean` | `false` | Read-only state (token background, no hover, no resize; focus uses the focus stroke) |
+| rows | `number` | `4` | Visible line count used for min-height (overridden by height; minimum when autoGrow) |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Textarea labelText="Comments" placeholder="Enter details" rows={4} />
+```
+
+```tsx
+<Textarea
+  labelText="Bio"
+  fieldDescription="Shown on your public profile."
+  required
+  autoGrow
+  counter
+  softOverflow
+  softOverflowMessage="Stay under the recommended limit."
+  maxLength={100}
+/>
+```
+
+
+## Notes
+
+- Associates label, field description, field message, and character count with
+- the native textarea for accessibility. Height comes from `rows` (line-height
+- calc) or an explicit `height`. `autoGrow` sizes the field to its content
+- (capped by `maxHeight`). Native attributes (`id`, `name`, `maxLength`,
+- `aria-*`) apply to the textarea; `className` applies to the root.
+- **Simple API** — `labelText`, `fieldDescription`, `placeholder`, `rows`,
+- `counter` + `maxLength`, optional `autoGrow` / `softOverflow` /
+- `softOverflowMessage`. Use `Textfield` for single-line values (email, search,
+- password).
+- **Label and message** — `label` and `fieldMessage` are visibility flags with
+- `labelText` and `fieldMessageContent` (same pattern as Textfield). Default
+- `labelText` is `"Label"` so the control has an accessible name. Set
+- `label={false}` and pass `aria-label` (or `aria-labelledby`) to hide the row.
+- **Composable API** — `labelSlot` replaces the default `Text` inside `Label`.
+- **Accessibility** — Pass `id` for stable `label` association. `fieldDescription`
+- is linked with `aria-describedby` and stays available during errors.
+- `required` shows the Label asterisk and native textarea `required`. Pass
+- `aria-label` when `label={false}` (placeholder is not a name). Keyboard users
+- scroll overflowing text; resize is pointer-only. Soft overflow paints the
+- counter and field stroke as warning; pass `softOverflowMessage` for a warning
+- `FieldMessage`. Overflow is not `aria-invalid`.