@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/ChoiceChipGroup.md

@@ -0,0 +1,50 @@
+# ChoiceChipGroup
+
+Import: `import { ChoiceChipGroup } from "@uxelle/components";`
+
+Groups choice toggles under an optional legend, wrapping to new rows as needed.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | **ChoiceChip** elements only. They render in a wrapping row inside the fieldset, above `fieldMessage`. |
+| label | `boolean` | `true` | Renders a `legend` naming the group when `true` and `labelText` is non-empty. When `false`, name the group with `aria-label` or `aria-labelledby` instead. |
+| labelText | `string` | `"Options"` | Text shown in the `legend` while `label` is `true`. It is trimmed first, so a blank string suppresses the legend and the group then needs `aria-label`. |
+| fieldMessage | `ReactNode` | `—` | Validation or helper content rendered below the chips. A string or number is wrapped in **FieldMessage** using `fieldMessageType`; any other node renders as-is. When `invalid` is true, a Danger field message is shown (this value when provided, otherwise a default error string). |
+| fieldMessageType | `"Info" \| "Danger" \| "Warning" \| "Success"` | `CHOICE_CHIP_GROUP_DEFAULTS.fieldMessageType` | Tone of the wrapped **FieldMessage** — `Info`, `Danger`, `Warning`, or `Success`. Forced to `Danger` while `invalid` is true. `Danger` wires the message as `aria-errormessage` and announces it politely; other tones link through `aria-describedby`. |
+| required | `boolean` | `false` | Sets `aria-required` on the fieldset and shows the **Label** asterisk while a legend is visible. No native validation is enforced — the app owns that. |
+| 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. `aria-invalid={true}` does the same; `false` is treated as omitted so this prop can still apply. |
+| role | `string` | `"group"` | ARIA role on the fieldset. Keep `group` for independent toggles; switch to `radiogroup` only when the app enforces exclusive selection and the chips carry matching roles. |
+| "aria-label" | `string` | `""` | Accessible name for the fieldset, used only when no legend is showing. Prefer a visible legend via `label` and `labelText`; this value is dropped while one renders. |
+| "aria-labelledby" | `string` | `""` | IDs of elements that name the fieldset when no legend renders, space-separated. Dropped while a legend is showing, since the legend already names the group. |
+| "aria-describedby" | `string` | `""` | IDs of elements describing the group, space-separated. Merged with the field-message region id for non-`Danger` messages rather than replacing it. |
+| "aria-errormessage" | `string` | `""` | ID of the element holding the error text. Defaults to the field-message region once the resolved message type is Danger, and is only announced while the group is also invalid. An empty string is treated as omitted so that default still applies. |
+| "aria-invalid" | `boolean` | `false` | Explicit `aria-invalid` on the fieldset. `true` marks the group invalid and triggers the Danger field message; `false` is treated as omitted so `invalid` can still apply. A `Danger` field message alone does not mark the group invalid. |
+| "aria-required" | `boolean` | `false` | Explicit `aria-required` on the fieldset. `true` marks a selection mandatory; `false` is treated as omitted so `required` can still apply. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<ChoiceChipGroup label labelText="Sort by">
+  <ChoiceChip label="Relevance" onChange={() => {}} />
+  <ChoiceChip label="Newest" checked onChange={() => {}} />
+</ChoiceChipGroup>
+```
+
+```tsx
+// Exclusive single-select (app-owned)
+<ChoiceChipGroup label labelText="Sort by" role="radiogroup">
+  <ChoiceChip label="Relevance" checked onChange={() => {}} />
+  <ChoiceChip label="Newest" onChange={() => {}} />
+</ChoiceChipGroup>
+```
+
+
+## Notes
+
+- Pass **ChoiceChip** children. Root is a **`fieldset`** with default **`role="group"`**; name it with the legend (`label` + `labelText`) or `aria-label` / `aria-labelledby`. Selection policy (single vs multi) is app-owned — this group does not enforce exclusivity. Keep **`role="group"`** for independent toggles. For exclusive single-select, keep one checked value in app state and set **`role="radiogroup"`** on the group. Form parity: **`fieldMessage`**, **`required`**, **`invalid`**, and merged **`aria-describedby`** / **`aria-errormessage`**. For dismissible applied filters, use **FilterChipGroup**. There is no InputChip — compose entry (e.g. Textfield) with FilterChips for removable values.

package/skills/uxelle-components/DatePicker.md

@@ -0,0 +1,59 @@
+# DatePicker
+
+Import: `import { DatePicker } from "@uxelle/components";`
+
+Form control for choosing a single calendar date by typing or from a month grid.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `boolean` | `true` | Renders the label row above the field. Set it false for a bare field, and then pass `aria-label` so the combobox still has an accessible name. |
+| labelText | `string` | `"Select a date"` | Visible label rendered as `Text` (Body Medium Alt) inside `Label`, and the element that names the combobox. An empty string drops the label row entirely. |
+| labelSlot | `ReactNode` | `—` | Custom label content replacing the default `Text`, while `Label` keeps `htmlFor` and the `required` asterisk. Use it for links or badges beside the label copy. |
+| fieldDescription | `string` | `""` | Supporting copy below the label (Condensed text), wired to the combobox through `aria-describedby`. Rendered only while the label row is visible. |
+| fieldMessage | `boolean` | `false` | Shows the message row below the field so helper copy is always visible. The row also appears on its own whenever `validation` is `error`. |
+| fieldMessageContent | `string` | `""` | Message text for the row. Falls back to `Enter a valid date.` when `validation` is `error`, or to generic helper copy otherwise; a rejected typed date overrides it with a locale format hint. |
+| validation | `"none" \| "error"` | `"none"` | Validation state of the field. `error` turns the message row into a Danger `FieldMessage` and sets `aria-invalid` / `aria-errormessage`; only `none` and `error` are supported. |
+| placeholder | `string` | `""` | Hint text shown in the field while no date is selected. |
+| value | `string` | `""` | Selected date as `YYYY-MM-DD`, controlled whenever the prop is present. Use `null` or `""` for empty; strings that are not valid ISO dates read as empty. |
+| defaultValue | `string \| null` | `—` | Starting date as `YYYY-MM-DD` while `value` is omitted, after which the component owns the selection. |
+| onChange | `(value: string \| null) => void` | `—` | Called with the committed date as `YYYY-MM-DD`, or `null` when the field is cleared or the picked date fails the availability rules. |
+| open | `boolean` | `—` | Controlled open state of the calendar. Pass with `onOpenChange`; omit to let the component manage its own. |
+| defaultOpen | `boolean` | `false` | Whether the calendar starts open while `open` is omitted. |
+| onOpenChange | `(open: boolean) => void` | `—` | Called with the next open state whenever the calendar opens or closes. |
+| readOnly | `boolean` | `false` | Keeps the formatted date visible but blocks editing: the calendar cannot open and the chevron is not rendered. Use `disabled` instead when the field is inactive. |
+| required | `boolean` | `false` | Marks the field as required — asterisk on `Label`, plus `required` and `aria-required` on the combobox. It does not block submission on its own. |
+| minDate | `string` | `""` | Earliest selectable date (`YYYY-MM-DD`). Earlier days are disabled, month navigation stops there, and an earlier typed date is rejected as invalid. |
+| maxDate | `string` | `""` | Latest selectable date (`YYYY-MM-DD`). Later days are disabled, month navigation stops there, and a later typed date is rejected as invalid. |
+| unavailableDates | `readonly string[] \| null` | `—` | ISO dates (`YYYY-MM-DD`) that cannot be selected. Combined with `isDateUnavailable` and `minDate` / `maxDate`. |
+| isDateUnavailable | `(iso: string) => boolean` | `—` | Return true to disable that calendar day. Receives an ISO date-only string. Combined with `unavailableDates` and `minDate` / `maxDate`. |
+| locale | `string` | `"en-US"` | BCP 47 tag driving the displayed date format, the field order accepted when typing, weekday labels, and which day starts the week. ISO input is always accepted regardless. |
+| today | `string \| null` | `—` | Overrides the date marked as today and the month opened when nothing is selected (`YYYY-MM-DD`). Pin it for deterministic tests and snapshots. |
+| datePickerSlot | `ReactNode` | `—` | Replaces the whole built-in calendar panel, month navigation included, so `previousMonthAriaLabel` / `nextMonthAriaLabel` no longer apply. Omit it to use the month grid. |
+| previousMonthAriaLabel | `string` | `"Previous month"` | Accessible name for the previous-month button. Defaults to English, so pass a translated string in localized apps. |
+| nextMonthAriaLabel | `string` | `"Next month"` | Accessible name for the next-month button. Defaults to English, so pass a translated string in localized apps. |
+| name | `string` | `—` | Form field name for a hidden input carrying the ISO date. The input is omitted while nothing is selected or a typed draft is still invalid. |
+| disabled | `boolean` | `false` | Blocks all interaction and applies disabled styling: the field cannot be typed in and the calendar cannot open. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<DatePicker labelText="Start date" value={date} onChange={setDate} locale="en-US" />
+```
+
+
+## Notes
+
+- **Value** — `onChange` receives an ISO date-only string (`YYYY-MM-DD`) or `null`. Display and typed input follow `locale` (week start included). Paste also accepts ISO. Month names and other non-numeric text are not parsed: the typed value stays, the field is marked invalid, and a locale format hint is shown (for example `Enter a date as MM/DD/YYYY.`). Hidden form values are omitted while the draft is invalid.
+- **Calendar** — Opens from the field; **Escape** or clicking outside closes it. Choosing a date commits and closes. Days outside the current month are shown but not selectable.
+- **Accessibility**: Visible label uses `<Label htmlFor>`; the combobox name uses `aria-labelledby` on the label text. `required` shows the Label asterisk and sets `aria-required` on the combobox. `FieldMessage` uses `aria-describedby` (info) or `aria-errormessage` (error). Pass `id` for stable ids; use `aria-label` when `label={false}`. `autoComplete` defaults to `off` so browser date autofill does not fight the calendar; pass `bday` (or another HTML token) when the field collects a known personal date.
+- **Keyboard**: **Tab** focuses the text field so a locale-formatted date can be typed (**Enter** commits). Dates in the calendar are not separate tab stops. **ArrowDown** opens the calendar and moves focus into the month grid; arrows move by day/week; **Home** / **End** move to the start/end of the week; **PageUp** / **PageDown** move the focused date by one month (same day, clamped); **Shift+PageUp** / **Shift+PageDown** move by one year. **Escape** (from the field or the grid) closes and returns focus to the field.
+- **Trigger**: The visible chevron is presentational (`aria-hidden`, `tabIndex={-1}`); the combobox owns `aria-haspopup`.
+- **Limits**: Selectable dates are gated with `minDate` / `maxDate`, `unavailableDates`, and `isDateUnavailable`. Those rules disable `DatePickerDate` cells. `validation` supports `none` and `error` only.
+- **Copy**: `previousMonthAriaLabel` / `nextMonthAriaLabel` default to English so the host app can pass translated strings. Month titles, weekdays, and typed values follow `locale`.
+- **Forms**: With `name`, a hidden input posts the ISO date; it is omitted when empty or the typed draft is invalid.

package/skills/uxelle-components/DatePickerRange.md

@@ -0,0 +1,73 @@
+# DatePickerRange
+
+Import: `import { DatePickerRange } from "@uxelle/components";`
+
+Form control for choosing a start and end calendar date by typing or from a month grid.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `boolean` | `true` | Renders the label row above the field. Set it false for a bare field, and then pass `aria-label` so the combobox still has an accessible name. |
+| labelText | `string` | `"Select your date range"` | Visible label rendered as `Text` (Body Medium Alt) inside `Label`, and the element that names the combobox. An empty string drops the label row entirely. |
+| labelSlot | `ReactNode` | `—` | Custom label content replacing the default `Text`, while `Label` keeps `htmlFor` and the `required` asterisk. Use it for links or badges beside the label copy. |
+| fieldDescription | `string` | `""` | Supporting copy below the label (Condensed text), wired to the combobox through `aria-describedby`. Rendered only while the label row is visible. |
+| fieldMessage | `boolean` | `false` | Shows the message row below the field so helper copy is always visible. The row also appears on its own whenever `validation` is `error`. |
+| fieldMessageContent | `string` | `""` | Message text for the row. Falls back to `Enter a valid date range.` when `validation` is `error`, or to generic helper copy otherwise; a rejected typed range overrides it with a locale format hint. |
+| validation | `"none" \| "error"` | `"none"` | Validation state of the field. `error` turns the message row into a Danger `FieldMessage` and sets `aria-invalid` / `aria-errormessage`; only `none` and `error` are supported. |
+| placeholder | `string` | `""` | Hint text shown in the field while no range is selected. |
+| start | `string` | `""` | Range start as `YYYY-MM-DD`, controlled whenever the prop is present and independent of `end`. Use `null` or `""` for empty; strings that are not valid ISO dates read as empty. |
+| end | `string` | `""` | Range end as `YYYY-MM-DD`, controlled whenever the prop is present and independent of `start`. Use `null` or `""` for empty; strings that are not valid ISO dates read as empty. |
+| defaultStart | `string \| null` | `—` | Starting range start while `start` is omitted, after which the component owns it. |
+| defaultEnd | `string \| null` | `—` | Starting range end while `end` is omitted, after which the component owns it. |
+| onChange | `(value: DatePickerRangeValue) => void` | `—` | Called with both sides of the range on every commit — `{ start, end }` as ISO dates or `null`. Picking a first date reports an end of `null` until the range is closed. |
+| open | `boolean` | `—` | Controlled open state of the calendar. Pass with `onOpenChange`; omit to let the component manage its own. |
+| defaultOpen | `boolean` | `false` | Whether the calendar starts open while `open` is omitted. |
+| onOpenChange | `(open: boolean) => void` | `—` | Called with the next open state whenever the calendar opens or closes. |
+| readOnly | `boolean` | `false` | Keeps the formatted range visible but blocks editing: the calendar cannot open and the chevron is not rendered. Use `disabled` instead when the field is inactive. |
+| required | `boolean` | `false` | Marks the field as required — asterisk on `Label`, plus `required` and `aria-required` on the combobox. It does not block submission on its own. |
+| minDate | `string` | `""` | Earliest selectable date (`YYYY-MM-DD`) for both ends of the range. Earlier days are disabled, month navigation stops there, and an earlier typed date is rejected. |
+| maxDate | `string` | `""` | Latest selectable date (`YYYY-MM-DD`) for both ends of the range. Later days are disabled, month navigation stops there, and a later typed date is rejected. |
+| unavailableDates | `readonly string[] \| null` | `—` | ISO dates (`YYYY-MM-DD`) that cannot be selected. Combined with `isDateUnavailable` and `minDate` / `maxDate`. Dates between the ends are not checked, so a range can span an unavailable day. |
+| isDateUnavailable | `(iso: string) => boolean` | `—` | Return true to disable that calendar day. Receives an ISO date-only string. Combined with `unavailableDates` and `minDate` / `maxDate`, and applied to the chosen ends rather than the days between them. |
+| locale | `string` | `"en-US"` | BCP 47 tag driving the displayed range format, the field order accepted when typing, weekday labels, and which day starts the week. ISO input is always accepted regardless. |
+| today | `string \| null` | `—` | Overrides the date marked as today and the month opened when nothing is selected (`YYYY-MM-DD`). Pin it for deterministic tests and snapshots. |
+| datePickerSlot | `ReactNode` | `—` | Replaces the whole built-in calendar panel, month navigation and range status included, so `previousMonthAriaLabel`, `nextMonthAriaLabel`, and `rangeSelectionStatus` no longer apply. Omit it to use the month grid. |
+| previousMonthAriaLabel | `string` | `"Previous month"` | Accessible name for the previous-month button. Defaults to English, so pass a translated string in localized apps. |
+| nextMonthAriaLabel | `string` | `"Next month"` | Accessible name for the next-month button. Defaults to English, so pass a translated string in localized apps. |
+| rangeSelectionStatus | `string` | `"Start date selected. Choose an end date."` | Polite live-region copy announced while a start date is chosen and an end date is still needed. Defaults to English, so pass a translated string in localized apps. |
+| startName | `string` | `—` | Form field name for a hidden input carrying the ISO start date; falls back to `name` when omitted. The input is omitted while no start is set or a typed draft is invalid. |
+| endName | `string` | `—` | Form field name for a hidden input carrying the ISO end date. The input is omitted while no end is set or a typed draft is invalid. |
+| disabled | `boolean` | `false` | Blocks all interaction and applies disabled styling: the field cannot be typed in and the calendar cannot open. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<DatePickerRange
+  labelText="Travel dates"
+  start={start}
+  end={end}
+  onChange={({ start, end }) => {
+    setStart(start);
+    setEnd(end);
+  }}
+/>
+```
+
+
+## Notes
+
+- **Value** — `start` / `end` are ISO date-only strings (`YYYY-MM-DD`) or `null`. `onChange` receives both. Display and typed input follow `locale` as `start - end`.
+- **Selection** — The first click sets start; the second sets end and closes the calendar. A later click starts a new range. Days outside the current month are shown but not selectable. v1 uses a single field and one month grid.
+- **Accessibility**: Same labeling pattern as DatePicker (`Label htmlFor`, `aria-describedby`, `aria-errormessage`). `required` shows the Label asterisk and sets `aria-required` on the combobox. Use `aria-label` when `label={false}`. After the start date is chosen, a live region announces `rangeSelectionStatus`. `autoComplete` defaults to `off`; pass an HTML token when the host needs browser autofill.
+- **Keyboard**: **Tab** focuses the text field so a locale-formatted range can be typed (**Enter** commits). Dates in the calendar are not separate tab stops. **ArrowDown** opens the calendar and moves focus into the grid; arrows move by day/week; **Home** / **End** move to the start/end of the week; **PageUp** / **PageDown** move the focused date by one month; **Shift+PageUp** / **Shift+PageDown** move by one year. **Escape** closes and returns focus to the field.
+- **Typing**: Display uses `start - end`. Range parsing splits on a spaced hyphen or an en/em dash so ISO dates and hyphen locales (e.g. `sv-SE`) are not shattered. Month names and other non-numeric text are not parsed: the typed value stays, the field is marked invalid, and a locale format hint is shown. Hidden form values are omitted while the draft is invalid.
+- **Controlled value**: `start` and `end` are controlled independently. Pass both (use `null` for an empty side) when the host owns the range. Passing only one leaves the other uncontrolled.
+- **Trigger**: The visible chevron is presentational (`aria-hidden`, `tabIndex={-1}`); the combobox owns `aria-haspopup`.
+- **Limits**: Selectable dates are gated with `minDate` / `maxDate`, `unavailableDates`, and `isDateUnavailable`. Those rules disable `DatePickerDate` cells. `validation` supports `none` and `error` only.
+- **Copy**: Chrome strings (`previousMonthAriaLabel`, `nextMonthAriaLabel`, `rangeSelectionStatus`) default to English so the host app can pass translated copy. Month titles, weekdays, and typed values follow `locale`.
+- **Forms**: `startName` / `endName` render hidden inputs with ISO dates when set; they are omitted while the typed draft is invalid.

package/skills/uxelle-components/Dialog.md

@@ -0,0 +1,83 @@
+# Dialog
+
+Import: `import { Dialog } from "@uxelle/components";`
+
+Centered modal for focused tasks such as confirmations and forms.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| fullScreen | `boolean` | `false` | Fills the viewport with edge-to-edge panel chrome and drops the scrim, so `size` and `closeOnScrimClick` no longer apply. |
+| size | `"Small" \| "Medium" \| "Large"` | `"Medium"` | Panel width preset — Small for confirmations, Medium for short forms, Large for denser content. Ignored while `fullScreen` is true. |
+| open | `boolean` | `—` | Controlled visibility. Pass it with `onOpenChange` and update it yourself; omit it to let the dialog track its own state from `defaultOpen`. |
+| defaultOpen | `boolean` | `false` | Whether the dialog 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 is pressed, or the scrim is dismissed. Required when `open` is controlled. |
+| trigger | `ReactElement` | `—` | Optional single element used to toggle visibility. Must accept and forward `onClick`, `aria-expanded`, `aria-haspopup`, and `aria-controls` (native button or a component that spreads props to its hit target). Fragments and wrappers that drop props are not supported — control `open` yourself instead. |
+| topSlotContent | `ReactNode` | `—` | Header region — the visible title, an optional subtitle, and a close control (`Text` plus `IconButton`). With no `aria-label` / `aria-labelledby`, the first non-kicker `Text` here becomes the dialog's accessible name. |
+| centerSlotContent | `ReactNode` | `—` | Body region holding the task content; it scrolls on its own once the panel overflows. Point `aria-describedby` at it when the body should be announced. |
+| bottomSlotContent | `ReactNode` | `—` | Footer region for the confirm and cancel actions, usually a `ButtonGroup` of `Button`s. Put a Cancel action here so the dialog is dismissible without relying on Escape or the scrim. |
+| initialFocusRef | `RefObject<HTMLElement \| null>` | `—` | Ref to the element that should take focus when the dialog opens — typically the first input, or the safe action for destructive flows. Omit it to focus the panel itself; a target outside the panel or one that refuses focus also falls back to the panel. Focus returns to the trigger on close either way. |
+| closeOnEscape | `boolean` | `true` | When true, Escape closes the dialog — only the topmost of stacked dialogs responds. Set false for critical flows the user must finish or cancel from in-panel actions. |
+| closeOnScrimClick | `boolean` | `true` | When true, pressing outside the panel closes the dialog. Has no effect while `fullScreen` is true, since there is no scrim to press. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Dialog
+  size="Large"
+  aria-labelledby="dialog-title"
+  topSlotContent={
+    <>
+      <div className="uxl-internal-dialog__title-block">
+        <Text id="dialog-title" type="Component Medium" width={false}>
+          Confirm your changes
+        </Text>
+        <Text type="Body Small" width={false}>
+          Step 2 of 3
+        </Text>
+      </div>
+      <IconButton
+        emphasis="low"
+        size="small"
+        iconName="close"
+        iconVariant="sharpFilled"
+        aria-label="Close"
+        onClick={() => setOpen(false)}
+      />
+    </>
+  }
+  centerSlotContent={
+    <Text type="Body Medium" width={false}>
+      Review the details below before continuing.
+    </Text>
+  }
+  bottomSlotContent={
+    <ButtonGroup direction="row" aria-label="Dialog actions">
+      <Button emphasis="low" size="medium" onClick={() => setOpen(false)}>
+        Cancel
+      </Button>
+      <Button emphasis="high" size="medium" onClick={() => setOpen(false)}>
+        Confirm
+      </Button>
+    </ButtonGroup>
+  }
+  trigger={<Button emphasis="high">Open</Button>}
+/>
+```
+
+
+## Notes
+
+- **Composition**: Renders `InternalDialog` for the panel chrome. Prefer this host over using `InternalDialog` alone so scrim, focus trap, Escape, and open/close stay consistent.
+- **Slots**: Compose header, body, and actions into `topSlotContent`, `centerSlotContent`, and `bottomSlotContent` (Text, IconButton, Button, ButtonGroup, etc.). Empty slots are omitted from the panel DOM.
+- **Dismiss affordance**: Always provide a visible Close control and/or Cancel action in the slots. Do not rely on Escape or scrim alone — especially for full screen, where there is no scrim.
+- **Critical flows**: Set `closeOnEscape={false}` and/or `closeOnScrimClick={false}` when the user must complete or cancel via in-panel actions.
+- **Full screen**: When `fullScreen` is true, the panel fills the viewport edge-to-edge and the scrim is omitted. Use `size` only for Small / Medium / Large widths.
+- **Trigger**: `trigger` must be a single element that forwards click and ARIA props to its hit target. Use controlled `open` / `onOpenChange` when the opener cannot accept those props.
+- **Text width**: `Text` in `topSlotContent` and `centerSlotContent` uses `width={false}` (100% of the slot). `width` / `width={true}` shrinks to the string and leaves a narrow column. Button labels stay `width` (fit content).
+- **Accessibility**: `role="dialog"`, `aria-modal="true"`. Prefer `aria-labelledby` pointing at the visible title in `topSlotContent`, or `aria-label`. When those are omitted, the first heading or non-kicker `Text` in `topSlotContent` is associated automatically. Kicker/caption `Text` variants (`Overline`, `Overline Alt`, `Body Small`, `Body Small Alt`) and close buttons are never bound; if only kicker text is present, set `aria-label`/`aria-labelledby` explicitly. Optionally describe the body with `aria-describedby`. Focus moves into the panel on open and returns to the trigger on close.

package/skills/uxelle-components/Divider.md

@@ -0,0 +1,37 @@
+# Divider
+
+Import: `import { Divider } from "@uxelle/components";`
+
+Thin rule that separates content, either horizontally or vertically.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | Direction the rule runs: `horizontal` spans the parent's width, `vertical` its height. Only `horizontal` supports the `text` label layout. |
+| emphasis | `"low" \| "high"` | `"low"` | Line weight and contrast: `low` is a hairline for separating items inside a list or card, `high` a darker, thicker rule for major section breaks. |
+| text | `boolean` | `undefined` | Forces the label layout, splitting the rule around centered `children` (`horizontal` only). Omit it to pick the layout automatically from whether `children` are present. |
+| children | `ReactNode` | `—` | Label rendered between the two line segments, wrapped in `Text` (`Condensed`). Passing children turns the label layout on unless `text` is explicitly false. |
+| decorative | `boolean` | `undefined` | Semantics of the rule: true hides it with `aria-hidden`, false exposes it as `role='separator'` with `aria-orientation` (plus `aria-label` when set). Resolves to hidden for a plain rule and exposed once the label layout is shown. |
+| "aria-label" | `string` | `""` | Accessible name for the separator, e.g. the section it introduces. Applied only when `decorative` resolves to false. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Divider />
+<Divider orientation="vertical" />
+<Divider emphasis="high" text>Section</Divider>
+```
+
+
+## Notes
+
+- **WCAG AA compliant**: Uses theme tokens that meet contrast requirements
+- **Semantic**: role="separator" with aria-orientation when not decorative
+- **Decorative by default**: aria-hidden="true" when not showing text; use decorative={false} for semantic dividers

package/skills/uxelle-components/DynamicAngleLine.md

@@ -0,0 +1,36 @@
+# DynamicAngleLine
+
+Import: `import { DynamicAngleLine } from "@uxelle/components";`
+
+Single diagonal brand accent line for decorative layouts and texture strips.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| dataColorSwitcher | `string` | `DYNAMIC_ANGLE_DEFAULT_DATA_COLOR_SWITCHER` | Palette name applied as `data-color-switcher` on the graphic, retinting its accent strokes or brand fill (for example `brand-1` or `brand-2`). On **DynamicAngleTextureText** it scopes the texture strip only, so the label keeps the surrounding page palette. |
+| "data-color-switcher" | `string` | `—` | Attribute-style alias for `dataColorSwitcher`, useful when spreading raw DOM props. It wins when both are set; a blank value is treated as unset. |
+| rotation | `"80" \| "75" \| "72" \| "65" \| "55" \| "50" \| "40"` | `"80"` | Stroke inclination in degrees: `80` is nearly upright and `40` the most reclined. Lower values also widen the cross-axis footprint, from 50px at `80` to 249px at `40` before `height` scaling. |
+| direction | `"Vertical" \| "Horizontal"` | `"Vertical"` | Orientation of the 160px long axis. `Vertical` makes it the height for a tall, narrow accent; `Horizontal` makes it the width and tilts the stroke the opposite way. |
+| height | `number` | `DYNAMIC_ANGLE_LINE_BASE_HEIGHT` | Long-axis length in px, scaled from the 160px base. The cross-axis grows in proportion while stroke thickness stays fixed; negative or non-finite values collapse to 0. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Decorative accent beside a hero band
+<DynamicAngleLine
+  rotation="80"
+  direction="Vertical"
+  height={160}
+  dataColorSwitcher="brand-1"
+/>
+```
+
+
+## Notes
+
+- Non-interactive graphic element. Stroke color follows `dataColorSwitcher` on this root (`--uxl-component-dynamic-angle-line-color`). Defaults to `aria-hidden={true}` for decorative hero and section accents; set `aria-hidden={false}` only when the graphic must be announced. `height` scales the footprint uniformly from its 160px long axis. Stroke thickness stays fixed via `--uxl-component-dynamic-angle-line-weight`.

package/skills/uxelle-components/DynamicAngleLineCombo.md

@@ -0,0 +1,30 @@
+# DynamicAngleLineCombo
+
+Import: `import { DynamicAngleLineCombo } from "@uxelle/components";`
+
+Paired diagonal accent lines arranged for brand expression layouts.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| dataColorSwitcher | `string` | `DYNAMIC_ANGLE_DEFAULT_DATA_COLOR_SWITCHER` | Palette name applied as `data-color-switcher` on the graphic, retinting its accent strokes or brand fill (for example `brand-1` or `brand-2`). On **DynamicAngleTextureText** it scopes the texture strip only, so the label keeps the surrounding page palette. |
+| "data-color-switcher" | `string` | `—` | Attribute-style alias for `dataColorSwitcher`, useful when spreading raw DOM props. It wins when both are set; a blank value is treated as unset. |
+| comboType | `"1" \| "2" \| "3"` | `"1"` | Which of the three built-in stroke pairings fills the 222×160 frame: `1` diverges from the bottom-left at 40° and 55°, `2` pairs a steep 75° with a reclined 50°, and `3` pairs 55° with 72°. |
+| height | `number` | `DYNAMIC_ANGLE_LINE_COMBO_DEFAULTS.height` | Rendered height in px, scaled from the 160px base frame. Width follows at the 222:160 aspect and stroke thickness does not scale; omit for 160, and negative or non-finite values collapse to 0. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Decorative pair in a hero layout
+<DynamicAngleLineCombo comboType="1" height={160} dataColorSwitcher="brand-1" />
+```
+
+
+## Notes
+
+- Non-interactive decorative graphic. Draws two design-accurate accent strokes for the selected combo type. Accent color is scoped via `dataColorSwitcher` on this root. Defaults to `aria-hidden={true}` for decorative hero and section accents. `height` uniformly scales the design frame; stroke thickness stays fixed via `--uxl-component-dynamic-angle-line-weight`.

package/skills/uxelle-components/DynamicAngleShape.md

@@ -0,0 +1,32 @@
+# DynamicAngleShape
+
+Import: `import { DynamicAngleShape } from "@uxelle/components";`
+
+Angled gradient shard for brand hero bands and section accents.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| dataColorSwitcher | `string` | `DYNAMIC_ANGLE_DEFAULT_DATA_COLOR_SWITCHER` | Palette name applied as `data-color-switcher` on the graphic, retinting its accent strokes or brand fill (for example `brand-1` or `brand-2`). On **DynamicAngleTextureText** it scopes the texture strip only, so the label keeps the surrounding page palette. |
+| "data-color-switcher" | `string` | `—` | Attribute-style alias for `dataColorSwitcher`, useful when spreading raw DOM props. It wins when both are set; a blank value is treated as unset. |
+| angleDirection | `"Right" \| "Left" \| "Bottom"` | `"Right"` | Edge the diagonal cuts from. `Right` and `Left` render a tall right triangle (mirrored from each other); `Bottom` renders a short wedge rising left to right and forces `angle` to `12`. |
+| angle | `"80" \| "75" \| "72" \| "12"` | `"80"` | Steepness of the diagonal in degrees: `80` is the narrowest wedge, `75` and `72` are progressively wider at the same height, and `12` is the shallow `Bottom` cut. Ignored when `angleDirection` is `Bottom`, which always renders at `12`. |
+| height | `number` | `DYNAMIC_ANGLE_SHAPE_BASE_HEIGHT` | Rendered height in px; width scales with it so the diagonal keeps its angle. Omit for the base height of the active direction (315.3 for `Right` and `Left`, 67 for `Bottom`); negative or non-finite values collapse to 0. |
+| colorSwitcherBrand | `boolean` | `false` | Swaps the fill from the default blue theme gradient to the flat brand color of the active `dataColorSwitcher` palette. Use it when the shard sits on a section that already carries a palette. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Decorative shard in a hero band
+<DynamicAngleShape angleDirection="Right" angle="80" colorSwitcherBrand />
+```
+
+
+## Notes
+
+- Non-interactive decorative fill. By default uses the theme blue gradient; set `colorSwitcherBrand` to fill with `--uxl-component-dynamic-angle-shape-color` instead. `dataColorSwitcher` scopes the palette on this root. Defaults to `aria-hidden={true}` for decorative hero placement. `height` scales the footprint from the design base for the active direction (width included).

package/skills/uxelle-components/DynamicAngleShapeSurface.md

@@ -0,0 +1,35 @@
+# DynamicAngleShapeSurface
+
+Import: `import { DynamicAngleShapeSurface } from "@uxelle/components";`
+
+Large angled surface for section backgrounds and hero bands.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| dataColorSwitcher | `string` | `DYNAMIC_ANGLE_DEFAULT_DATA_COLOR_SWITCHER` | Palette name applied as `data-color-switcher` on the graphic, retinting its accent strokes or brand fill (for example `brand-1` or `brand-2`). On **DynamicAngleTextureText** it scopes the texture strip only, so the label keeps the surrounding page palette. |
+| "data-color-switcher" | `string` | `—` | Attribute-style alias for `dataColorSwitcher`, useful when spreading raw DOM props. It wins when both are set; a blank value is treated as unset. |
+| angleDirection | `"Right" \| "Left" \| "Top"` | `"Right"` | Corner or edge the diagonal cut runs along: `Right` slopes the bottom-right corner inward, `Left` slopes the top-left corner, and `Top` shaves a shallow rise across the top edge. It also selects the base frame — 742×618 for `Right` and `Left`, 742×487 for `Top`. |
+| height | `number` | `DYNAMIC_ANGLE_SHAPE_SURFACE_BASE_HEIGHT` | Rendered height in px; width scales with it so the cut keeps its angle. Omit for the base height of the active direction (618 for `Right` and `Left`, 487 for `Top`); negative or non-finite values collapse to 0. |
+| colorSwitcherBrand | `boolean` | `false` | Swaps the fill from the default blue theme gradient to the flat brand color of the active `dataColorSwitcher` palette. Use it when the surface sits on a section that already carries a palette. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Decorative surface in a hero band
+<DynamicAngleShapeSurface
+  angleDirection="Right"
+  height={618}
+  colorSwitcherBrand
+/>
+```
+
+
+## Notes
+
+- Non-interactive decorative background. By default uses the theme blue gradient; set `colorSwitcherBrand` to fill with `--uxl-component-dynamic-angle-shape-color` instead. `dataColorSwitcher` scopes the palette on this root. Defaults to `aria-hidden={true}` for decorative hero placement. `height` uniformly scales the design frame so the angle cut does not warp.

package/skills/uxelle-components/DynamicAngleTexture.md

@@ -0,0 +1,29 @@
+# DynamicAngleTexture
+
+Import: `import { DynamicAngleTexture } from "@uxelle/components";`
+
+Repeating diagonal line strip for inline brand texture accents.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| dataColorSwitcher | `string` | `DYNAMIC_ANGLE_DEFAULT_DATA_COLOR_SWITCHER` | Palette name applied as `data-color-switcher` on the graphic, retinting its accent strokes or brand fill (for example `brand-1` or `brand-2`). On **DynamicAngleTextureText** it scopes the texture strip only, so the label keeps the surrounding page palette. |
+| "data-color-switcher" | `string` | `—` | Attribute-style alias for `dataColorSwitcher`, useful when spreading raw DOM props. It wins when both are set; a blank value is treated as unset. |
+| lineCount | `number` | `DYNAMIC_ANGLE_TEXTURE_LINE_COUNT` | Number of repeated diagonal strokes; each adds about 3.6px of width, so the default 52 spans roughly 192px. Height is fixed at about 20.5px, and the value is floored and clamped to 0–500. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Decorative texture strip in a hero layout
+<DynamicAngleTexture lineCount={52} dataColorSwitcher="brand-1" />
+```
+
+
+## Notes
+
+- Non-interactive decorative graphic with compact stroke geometry (not a scaled **DynamicAngleLine**). Strokes are drawn in one SVG on an exact pitch grid so spacing stays even (avoids sub-pixel flex rounding). The strip uses a fixed height and clips stroke tips at the top and bottom edges. Defaults to `aria-hidden={true}`. `lineCount` is capped at **DYNAMIC_ANGLE_TEXTURE_LINE_COUNT_MAX**.

package/skills/uxelle-components/DynamicAngleTextureText.md

@@ -0,0 +1,35 @@
+# DynamicAngleTextureText
+
+Import: `import { DynamicAngleTextureText } from "@uxelle/components";`
+
+Inline label paired with a repeating diagonal texture strip.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| dataColorSwitcher | `string` | `DYNAMIC_ANGLE_DEFAULT_DATA_COLOR_SWITCHER` | Palette name applied as `data-color-switcher` on the graphic, retinting its accent strokes or brand fill (for example `brand-1` or `brand-2`). On **DynamicAngleTextureText** it scopes the texture strip only, so the label keeps the surrounding page palette. |
+| "data-color-switcher" | `string` | `—` | Attribute-style alias for `dataColorSwitcher`, useful when spreading raw DOM props. It wins when both are set; a blank value is treated as unset. |
+| textDirection | `"Right" \| "Left"` | `"Right"` | Side the label sits on. `Right` renders the texture strip first with the label after it; `Left` puts the label first and the strip after. |
+| text | `string` | `"Health for all, Hunger for none"` | Tagline copy rendered as Body Medium **Text** beside the strip. Unlike the texture it keeps the surrounding page palette, so it stays readable whatever `dataColorSwitcher` is set to. |
+| lineCount | `number` | `DYNAMIC_ANGLE_TEXTURE_LINE_COUNT` | Number of repeated diagonal strokes; each adds about 3.6px of width, so the default 52 spans roughly 192px. Height is fixed at about 20.5px, and the value is floored and clamped to 0–500. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Tagline row in a hero band
+<DynamicAngleTextureText
+  textDirection="Right"
+  text="Health for all, Hunger for none"
+  dataColorSwitcher="brand-1"
+/>
+```
+
+
+## Notes
+
+- Decorative brand expression row for taglines and manifesto copy in hero and section layouts. `dataColorSwitcher` applies to the texture strip only so label text keeps the page palette. The texture is hidden from assistive technologies; the label uses **Text** Body Medium styling and remains readable.

package/skills/uxelle-components/FieldMessage.md

@@ -0,0 +1,31 @@
+# FieldMessage
+
+Import: `import { FieldMessage } from "@uxelle/components";`
+
+Contextual helper, error, or success message shown below a form field or input.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| messageType | `"Info" \| "Danger" \| "Warning" \| "Success"` | `"Info"` | Status the message conveys, which picks the default icon (`help`, `error`, `warning`, `check_circle`) and the status color. When you compose your own children the color still applies, but you supply the icon. |
+| children (required) | `ReactNode` | `—` | Message content. Pass a plain string to get the `messageType` icon plus `Condensed` `Text` automatically; pass elements — your own `Icon` and `Text` — to render them verbatim instead. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<FieldMessage>
+  {/* React.ReactNode */}
+</FieldMessage>
+```
+
+## Notes
+
+- Message types: Info, Danger, Warning, Success.
+- **Simple usage** — pass a string; default Icon and Text are rendered: <FieldMessage messageType="Danger">You must choose at least 1 option</FieldMessage>
+- **Composable usage** — pass Icon and Text as children for full control: <FieldMessage messageType="Danger"> <Icon iconName="error" variant="sharpFilled" size={16} aria-hidden /> <Text type="Condensed" inline>You must choose at least 1 option</Text> </FieldMessage>
+- **Accessibility**: Use for validation hints, character counts, or supplemental guidance.

package/skills/uxelle-components/FileUpload.md

@@ -0,0 +1,53 @@
+# FileUpload
+
+Import: `import { FileUpload } from "@uxelle/components";`
+
+Form control for choosing files with optional drag-and-drop, file list, and validation.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `boolean` | `true` | When false, the label row is not rendered — pass `aria-label` (or `aria-labelledby`) for the accessible name. `fieldDescription` is dropped with it, so move helper copy to `aria-describedby`. |
+| labelText | `string` | `"Upload documents"` | Visible label text, rendered as Body Medium Alt inside `Label`; ignored when `labelSlot` is set, and an empty string hides the label row. |
+| fieldDescription | `string` | `"Max file size is 10MB."` | Helper copy under the label, linked to the file input with `aria-describedby`; keep it aligned with the active size limit. |
+| labelSlot | `ReactNode` | `—` | Replaces `labelText` with custom content inside `Label`, which keeps `htmlFor` and the required asterisk. |
+| fieldMessage | `boolean` | `false` | Renders a `FieldMessage` row below the control; `validation` set to `success` or `error` shows the row as well, so use this flag for neutral helper copy. |
+| fieldMessageContent | `string` | `""` | Content for the `FieldMessage` row; when set it also replaces the built-in oversize-file error. |
+| validation | `"none" \| "success" \| "error"` | `"none"` | Validation state: `success` and `error` restyle the field message and force the row. Any value other than `none` also suppresses the built-in oversize-file error, leaving the message to the app. |
+| dragFiles | `boolean` | `false` | When true, the trigger is a dashed drop zone that accepts dropped files; when false, it is an upload `Button` that opens the file picker. |
+| fullWidth | `boolean` | `false` | When true, the root fills its container; when false, it stays at the compact 243px width. |
+| height | `number` | `150` | Height in pixels of the dashed drop zone. Only applies when `dragFiles` is true; the button trigger keeps the button’s intrinsic height. |
+| buttonText | `string` | `"Upload Files"` | Label on the upload `Button`, or the centered copy inside the drop zone when `dragFiles` is true. |
+| fileItems | `FileUploadFileItem[]` | `—` | Controlled list of rows shown under the trigger. Pair it with `onFileItemsChange` (or update it from `onFilesSelected`) — the component never mutates it. |
+| onFileItemsChange | `(items: FileUploadFileItem[]) => void` | `—` | Called with the next row array whenever files are added or removed, in both controlled and uncontrolled mode. |
+| defaultFileItems | `FileUploadFileItem[]` | `—` | Starting rows for uncontrolled usage; ignored once `fileItems` is set. |
+| listSlot | `ReactNode` | `—` | Custom node rendered in place of the built-in file list. While it is set, selections no longer update the row state, so own the list from `onFilesSelected`. |
+| onFilesSelected | `(files: FileList) => void` | `—` | Called with the accepted files as a `FileList` after a pick or drop; oversized files are already filtered out. Fires alongside the native `onChange`. |
+| onRemoveFile | `(id: string) => void` | `—` | Called with the removed row's `id` after a built-in remove control is used. |
+| removeFileAriaLabel | `string` | `"Remove {name}"` | `aria-label` template for each row's remove control; `{name}` is replaced with the file name. |
+| maxFileSizeBytes | `number \| null` | `10 * 1024 * 1024` | Size limit in bytes: oversized files are dropped before `onFilesSelected` and the file list, and a danger `FieldMessage` appears while `validation` is `none`. Takes precedence over `maxFileSizeMB`; pass `null` to turn the check off. |
+| maxFileSizeMB | `number` | `10` | Size limit in mebibytes (1024×1024 bytes) — the friendlier alias for `maxFileSizeBytes`. Ignored when `maxFileSizeBytes` is set; pass `null` to turn the check off. |
+| maxFileSizeMessage | `string` | `"File exceeds the {limit}MB limit."` | Copy for the built-in oversize-file error, where `{limit}` is replaced with the limit in MB. Ignored when `fieldMessageContent` is set. |
+| onMaxFileSizeExceeded | `(files: File[]) => void` | `—` | Called with the rejected `File` objects whenever files exceed the size limit. Fires even when the app owns `validation`, so it can raise its own message. |
+| multiple | `boolean` | `true` | Allows picking or dropping several files at once; when false, each new selection replaces the current row instead of appending. |
+| accept | `string` | `""` | Comma-separated file types forwarded to the native input `accept` (e.g. `image/*,.pdf`); it filters the file picker, not dropped files. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<FileUpload name="documents" accept="image/*,.pdf" onFilesSelected={upload} />
+```
+
+
+## Notes
+
+- **Uncontrolled list** — omit `fileItems`; selected files appear in the list automatically.
+- **Controlled list** — pass `fileItems` and `onFileItemsChange` (or update `fileItems` from `onFilesSelected`).
+- **File size** — `maxFileSizeMB` (default 10) or `maxFileSizeBytes` (bytes win if both are set; `null` disables) rejects oversized files and shows a FieldMessage when `validation` is `"none"`. Customize copy with `maxFileSizeMessage` (`{limit}` = MB) or own the message via `validation` / `fieldMessageContent` / `onMaxFileSizeExceeded`. Keep `fieldDescription` aligned with the limit.
+- Root width defaults to 243px; set `fullWidth` to stretch to the container. Drop-zone height defaults to 150px via `height` (only when `dragFiles`). Remaining HTML attributes forward to the native file input; `className` applies to the root wrapper.
+- **Accessibility**: Built-in `label` / `fieldDescription` wire `aria-labelledby` and `aria-describedby` on the file input. When `label={false}`, pass `aria-label` (or `aria-labelledby`). Upload rows use determinate `LinearProgress` while in progress.