@uxelle/skills 0.2.0-beta.2

package/skills/uxelle-components/FilterChip.md

@@ -0,0 +1,35 @@
+# FilterChip
+
+Import: `import { FilterChip } from "@uxelle/components";`
+
+Removable pill for an applied filter value.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label (required) | `string` | `"Filter Chip"` | Filter value shown on the chip; also seeds the remove control's default name (`Remove {label}`). Whitespace is trimmed, an empty result renders no chip, and long values are not truncated. |
+| disabled | `boolean` | `false` | Applies disabled styling and blocks dismissal — the remove control ignores clicks and keys, and arrow-key navigation inside **FilterChipGroup** skips it. |
+| leadingIcon | `boolean` | `false` | Adds a decorative icon before the label, useful for showing which facet the value belongs to. |
+| leadingIconName | `string` | `"add"` | Material Symbol drawn before the label. Ignored unless `leadingIcon` is `true`. |
+| leadingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Glyph weight of the leading icon: `sharpFilled` is the solid form, `sharpUnfilled` the outlined one. |
+| onRemove (required) | `(event: SyntheticEvent<HTMLButtonElement>) => void` | `—` | Fires when the user dismisses the chip — clicking the remove control, or pressing Enter, Space, Delete, or Backspace while it is focused. Drop the value from your own state here; the chip does not remove itself. |
+| removeAriaLabel | `string` | `""` | Accessible name for the icon-only remove button. Falls back to `Remove {label}`, so set it only when the label alone would be ambiguous out of context. Overridden when `aria-label` or `aria-labelledby` is set. |
+| "aria-label" | `string` | `""` | Accessible name for the remove control. Overrides `removeAriaLabel`. Ignored when `aria-labelledby` is set (browsers prefer labelledby). |
+| "aria-labelledby" | `string` | `""` | IDs of elements that name the remove control, space-separated. Takes precedence over `aria-label` and `removeAriaLabel`. |
+| "aria-describedby" | `string` | `""` | IDs of elements holding extra description for the remove control, space-separated. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<FilterChip label="Region" leadingIcon leadingIconName="location_on" onRemove={() => {}} />
+```
+
+
+## Notes
+
+- Always requires `onRemove` — the chip’s job is to represent a filter that can be dismissed. Root is a non-interactive `span` so the dismiss Icon Button nests correctly; the surface does not use hover/pressed fills. Prefer **ChoiceChip** for selectable option sets. There is no InputChip — compose entry (e.g. Textfield) with FilterChips for removable values. Keyboard: focus the remove control, then **Enter** / **Space** or **Delete** / **Backspace** to dismiss. Inside **FilterChipGroup**, arrow keys move between chips (one Tab stop for the set). Removal is announced via a polite live region.

package/skills/uxelle-components/FilterChipGroup.md

@@ -0,0 +1,42 @@
+# FilterChipGroup
+
+Import: `import { FilterChipGroup } from "@uxelle/components";`
+
+Groups dismissible applied-filter chips under an optional legend, wrapping to new rows as needed.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | `—` | **FilterChip** 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` | `"Filters"` | 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"` | `FILTER_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. Leave it as `group`: the chips are independent dismissible filters, not a selection set. |
+| "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
+<FilterChipGroup label labelText="Fruit">
+  <FilterChip label="Apple" onRemove={() => {}} />
+  <FilterChip label="Banana" onRemove={() => {}} />
+</FilterChipGroup>
+```
+
+
+## Notes
+
+- Pass **FilterChip** children. Root is a **`fieldset`** with default **`role="group"`**; name it with the legend (`label` + `labelText`) or `aria-label` / `aria-labelledby`. Keyboard: one Tab stop into the set; **Arrow** keys move between remove controls; **Delete** / **Backspace** dismisses the focused chip. Removals are announced politely. Form parity: **`fieldMessage`**, **`required`**, **`invalid`**, and merged **`aria-describedby`** / **`aria-errormessage`**. For choice option toggles, use **ChoiceChipGroup**. There is no InputChip — compose entry (e.g. Textfield) with FilterChips for removable values.

package/skills/uxelle-components/Footer.md

@@ -0,0 +1,34 @@
+# Footer
+
+Import: `import { Footer, DefaultTopMainContent, DefaultBottomMainContent } from "@uxelle/components";`
+
+Two-tier footer for enterprise applications.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| topMainContent | `ReactNode` | `undefined` | Contents of the upper band, which sets a `brand-2` color context — typically link columns, CTAs, a social row, and approval copy. Pass `null` to drop the band entirely; omit it to render catalog demo content. |
+| bottomMainContent | `ReactNode` | `undefined` | Contents of the lower band, which sets a `neutral` color context — typically a **Logo** brand lockup and legal copy. Pass `null` to drop the band entirely; omit it to render catalog demo content. |
+
+<!-- prettier-ignore-end -->
+
+Extends `HTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Footer
+  topMainContent={<DefaultTopMainContent />}
+  bottomMainContent={<DefaultBottomMainContent />}
+/>
+```
+
+
+## Notes
+
+- **Top section**: Main content slot (`topMainContent`) — columns, CTAs, social, approval.
+- **Bottom section**: Branding and legal copy (`bottomMainContent`).
+- Pass `null` on a slot to hide that band. Omit the `Footer` when the page has none.

package/skills/uxelle-components/Hero.md

@@ -0,0 +1,61 @@
+# Hero
+
+Import: `import { Hero } from "@uxelle/components";`
+
+Full-bleed marketing band with overlaid copy and actions.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| contentDirection | `"Left" \| "Right" \| "Bottom"` | `"Left"` | Where the content panel sits over the media. From the tablet breakpoint (678px) up, `Left` and `Right` pin a half-width, vertically centered panel to that edge, while `Bottom` keeps a full-width panel along the bottom. Below 678px all three collapse to the same full-width bottom panel. |
+| image (required) | `ReactNode` | `—` | Full-bleed media behind the hero. Pass a **direct** child `Image`, `img`, `picture`, or `video` — extra wrappers are unsupported and will not fill the media layer. Prefer `Image` for source, alt text, and optional overlay. Do not rely on `Image` aspect ratio — Hero owns the responsive crop. Keep this region non-interactive; put actions in `contentSlot`. |
+| contentSlot (required) | `ReactNode` | `—` | Overlay panel content, stacked in a column with theme gap — typically a `Lockup` plus a `ButtonGroup`. Required: the hero always renders the panel, and it is where any interactive content belongs. |
+| "data-color-switcher" | `string` | `—` | Color-switcher palette applied to the hero root, which drives the content panel surface and text colors. Falls back to `brand-1`; pass another palette name such as `brand-2` or `neutral` to override it. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Hero
+  contentDirection="Left"
+  image={<Image src="/hero.jpg" alt="Office building facade" />}
+  contentSlot={
+    <>
+      <Lockup
+        overline={<Text type="Overline" width={false}>Our mission</Text>}
+        title={
+          <Text type="Display Medium" as="h1" width={false}>
+            Health for all, Hunger for none
+          </Text>
+        }
+        body={
+          <Text type="Body Medium" width={false}>
+            Advancing access to health and nutrition for everyone, everywhere.
+          </Text>
+        }
+      />
+      <ButtonGroup aria-label="Actions">
+        <Button emphasis="high">
+          <Text type="Button" width={false}>
+            Primary action
+          </Text>
+        </Button>
+        <Button emphasis="medium">
+          <Text type="Button" width={false}>
+            Secondary action
+          </Text>
+        </Button>
+      </ButtonGroup>
+    </>
+  }
+/>
+```
+
+
+## Notes
+
+- Pass media in `image` as a direct child `Image`, `img`, `picture`, or `video` (wrappers are unsupported) and composed intro content in `contentSlot` (usually `Lockup` and `ButtonGroup`). `contentDirection` controls panel placement: `Left` / `Right` for side panels on tablet and up, `Bottom` for a full-width bottom panel at every size. Below the tablet breakpoint, `Left` and `Right` use the bottom panel layout. Content-area spacing remaps through theme breakpoint aliases that currently start at 375px — widths below that need a theme update before spacing sign-off. The root defaults to `data-color-switcher="brand-1"`; pass a different attribute to override. Do not add a landmark role by default — pass `role="region"` with `aria-label` or `aria-labelledby` when a named region is needed. Remaining HTML attributes are forwarded to the root element.

package/skills/uxelle-components/Icon.md

@@ -0,0 +1,43 @@
+# Icon
+
+Import: `import { Icon } from "@uxelle/components";`
+
+Renders Material Symbols icons.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| iconName | `string` | `"add"` | Material Symbols ligature name to render, e.g. `home`, `close`, or `settings`. Names outside that set render as literal text. |
+| size | `number` | `24` | Glyph size in pixels, applied as an inline `font-size`. Valid range is 8–128 and out-of-range values warn in development; leaving it at the default emits no inline size, so CSS or a parent token can drive it. |
+| style | `CSSProperties` | `—` | Inline styles merged onto the icon `span`, applied after the `size`-derived `font-size` — a `fontSize` here therefore overrides `size`. |
+| "aria-label" | `string` | `""` | Accessible name for an icon that carries meaning. Setting it also suppresses the automatic `aria-hidden`, so the icon becomes visible to assistive technology. |
+| "aria-hidden" | `"auto" \| "true" \| "false"` | `undefined` | Explicitly includes or excludes the icon from the accessibility tree. Leave it unset for the default: hidden when there is no `aria-label`, exposed once there is one. |
+| role | `string` | `""` | Role placed on the icon `span`. Pair `img` with `aria-label` when the glyph is meaningful content; leave it unset for decorative icons. |
+| variant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Glyph weight: `sharpFilled` renders the solid form through font-variation settings, `sharpUnfilled` the outlined form. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Decorative icon (default - hidden from screen readers)
+<Icon iconName="home" size={24} />
+```
+
+```tsx
+// Meaningful icon with accessible name
+<Icon iconName="close" aria-label="Close dialog" size={24} />
+```
+
+```tsx
+// Icon with custom role
+<Icon iconName="settings" role="img" aria-label="Settings" size={32} />
+```
+
+
+## Notes
+
+- Uses the material-symbols sharp font; updates instantly when `iconName` changes. By default, icons are hidden from screen readers (`aria-hidden="true"`) as they are typically decorative. Provide an `aria-label` when the icon conveys meaningful information.

package/skills/uxelle-components/IconButton.md

@@ -0,0 +1,44 @@
+# IconButton
+
+Import: `import { IconButton } from "@uxelle/components";`
+
+Compact button whose only visible content is an icon.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| emphasis | `"high" \| "medium" \| "low"` | `"high"` | Visual weight: `high` is a filled surface for the one primary action in a view, `medium` an outlined surface for secondary actions, `low` glyph-only for tertiary or inline actions. |
+| activated | `boolean` | `false` | Applies the selected, persistently-on surface and sets `aria-pressed` unless you pass your own. Use it for toggles that stay on, not for hover or focus feedback. |
+| size | `"extraSmall" \| "small" \| "medium" \| "large"` | `"medium"` | Padding around the glyph, so it sets the overall hit area: `extraSmall` removes padding entirely, `large` gives the most. The glyph itself never scales. |
+| iconName | `string` | `"add"` | Material Symbol glyph shown in the button. It is `aria-hidden`, so whatever it conveys must also be spelled out in `aria-label`. |
+| iconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Fill style for the glyph: `sharpFilled` solid, `sharpUnfilled` outlined. |
+| loading | `boolean` | `false` | Shows a centered spinner while the icon stays in layout at opacity 0 so the box does not resize. Blocks activation, sets `aria-busy` / `aria-disabled`, and keeps enabled visuals even when `disabled` is also true. Set `aria-label` to change what is announced while loading. |
+| "aria-label" | `string` | `""` | Accessible name for the button — effectively required, since the glyph is `aria-hidden` and contributes no text. Development builds warn when neither this nor `aria-labelledby` is set. |
+| disabled | `boolean` | `false` | Blocks activation and applies disabled styling through the native `disabled` attribute. For work in progress use `loading` instead — it keeps enabled visuals and overrides this prop. |
+
+<!-- prettier-ignore-end -->
+
+Extends `ButtonHTMLAttributes` — supports `disabled`, `onClick`, `className`, etc.
+
+## Usage
+
+```tsx
+<IconButton iconName="add" aria-label="Add item" />
+<IconButton emphasis="medium" iconName="close" aria-label="Close" />
+<IconButton emphasis="low" iconName="settings" aria-label="Settings" />
+<IconButton emphasis="high" activated iconName="add" aria-label="Pinned" aria-pressed />
+<IconButton loading iconName="save" aria-label="Saving" />
+```
+
+
+## Notes
+
+- **WCAG AA compliant**: Contrast ratios meet 4.5:1 for icon
+- **Browser-based focus ring**: Uses native outline on :focus-visible (keyboard only)
+- **Keyboard operable**: Native <button> supports Enter and Space
+- **ARIA**: Provide `aria-label` or `aria-labelledby` (the icon is `aria-hidden`). Development builds warn when neither is set.
+- **Activated**: Set `activated` for selected/toggled-on visuals; pair with `aria-pressed` on toggle buttons (set automatically when `activated` is true)
+- **Loading**: Set `loading` while an action is in progress. The icon remains in the layout at opacity 0 so size is stable; a centered spinner is shown. The control sets `aria-busy` / `aria-disabled`, keeps enabled visuals (including when `disabled` is also true), and blocks activation until loading ends. Prefer `loading` alone for pending work. The accessible name stays `aria-label`; change that prop to customize what assistive tech announces while loading.

package/skills/uxelle-components/Image.md

@@ -0,0 +1,40 @@
+# Image
+
+Import: `import { Image } from "@uxelle/components";`
+
+Responsive image that optionally crops its source to a selected aspect ratio.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| src (required) | `string` | `""` | Source URL forwarded to the inner `img` element. Nothing renders in its place when the request fails, so guard missing values upstream. |
+| alt (required) | `string` | `""` | Text alternative announced by assistive technology. Describe what the image conveys, or pass an empty string to mark it decorative and drop it from the accessibility tree. |
+| aspectRatio | `"1:1" \| "4:3" \| "3:2" \| "16:9" \| "21:9" \| "3:4" \| "2:3"` | `undefined` | Crops the image to a fixed ratio — `1:1`, `4:3`, `3:2`, `16:9`, `21:9`, `3:4`, or `2:3`. The image fills the available width and covers the box, so overflow is trimmed; omit to keep the source's intrinsic proportions. |
+| overlay | `"100" \| "200"` | `undefined` | Layers a decorative gradient wash over the image so text placed on top keeps contrast: `100` is a light wash, `200` a dark wash weighted to the bottom edge. Omit for no overlay. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<Image src="/images/team.jpg" alt="Product team collaborating" aspectRatio="16:9" />
+```
+
+```tsx
+<Image
+  src="/images/hero.jpg"
+  alt="Crop field at sunrise"
+  aspectRatio="21:9"
+  overlay="200"
+/>
+```
+
+
+## Notes
+
+- When `aspectRatio` is set, the image fills its available width and uses `object-fit: cover` to preserve the ratio. Omit `aspectRatio` to keep the intrinsic proportions. Supply meaningful `alt` text when the image conveys information, or `alt=""` when it is decorative.
+- Set `overlay` to `"100"` or `"200"` to layer a decorative gradient wash for contrast (for example under text). The wash is non-interactive and hidden from assistive technologies.
+- This component is non-interactive. Wrap it in a link or button only when the surrounding experience requires an action, and name that control separately.

package/skills/uxelle-components/Label.md

@@ -0,0 +1,35 @@
+# Label
+
+Import: `import { Label } from "@uxelle/components";`
+
+Accessible caption that names a form field or input.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| required | `boolean` | `false` | Prefixes the label with a danger-colored asterisk marking the field as mandatory. The asterisk is `aria-hidden`, so set `required` on the control itself as well. |
+| disabled | `boolean` | `false` | Switches the label and its asterisk to the disabled text color so they match a disabled control. Styling only — it does not block interaction, so set `disabled` on the control too. |
+| fieldDescription | `string` | `""` | Helper copy rendered below the label as full-width `Condensed` **Text**; an empty string renders nothing. It gets a stable id (`{label id}-field-description`) to reference from the control's `aria-describedby`. |
+| children | `ReactNode` | `—` | Label content, typically `Text`. Prefer `fieldDescription` for helper copy; extra `Text` children can be composed as well. |
+
+<!-- prettier-ignore-end -->
+
+Extends `React.LabelHTMLAttributes` — supports standard HTML attributes.
+
+## Usage
+
+```tsx
+<Label required fieldDescription="Your full legal name">
+  <Text type="Body Medium Alt">Field name</Text>
+</Label>
+```
+
+
+## Notes
+
+- Composable: pass label content as `children` (typically Text). Prefer `fieldDescription` for helper copy; you can also add extra Text children for advanced composition.
+- **Accessibility**: Renders as semantic `<label>`. Associate with controls via `htmlFor` / `id`. `fieldDescription` gets a stable `id` (`{label id}-field-description`) for `aria-describedby` on the control.
+- **States**: Required (asterisk always uses `data-color-switcher="danger"`), disabled.

package/skills/uxelle-components/LabelBadge.md

@@ -0,0 +1,58 @@
+# LabelBadge
+
+Import: `import { LabelBadge } from "@uxelle/components";`
+
+Pill label with optional leading and trailing icons. Non-interactive; visible text is the accessible name (avoid duplicating it with `aria-label` unless the visible label is abbreviated).
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label (required) | `ReactNode` | `"Label"` | Visible badge text, which is also the accessible name. A string is trimmed and wrapped in `Text` with `type="Condensed Alt"`; pass a `Text` node instead to pick a different type. Empty or whitespace-only renders nothing and warns in development. |
+| emphasis | `"low" \| "high"` | `"low"` | Fill strength: `low` tints the badge background and keeps body-colored text, `high` uses a solid fill with text-on-fill color. Combine with `dataColorSwitcher` to make either strength carry a status color. |
+| dataColorSwitcher | `string` | `—` | Status palette for this badge only, such as `success` for a delivered row. Sets `data-color-switcher` on the root so the fill and text resolve from that palette instead of the surrounding page palette. |
+| "data-color-switcher" | `string` | `—` | Attribute spelling of `dataColorSwitcher`, for call sites that spread DOM props. Wins over `dataColorSwitcher` when both are set. |
+| leadingIcon | `boolean` | `false` | Renders a 12px decorative icon before the label, chosen with `leadingIconName` and `leadingIconVariant`. Those two props have no effect while this is false. |
+| trailingIcon | `boolean` | `false` | Renders a 12px decorative icon after the label, chosen with `trailingIconName` and `trailingIconVariant`. Those two props have no effect while this is false. |
+| leadingIconName | `string` | `"add"` | Material Symbol rendered in the leading slot; applies only when `leadingIcon` is true. |
+| trailingIconName | `string` | `"add"` | Material Symbol rendered in the trailing slot; applies only when `trailingIcon` is true. |
+| leadingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Leading glyph weight: `sharpUnfilled` is outlined, `sharpFilled` is solid. |
+| trailingIconVariant | `"sharpUnfilled" \| "sharpFilled"` | `"sharpUnfilled"` | Trailing glyph weight: `sharpUnfilled` is outlined, `sharpFilled` is solid. |
+| "aria-label" | `string` | `""` | Overrides the visible label as the accessible name. Use it only when the visible text is abbreviated or symbolic; leaving it unset keeps the two in sync. |
+| "aria-labelledby" | `string` | `""` | Space-separated ids of elements that already name this badge elsewhere on the page. Takes the place of `aria-label`. |
+| "aria-describedby" | `string` | `""` | Space-separated ids of elements read after the badge name as supporting detail, such as an explanation of what the status means. |
+| role | `string` | `""` | ARIA role for the root span, which is otherwise a plain generic element. Static badges need none; `status` suits a badge whose text reports changing state. |
+| "aria-live" | `"polite" \| "assertive" \| "off"` | `""` | How updates to the badge text are announced: `polite` waits for a pause, `assertive` interrupts. Leave unset for badges whose text never changes. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<LabelBadge label="Badge" />
+```
+
+```tsx
+<LabelBadge label={<Text type="Overline">Status</Text>} />
+```
+
+```tsx
+<LabelBadge label="Badge" leadingIcon />
+```
+
+```tsx
+<LabelBadge label="Badge" trailingIcon />
+```
+
+```tsx
+<LabelBadge label="Badge" leadingIcon leadingIconName="star" leadingIconVariant="sharpFilled" />
+```
+
+
+## Notes
+
+- **Label:** Pass a string (wrapped as **Text** `type="Condensed Alt"`) or a **Text** node to choose a different type.
+- **Color:** Set `dataColorSwitcher` (or `data-color-switcher`) for status palettes (`success`, `warning`, `danger`, etc.). Low emphasis uses subtle status background + text; high uses fill + text-on-fill.
+- **Accessibility:** Leading/trailing icons are decorative and omitted from the accessibility tree. Pass `aria-label`, `aria-labelledby`, or other attributes via props when needed for context. If the badge carries meaning on an interactive parent, mirror it on that focus target (e.g. `aria-label` on `IconButton`).

package/skills/uxelle-components/LanguageSelector.md

@@ -0,0 +1,38 @@
+# LanguageSelector
+
+Import: `import { LanguageSelector } from "@uxelle/components";`
+
+Language selector dropdown for switching locale in enterprise applications.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| value | `string` | `"EN"` | Language code of the active locale, matched case-insensitively against `options` to pick the code shown on the trigger. Fully controlled — selecting an option only fires `onChange`, so update this value yourself. |
+| onChange | `(code: string) => void` | `—` | Fires with the chosen option's `code` when the user picks a language, and closes the menu. Handle it by switching your locale and passing the new code back as `value`; without it the selection has no effect. |
+| options | `LanguageOption[]` | `LANGUAGE_SELECTOR_DEFAULT_OPTIONS` | Languages listed in the dropdown, each a `{ code, label }` pair rendered as `code – label`. Omit to offer the built-in EN, ES, BR, and DE set. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// With i18n (e.g. react-i18next)
+<LanguageSelector
+  value={i18n.language}
+  onChange={(code) => i18n.changeLanguage(code)}
+  options={[
+    { code: "EN", label: "English" },
+    { code: "ES", label: "Español" },
+  ]}
+/>
+```
+
+
+## Notes
+
+- **Controlled**: Parent owns the current locale (from i18n context, URL, or state) and passes `value`. On selection, `onChange` fires so the parent can update locale and re-render.
+- **Trigger**: Shows current language code and chevron; opens menu on click.
+- **Menu**: List of options in "code – label" format (e.g. "EN – English").

package/skills/uxelle-components/LanguageSelectorButton.md

@@ -0,0 +1,34 @@
+# LanguageSelectorButton
+
+Import: `import { LanguageSelectorButton } from "@uxelle/components";`
+
+Button used as the trigger for the Language Selector dropdown.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| languageCode | `string` | `"EN"` | Short code rendered between the globe and chevron icons, typically two letters such as `EN`. Inside **LanguageSelector** it is supplied automatically from that component's `value`. |
+| open | `boolean` | `false` | Reflects the popup state: the chevron points up and `aria-expanded` becomes true when set, and points down when not. Drive it from the menu's open state so the trigger and popup stay in sync. |
+| "aria-label" | `string` | `""` | Accessible name for the button. The visible content is only a language code, so supply something like `Select language. Current: EN`; **LanguageSelector** sets this for you. |
+| trailingIconName | `string` | `—` | Accepted but never rendered — **Menu** passes it when cloning a trigger, and the chevron is always derived from `open`. Do not set it. |
+
+<!-- prettier-ignore-end -->
+
+Extends `ButtonHTMLAttributes` — supports `disabled`, `onClick`, `className`, etc.
+
+## Usage
+
+```tsx
+<LanguageSelectorButton languageCode="EN" open={isOpen} />
+```
+
+
+## Notes
+
+- **Globe icon**: Leading icon indicating language selection.
+- **Language code**: Displays the current language (e.g. EN, ES).
+- **Chevron**: Trailing icon; points down when closed, up when open.
+- **States**: Uses language-selector theme tokens for hover, pressed, and activated.

package/skills/uxelle-components/Layout.md

@@ -0,0 +1,81 @@
+# Layout
+
+Import: `import { Layout } from "@uxelle/components";`
+
+Flex and grid container with tokenized spacing shortcuts.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| p | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Padding on all four sides. Prefer a theme layout-spacing var (`var(--uxl-theme-layout-spacing-*)`) or `0`; named aliases (`none` | `xs` | `sm` | `md` | `lg` | `xl`), numbers as px, and raw CSS lengths also resolve. |
+| pt | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Padding on the top edge only. Same values as `p`; wins over `pv` and `p`. |
+| pr | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Padding on the right edge only. Same values as `p`; wins over `ph` and `p`. |
+| pb | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Padding on the bottom edge only. Same values as `p`; wins over `pv` and `p`. |
+| pl | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Padding on the left edge only. Same values as `p`; wins over `ph` and `p`. |
+| ph | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Padding on the left and right edges, leaving top and bottom untouched. Same values as `p`; `pl` / `pr` win over it. |
+| pv | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Padding on the top and bottom edges, leaving left and right untouched. Same values as `p`; `pt` / `pb` win over it. |
+| m | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Margin on all four sides. Same values as `p` — a theme layout-spacing var or `0` is preferred over a named alias or raw length. |
+| mt | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Margin on the top edge only. Same values as `p`; wins over `mv` and `m`. |
+| mr | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Margin on the right edge only. Same values as `p`; wins over `mh` and `m`. |
+| mb | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Margin on the bottom edge only. Same values as `p`; wins over `mv` and `m`. |
+| ml | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Margin on the left edge only. Same values as `p`; wins over `mh` and `m`. |
+| mh | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Margin on the left and right edges, leaving top and bottom untouched. Same values as `p`; `ml` / `mr` win over it. |
+| mv | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Margin on the top and bottom edges, leaving left and right untouched. Same values as `p`; `mt` / `mb` win over it. |
+| display | `"block" \| "flex" \| "grid" \| "inline" \| "inline-block" \| "inline-flex" \| "inline-grid"` | `"block"` | CSS `display` for the container, and the switch that decides which layout props are written: flex props apply only for `flex` / `inline-flex`, grid props only for `grid` / `inline-grid`, and `gap` for either. |
+| gap | `"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl"` | `undefined` | Space between flex or grid children, ignored unless `display` is a flex or grid value. Same values as `p`; `rowGap` / `columnGap` override one axis. |
+| width | `string` | `""` | Width of the box (border-box). Numbers become px; strings pass through as CSS (`100%`, `24rem`, `var(--uxl-…)`). Omit to size from content. |
+| height | `string` | `""` | Height of the box (border-box). Numbers become px; strings pass through as CSS. Omit to size from content. |
+| minWidth | `number \| string` | `—` | Floor for the rendered width. Numbers become px; strings pass through as CSS. |
+| minHeight | `number \| string` | `—` | Floor for the rendered height. Numbers become px; strings pass through as CSS. |
+| maxWidth | `number \| string` | `—` | Ceiling for the rendered width, letting the box shrink below `width` on narrow viewports. Numbers become px; strings pass through as CSS. |
+| maxHeight | `number \| string` | `—` | Ceiling for the rendered height. Numbers become px; strings pass through as CSS. |
+| style | `CSSProperties` | `—` | Escape hatch for CSS with no matching prop. Merged after the computed styles, so entries here override `display`, spacing, and size props. |
+| as | `"div" \| "section" \| "main" \| "article" \| "aside" \| "span" \| "nav"` | `"div"` | Tag rendered for the container. Use `section`, `main`, `nav`, `article`, or `aside` to give the box document semantics instead of a generic `div`. |
+| className | `string` | `—` | Extra classes appended after the base `uxl-layout` class, which always stays. |
+| role | `string` | `—` | ARIA role for the container. Reach for it when `as` renders a generic `div` or `span` that needs a landmark or widget role; omit when `as` already carries the right semantics. |
+| "aria-label" | `string` | `—` | Accessible name for a container that has a landmark or widget `role` but no visible text label. Prefer `aria-labelledby` when the name is already on screen. |
+| "aria-describedby" | `string` | `—` | Space-separated ids of elements that describe the container; assistive technology announces them after the name. |
+| "aria-labelledby" | `string` | `—` | Space-separated ids of elements whose text names the container. Wins over `aria-label` and keeps the name in sync with visible copy. |
+| "aria-hidden" | `boolean` | `—` | When true, removes the container and its subtree from the accessibility tree while leaving it visible. Never set it on a box holding focusable elements. |
+| "aria-live" | `"off" \| "polite" \| "assertive"` | `—` | Turns the container into a live region so asynchronous content updates are announced: `polite` waits for a pause, `assertive` interrupts, `off` stops announcements. |
+| "aria-atomic" | `boolean` | `—` | When true, the live region is announced in full on every change instead of just the changed node. Only meaningful alongside `aria-live`. |
+| "aria-relevant" | `"additions" \| "removals" \| "text" \| "all"` | `—` | Which mutations a live region announces — `additions`, `removals`, `text`, or `all`. Only meaningful alongside `aria-live`. |
+| tabIndex | `number` | `—` | Keyboard reachability of the container: `0` puts it in DOM tab order, `-1` makes it focusable only from script. Omit for a non-interactive box. |
+| children | `ReactNode` | `—` | Content the container lays out — the flex or grid items, or arbitrary nodes when `display` is `block`. |
+| flexDirection | `"row" \| "row-reverse" \| "column" \| "column-reverse"` | `"column"` | Main-axis direction for flex children: `row` lays them out horizontally, `column` vertically. Applies only when `display` is `flex` or `inline-flex`. |
+| flexWrap | `"nowrap" \| "wrap" \| "wrap-reverse"` | `"nowrap"` | Whether flex children wrap onto new lines instead of overflowing the main axis. Applies only when `display` is `flex` or `inline-flex`. |
+| justifyContent | `"flex-start" \| "flex-end" \| "center" \| "space-between" \| "space-around" \| "space-evenly" \| "stretch"` | `"flex-start"` | Distribution of flex children along the main axis set by `flexDirection`. Applies only when `display` is `flex` or `inline-flex`. |
+| alignItems | `"flex-start" \| "flex-end" \| "center" \| "baseline" \| "stretch"` | `"stretch"` | Alignment of flex children across the cross axis; `stretch` makes them fill it. Applies only when `display` is `flex` or `inline-flex` — grid containers use `gridAlignItems`. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+// Theme spacing tokens (preferred)
+<Layout display="flex" gap="var(--uxl-theme-layout-spacing-medium-8)" p="var(--uxl-theme-layout-spacing-medium-12)" alignItems="center">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</Layout>
+```
+
+```tsx
+// Grid layout
+<Layout
+  display="grid"
+  gridTemplateColumns="1fr 1fr 1fr"
+  gap="var(--uxl-theme-layout-spacing-medium-12)"
+>
+  <div>Column 1</div>
+  <div>Column 2</div>
+  <div>Column 3</div>
+</Layout>
+```
+
+
+## Notes
+
+- Props map to inline styles (`display`, flex/grid tracks, `gap`, and spacing shortcuts such as `p`, `ph`, `pt`). Prefer theme layout-spacing variables from `LAYOUT_SPACING_VARS` (`var(--uxl-theme-layout-spacing-*)` or `0`) for new UI. Named aliases (`none` | `xs` | `sm` | `md` | `lg` | `xl`) still resolve. Numbers stay px for back-compat; other unit strings pass through. `gap` applies when `display` is flex or grid.

package/skills/uxelle-components/LinearProgress.md

@@ -0,0 +1,53 @@
+# LinearProgress
+
+Import: `import { LinearProgress } from "@uxelle/components";`
+
+Horizontal progress bar with optional label, percentage, and field message.
+
+## Props
+
+<!-- prettier-ignore-start -->
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| progress | `"0" \| "20" \| "40" \| "60" \| "80" \| "100" \| "unknown"` | `0 as const satisfies LinearProgressProgress` | How full the bar is: `0`, `20`, `40`, `60`, `80`, `100`, or `Unknown` to switch to indeterminate. `Success` and `Danger` fill the track regardless and report `100` and `0`; indeterminate ignores the value entirely. |
+| indeterminate | `boolean` | `false` | Runs the sliding animation used when work cannot be measured, dropping `aria-valuenow`. Also on when `progress` is `Unknown`, and forced off once `status` reaches the terminal `Success` or `Danger`. |
+| status | `"Loading" \| "Success" \| "Warning" \| "Danger"` | `"Loading"` | Outcome the bar is reporting. `Loading` and `Warning` stay busy; `Success` and `Danger` are terminal and stop the animation. Drives track color, default label and footer copy, `aria-busy`, `aria-invalid`, and the live status text. |
+| label | `boolean` | `true` | Renders the label row above the bar and names the progressbar through `aria-labelledby`. Also gates `labelSlot` and `fieldDescription`; with `false`, pass `aria-label` or `aria-labelledby` so the bar is not left unnamed. |
+| required | `boolean` | `false` | Adds the required asterisk to the built-in `Label`. Visual only — a progressbar is not a form control, so no `aria-required` is emitted. |
+| disabled | `boolean` | `false` | Applies disabled styling to the built-in `Label` only. The bar keeps animating and stays exposed to assistive technology. |
+| labelSlot | `ReactNode` | `—` | Your own label region (typically a **Label**) in place of the built-in one, suppressing `labelTitle` and the supporting line. Still requires `label` to be `true`, and you must wire `aria-label` or `aria-labelledby` yourself. |
+| labelTitle | `string` | `""` | Headline in the built-in label row, and the source of the progressbar's accessible name. An empty string falls back to sample copy for the current `status`; ignored when `labelSlot` is set. |
+| fieldDescriptionContent | `string` | `""` | Supporting sentence under `labelTitle`. An empty string falls back to sample copy for the current `status`, and the line is linked with `aria-describedby` only when both it and `labelTitle` resolve to text. |
+| fieldDescription | `boolean` | `true` | Shows the supporting line under `labelTitle`. Only takes effect while `label` is true; false hides that line without touching the footer message. |
+| percentage | `boolean` | `true` | Shows the numeric percent column beside the track. Decorative only — the value is always exposed through `aria-valuenow` — and suppressed while indeterminate or when `status` is `Danger`. |
+| fieldMessage | `boolean` | `true` | Renders the footer message row below the bar and links it to the progressbar with `aria-describedby`. Keep it on for indeterminate and `Danger`, which carry the only text describing the outcome; turning it off warns in development. |
+| fieldMessageContent | `string` | `""` | Footer message text. An empty string falls back to sample copy for the current `status`; ignored when `fieldMessageSlot` replaces the footer. |
+| fieldMessageSlot | `ReactNode` | `—` | Your own footer content in place of the built-in **FieldMessage**. Still requires `fieldMessage` to be `true`; the wrapper carries the `id` the progressbar points at with `aria-describedby`. |
+| messageType | `"Info" \| "Success" \| "Warning" \| "Danger"` | `FIELD_MESSAGE_DEFAULTS.messageType` | Icon and tone for the built-in footer message. Omit to follow `status` (`Loading` maps to `Info`); ignored when `fieldMessageSlot` replaces the footer. |
+| "aria-label" | `string` | `""` | Accessible name on the progressbar when the built-in label is hidden or insufficient (`label={false}`, `labelSlot`). Omit when `labelTitle` wires `aria-labelledby`. |
+| "aria-labelledby" | `string` | `""` | Extra element IDs merged into progressbar `aria-labelledby` (space-separated). Built-in label id is added automatically. |
+| "aria-describedby" | `string` | `""` | Extra element IDs merged into progressbar `aria-describedby` (space-separated). Supporting copy and footer ids are added automatically. |
+| role | `string` | `""` | ARIA role on the track element. Defaults to `progressbar`; override only for exceptional cases. |
+| "aria-live" | `"polite" \| "assertive" \| "off"` | `""` | Politeness of the visually hidden status live region. Unset uses `polite` (recommended). |
+| className | `string` | `""` | Extra class names appended to the root wrapper. The track, label row, and footer keep their own classes and are not affected. |
+
+<!-- prettier-ignore-end -->
+
+## Usage
+
+```tsx
+<LinearProgress progress={40} status="Loading" labelTitle="Uploading report" />
+```
+
+```tsx
+<LinearProgress progress="Unknown" indeterminate status="Loading" />
+```
+
+
+## Notes
+
+- Determinate and indeterminate modes; Loading, Success, Warning, and Danger states.
+- **Simple API** — toggle `label`, `percentage`, and `fieldMessage`; set `progress` and `status`.
+- **Composable API** — `labelSlot` and `fieldMessageSlot` replace the built-in regions.
+- **Accessibility**: Most ARIA is automatic: built-in `label`/`fieldMessage` wire `aria-labelledby` / `aria-describedby`; the track exposes `role="progressbar"`, value attrs, `aria-busy`, and `aria-invalid`; status updates use a polite live region. Pass `aria-label`, `aria-labelledby`, or `aria-describedby` only when hiding the built-in label, using slots, or supplementing associations. Keep `fieldMessage` for indeterminate and error outcomes.