srcdev-nuxt-components 9.4.11 → 9.5.0

package/.claude/skills/components/form-field.md

@@ -0,0 +1,79 @@
+# FormField Component
+
+## Overview
+
+`FormField` is a layout-only wrapper for a single form control inside a form. It caps the
+field's width (`narrow`/`medium`/`wide`), centres it with `margin-inline: auto`, optionally insets
+it from its container edges with a gutter, and applies the shared vertical field spacing
+(`--field-margin-block`). It renders no label, input or error text itself: put an `*Field`
+component (`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`, ...) in its default
+slot.
+
+Typical use inside `FormWrapper` / a pattern form: `<FormField width="wide" :has-gutter="false">`
+around each control, so the form's own container controls the width.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: write camelCase props hyphenated in templates: `:has-gutter`, `:field-has-error`, `:style-class-passthrough`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `width` | `"narrow" \| "medium" \| "wide"` | `"narrow"` | Max width: 400px / 800px / 1200px by default (each a public token). Rendered as `data-width` on the root. |
+| `:has-gutter` | `boolean` | `true` | Insets the field by `--form-field-gutter-width` (1.6rem) on each side. Rendered as `data-has-gutter`. Pass `false` when the parent already handles inline padding. |
+| `:field-has-error` | `boolean` | `false` | Adds `data-invalid` to the root. This is load-bearing, not just a hook: the global theming stylesheets (`_error.css`, `_theme-slots.css`, `theme-ramp.css`) treat `[data-invalid]` like `[data-theme="error"]` and re-evaluate the `--theme-*` ramp there, so every descendant control inherits the red error theme. Must stay a data attribute, not a class. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root `.form-field`, via `useStyleClassPassthrough` (reacts to prop changes). |
+
+## Slots
+
+| Slot | Notes |
+|------|-------|
+| `default` | The form control. Rendered inside `.form-field-inner`. |
+
+---
+
+## Usage
+
+```vue
+<FormField width="wide" :has-gutter="false" :field-has-error="!!errors.email">
+  <InputTextWithLabel
+    v-model="state.email"
+    name="email"
+    label="Email"
+    :error-message="errors.email"
+    :field-has-error="!!errors.email"
+  />
+</FormField>
+```
+
+---
+
+## Styling
+
+Full token table in `app/components/05.forms/form-field/CONSUMER-STYLING.md`. Public tokens:
+`--form-field-max-width-narrow|medium|wide`, `--form-field-gutter-width`,
+`--form-field-margin-block`, `--form-field-background-color`, `--form-field-border-radius`.
+Target state via `.form-field[data-width="wide"]`, `.form-field[data-has-gutter]`,
+`.form-field[data-invalid]`.
+
+---
+
+## History
+
+**Migrated 2026-09-26** (0/5 → full compliance):
+
+- Width and gutter modifiers moved from bare classes (`.narrow`, `.medium`, `.wide`, `.has-gutter`)
+  to `data-width` / `data-has-gutter`. The bare names collide with common consumer utility
+  classes (same bug class as pitfall #16). No layer consumer targeted the old classes.
+- `data-invalid` now renders as `""` / absent, matching every other `05.forms` component (was
+  `"true"` / absent). `[data-invalid]` selectors are unaffected.
+- Removed a dead `&:has(.underline)` rule: no component renders `.underline` (inputs use
+  `.underlined`), and the token it set (`--theme-form-input-bg-underlined`) was never declared.
+  Use `--form-field-background-color` scoped to `.form-field:has(.underlined)` if you want that effect.
+- Removed zero-width debug `outline` declarations and the duplicated background/radius on
+  `.form-field-inner` (it sat exactly on top of the root with the same values).
+- Private-only `--_background-color` / `--_border-radius` / `--_max-width` values promoted to
+  public tokens; `--_max-width` and `--_gutter-width` remain private as state-swapped intermediates.
+- `styleClassPassthrough` widened from `string` to `string | string[]` and wired through
+  `useStyleClassPassthrough`.

package/.claude/skills/components/form-fieldset.md

@@ -0,0 +1,75 @@
+# FormFieldset Component
+
+## Overview
+
+`FormFieldset` is the shared `<fieldset>` + `<legend>` wrapper for grouped form controls. It is
+mostly an internal building block: `SingleCheckbox`, `MultipleCheckboxes` and
+`MultipleRadiobuttons` all render it and pass their own props through. Reach for those components
+first. Use `FormFieldset` directly only when building a new grouped control.
+
+It removes the native fieldset border/margin/padding, styles the legend, and handles the group's
+ARIA semantics.
+
+---
+
+## Props reference
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | (required) | Fieldset `id`. |
+| `:name` | `string` | (required) | Fieldset `name` (valid on `<fieldset>`, exposes it via `form.elements`). |
+| `:legend` | `string` | `""` | Legend text. The legend renders when this or the `legend` slot is given. |
+| `group-role` | `"group" \| "radiogroup"` | `"group"` | `"group"` renders no `role` attribute (a fieldset's native role is already `group`). `"radiogroup"` sets `role="radiogroup"`: use it for radio buttons only. |
+| `:required` | `boolean` | `false` | Sets `aria-required="true"` **only** when `group-role="radiogroup"`. `aria-required` isn't allowed on `role="group"`, so checkbox groups get nothing; put "(required)" in the legend text instead. |
+| `:field-has-error` | `boolean` | `false` | Sets `aria-invalid` on the fieldset. |
+| `:data-testid` | `string` | `""` | Passed to the fieldset. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the fieldset, via `useStyleClassPassthrough` (reacts to prop changes). |
+
+## Slots
+
+| Slot | Notes |
+|------|-------|
+| `legend` | Replaces the legend text. Renders even without a `legend` prop. |
+| `content` | The grouped controls, rendered in `.form-fieldset-content`. |
+
+---
+
+## Usage
+
+```vue
+<FormFieldset id="contact-preference" name="contactPreference" legend="How should we contact you?" group-role="radiogroup" required>
+  <template #content>
+    <!-- radio controls -->
+  </template>
+</FormFieldset>
+```
+
+---
+
+## Styling
+
+Full table in `app/components/05.forms/form-fieldset/CONSUMER-STYLING.md`. Public tokens: fieldset
+`--form-fieldset-margin-block|margin-inline|padding-block|padding-inline|border|border-radius|outline|outline-offset`,
+content `--form-fieldset-content-margin-block|margin-inline`, legend
+`--form-fieldset-legend-color|font-size|font-weight|line-height|margin-block|margin-inline`. Error state hook:
+`.form-fieldset[aria-invalid="true"]`.
+
+---
+
+## History
+
+**Migrated 2026-09-26** (0/5 → full compliance):
+
+- **Role bug fixed:** `role="radiogroup"` used to be hardcoded, so screen readers announced
+  checkbox groups (`SingleCheckbox`, `MultipleCheckboxes`) as radio groups. New `groupRole` prop
+  defaults to the native `group`; `MultipleRadiobuttons` passes `group-role="radiogroup"`.
+- `aria-required` is now limited to `radiogroup`, where ARIA allows it.
+- Legend slot now renders without a `legend` prop (it used to be gated on the prop).
+- Removed a dead `has-description` legend class and `.form-fieldset-description` CSS: they
+  referred to a `description` slot the template never rendered. The wrapping components render
+  descriptions through `InputDescription` inside `content`.
+- Removed the bare `.error` class (collision-prone, nothing styled it). Use `[aria-invalid="true"]`.
+- `--form-fieldset-legend-color` had no fallback and no declaration in the layer; it now falls
+  back to `inherit` (the previous effective behaviour). The legend's size, weight, line height and
+  margin became public tokens with the old values as defaults.
+- `styleClassPassthrough` changes after mount are now picked up (added the `watch`/reset).

package/.claude/skills/components/form-wrapper.md

@@ -0,0 +1,71 @@
+# FormWrapper Component
+
+## Overview
+
+`FormWrapper` is the outer container for a whole form. It caps the form's width
+(`narrow`/`medium`/`wide`) and adds bottom padding. Put your own `<form>` element inside it, and
+wrap each control in `FormField`. `FormField` has its own width cap, and the usual pattern is
+`<FormField width="wide" :has-gutter="false">` so each field fills the `FormWrapper`.
+
+It is a named size container (`@container form-wrapper (...)`) so the form's children can use
+container queries against the form's width. See CONSUMER-STYLING.md for the shrink-to-fit caveat.
+
+It is not centred by default (unlike `FormField`). Set `--form-wrapper-margin-inline: auto` to
+centre it.
+
+---
+
+## Props reference
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `width` | `"narrow" \| "medium" \| "wide"` | `"narrow"` | Max width: 400px / 800px / 1200px by default (each a public token). Rendered as `data-width`. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root `.form-wrapper`, via `useStyleClassPassthrough` (reacts to prop changes). |
+
+## Slots
+
+| Slot | Notes |
+|------|-------|
+| `default` | The form. |
+
+---
+
+## Usage
+
+```vue
+<FormWrapper width="medium">
+  <form @submit.prevent="submitForm">
+    <FormField width="wide" :has-gutter="false">
+      <InputTextWithLabel ... />
+    </FormField>
+  </form>
+</FormWrapper>
+```
+
+Don't also give the inner `<form>` a `form-wrapper` class (an old nuxt-forms habit): the
+component's styles then apply twice.
+
+---
+
+## Styling
+
+Full table in `app/components/05.forms/form-wrapper/CONSUMER-STYLING.md`. Public tokens:
+`--form-wrapper-max-width-narrow|medium|wide`, `--form-wrapper-margin-block|margin-inline`, `--form-wrapper-container-type`,
+`--form-wrapper-padding-block|padding-inline`, `--form-wrapper-border|border-radius|outline|outline-offset`. Target width via
+`.form-wrapper[data-width="medium"]`.
+
+---
+
+## History
+
+**Migrated 2026-09-26** (0/5 → full compliance):
+
+- Width modifier moved from bare classes (`.narrow`, `.medium`, `.wide`) to `data-width`, the
+  same fix as `FormField` (the bare names collide with consumer utility classes). The only known
+  consumer only targets plain `.form-wrapper`, which still works.
+- Removed a zero-width debug `outline`.
+- Hardcoded max widths and `padding-bottom: 2rem` (now `--form-wrapper-padding-block: 0 2rem`) became public tokens, with the old values as
+  defaults. Added margin-block, margin-inline, padding-inline, border, border-radius, outline and outline-offset tokens defaulting to `0`, so nothing changes visually.
+- Added `styleClassPassthrough`.
+- Made the wrapper a named inline-size container (`form-wrapper`) for child container queries;
+  `--form-wrapper-container-type: normal` opts out.

package/.claude/skills/components/glass-panel.md

@@ -8,82 +8,91 @@ type: reference
 
 ## Overview
 
-`GlassPanel` is a semantic container with a frosted-glass visual effect — blurred background, border, drop shadow, and an angled specular highlight on the top-left corner. All visual properties are driven by CSS custom properties so they can be overridden per-theme.
+`GlassPanel` is a semantic container with a frosted-glass look: translucent background,
+blurred and saturated backdrop, border, drop shadow, and an angled highlight across the top-left.
+Every visual value is a public token with a light-mode default built in.
+
+It only reads as glass when layered over an image, gradient or textured background.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `tag` | `"div" \| "section" \| "article" \| "main" \| "header" \| "footer"` | `"div"` | Rendered HTML element |
-| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element |
+| `tag` | `"div" \| "section" \| "article" \| "main" \| "header" \| "footer"` | `"div"` | Rendered element. `section`/`article` get `aria-labelledby` (see below). |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra classes on the root, via `useStyleClassPassthrough` (reacts to prop changes). |
 
 ## Slots
 
-| Slot | Description |
-|------|-------------|
-| `default` | Panel content |
+| Slot | Slot props | Description |
+|------|-----------|-------------|
+| `default` | `headingId` | Panel content. Bind `headingId` onto the panel's heading when `tag` is `section` or `article`. |
+
+## Accessibility
 
-## Basic usage
+With `tag="section"` or `tag="article"`, the root gets `aria-labelledby` pointing at
+`headingId` (via `useAriaLabelledById`). Bind it to a real heading or a dev-mode console warning
+fires about the broken reference:
 
 ```vue
-<GlassPanel tag="section" :style-class-passthrough="['p-8']">
-  <p>Content here</p>
+<GlassPanel tag="section">
+  <template #default="{ headingId }">
+    <h2 :id="headingId">Book a consultation</h2>
+    ...
+  </template>
 </GlassPanel>
 ```
 
+`div`, `main`, `header` and `footer` never get it.
+
 ## CSS token API
 
-All four tokens must be defined — the component has no built-in fallbacks.
+Full table with defaults in `app/components/01.atoms/glass-panel/CONSUMER-STYLING.md`.
 
 | Token | What it controls |
 |-------|-----------------|
-| `--glass-panel-bg` | Panel background (use `rgba` / `oklch` with alpha for the glass effect) |
-| `--glass-panel-border-color` | 1px border colour (typically a translucent white) |
-| `--glass-panel-shadow` | `box-shadow` value |
-| `--glass-panel-highlight` | Colour of the `135deg` specular gradient overlay (`::before`) |
+| `--glass-panel-bg` | Background (keep it translucent) |
+| `--glass-panel-border-width` / `--glass-panel-border-color` | Border |
+| `--glass-panel-border-radius` | Corner radius |
+| `--glass-panel-shadow` | `box-shadow` |
+| `--glass-panel-backdrop-filter` | `backdrop-filter` (`none` to switch off frosting) |
+| `--glass-panel-highlight` / `-highlight-angle` / `-highlight-stop` | The `::before` highlight gradient |
 
-## Layer defaults
+## Dark mode
 
-**Light mode** (`:root` / `[data-color-scheme="light"]`):
-```css
---glass-panel-bg:           rgba(255, 255, 255, 0.55);
---glass-panel-border-color: rgba(255, 255, 255, 0.8);
---glass-panel-shadow:       0 8px 32px rgba(0, 0, 0, 0.08), 0 2px 8px rgba(0, 0, 0, 0.04);
---glass-panel-highlight:    rgba(255, 255, 255, 0.9);
-```
+There is no built-in dark glass. The defaults are light-mode values only (the library avoids
+`light-dark()` for older iPad Safari support). Apps with dark pages set their own values; the
+old dark defaults were:
 
-**Dark mode** (`[data-color-scheme="dark"]`):
 ```css
---glass-panel-bg:           rgba(12, 12, 20, 0.45);
---glass-panel-border-color: rgba(255, 255, 255, 0.07);
---glass-panel-shadow:       0 8px 32px rgba(0, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);
---glass-panel-highlight:    rgba(255, 255, 255, 0.04);
+[data-color-scheme="dark"] {
+  --glass-panel-bg: rgba(12, 12, 20, 0.45);
+  --glass-panel-border-color: rgba(255, 255, 255, 0.07);
+  --glass-panel-shadow: 0 8px 32px rgba(0, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);
+  --glass-panel-highlight: rgba(255, 255, 255, 0.04);
+}
 ```
 
-## Overriding in a consuming app
-
-Add overrides to `app/assets/styles/setup/03.theming/default/_light.css` and `_dark.css`.
-
-For this site the background is dark/warm, so the dark-mode values are the primary brand values. Warm rose tints work well for the border and highlight:
-
-```css
-/* _dark.css — example warm-rose override */
---glass-panel-bg:           oklch(12% 0.01 15 / 0.5);   /* warm near-black, semi-transparent */
---glass-panel-border-color: oklch(60% 0.06 15 / 0.15);  /* muted rose border */
---glass-panel-shadow:       0 8px 32px oklch(0% 0 0 / 0.6), 0 2px 8px oklch(0% 0 0 / 0.4);
---glass-panel-highlight:    oklch(80% 0.04 15 / 0.06);  /* faint rose specular */
-```
-
-```css
-/* _light.css — example warm-rose override */
---glass-panel-bg:           oklch(98% 0.005 15 / 0.6);
---glass-panel-border-color: oklch(100% 0 0 / 0.75);
---glass-panel-shadow:       0 8px 32px oklch(0% 0 0 / 0.06), 0 2px 8px oklch(0% 0 0 / 0.03);
---glass-panel-highlight:    oklch(100% 0 0 / 0.85);
-```
+Consumer apps typically set their own values in
+`app/assets/styles/setup/03.theming/_glass-panel.css`.
 
 ## Notes
 
-- The `backdrop-filter: blur(14px) saturate(180%)` is baked into the component — the blurred-background effect only looks right when the panel is layered over an image or textured background.
-- `overflow: hidden` is set on the root — ensure content that needs to escape (e.g. tooltips, dropdowns) is portalled outside.
-- The `::before` highlight overlay is `pointer-events: none` so it never blocks clicks.
+- `overflow: hidden` is set on the root; portal anything that needs to escape (tooltips,
+  dropdowns), and leave room for things drawn outside their box (e.g. PendingEffect borders).
+- The root is `isolation: isolate` and the highlight is `z-index: -1`, so the highlight sits
+  above the background but beneath the content. Before 2026-09-26 it painted over the content and
+  washed out text in the top-left corner.
+- Used by `ServiceDetail` for its booking card.
+
+## History
+
+**Migrated 2026-09-26** (1/5 → full compliance):
+
+- Defaults moved from `03.theming/_default.css` (`light-dark()`, unsupported on older iPad Safari,
+  where the panel lost its background/border/shadow/highlight) into the component as light-only
+  fallbacks. Dark-mode defaults dropped; see above.
+- Removed four `--_*` vars that were pure pass-throughs of the public tokens.
+- Radius, border width, backdrop filter and highlight angle/stop became public tokens.
+- Highlight moved behind the content (see Notes).
+- `section`/`article` now labelled via `useAriaLabelledById`; `headingId` exposed as a slot prop.
+- `styleClassPassthrough` changes after mount are picked up.

package/.claude/skills/components/grid-stack.md

@@ -15,7 +15,10 @@ type: reference
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
-| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. Reactive: changing it after mount swaps the classes. |
+
+GridStack never sets `aria-labelledby`. If `tag="section"` needs an accessible name, pass
+`aria-label` (it falls through to the root).
 
 ## Slot API
 
@@ -106,7 +109,10 @@ To pin the stack to a fixed height, set it on the root from the consuming page:
 
 ## Consumer styling
 
-No `:deep()` needed — `@layer components` means page styles win automatically.
+GridStack has no CSS custom properties; style `.grid-stack` / `.grid-stack__layer` directly from an
+unlayered page block (`@layer components` means it wins without extra specificity). From a
+consumer's `<style scoped>` file, `.grid-stack__layer` rules need `:deep()`. Full reference:
+`app/components/01.atoms/grids/grid-stack/CONSUMER-STYLING.md`.
 
 ```vue
 <style>

package/.claude/skills/components/header-block.md

@@ -58,7 +58,7 @@ heading to have an accessible name. Bind the same id to both:
 </section>
 ```
 
-Several components in this library (`PageRow`, `LayoutGridByCols`/`LayoutGridByWidth`,
+Several components in this library (`PageRow`, `LayoutGridByCols`,
 `ProfileSection`, `ServiceSummary`, `ServiceDetail`, `PageHeroHighlights`) already generate this id
 automatically via the `useAriaLabelledById` composable and expose it as a `heading-id` slot prop —
 when composing inside one of those, bind `HeaderBlock`'s `id` to that slot prop instead of writing

package/.claude/skills/components/hero-text.md

@@ -9,7 +9,7 @@
 Always ask the user for the following before placing the component:
 
 1. **`tag`** — what heading level? (`h1` | `h2` | `h3` | `h4` | `h5` | `h6`)
-2. **Text segments** — for each segment, what is the text and should it be `normal` (default) or `accent` (italic, `--colour-text-accent` colour)?
+2. **Text segments** — for each segment, what is the text and should it be `normal` (default) or `accent` (italic, filled with the `--hero-text-bg-img` gradient)?
 3. **`axis`** — should segments sit inline (`horizontal`, default) or stack in a column (`vertical`)?
 4. **`fontSize`** — which size? (`display` | `title` | `heading` | `subheading` | `label`) — default is `title`
 5. **`styleClassPassthrough`** — any extra classes to add? (layout, spacing, custom styling hooks)
@@ -38,7 +38,7 @@ interface TextConfig {
 ```
 
 - `"normal"` — default unstyled text
-- `"accent"` — italic, coloured with `--colour-text-accent`
+- `"accent"` — italic, text filled with the `--hero-text-bg-img` gradient (`background-clip: text`)
 
 ## Basic Usage
 
@@ -102,8 +102,9 @@ Key CSS custom properties:
 
 | Property | Default | Controls |
 | -------- | ------- | -------- |
-| `--colour-text-accent` | — | Colour of `.accent` spans and the icon |
-| `--hero-text-{scale}` | — | Font size per `fontSize` prop value |
+| `--hero-text-bg-img` | gold/rose `linear-gradient(135deg, ...)` | Fill of `.accent` spans |
+| `--hero-text-icon-colour` | `var(--colour-text-accent)` | Icon colour |
+| `--hero-text-{scale}` | see CONSUMER-STYLING.md | Font size per `fontSize` prop value (the library theme sets them on `:root`; the component has matching fallbacks) |
 | `--hero-text-font-family` | `"Playfair Display"` | Font family of the whole component |
 | `--hero-text-margin` | `0` | Margin on the root element |
 | `--hero-text-horizontal-gap` | `0.5ch` | Gap between segments in `axis="horizontal"` mode |
@@ -137,7 +138,8 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 .hero-text {
   &.my-hero {
     /* Colours */
-    /* --colour-text-accent: var(--brand-primary); */
+    /* --hero-text-icon-colour: var(--brand-primary); */
+    /* --hero-text-bg-img: linear-gradient(135deg, var(--brand-primary), var(--brand-accent)); */
   }
 }
 </style>
@@ -148,5 +150,5 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 ## Notes
 
 - Text segments are trimmed and a trailing space is automatically appended between segments in horizontal axis — do not manually pad `text` values.
-- The icon is sized to match the font size. At `subheading` scale it is explicitly capped at `0.75 * --hero-text-subheading`.
+- The icon is sized to match the font size. At `subheading` scale it is `0.75em` (applied as `font-size`, since `width`/`height` on an `<Icon>` are overridden by `@nuxt/icon`).
 - Component is auto-imported in Nuxt — no import needed.

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

@@ -0,0 +1,72 @@
+# InputButton
+
+> **Renamed 2026-09-28:** `InputButtonCore` → `InputButton`; root class `.input-button-core` →
+> `.input-button`; `data-testid="input-button-core"` → `"input-button"`. Same props, slots and
+> tokens. Consumer apps keep the old name until they bump to the release that ships the rename.
+
+## Overview
+
+`InputButton` (`05.forms/input-button`) is the library's button. It renders a `<button>` by
+default, a `NuxtLink` for an internal `href` (leading `/`), or an `<a>` for an external one. Every
+other library component that needs a button (dialogs, navigation burgers, grids, alerts) uses it,
+so its tokens restyle those too.
+
+## Props
+
+> Hyphenate props in templates (`:button-text`, `:is-pill`, `:style-class-passthrough`).
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `buttonText` | `string` | `""` | Visible label; becomes `sr-only` with the `#iconOnly` slot, so always set it for icon-only buttons |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "inline"` | `"primary"` | `inline` is for action buttons inside custom wrappers (see `component-inline-action-button.md`) |
+| `type` | `"button" \| "reset" \| "submit"` | `"button"` | Ignored when rendered as a link |
+| `href` | `string` | — | Renders a link instead of a button |
+| `external` | `boolean` | `false` | Force a real navigation for a same-origin `href` that isn't a Vue Router page (e.g. a Nitro server route) |
+| `theme` | `"default" \| "success" \| "error" \| "warning"` | `"default"` | Sets `data-theme`, re-declaring the `--theme-*` palette on the button |
+| `isPill` | `boolean` | `false` | Fully rounded |
+| `isPending` | `boolean` | `false` | Adds `.is-pending` |
+| `hasPendingEffect` | `boolean` | `false` | Renders the `PendingEffect` overlay |
+| `readonly` | `boolean` | `false` | Dimmed, `aria-disabled="true"`, and not operable: clicks (mouse or keyboard) are swallowed before any consumer `@click` runs |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Classes on the root. Reactive after mount |
+
+## Slots
+
+| Slot | Notes |
+|---|---|
+| `#left` | Icon/content before the text (ignored with `#iconOnly`) |
+| `#right` | Icon/content after the text (ignored with `#iconOnly`) |
+| `#iconOnly` | Square icon-only button; `buttonText` becomes the accessible name |
+
+Give slotted `<Icon>`s `class="icon"` to pick up `--input-icon-size` (applied as `font-size`).
+
+## Usage
+
+```vue
+<InputButton button-text="Save" type="submit" />
+
+<InputButton variant="secondary" button-text="Read more" href="/about">
+  <template #right><Icon name="mdi:arrow-right" class="icon" /></template>
+</InputButton>
+
+<InputButton variant="tertiary" button-text="Close menu">
+  <template #iconOnly><Icon name="mdi:close" class="icon" /></template>
+</InputButton>
+```
+
+## Accessibility
+
+- Icon-only buttons keep `buttonText` as `sr-only` text: never leave it empty.
+- `readonly` is exposed as `aria-disabled="true"` and blocks activation; the button stays focusable
+  so its label is still discoverable (unlike native `disabled`).
+- Focus ring: `:focus-visible` with `--button-focus-ring-width` / `-offset`.
+
+## Styling
+
+Colour tokens are `--input-button-{variant}-{property}` with `--theme-*` fallbacks; geometry and
+typography are the global `--button-*` tokens. Full reference:
+`app/components/05.forms/input-button/CONSUMER-STYLING.md`.
+
+## Notes
+
+- Before 2026-09-28, `readonly` only set `pointer-events: none`, so keyboard users could still
+  activate it; the icon size (`width`/`height` on `.icon`) was silently overridden by `@nuxt/icon`.