srcdev-nuxt-components 9.4.9 → 9.4.11

package/.claude/skills/components/dashboard-quad-grid.md

@@ -0,0 +1,98 @@
+# DashboardQuadGrid Component
+
+## Overview
+
+`DashboardQuadGrid` (renamed from `LayoutGridA`) is a fixed 4-panel dashboard layout. Unlike
+`LayoutGridByCols`/`LayoutGridByWidth`, it does not take a column-count prop — it has four
+**named** slots (`slot1`–`slot4`) with a fixed responsive arrangement that changes shape (not
+just column count) across breakpoints, designed for dashboard-style layouts (one primary panel
+plus three supporting panels).
+
+---
+
+## Slot pattern
+
+Exactly four fixed slot names — `slot1`, `slot2`, `slot3`, `slot4`. Not dynamic; each is a named
+slot with a specific position in the layout at each breakpoint.
+
+```vue
+<DashboardQuadGrid>
+  <template #slot1><ArticleCard /></template>
+  <template #slot2><StatsPanel /></template>
+  <template #slot3><QuickActions /></template>
+  <template #slot4><ActivityFeed /></template>
+</DashboardQuadGrid>
+```
+
+---
+
+## Props reference
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes on the root element. |
+
+---
+
+## Responsive behaviour
+
+Uses **CSS container queries** (`container-type: inline-size`) on the wrapper — responds to its
+own container width, not the viewport.
+
+- **Below 768px**: all four slots stack vertically in order (slot1 → slot2 → slot3 → slot4).
+- **768px–1059px**: 2-column, 3-row grid. `slot1` and `slot2` each span the full width (rows 1
+  and 2); `slot3`/`slot4` sit side by side in row 3.
+- **≥1060px**: 3-column, 2-row grid. `slot1` spans vertically down the left column; `slot2` spans
+  horizontally across the top-right; `slot3`/`slot4` sit in the bottom-right.
+
+This shape is structural — there is no prop to reconfigure it. If you need an arbitrary
+column count instead, use `LayoutGridByCols`/`LayoutGridByWidth`.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/01.atoms/content-wrappers/layout-grid/dashboard-quad-grid/CONSUMER-STYLING.md).
+
+| Token | Default | Controls |
+|---|---|---|
+| `--dashboard-quad-grid-gap` | `2rem` | Gap between the four slot panels |
+| `--dashboard-quad-grid-padding` | `2rem` | Padding inside each slot panel |
+| `--dashboard-quad-grid-outline-width` | `0.1rem` | Slot panel outline width |
+| `--dashboard-quad-grid-outline-colour` | `light-dark(black, white)` | Slot panel outline colour |
+| `--dashboard-quad-grid-outline-offset` | `0` | Slot panel outline offset |
+| `--dashboard-quad-grid-border-width` | `0` | Slot panel border width (off by default — the panel edge is drawn by the outline) |
+| `--dashboard-quad-grid-border-colour` | `light-dark(black, white)` | Slot panel border colour, only visible once `--dashboard-quad-grid-border-width` is set |
+| `--dashboard-quad-grid-border-radius` | `0.5rem` | Slot panel corner radius |
+| `--dashboard-quad-grid-rule-width` | `0.1rem` | Width of the grid gap rule line (CSS Gap Decorations, limited browser support) |
+| `--dashboard-quad-grid-rule-colour` | `transparent` | Colour of the grid gap rule line, invisible by default |
+| `--dashboard-quad-grid-rule-inset` | `0` | Inset of the grid gap rule line from the panel edges |
+
+---
+
+## Local style override scaffold
+
+```vue
+<DashboardQuadGrid :style-class-passthrough="['my-grid']">
+  ...
+</DashboardQuadGrid>
+
+<style>
+.dashboard-quad-grid-wrapper {
+  &.my-grid {
+    --dashboard-quad-grid-gap: 1.6rem;
+  }
+}
+</style>
+```
+
+---
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- Renamed from `LayoutGridA` during the 2026-09-21 compliance migration; previously lived
+  unplaced at `app/components/layout-grids/LayoutGridA.vue` with options-style props and no
+  public CSS tokens (its geometry values were hardcoded px literals).
+- For a generic, arbitrary-column-count grid, use `LayoutGridByCols`/`LayoutGridByWidth` instead
+  — this component's 4-slot shape is fixed and specifically dashboard-oriented.

package/.claude/skills/components/dashboard-stats-grid.md

@@ -0,0 +1,103 @@
+# DashboardStatsGrid Component
+
+## Overview
+
+`DashboardStatsGrid` (renamed from `LayoutGridB`) is a dashboard layout combining a multi-panel
+top row (a cluster of small stat/summary panels plus two static side panels) with a strip of
+panels in the bottom row. Item counts in the two dynamic clusters are prop-driven; the two static
+top-row slots and overall shape are fixed.
+
+---
+
+## Slot pattern
+
+- `top-row-slot1-{n}-content` — dynamic, `n` from `1` to `topRowSlot1ItemCount`
+- `top-row-slot-2` — static
+- `top-row-slot-3` — static
+- `bottom-row-{n}-content` — dynamic, `n` from `1` to `bottomRowItemCount`
+
+```vue
+<DashboardStatsGrid :top-row-slot1-item-count="3" :bottom-row-item-count="2">
+  <template #top-row-slot1-1-content><StatCard label="Uptime" value="98.5%" /></template>
+  <template #top-row-slot1-2-content><StatCard label="Users" value="1,247" /></template>
+  <template #top-row-slot1-3-content><StatCard label="Latency" value="342ms" /></template>
+
+  <template #top-row-slot-2><FeaturedPanel /></template>
+  <template #top-row-slot-3><InfoPanel /></template>
+
+  <template #bottom-row-1-content><FeaturePanel /></template>
+  <template #bottom-row-2-content><FeaturePanel /></template>
+</DashboardStatsGrid>
+```
+
+---
+
+## Props reference
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:top-row-slot1-item-count` | `number` | `6` | Number of dynamic panels rendered in the top-row cluster (`top-row-slot1-{n}-content`). |
+| `:bottom-row-item-count` | `number` | `4` | Number of dynamic panels rendered in the bottom row (`bottom-row-{n}-content`). |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes on the root element. |
+
+---
+
+## Responsive behaviour
+
+Uses **CSS container queries** (`container-type: inline-size`) — responds to its own container
+width, not the viewport.
+
+- **Top row, below 1024px**: `slot1` cluster, `slot2`, `slot3` stack vertically.
+- **Top row, ≥1024px**: two-column layout — `slot1` cluster + `slot3` on the left
+  (`minmax(46rem, 33%)` on the right for `slot2`), with `slot2` spanning both rows on the right.
+- **`slot1` cluster, below 680px**: 2 columns.
+- **`slot1` cluster, ≥680px**: 3 columns.
+- **Bottom row**: always a fixed 2-column grid regardless of container width.
+
+This shape is structural — there is no prop to reconfigure it.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/01.atoms/content-wrappers/layout-grid/dashboard-stats-grid/CONSUMER-STYLING.md).
+
+| Token | Default | Controls |
+|---|---|---|
+| `--dashboard-stats-grid-gap` | `1.2rem` | Gap between panels, in every row |
+| `--dashboard-stats-grid-panel-padding` | `1.2rem` | Padding inside each panel |
+| `--dashboard-stats-grid-border-width` | `0.1rem` | Panel border width |
+| `--dashboard-stats-grid-border-colour` | `light-dark(hsl(0, 29%, 3%), hsl(0, 0%, 92%))` | Panel border colour |
+| `--dashboard-stats-grid-border-radius` | `1.2rem` | Panel corner radius |
+| `--dashboard-stats-grid-rule-width` | `0.1rem` | Width of the grid gap rule line (CSS Gap Decorations, limited browser support) |
+| `--dashboard-stats-grid-rule-colour` | `transparent` | Colour of the grid gap rule line, invisible by default |
+| `--dashboard-stats-grid-rule-inset` | `0` | Inset of the grid gap rule line from the panel edges |
+
+---
+
+## Local style override scaffold
+
+```vue
+<DashboardStatsGrid :style-class-passthrough="['my-grid']">
+  ...
+</DashboardStatsGrid>
+
+<style>
+.dashboard-stats-grid {
+  &.my-grid {
+    --dashboard-stats-grid-gap: 1.6rem;
+  }
+}
+</style>
+```
+
+---
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- Renamed from `LayoutGridB` during the 2026-09-21 compliance migration; previously lived
+  unplaced at `app/components/layout-grids/LayoutGridB.vue` with options-style props. Its old
+  `--_color` custom property was dead code (declared, never consumed) and was removed rather than
+  promoted; `--_gap`/`--_border-color` had no public fallback and are now
+  `--dashboard-stats-grid-gap`/`--dashboard-stats-grid-border-colour`.

package/.claude/skills/components/display-theme-switch.md

@@ -0,0 +1,60 @@
+---
+name: DisplayThemeSwitch
+description: DisplayThemeSwitch system/light/dark theme picker wired to useSettingsStore, wraps TripleToggleSwitchCore
+type: reference
+---
+
+# DisplayThemeSwitch
+
+## Overview
+
+`DisplayThemeSwitch` is a system/light/dark colour-scheme picker. It's a thin wrapper around
+`TripleToggleSwitchCore` (`app/components/05.forms/triple-toggle-switch/`), wired to
+`useSettingsStore` (`app/stores/useSettingsStore.ts`) so selecting an option updates the app's
+`colourScheme` state and applies the matching class (`system`/`light`/`dark`) to
+`<html>`. Renders inside `<ClientOnly>` since the store's persisted value isn't known until
+hydration.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes on the root. Pass `"small"` for compact sizing. |
+| `systemLabel` | `string` | `"System"` | Accessible label for the system option. |
+| `lightLabel` | `string` | `"Light"` | Accessible label for the light option. |
+| `darkLabel` | `string` | `"Dark"` | Accessible label for the dark option. |
+| `systemIcon` | `string` | `"material-symbols:night-sight-auto-sharp"` | Icon name for the system option. |
+| `lightIcon` | `string` | `"radix-icons:sun"` | Icon name for the light option. |
+| `darkIcon` | `string` | `"radix-icons:moon"` | Icon name for the dark option. |
+
+## Basic usage
+
+```vue
+<DisplayThemeSwitch />
+
+<!-- Compact, for a header/nav slot -->
+<DisplayThemeSwitch style-class-passthrough="small" />
+
+<!-- Translated labels -->
+<DisplayThemeSwitch system-label="Automatique" light-label="Clair" dark-label="Sombre" />
+```
+
+## Styling
+
+No `--display-theme-switch-*` tokens of its own — every visual aspect (colour, marker gradient,
+sizing) is delegated to `TripleToggleSwitchCore`'s public `--triple-toggle-switch-*` tokens. See
+CONSUMER-STYLING.md here and `TripleToggleSwitchCore`'s own CONSUMER-STYLING.md.
+
+## Notes
+
+- 2026-09-20 migration: moved from `app/components/display-theme-switch/` (unplaced) into
+  `02.molecules/`. Added `systemLabel`/`lightLabel`/`darkLabel`/`systemIcon`/`lightIcon`/`darkIcon`
+  props — the three option labels/icons were previously hardcoded English strings with no override
+  hook. Removed a large block of dead/duplicate CSS in this component's own `<style>` that either
+  no-op-duplicated `TripleToggleSwitchCore`'s own default styling (same selectors, same values) or
+  actively bypassed its public `--triple-toggle-switch-*` tokens with hardcoded literals (a
+  consumer setting e.g. `--triple-toggle-switch-surface` globally would have been silently
+  overridden back). Only the genuine `small`-variant sizing override remains, now driving
+  `TripleToggleSwitchCore`'s own public sizing tokens (`--triple-toggle-switch-gap`/`-padding`/
+  `-option-padding`/`-icon-size`, added in the same migration) instead of reaching into its
+  private `--_form-*`/`--_scheme-icon-font-size` locals directly.

package/.claude/skills/components/glowing-border.md

@@ -0,0 +1,66 @@
+---
+name: GlowingBorder
+description: GlowingBorder decorative wrapper with an animated conic-gradient glow border in 5 colour variants
+type: reference
+---
+
+# GlowingBorder
+
+## Overview
+
+`GlowingBorder` wraps its default slot content in a rotating conic-gradient border effect, built
+with `@property`-registered custom properties so the hue rotation animates smoothly. It renders as
+a configurable root element via the `tag` prop.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "p" \| "span" \| "section" \| "article" \| "aside" \| "header" \| "footer" \| "main" \| "nav" \| "ul" \| "ol"` | `"div"` | Root element tag. |
+| `variant` | `"subtle" \| "vivid" \| "silver" \| "steel" \| "green"` | `"subtle"` | Glow colour variant. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slots
+
+| Slot | Description |
+|---|---|
+| `default` | Content rendered inside the glowing border. |
+
+## Basic usage
+
+```vue
+<GlowingBorder variant="vivid">
+  <p>Content wrapped in a glowing border</p>
+</GlowingBorder>
+```
+
+## Styling
+
+Border width, radius, surface colour, animation duration, and every variant's 5 gradient colour
+stops are public CSS custom properties — see `CONSUMER-STYLING.md` for the full token table.
+
+```vue
+<GlowingBorder
+  variant="steel"
+  style="--glowing-border-width: 2px; --glowing-border-animation-duration: 6s;"
+>
+  <p>Slower, thinner steel glow</p>
+</GlowingBorder>
+```
+
+## Motion
+
+The glow animation stops automatically under `prefers-reduced-motion: reduce`.
+
+## Notes
+
+- 2026-09-20 migration: moved from `app/components/glowing-border/` (unplaced) into
+  `01.atoms/animations/glowing-border/`; converted from options-style `defineProps({...})` to
+  `interface Props` + `withDefaults`; promoted border width/radius/surface/animation-duration and
+  every variant's 5 colour stops (previously hardcoded or unprefixed `--border-width`/`--surface`)
+  to public `--glowing-border-*` tokens; renamed internal composition custom properties
+  (`--clr-1..5`, `--glow-deg`, `--gradient-glow`) to private `--_clr-1..5`/`--_glow-deg`/
+  `--_gradient-glow`; added a `prefers-reduced-motion` guard. No behaviour change beyond the new
+  override surface.
+- 2026-09-20: added `green` variant (vibrant, saturated greens: `#00ff87`, `#39ff14`, `#00c853`,
+  `#64dd17`, `#00e676`), each stop overridable via `--glowing-border-green-color-{1-5}`.

package/.claude/skills/components/input-number-core.md

@@ -0,0 +1,214 @@
+# InputNumberCore Component
+
+## Overview
+
+`InputNumberCore` is the low-level native `<input type="number">` primitive for the `05.forms`
+number-input family. It renders a single native number input with left/right button slots (for
+step-down/step-up controls). It has no label, description, or error-message rendering of its
+own — that's composed by the `InputNumberDefault` variant below.
+
+Most consumers should reach for **InputNumberDefault** rather than `InputNumberCore` directly.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:field-has-error`, `:style-class-passthrough`, `:aria-describedby`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | (required) | Applied to the native input. |
+| `:name` | `string` | (required) | Applied to the native input. |
+| `:min` | `number` | (required) | Native `min`. |
+| `:max` | `number` | (required) | Native `max`. |
+| `:step` | `number` | `1` | Native `step`. |
+| `:placeholder` | `string` | `""` | Native `placeholder`. |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
+| `:weight` | `FormWeight` | `"normal"` | Adds an `input-number--{weight}` class to the input, for prop-shape consistency with sibling `05.forms` components. **No CSS in the library currently styles this class — it's a no-op today**, same convention as `InputRangeCore`'s `weight` prop. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Adds the variant name as a class on the wrapper — `"normal"` (bordered box) and `"underlined"` (bottom-border only) have CSS; `"outlined"` doesn't (see CONSUMER-STYLING.md). Same prop/behaviour as `InputTextCore`. |
+| `:field-has-error` | `boolean` | `false` | Drives `data-invalid` on the wrapper. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the input element. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native input. |
+
+### v-model
+
+`v-model` — `number | readonly number[]`, **required** (`defineModel({ required: true })`). Bound
+directly to the native number input. Required rather than defaulted deliberately — same reasoning
+as `InputRangeCore`'s `v-model` (see that skill doc) — this also satisfies `vue/require-default-prop`.
+
+---
+
+## Slots
+
+| Slot | Notes |
+|------|-------|
+| `left` | Rendered before the input (e.g. a step-down button). Adds `has-left-slot` to the wrapper. |
+| `right` | Rendered after the input (e.g. a step-up button). Adds `has-right-slot` to the wrapper. |
+
+Any `.input-button-core` inside `.slot` gets its own border/outline stripped and is sized to
+match the input (`aspect-ratio: 1`, `width: var(--input-min-height)`) regardless of which slot
+it's in. The divider border is then added directly to that button element specifically when its
+slot is present — `&.has-left-slot .left-slot .input-button-core { border-right: ... }` and the
+right-hand mirror — so it sits flush against the button's own edge rather than around the
+containing `.slot` div. This makes step buttons read as embedded segments of the same control
+rather than separate floating buttons. The divider reuses the wrapper's own border colour token
+(no separate divider token), same as `InputTextCore`/`InputTextAsNumberWithLabel`.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-number/CONSUMER-STYLING.md) for the
+full table with defaults.
+
+**Common tokens:**
+- `--input-number-surface` / `-surface-hover` — wrapper/input/embedded-button background, resting and hover, falls back to `--theme-input-surface`/`-surface-hover`
+- `--input-number-border` / `-border-hover` / `-border-focus` — border colour resting, mouse-hover outline, and `:focus-visible` outline (also the divider colour and the embedded button's own focus outline), falls back to `--theme-border`/`--theme-border-focus`
+- `--input-number-text-color` — input text colour, falls back to `--theme-input-text-color-normal`
+- `--input-number-placeholder-color` — placeholder text colour, falls back to `--theme-input-placeholder`
+
+---
+
+## Fixed 2026-09-22: dead CSS from a missing base class and mismatched selectors
+
+`InputNumberCore` migrated to full compliance from a `variants:true`, `eslint_issues:true`,
+score-1/5 state. Several latent bugs were fixed alongside the standard checklist:
+
+- The native `<input>` had no static `input-number-core` class — only the dynamic
+  `elementClasses` passthrough — so the entire `.input-number-core { ... }` style block (font,
+  padding, colour, focus box-shadow) never matched anything. Fixed by adding the class directly.
+- `placeholder` was declared as a prop but never bound on the `<input>` — unlike `InputRangeCore`
+  (where a range input genuinely has no placeholder concept and the no-op is intentional and
+  documented), a number input *does* support `placeholder` meaningfully, so this was a real gap,
+  not a deliberate no-op. Fixed by binding `:placeholder`.
+- The left/right slot divs rendered with classes `slot left`/`slot right`, but the CSS targeted
+  `.left-slot`/`.right-slot` and `.has-left-slot`/`.has-right-slot` — neither the slot divs nor
+  the wrapper ever carried those exact class names, so the divider-border and flex-alignment
+  rules for embedded step buttons never applied. Fixed by renaming the slot divs to
+  `slot left-slot`/`slot right-slot` and adding `has-left-slot`/`has-right-slot` to the wrapper
+  directly from `slots.left`/`slots.right` (Vue's own `useSlots()`), rather than a fragile,
+  cross-component class-toggling relay.
+- Relatedly, `InputNumberDefault` called `updateElementClasses(["has-left-button",
+  "has-right-button"])` unconditionally on mount, which permanently added those two classes to
+  its own outer `.input-number-with-label` wrapper — a different element than
+  `InputNumberCore`'s `.input-number-wrapper`, so the `:has()` selector that was meant to key off
+  those classes could never match (the class lived on an ancestor, not a descendant). Replaced
+  entirely: `InputNumberCore` now detects an embedded button directly via
+  `:has(.left-slot .input-button-core)` / `:has(.right-slot .input-button-core)`, so no
+  JS-driven class relay is needed at all.
+- `theme` was typed as an inline `"default" | "success" | "error" | "warning"` union in both
+  `InputNumberCore` and `InputNumberDefault` instead of importing the shared `FormUiTheme` type —
+  aligned with the rest of `05.forms`.
+- `weight` was passed from `InputNumberDefault` to `InputNumberCore` but `InputNumberCore` had no
+  matching prop, so it fell through as a raw, meaningless `weight="normal"` HTML attribute on the
+  wrapper `<div>`. Fixed by declaring the prop on `InputNumberCore` too, matching `InputRangeCore`.
+- `defineModel()` had no default, tripping `vue/require-default-prop` — fixed the same way as
+  `InputRangeCore`: `defineModel({ required: true })`, not a rule disable or an artificial default.
+- A single-use private token, `--_border`, was inlined to the public
+  `var(--input-number-border, var(--theme-border))` directly at its point of use — it had no
+  composition or state-swap behind it, just a bare pass-through (see pitfall #20). `--_surface`
+  (used twice) and `--_min-width` (composed from a `v-bind()` value) correctly stayed private.
+
+---
+
+## Fixed 2026-09-22 (follow-up): rewritten to visually mirror InputTextCore
+
+The first migration pass above only made `InputNumberCore`'s *own* (pre-existing, previously dead)
+CSS active — it didn't reconsider whether that CSS was actually the right design. Once live, it
+was visually inconsistent with the rest of `05.forms`: no border-radius, no hover/focus outline
+state, wrong padding-token family (`--form-textarea-padding-*` instead of the shared input
+padding tokens), and a box-shadow-toggle focus mechanism instead of the `:has()`-based outline
+approach every other input in this library uses. `InputNumberCore` is meant to be a native
+`<input type="number">` sibling to the text-based `InputTextAsNumberWithLabel` variant (see
+`input-text-core.md`'s Variants section) — both should look and behave the same. The CSS was rewritten
+to mirror `InputTextCore` directly:
+
+- Added `:input-variant` (`"normal"` / `"outlined"` / `"underlined"`), matching `InputTextCore`'s
+  prop and wrapper-class shape (`InputNumberDefault` forwards it the same way
+  `InputTextWithLabel` forwards it to `InputTextCore`, including to `InputLabel`).
+- Replaced the flat, unconditional border/radius/box-shadow with `InputTextCore`'s `.normal`
+  variant shape: border + `border-radius: var(--form-input-border-radius)` (previously this read
+  `var(--form-element-border-width)` — a pre-existing bug that used the *border-width* token as
+  the *radius*, coincidentally invisible while the block was dead), plus `:has(input:hover)` /
+  `:has(input:focus-visible)` outline states instead of the old `--_focus-box-shadow` custom
+  property toggle.
+  - `--input-number-border-hover` and `--input-number-border-focus` are new public tokens for
+    these two states (both fall back to `--theme-border-focus`, same as `InputTextCore`).
+- Padding moved from `--form-textarea-padding-*` (the wrong token family — textarea, not input)
+  to the shared `--input-padding-block`/`--input-padding-inline`/`--input-min-height` tokens every
+  other `05.forms` text-like input uses.
+- The embedded step button now gets a hover background (`--input-number-surface-hover`, new
+  public token) and a visible `:focus-visible` outline (reusing `--input-number-border-focus`) —
+  previously it had neither, an accessibility gap beyond the visual mismatch (checklist item 9).
+- The divider between the input and an embedded button now reuses the border colour
+  (`--_border`) directly instead of a separate `--input-number-divider-color` token — removed,
+  since `InputTextCore` doesn't have an equivalent separate token either (the border colour
+  *is* the divider colour there too).
+- `--_border-hover` and `--_surface-hover` were each used only once with no composition or
+  state-swap, so per the public-token rule they were inlined directly
+  (`var(--input-number-border-hover, var(--theme-border-focus))` /
+  `var(--input-number-surface-hover, var(--theme-input-surface-hover))`) rather than kept as
+  private wrappers. `--_border-focus` stayed private since it's now genuinely reused (the
+  wrapper's own focus outline *and* the embedded button's focus outline both read it).
+
+**Separately found in the same investigation** (not an `InputNumberCore` bug, but what the visual
+comparison was originally checking against): `InputTextAsNumberWithLabel.vue` had its own,
+unrelated pre-existing bug — see `input-text-core.md`'s Variants section for the fix.
+
+**Correction, same day**: the first version of this rewrite still didn't visually match — the
+divider border and button sizing (`aspect-ratio: 1`, `width: var(--input-min-height)`) had been
+put on the `.left-slot`/`.right-slot` *wrapper divs*, not on `.input-button-core` itself, unlike
+`InputTextCore`'s equivalent block. That left an unstyled gap between the button and the border
+line instead of a flush edge, and the buttons weren't sized to match the input's height. Fixed by
+moving the divider border and all button sizing/colour rules onto `.input-button-core` directly
+(`&.has-left-slot .left-slot .input-button-core { border-right: ... }`, matching
+`InputTextAsNumberWithLabel`'s `.left-slot .input-button-core { border-right: ... }` exactly)
+rather than the containing `.slot` div. When mirroring another component's CSS structure, check
+*which element* a rule targets, not just that an equivalent rule exists somewhere in the block —
+a border/sizing rule one level off in the DOM tree produces a visually-close-but-not-matching
+result that's easy to miss without a side-by-side screenshot comparison.
+
+---
+
+## Variants
+
+### InputNumberDefault
+
+`InputNumberDefault` (`variants/InputNumberDefault.vue`) composes `InputNumberCore` with
+`InputLabel`, `InputDescription`, and `InputError`, plus optional step-down/step-up buttons
+(`InputButtonCore`) wired into the `left`/`right` slots.
+
+**Additional props over InputNumberCore:**
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:label` | `string` | (required) | Rendered via `InputLabel`. |
+| `:error-message` | `object \| string` | (required) | Rendered via `InputError` when `field-has-error` is true. |
+| `:step-down-label` | `string` | `"Step down"` | `button-text` on the step-down `InputButtonCore` — override for localisation. |
+| `:step-up-label` | `string` | `"Step up"` | `button-text` on the step-up `InputButtonCore` — override for localisation. |
+
+**Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`), plus
+`left`/`right` (forwarded straight through to the underlying `InputNumberCore` — the
+step-down/step-up buttons only render when you use the `left`/`right` slots yourself, since the
+button icon content itself is consumer-supplied).
+
+```vue
+<InputNumberDefault
+  name="quantity"
+  label="Quantity"
+  v-model="quantity"
+  :min="1"
+  :max="10"
+  error-message="Please choose a value between 1 and 10"
+  :field-has-error="hasError"
+>
+  <template #left><Icon name="mdi:minus" /></template>
+  <template #right><Icon name="mdi:plus" /></template>
+</InputNumberDefault>
+```
+
+`v-model` is `number | readonly number[]`, **required** — same as `InputNumberCore` above.
+
+Step-down is disabled (`readonly` on its `InputButtonCore`) once the value reaches `min`, and
+step-up once it reaches `max`; clicking either button while at that boundary is a no-op.