srcdev-nuxt-components 9.4.11 → 9.5.0

package/.claude/skills/components/input-checkbox-radio.md

@@ -0,0 +1,149 @@
+# InputCheckboxRadio Component
+
+> **Renamed 2026-09-27**: `InputCheckboxRadioCore` → `InputCheckboxRadio`,
+> `InputCheckboxRadioWithLabel` → `InputCheckboxRadioField`; `InputCheckboxRadioButton` kept its
+> name. Root classes: `.input-checkbox-radio-wrapper` → `.input-checkbox-radio`,
+> `.input-checkbox-radio-with-label` → `.input-checkbox-radio-field`,
+> `.input-checkbox-radio-options-button` → `.input-checkbox-radio-button` (full list in
+> CONSUMER-STYLING.md). Tokens unchanged.
+
+## Overview
+
+The single checkbox or radio control that every checkbox and radio in `05.forms` is built from.
+Consumers normally use the group components instead:
+
+- `MultipleCheckboxes` / `SingleCheckbox` (`input-checkbox.md`)
+- `MultipleRadiobuttons` (`input-radio.md`)
+
+Use these three directly only for a custom group or layout:
+
+| Component | Renders | Used by |
+|---|---|---|
+| `InputCheckboxRadio` | The visual square/circle stacked over a hidden native `<input>`. No label. | The other two |
+| `InputCheckboxRadioField` | `<label>` with the control and a text label | `SingleCheckbox`, non-button `MultipleCheckboxes`/`MultipleRadiobuttons` |
+| `InputCheckboxRadioButton` | `<label>` drawn as a button/pill: control, centred label, decorator icon | `is-button` mode of the group components |
+
+```vue
+<InputCheckboxRadioField v-model="state.rememberMe" type="checkbox" name="rememberMe" label="Remember me" />
+
+<InputCheckboxRadioButton
+  v-for="option in options"
+  :id="`service-${option.value}`"
+  :key="option.value"
+  v-model="state.services"
+  type="checkbox"
+  name="services"
+  :label="option.label"
+  :true-value="option.value"
+  :multiple-options="true"
+  :is-pill="true"
+/>
+```
+
+---
+
+## InputCheckboxRadio (the control)
+
+> **Hyphenation rule**: write camelCase props hyphenated: `:true-value`, `:false-value`, `:multiple-options`, `:field-has-error`, `:aria-describedby`, `:display-as-disc`, `:is-button`, `:input-variant`, `:style-class-passthrough`.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `type` | `"checkbox" \| "radio"` | required | Can change at runtime: the input is keyed on it, so it's recreated with the right v-model handling. |
+| `id` | `string` | required | Native input id; pair it with a `label[for]`. |
+| `name` | `string` | required | Share one `name` across a radio group. |
+| `:true-value` / `:false-value` | `string \| number \| boolean` | `true` / `false` | Checked / unchecked value. `trueValue` is also the native `value`. |
+| `:multiple-options` | `boolean` | `false` | Part of a checkbox group (array model). Also drops native `required` (a group can't require every box). |
+| `:required` | `boolean` | `false` | Native `required` (unless `multiple-options`). |
+| `:field-has-error` | `boolean` | `false` | `aria-invalid="true"` on the input, `data-invalid` on the root. |
+| `:aria-describedby` | `string` | `""` | On the input, omitted when empty. |
+| `theme` | `FormUiTheme` | `"default"` | `data-theme`. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | `data-input-variant`; `underlined` squares off a checkbox. |
+| `:is-button` | `boolean` | `false` | Set by `InputCheckboxRadioButton`: no focus outline of its own, enables `display-as-disc`. |
+| `:display-as-disc` | `boolean` | `false` | Rounds a checkbox, button mode only. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | On the root, reacts to changes. |
+
+`v-model` (**required**): a single value, or an array for a checkbox group (the control toggles its
+`trueValue` in and out of the array).
+
+Slot: `checkedIcon` replaces the default icon (`material-symbols:check-small`, or
+`material-symbols:circle` for radios) shown when checked.
+
+---
+
+## Variants
+
+### InputCheckboxRadioField
+
+Same props as the control minus `id`, `isButton`; plus `label?: string` (`""`). Generates its own
+id with `useId()` and links the `<label for>` to it. Slots: `checkedIcon` (forwarded),
+`labelContent` (replaces the `label` text, e.g. a label containing a terms link). Root
+`<label class="input-checkbox-radio-field">` with `data-invalid`.
+
+### InputCheckboxRadioButton
+
+Same props as the control minus `isButton` (always on), plus:
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `id` | `string` | required | Used for both the input and `label[for]`. |
+| `label` | `string` | `""` | Replaced by the `labelContent` slot when given. |
+| `:options-layout` | `OptionsLayout` | `"equal-widths"` | `data-options-layout`; `inline` stops the label wrapping. |
+| `direction` | `"row" \| "row-reverse"` | `"row"` | `data-direction`; `row-reverse` puts the control on the right. Reacts to changes. |
+| `:is-pill` | `boolean` | `false` | `data-pill`, fully rounded. |
+| `:item-icon` | `string` | `"material-symbols:add-2"` | Decorator icon name. The `itemIcon` slot replaces it entirely. |
+
+Slots: `checkedIcon`, `labelContent`, `itemIcon`.
+
+---
+
+## Accessibility
+
+- A real native `<input type="checkbox|radio">` does the work: native checked state, keyboard
+  (Space; arrow keys within a same-`name` radio group), form validation. It's visually hidden with
+  `opacity: 0` and sized to the visible box, so it's still what gets clicked and focused.
+- No `aria-checked` on the input: it's a native checkbox/radio, and ARIA in HTML forbids
+  `aria-checked` there (the native state is what's announced).
+- Focus: the control draws an outline on `:has(input:focus-visible)`; the button draws its own
+  background and outline change instead.
+- The Field and Button are `<label>` elements, so the whole row is clickable and labels the input.
+  The decorator icon is `aria-hidden`.
+- Transitions are off under `prefers-reduced-motion: reduce`.
+- No hardcoded copy; the icon names are props or slots.
+
+---
+
+## Styling
+
+Full detail in `app/components/05.forms/input-checkbox-radio/CONSUMER-STYLING.md`. Tokens:
+`--input-checkbox-*` (control colours, label colour/padding, transition duration) and
+`--input-checkbox-button-*` (button colours, radius, pill radius, gap, paddings); shared geometry
+`--input-checked-element-size`, `--input-checked-icon-size`, `--input-checked-icon-gap`,
+`--input-checkbox-decorator-icon-size`. Hooks: `data-type`, `data-input-variant`, `data-theme`,
+`data-button`, `data-display-as-disc`, `data-invalid`, `data-pill`, `data-direction`,
+`data-options-layout`.
+
+---
+
+## History
+
+**Migrated 2026-09-27** (3/5 → full compliance):
+
+- Renamed (see top). Every state class became a data attribute (`.error`, `.button`, `.checkbox`,
+  `.inline` etc. collided with common consumer CSS).
+- A runtime `type` switch left the checkbox v-model handler attached to the input, so a radio kept
+  toggling values in the old array; the input is now keyed on `type`.
+- Removed `aria-checked` from the native input (and the `isChecked` computed that only fed it) and
+  the `is-button` input class, which nothing styled.
+- `direction` on the button was copied into a plain `ref` at setup, so changing it did nothing; now
+  `data-direction`.
+- The decorator icon and the button's checked icon were sized with `width`/`height` (ignored,
+  pitfall #24); now `font-size`, so they change size for the first time.
+- The Field no longer takes `id` or `optionsLayout` (its id is always generated; the layout class
+  set a variable nothing read); the group components stopped passing them, so the id no longer
+  falls through onto the `<label>`. Removed its non-existent `body-normal*` utility classes.
+  `label` is optional on both Field and Button.
+- The button forwards `inputVariant` (the group components already passed it, but it fell through
+  as an attribute). New `itemIcon` prop.
+- Button radius, gap, paddings and the Field label colour became tokens; label colour default moved
+  from `--colour-text-default` to `--theme-text`. Removed an undeclared `--_box-shadow` and an
+  invalid unitless `min-height`.

package/.claude/skills/components/input-checkbox.md

@@ -0,0 +1,148 @@
+# MultipleCheckboxes / SingleCheckbox Components
+
+## Overview
+
+The `input-checkbox` folder holds two ready-to-use checkbox fields. Each renders a `FormFieldset`
+(with `<legend>`), an optional description, the checkbox control(s), and an `InputError` message,
+with `aria-describedby` wired up via `useAriaDescribedById`.
+
+- **MultipleCheckboxes**: a group of checkboxes built from a data list (`v-model:field-data`).
+  The model is an array of the checked items' values. Each option renders as either a pill/button
+  (`InputCheckboxRadioButton`, `:is-button="true"`) or a plain labelled checkbox
+  (`InputCheckboxRadioField`, the default).
+- **SingleCheckbox**: one labelled checkbox (e.g. "I agree to the terms"). The model toggles
+  between `trueValue` and `falseValue`.
+
+For a group where only one option can be chosen, use `MultipleRadiobuttons` (`input-radio`)
+instead.
+
+---
+
+## MultipleCheckboxes
+
+> **Hyphenation rule**: always write camelCase props hyphenated in templates: `:field-has-error`, `:is-button`, `:options-layout`.
+
+| Prop (template form) | Type | Default | Notes |
+|---|---|---|---|
+| `name` | `string` | (required) | Shared `name` on every checkbox; also used to build each checkbox `id` (`${name}-${item.value}`) and the error/description ids. |
+| `legend` | `string` | (required) | Fieldset `<legend>` text. |
+| `:error-message` | `string \| object` | (required) | Shown by `InputError` when `fieldHasError` is true. Pass `""` when there's no error. An array renders as a list. |
+| `:field-has-error` | `boolean` | `false` | Shows the error, sets `aria-invalid` on the fieldset and points each checkbox's `aria-describedby` at the error. |
+| `:required` | `boolean` | `false` | No ARIA output: `aria-required` isn't valid on a checkbox group (`role="group"`), so it was dropped from the fieldset 2026-09-26. Signal "required" in the legend text instead (e.g. "Interests (required)"). Native `required` is deliberately **not** put on the individual checkboxes, since that would force every box to be ticked. Validate "at least N selected" in the consuming app. |
+| `:is-button` | `boolean` | `false` | Pill/button presentation (`InputCheckboxRadioButton`) instead of labelled checkboxes. |
+| `:is-pill` | `boolean` | `false` | With `is-button`, fully rounded pills. |
+| `:options-layout` | `OptionsLayout` | `"equal-widths"` | `"equal-widths"` (auto-fit grid, columns sized to the longest label), `"inline"` (wrapping row) or `"block"` (column). Rendered as `data-options-layout` on the items container (was a bare class until 2026-09-27). |
+| `:direction` | `"row" \| "row-reverse"` | `"row"` | Button presentation only: icon/label order. |
+| `:display-as-disc` | `boolean` | `false` | Round checkbox symbol. |
+| `:theme` | `FormUiTheme` | `"default"` | Forwarded to each control. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Forwarded to each control and the error message. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Classes on the root `<fieldset>`. Read once at mount. |
+| `data-testid` | `string` | `"multiple-checkboxes"` | On the root `<fieldset>`. |
+| `label` | `string` | `""` | **Ignored.** Kept only so existing call sites that pass it don't break; it has never rendered. Use `legend` or the description slots. |
+
+### v-models
+
+- `v-model`: `(string | number | boolean)[]`, **required**. Bind an array (start with `[]`); checked values are added and removed from it.
+- `v-model:field-data`: `IFormMultipleOptions` (`{ data: IOptionsConfig[]; total; skip; limit }`), **required**. Each `data` item's `value` is the checkbox value and `label` its text.
+
+### Slots
+
+| Slot | Notes |
+|---|---|
+| `descriptionText` / `descriptionHtml` | Description under the legend (via `InputDescription`). |
+| `checkedIcon` | Replaces the checked-state icon in every control. |
+| `itemIcon` | Button presentation only: the trailing decorator icon (default `material-symbols:add-2`). |
+
+### Example
+
+```vue
+<MultipleCheckboxes
+  v-model="state.services"
+  v-model:field-data="servicesData"
+  name="services"
+  legend="Services of interest"
+  :error-message="errors.services"
+  :field-has-error="!!errors.services"
+  options-layout="inline"
+  :is-button="true"
+/>
+```
+
+---
+
+## SingleCheckbox
+
+| Prop (template form) | Type | Default | Notes |
+|---|---|---|---|
+| `name` | `string` | (required) | Checkbox `name`; also used for the error/description ids. |
+| `legend` | `string` | (required) | Fieldset `<legend>` text. |
+| `label` | `string` | `""` | Text next to the checkbox. Replaced by the `labelContent` slot when given. |
+| `:error-message` | `string \| object` | (required) | Pass `""` when there's no error. |
+| `:field-has-error` | `boolean` | `false` | Shows the error, sets `aria-invalid` on the fieldset and the checkbox's `aria-describedby`. |
+| `:required` | `boolean` | `false` | Native `required` on the checkbox. (The fieldset no longer gets `aria-required`, see above.) |
+| `:true-value` / `:false-value` | `string \| number \| boolean` | `true` / `false` | Model values for checked/unchecked. |
+| `:options-layout` | `OptionsLayout` | `"equal-widths"` | Rendered as `data-options-layout` on the items container. |
+| `:theme` | `FormUiTheme` | `"default"` | |
+| `:input-variant` | `InputUiVariant` | `"normal"` | |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Classes on the root `<fieldset>`. Read once at mount. |
+| `data-testid` | `string` | `"single-checkbox"` | On the root `<fieldset>`. |
+
+### v-model
+
+- `v-model`: `string | number | boolean`, **required**. Toggles between `trueValue` and `falseValue`. Works with `@update:model-value` for save-on-change settings toggles.
+
+### Slots
+
+`descriptionText` / `descriptionHtml`, `checkedIcon`, and `labelContent` (rich label, e.g. a
+terms link).
+
+### Example
+
+```vue
+<SingleCheckbox
+  v-model="state.terms"
+  name="terms"
+  legend="Terms and conditions"
+  label="I agree to the terms"
+  :required="true"
+  :error-message="errors.terms"
+  :field-has-error="!!errors.terms"
+/>
+```
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../../app/components/05.forms/input-checkbox/CONSUMER-STYLING.md).
+These components own only the items-container spacing (`--multiple-checkboxes-gap`,
+`--multiple-checkboxes-margin-block-start`, `--single-checkbox-gap`,
+`--single-checkbox-margin-block-start`, `--single-checkbox-column-min-width`). The checkbox
+controls' own colours are the `--input-checkbox-*` tokens in `input-checkbox-radio`.
+
+---
+
+## Migration notes (2026-09-25)
+
+Brought to full compliance. Behaviour changes a consumer could notice:
+
+- **MultipleCheckboxes no longer puts native `required` on every checkbox.** Previously each box
+  got `required`, so a form without `novalidate` would refuse to submit until every option was
+  ticked. `InputCheckboxRadioField`/`InputCheckboxRadioButton` now forward `multipleOptions`
+  to `InputCheckboxRadio` (they declared it but dropped it), and `MultipleCheckboxes` passes
+  `true`.
+- **SingleCheckbox `styleClassPassthrough` now lands on the root `<fieldset>`**, matching
+  `MultipleCheckboxes`. It was being applied to the error message.
+- **SingleCheckbox default `data-testid` is now `"single-checkbox"`** (was a copy-paste
+  `"multiple-radio-buttons"`).
+- Removed never-used props: `placeholder`, `multipleOptions`, `equalCols` (MultipleCheckboxes);
+  `multipleOptions`, `equalCols` (SingleCheckbox). MultipleCheckboxes' `label` became optional
+  and stays ignored.
+- Removed SingleCheckbox's dead `watchEffect` that tried to add `mbs-12` to the error message (it
+  never reached the DOM, since `InputError` reads its classes once at mount).
+- Both `v-model`s (and `v-model:field-data`) are now `defineModel({ required: true })`.
+- Items-container spacing is now overridable via the public tokens above (defaults unchanged).
+
+Fixed 2026-09-26 (FormFieldset migration): the shared `FormFieldset` used to hardcode
+`role="radiogroup"`, so screen readers announced checkbox groups as radio groups. It now defaults
+to the native fieldset `group` role; only `MultipleRadiobuttons` opts into `radiogroup`.

package/.claude/skills/components/input-description.md

@@ -0,0 +1,102 @@
+# InputDescription Component
+
+## Overview
+
+`InputDescription` renders a form field's help text. Every `*Field` wrapper in `05.forms`
+(`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`, `InputTextareaWithLabel`,
+`InputRangeDefault`, `InputTextAsNumberWithLabel`, `SingleCheckbox`, `MultipleCheckboxes`,
+`MultipleRadiobuttons`) already renders one and forwards its own `descriptionText` /
+`descriptionHtml` slots into it, so consumers normally just pass those slots to the wrapper:
+
+```vue
+<InputTextWithLabel v-model="email" name="email" label="Email" :field-has-error :error-message>
+  <template #descriptionText>We'll only use this for your booking confirmation</template>
+</InputTextWithLabel>
+```
+
+Use `InputDescription` directly only when building a custom field wrapper.
+
+With neither slot provided it renders nothing (no empty element, no dangling id).
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: write camelCase props hyphenated in templates: `:description-id`, `:field-has-error`, `:input-variant`, `:style-class-passthrough`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:description-id` | `string` | `""` | Rendered as the root `id`, omitted when empty. Must match the id in the control's `aria-describedby`; wrappers get it from `useAriaDescribedById(...).descriptionId`, which only adds it to `aria-describedby` when a description slot is present. |
+| `:field-has-error` | `boolean` | `false` | Rendered as `data-invalid`. Styling hook only. |
+| `:input-variant` | `"normal" \| "outlined" \| "underlined"` | `"normal"` | Rendered as `data-input-variant`. Styling hook only. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root, reacts to prop changes. |
+
+## Slots
+
+| Slot | Rendered in | Notes |
+|------|-------------|-------|
+| `descriptionHtml` | `<div class="input-description-html">` | Rich markup (lists, links). Rendered first. |
+| `descriptionText` | `<p class="input-description-text">` | Plain text only (it's inside a `<p>`, so no block elements). |
+
+**Forwarding slots from a wrapper**: only forward a slot when your own consumer provided it,
+otherwise `InputDescription` sees an (empty) slot and renders an empty element:
+
+```vue
+<InputDescription :description-id :input-variant :field-has-error>
+  <template v-if="slots.descriptionHtml" #descriptionHtml><slot name="descriptionHtml"></slot></template>
+  <template v-if="slots.descriptionText" #descriptionText><slot name="descriptionText"></slot></template>
+</InputDescription>
+```
+
+---
+
+## Accessibility
+
+- It's a plain description, not a live region: link it with `aria-describedby` on the control
+  (`useAriaDescribedById` does this in every wrapper).
+- `InputTextWithLabel`, `InputSelectWithLabel` and `InputTextareaWithLabel` render it **after**
+  the control for the `outlined` variant and before it otherwise; both positions carry the same id.
+
+---
+
+## Styling
+
+Full token table in `app/components/05.forms/input-description/CONSUMER-STYLING.md`. Public
+tokens: `--input-description-color`, `--input-description-font-size`,
+`--input-description-line-height`, `--input-description-slot-margin-block-start|end`,
+`--input-description-slot-margin-inline`; panel tokens on the root (matching `FormFieldset`):
+`--input-description-background-color`, `--input-description-margin-block|inline`,
+`--input-description-padding-block|inline`, `--input-description-border`,
+`--input-description-border-radius`, `--input-description-outline|outline-offset`. For a callout
+look, zero the slot margins and space it with the root margins (example in CONSUMER-STYLING.md). Hooks:
+`data-input-variant`, `data-invalid`.
+
+
+---
+
+## History
+
+**Migrated 2026-09-26** (1/5 → full compliance):
+
+- Wrappers forwarded both description slots unconditionally, so every field rendered an empty
+  description element (with its id) even when no description was given. Each wrapper now forwards
+  a slot only when its own consumer supplied it.
+- `InputTextWithLabel` and `InputSelectWithLabel` rendered the description **twice** for the
+  `outlined` variant (before and after the control); the first copy now has
+  `v-if="inputVariant !== 'outlined'"`, matching `InputTextareaWithLabel`.
+- The outlined-variant copies had no `description-id`, so the control's `aria-describedby`
+  pointed at an id that didn't exist. They now pass it.
+- Removed props that were never read: `id` (a leftover from a commented-out id computation) and
+  `theme`. Wrappers also stopped passing `name`, which wasn't a prop and fell through as an
+  invalid `name` attribute on the `<div>`.
+- `inputVariant` and `fieldHasError` (previously accepted but unused) now render as
+  `data-input-variant` / `data-invalid` styling hooks.
+- Colour read `--form-description-color`, which was never declared anywhere; replaced by
+  `--input-description-color` (defaults to `inherit`, same visual result). Font size, line height
+  and margins promoted to public tokens with the old values as defaults.
+- Added root panel tokens (background, margin, padding, border, radius, outline) matching
+  `FormFieldset`. Removed `InputLabel`'s `.input-label + .input-description { margin-block-end: 0.2rem }`
+  rule, which overrode the root margin token (no visual change by default: the slot's `0.8rem`
+  bottom margin collapsed through and won anyway).
+- An empty `descriptionId` no longer renders `id=""`. `styleClassPassthrough` now reacts to prop
+  changes.

package/.claude/skills/components/input-error.md

@@ -0,0 +1,105 @@
+# InputError Component
+
+## Overview
+
+`InputError` renders the red error message strip under a form control. Every `*Field` wrapper in
+`05.forms` (`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`, `InputTextareaWithLabel`,
+`InputRangeDefault`, `ToggleSwitchWithLabel`, `SingleCheckbox`, `MultipleCheckboxes`,
+`MultipleRadiobuttons`, `InputTextAsNumberWithLabel`) already renders one, so consumers rarely use
+it directly. Use it yourself only when building a custom field wrapper.
+
+It is designed to sit in **grid row 2** of the wrapper, directly under the control in row 1: it is
+translated up by the control's border width + radius so an attached error tucks under the
+control's bottom edge. It opens with a `grid-template-rows: 0fr → 1fr` + opacity transition.
+
+Its root carries `data-theme="error"`, so the red `--theme-*` ramp applies inside it regardless of
+the surrounding theme.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: write camelCase props hyphenated in templates: `:error-message`, `:show-error`, `:is-detached`, `:input-variant`, `:style-class-passthrough`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | (required) | Must match an id in the control's `aria-describedby` while in error. Wrappers get it from `useAriaDescribedById(...).errorId`, which only adds it to `aria-describedby` when `fieldHasError` is true. |
+| `:error-message` | `string \| string[] \| object` | (required) | A string renders as one message; an array renders as a `<ul>` list. |
+| `:show-error` | `boolean` | (required) | Opens the strip. Rendered as `data-visible`; when `false` the root gets `aria-hidden="true"`. |
+| `:is-detached` | `boolean` | (required) | `true`: sits below the control with a `2rem` gap, fully rounded. `false`: tucked under the control's bottom edge. Rendered as `data-detached`. |
+| `:input-variant` | `"normal" \| "outlined" \| "underlined"` | `"normal"` | Match the control's variant. Rendered as `data-input-variant`. `underlined` drops the rounded corners and (when attached) the outline. |
+| `icon` | `string` | `"radix-icons:circle-backslash"` | Iconify name for the decorative icon (`aria-hidden`). |
+| `data-testid` | `string` | `"inputError"` | |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root, reacts to prop changes. |
+
+No slots.
+
+---
+
+## Usage (inside a custom field wrapper)
+
+```vue
+<template>
+  <div class="my-field">
+    <input :id :aria-describedby :aria-invalid="fieldHasError" />
+    <InputError :id="errorId" :error-message :show-error="fieldHasError" :is-detached="false" :input-variant />
+  </div>
+</template>
+
+<script setup lang="ts">
+const { id, errorId, ariaDescribedby } = useAriaDescribedById(props.name, toRef(props, "fieldHasError"), useSlots());
+</script>
+
+<style>
+.my-field {
+  display: grid;
+  grid-template-rows: auto auto;
+}
+</style>
+```
+
+---
+
+## Accessibility
+
+- The message is exposed through the control's `aria-describedby`, not a live region, so it's
+  read when the control is focused. Moving focus to the first invalid field on submit is the
+  form's job (see `FormWrapper` / pattern forms).
+- Hidden errors are `aria-hidden="true"`; the icon is always `aria-hidden`.
+- The open/close transition is disabled under `prefers-reduced-motion: reduce`.
+
+---
+
+## Styling
+
+Full token table in `app/components/05.forms/form-errors/CONSUMER-STYLING.md`. Public tokens:
+`--input-error-text-color`, `--input-error-icon-color`, `--input-error-icon-size`,
+`--input-error-background-color`, `--input-error-border-color`, `--input-error-outline-color`,
+`--input-error-border-radius`, `--input-error-font-family|size|weight`,
+`--input-error-padding-inline`, `--input-error-padding-block-start|end`, `--input-error-list-gap`,
+`--input-error-detached-offset`, `--input-error-margin-block-start`,
+`--input-error-transition-duration`.
+
+Set them on an ancestor, not the global `--theme-error-*` tokens: the root's `data-theme="error"`
+re-declares those on the element itself, so ancestor overrides of them never land.
+
+---
+
+## History
+
+**Migrated 2026-09-26** (1/5 → full compliance):
+
+- State moved from bare classes (`.show`, `.detached`, `.normal`/`.outlined`/`.underlined`) to
+  `data-visible`, `data-detached`, `data-input-variant`; inner elements renamed from generic
+  `.inner`/`.inner-content`/`.inner-icon`/`.icon`/`.message`/`.message-*` to
+  `.input-error-message-*`. It renders inline in the consumer's DOM, so those names collided with
+  consumer CSS (pitfall #16).
+- Removed the unused `compact` prop (declared, never read, never passed).
+- Added the `icon` prop.
+- Removed dead CSS: detached-state border colours (including a hardcoded `--red-08` bottom border)
+  only applied while hidden at `opacity: 0` and were overridden by the visible-state border, and a
+  top-level `.underlined` outline rule that the visible state always overrode.
+- Hardcoded `white` on the icon and list items replaced by the text-colour token (same default).
+  Hardcoded font size/weight, padding, list gap and detached gap promoted to public tokens.
+- `aria-hidden` now omitted when visible (was `"false"`); icon marked `aria-hidden`;
+  `prefers-reduced-motion` respected; `styleClassPassthrough` now reacts to prop changes.

package/.claude/skills/components/input-label.md

@@ -0,0 +1,119 @@
+# InputLabel Component
+
+## Overview
+
+`InputLabel` renders a form field's `<label>`. Every labelled wrapper in `05.forms`
+(`InputTextWithLabel`, `InputTextAsNumberWithLabel`, `InputNumberField`, `InputSelectWithLabel`,
+`InputTextareaWithLabel`, `InputRangeDefault`, `ToggleSwitchWithLabel`,
+`ToggleSwitchWithLabelInline`) already renders one from its `label` prop, so consumers normally
+never use it directly.
+
+Use `InputLabel` directly only when building a custom field wrapper:
+
+```vue
+<InputLabel :id="inputId" :input-variant :field-has-error>
+  <template #textLabel>{{ label }}</template>
+</InputLabel>
+```
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: write camelCase props hyphenated in templates: `:required-text`, `:optional-icon`, `:field-has-error`, `:input-variant`, `:style-class-passthrough`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | required | The **control's** id, rendered as the label's `for`. The label itself gets no id. Must match the id actually on the `<input>`/`<select>`/`<textarea>` (e.g. `ToggleSwitchCore` prefixes its input id with `toggle-switch-`, so its wrappers pass `toggleSwitchId`). |
+| `:required` | `boolean` | `false` | Whether the field is required. Only decides which fields the indicator marks; it doesn't set `required` on the control. Wrappers forward their own `required`. |
+| `:indicator` | `"none" \| "required" \| "optional"` | `undefined` → app.config → `"none"` | Which fields get a marker. |
+| `:required-text` | `string` | `undefined` → app.config → `"*"` | Required marker text. |
+| `:optional-text` | `string` | `undefined` → app.config → `"(optional)"` | Optional marker text (translatable). |
+| `:required-icon` | `string` | `undefined` → app.config → none | Iconify name that replaces the required text. |
+| `:optional-icon` | `string` | `undefined` → app.config → none | Iconify name that replaces the visible optional text (the text stays as `.sr-only`). |
+| `:field-has-error` | `boolean` | `false` | Rendered as `data-invalid`. Styling hook only. |
+| `:input-variant` | `"normal" \| "outlined" \| "underlined"` | `"normal"` | Rendered as `data-input-variant`. Styling hook only. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the `<label>`, reacts to prop changes. |
+
+## Slots
+
+| Slot | Notes |
+|------|-------|
+| `htmlLabel` | Rich markup (e.g. a required marker). Rendered first. Phrasing content only: it's inside a `<label>`, so no interactive elements. |
+| `textLabel` | Plain label text. |
+
+Both render directly inside the `<label>`, no wrapper elements. Don't hardcode a required
+asterisk in a slot: use the indicator below.
+
+---
+
+## Required / optional indicator
+
+Resolution for every indicator prop: **explicit prop → `app.config` `srcdev.inputLabel.*` → fallback**.
+Consumers normally set it once site-wide and never touch the props:
+
+```ts
+// consumer app.config.ts
+export default defineAppConfig({
+  srcdev: { inputLabel: { indicator: "required", requiredIcon: "mdi:asterisk" } },
+});
+```
+
+- `"required"` mode: a marker on fields with `required`; `"optional"` mode: a marker on fields
+  without it; `"none"`: nothing (default, so existing sites are unchanged).
+- `InputTextWithLabel`, `InputTextAsNumberWithLabel`, `InputNumberField`, `InputSelectWithLabel`,
+  `InputTextareaWithLabel` and `InputRangeDefault` forward `:required`.
+  `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline` pass `indicator="none"`: a switch always
+  has a value, so neither marker means anything there.
+- The wrappers don't expose the indicator props per field; use `app.config`.
+- Text props are the i18n hook: pass translated `optionalText`/`requiredText` (or set them in
+  `app.config`).
+
+---
+
+## Accessibility
+
+- The `for`/`id` pairing is the accessible name for the control. If the ids don't match, the
+  control has no name and clicking the label does nothing; check this whenever the control
+  component derives its own id from the one you pass it.
+- The required marker is `aria-hidden`: the control's own `required` attribute is what screen
+  readers announce, so the control must actually carry it. The optional marker is announced, and
+  keeps its text as `.sr-only` when an icon replaces it.
+
+---
+
+## Styling
+
+Full token table in `app/components/05.forms/input-label/CONSUMER-STYLING.md`. Public tokens:
+`--input-label-color` (defaults to `inherit`),
+`--input-label-font-size`, `--input-label-font-weight`, `--input-label-line-height`,
+`--input-label-margin-block`, `--input-label-margin-inline`; indicator:
+`--input-label-indicator-color[-required|-optional]`, `--input-label-indicator-font-size[-required|-optional]`,
+`--input-label-indicator-font-weight`, `--input-label-indicator-gap`, `--input-label-indicator-icon-size`.
+Hooks: `data-input-variant`, `data-invalid`, `.input-label-indicator[data-indicator]`.
+
+---
+
+## History
+
+**Migrated 2026-09-26** (1/5 → full compliance):
+
+- Removed props that were never read: `name` and `theme`. Wrappers stopped passing them.
+- Wrappers also passed a non-prop `:for`, which fell through and overrode the `for` built from
+  `id`. For the text/number/select/textarea/range wrappers it was the same value (dropped). For
+  `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline` it was the only thing pointing the label
+  at the real input (`toggle-switch-<id>`); they now pass `:id="toggleSwitchId"` explicitly.
+- `inputVariant` moved from a bare class (`.normal`/`.underlined`, whose rules were duplicates of
+  the base rule) to `data-input-variant`. `fieldHasError` (accepted but unused) now renders
+  `data-invalid`.
+- Colour, font size, font weight, line height and margins are public tokens with the old values
+  as defaults. The colour used to read `--form-label-color`, never declared in this library;
+  replaced by `--input-label-color` (defaults to `inherit`, same visual result).
+- Removed the unused `--field-label-*`, `--field-description-*`, `--field-error-*` and
+  `--input-line-height` globals from `04.elements/forms/02.typography.css`, left over from before
+  the per-component token pattern.
+- `styleClassPassthrough` now reacts to prop changes.
+
+**2026-09-27**: added the required/optional indicator (`required`, `indicator`, `requiredText`,
+`optionalText`, `requiredIcon`, `optionalIcon`, all app.config-backed under `srcdev.inputLabel`),
+with wrappers forwarding `:required`.