srcdev-nuxt-components 9.3.12 → 9.3.13

package/.claude/skills/index.md

@@ -32,6 +32,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 ├── theming-override-default.md      — replace the entire default theme with a custom palette (set --theme-hue/--theme-chroma)
 ├── theming-partial-override.md      — override a specific colour token category (palette, buttons, inputs) without a full theme replacement
 ├── theming-form-geometry-tokens.md  — non-colour form/button/input tokens (padding, border-radius, gaps): full inventory, why partial override doesn't need duplicating the source files
+├── theming-component-token-pattern.md — standard shape for overridable component colours: public token + inline fallback, no bare var()/no private-only indirection; the three tiers (theme slots / cross-component families / component-scoped); rollout status
 ├── colour-scheme-disable.md         — disable light/dark scheme support in a consumer app
 ├── component-dynamic-slots.md        — named dynamic slots ($slots iteration) vs indexed dynamic slots (itemCount pattern)
 ├── component-local-style-override.md — styleClassPassthrough + scoped style block for per-usage visual customisation

package/.claude/skills/theming-component-token-pattern.md

@@ -0,0 +1,126 @@
+# Component Token Pattern — Public Token + Inline Fallback
+
+## Overview
+
+The standard shape for every overridable CSS value in a component, from now on:
+
+```css
+background-color: var(--{component}-{property}, {real-default-or-shared-fallback});
+```
+
+One name, declared inline at the point of use, with a real default right there in the component
+source. No separate "public token must be declared somewhere else or the component breaks"
+requirement, and no private `--_` indirection standing in for the actual override point.
+`ServicesCard.vue` is the reference implementation — read its `<style>` block for the shape in
+practice.
+
+## Why this replaced the old pattern
+
+Two things used to go wrong, both found while auditing `luxury-locs-by-natasha`'s theming
+overrides (2026-08-25):
+
+1. **Bare `var(--theme-checkbox-symbol-color)` with no fallback anywhere.** The only way for this
+   to resolve to something was a consuming app declaring it globally. When the component was later
+   refactored (buttons moved onto the shared theme-slot system) and stopped reading the token, nothing
+   signalled that to the consumer — the app's declaration became permanently dead, silently. A
+   `var()` with an undefined custom property and no fallback just resolves to the property's
+   initial value; there is no error, no warning, ever.
+2. **Tokens that were "shared" only by accident.** `InputTextCore`, `InputSelectCore`,
+   `InputNumberCore` and the checkbox button all read the exact same `--theme-input-surface`, so a
+   consumer wanting to restyle just text inputs had no way to do that without also restyling every
+   other input type. The private `--_input-text-surface: var(--theme-input-surface);` indirection
+   made this look like it had its own override point when it didn't.
+
+## The three tiers
+
+| Tier | Example | No-fallback allowed? |
+|---|---|---|
+| **1 — theme slots** | `--theme-surface`, `--theme-border`, `--theme-ring`, `--theme-text`, ... (`_theme-slots.css`) | Yes — deliberately global, small, stable set. Changing one is meant to reskin everything that shares it. |
+| **2 — cross-component families** | `--theme-input-surface`, `--theme-checkbox-symbol-surface` | No longer created new. Existing ones stay as the *fallback value* inside Tier 3 tokens, not as the thing components read directly. |
+| **3 — component-scoped** | `--input-button-primary-surface`, `--services-card-border-colour` | Never — always `var(--{component}-token, <fallback>)`. |
+
+Tier 1 is the one deliberate exception. Everything else gets a real component-prefixed name with
+an inline fallback, even if that fallback happens to be a Tier 1 or Tier 2 token underneath.
+
+## Naming convention
+
+`--{component-kebab-name}-{variant-if-any}-{property}[-state]`
+
+- `--input-button-primary-surface` / `-surface-hover` — variant + property + state
+- `--services-card-border-colour` / `-border-colour-hover` — property + state
+- Only add a `-hover`/`-focus`/`-active` suffix if that state's value actually differs from the
+  base token. If hover reuses the exact same value as base (see `InputButtonCore`'s primary text
+  colour, fixed on purpose across states), reuse the base token — don't manufacture a second name
+  for a value that never diverges.
+
+## Multi-level fallback chains are fine
+
+A component that wants to *look like* another component's default (rather than duplicating a
+raw value) chains through it:
+
+```css
+/* InputCopy's copy button defaults to InputButtonCore's primary look */
+--_button-bg: var(--input-copy-button-bg, var(--input-button-primary-surface, var(--theme-surface)));
+```
+
+Three tiers deep here: instance/global override → "look like the primary button" → the theme
+slot underneath that. Each link in the chain is a real, resolvable token — nothing depends on a
+consuming app having declared anything.
+
+## What this does NOT change
+
+- Tier 1 theme slots (`_theme-slots.css`) stay bare `var()`, no fallback, by design.
+- Geometry/typography tokens that already have real component-local defaults
+  (`--button-padding-block: 1rem;` in `06.button-geometry.css`) were never part of this problem —
+  they're declared with real values already, just not inline at the point of use. Leave them.
+
+## Rollout status
+
+- ✅ `InputButtonCore` (primary/secondary/tertiary), `InputCopy`, `PricingCard` — migrated
+  2026-08-25, see their `CONSUMER-STYLING.md` for the full token list. This pass also included a
+  deliberate visual redesign (flat borders, `color-mix()`-darkened hover, transparent resting
+  outline, separated `:focus-visible`), not just the token API change.
+- ✅ `InputCheckboxRadioCore`/`Button` — migrated 2026-08-25, see their `CONSUMER-STYLING.md`.
+  Pure token-rename pass, no visual/default changes (unlike `InputButtonCore`'s redesign above).
+  Added Storybook stories for both (`InputCheckboxRadioCore`, `InputCheckboxRadioButton`) —
+  neither had one before.
+- ✅ `InputTextCore`, `InputSelectCore`, `InputNumberCore` — migrated 2026-08-25, see their
+  `CONSUMER-STYLING.md`. `InputTextCore`/`InputSelectCore` also had this exact problem's original
+  form: a private `--_input-text-*`/`--_input-select-*` naming scheme documented as a second
+  "local override path" alongside the global tokens, added 2026-08-22 (three days before this
+  pattern was formalised) as a workaround for a global-override-not-landing report that was never
+  root-caused. That private-var-as-override-point shape is exactly what this pattern replaces —
+  renamed public with real fallbacks, old two-path docs removed. `InputNumberCore` had no
+  component-scoped tokens at all before this (bare `--theme-input-*` throughout). Added a
+  Storybook story for `InputSelectCore` (didn't have one); `InputNumberCore` still doesn't.
+  `InputTextCore`/`InputSelectCore`'s `.normal` variant also had hover and `:focus-visible` share
+  one token (literally the same rule content duplicated under two selectors) — split into
+  `--input-text-border-hover`/`--input-select-border-hover` alongside the existing `-border-focus`
+  pair, both still defaulting to `--theme-border-focus` so default rendering is unchanged, but
+  mouse and assistive-tech interaction can now be themed independently. `InputNumberCore` has no
+  hover state on its border at all (only a `:focus-visible` box-shadow toggle), so there was
+  nothing to split there.
+- ✅ `ToggleSwitchCore`, `TripleToggleSwitchCore`, `DisplayThemeSwitch` — migrated 2026-08-25, see
+  the first two's `CONSUMER-STYLING.md`. Correction to the two lines this replaces: they claimed
+  `ToggleSwitchCore` read a bare `--theme-toggle-symbol-color-*` — that token doesn't exist
+  anywhere in this codebase and never did; false memory from conflating it with the checkbox
+  fix. `ToggleSwitchCore` itself turned out to be a plain Tier 2 case (real, live tokens, just no
+  component-scoped override point) plus five confirmed-dead private locals (declared, never read
+  anywhere in the file) removed outright. The real dead-token bug was in `TripleToggleSwitchCore`
+  (and duplicated in `DisplayThemeSwitch`'s own override): `--theme-form-radio-border`,
+  `--theme-form-radio-outline`, `--theme-form-checkbox-bg` — all three declared nowhere in the
+  layer. The first two fed two further-unused private locals (removed); the third fed the
+  selected-option marker's background (real bug, narrow impact — only visible when none of the
+  component's `system`/`light`/`dark` `:has()` overrides match).
+
+  Second bug, found while adding the Storybook story `TripleToggleSwitchCore` never had: those
+  `:has()` selectors (and the matching `.option-icon.system/.light/.dark` classes, template-bound
+  to each option's `id`) said `"auto"`, not `"system"` — but the only known consumer,
+  `DisplayThemeSwitch`, has only ever emitted `id`/`value: "system"` (it has to; that literal
+  string is `useSettingsStore.setColourScheme`'s type and the CSS class it applies to `<html>`).
+  `"auto"` never matched anything real, so the system option's green gradient marker had never
+  actually fired — confirmed live before and after the fix. Renamed the selectors to `"system"`
+  rather than the data, since the data value is a real external contract this component's
+  presentational selectors have no business dictating. `TripleToggleSwitchCore` still hardcodes
+  three option values as CSS selectors rather than being genuinely value-agnostic — noted in its
+  `CONSUMER-STYLING.md`, left as a larger separate change.

package/app/assets/styles/setup/04.elements/forms/06.button-geometry.css

@@ -13,5 +13,14 @@
 
   --button-icon-gap: 1.8rem;
 
-  /* --button-min-height: 4rem; */
+  /* Sized so the button's TOTAL rendered height matches --input-min-height, not its content
+     box alone — .input-button-core keeps box-sizing: content-box (changing that risks shifting
+     icon-only's aspect-ratio: 1 sizing), so its own padding-block and border have to be
+     subtracted back out here, unlike --input-min-height itself which happens to need no such
+     adjustment (InputTextCore has zero padding-block and no full border in its resting state).
+     This is a floor, not a fixed height — icon-only/pill buttons or longer button-text can
+     still grow past it. Textareas are the deliberate exception to this alignment entirely. */
+  --button-min-height: calc(
+    var(--input-min-height) - (2 * var(--button-padding-block)) - (2 * var(--button-border-width))
+  );
 }

package/app/components/02.molecules/input-copy/CONSUMER-STYLING.md

@@ -14,9 +14,9 @@ or instance) without touching the component itself.
 | `--input-copy-input-text-color` | `#333` | Input text colour |
 | `--input-copy-input-placeholder-color` | `#999` | Placeholder text colour |
 | `--input-copy-input-font-size` | `0.95rem` | Input field font size |
-| `--input-copy-button-bg` | `var(--theme-button-primary-surface)` | Copy button background |
-| `--input-copy-button-bg-hover` | `var(--theme-button-primary-surface-hover)` | Copy button background on hover |
-| `--input-copy-button-text-color` | `var(--theme-button-primary-text)` | Copy button text colour |
+| `--input-copy-button-bg` | `var(--input-button-primary-surface)` | Copy button background |
+| `--input-copy-button-bg-hover` | `var(--input-button-primary-surface-hover)` | Copy button background on hover |
+| `--input-copy-button-text-color` | `var(--input-button-primary-text)` | Copy button text colour |
 | `--input-copy-button-padding` | `0.8rem 1.2rem` | Copy button padding |
 | `--input-copy-button-border-radius` | `0.4rem` | Copy button corner rounding |
 | `--input-copy-button-gap` | `0.6rem` | Gap between icon and text in button |

package/app/components/02.molecules/input-copy/InputCopy.vue

@@ -102,9 +102,15 @@ onUnmounted(() => {
     --_input-placeholder-color: var(--input-copy-input-placeholder-color, #999);
     --_input-font-size: var(--input-copy-input-font-size, 0.95rem);
 
-    --_button-bg: var(--input-copy-button-bg, var(--theme-button-primary-surface));
-    --_button-bg-hover: var(--input-copy-button-bg-hover, var(--theme-button-primary-surface-hover));
-    --_button-text-color: var(--input-copy-button-text-color, var(--theme-button-primary-text));
+    --_button-bg: var(--input-copy-button-bg, var(--input-button-primary-surface, var(--theme-surface)));
+    --_button-bg-hover: var(
+      --input-copy-button-bg-hover,
+      var(--input-button-primary-surface-hover, var(--theme-surface-hover))
+    );
+    --_button-text-color: var(
+      --input-copy-button-text-color,
+      var(--input-button-primary-text, var(--theme-on-surface))
+    );
     --_button-padding: var(--input-copy-button-padding, 0.8rem 1.2rem);
     --_button-border-radius: var(--input-copy-button-border-radius, 0.4rem);
     --_button-gap: var(--input-copy-button-gap, 0.6rem);

package/app/components/02.molecules/pricing-card/CONSUMER-STYLING.md

@@ -33,9 +33,9 @@ override it — there is no locale-aware formatting, just a literal prefix chara
 | `--pricing-card-description-color` | `#555` | Plan description text colour |
 | `--pricing-card-feature-color` | `#333` | Feature list text colour |
 | `--pricing-card-cta-align` | `flex-start` | CTA wrapper `align-self` — set to `stretch`, `center`, or `flex-end` to change CTA alignment/width within the card |
-| `--pricing-card-cta-bg` | `var(--theme-button-primary-surface)` | CTA button background |
-| `--pricing-card-cta-bg-hover` | `var(--theme-button-primary-surface-hover)` | CTA button background on hover |
-| `--pricing-card-cta-text` | `var(--theme-button-primary-text)` | CTA button text colour |
+| `--pricing-card-cta-bg` | `var(--input-button-primary-surface)` | CTA button background |
+| `--pricing-card-cta-bg-hover` | `var(--input-button-primary-surface-hover)` | CTA button background on hover |
+| `--pricing-card-cta-text` | `var(--input-button-primary-text)` | CTA button text colour |
 | `--pricing-card-cta-padding` | `1rem 1.6rem` | CTA button padding |
 | `--pricing-card-cta-border-radius` | `0.4rem` | CTA button corner rounding |
 

package/app/components/02.molecules/pricing-card/PricingCard.vue

@@ -111,9 +111,12 @@ watch(
     --_feature-color: var(--pricing-card-feature-color, #333);
 
     --_cta-align: var(--pricing-card-cta-align, flex-start);
-    --_cta-bg: var(--pricing-card-cta-bg, var(--theme-button-primary-surface));
-    --_cta-bg-hover: var(--pricing-card-cta-bg-hover, var(--theme-button-primary-surface-hover));
-    --_cta-text: var(--pricing-card-cta-text, var(--theme-button-primary-text));
+    --_cta-bg: var(--pricing-card-cta-bg, var(--input-button-primary-surface, var(--theme-surface)));
+    --_cta-bg-hover: var(
+      --pricing-card-cta-bg-hover,
+      var(--input-button-primary-surface-hover, var(--theme-surface-hover))
+    );
+    --_cta-text: var(--pricing-card-cta-text, var(--input-button-primary-text, var(--theme-on-surface)));
     --_cta-padding: var(--pricing-card-cta-padding, 1rem 1.6rem);
     --_cta-border-radius: var(--pricing-card-cta-border-radius, 0.4rem);
 

package/app/components/05.forms/input-button/CONSUMER-STYLING.md

@@ -0,0 +1,117 @@
+# InputButtonCore — Consumer Styling Guide
+
+## Public token API
+
+Every colour token below is `var(--input-button-{variant}-{property}, {default})` — set the
+`--input-button-*` name to override just this component's variant; leave it unset and it inherits
+the shared `--theme-*` slot every other themed component (inputs, alerts, ...) also falls back to.
+See `theming-component-token-pattern.md` for why this two-tier shape exists.
+
+**Resting state is flat by design**: `border` defaults to the variant's own surface colour, so
+there's no visible edge until you hover, focus, or override it. **`outline` defaults to fully
+transparent** in both resting and hover state — outline is reserved for the focus-visible ring,
+not used to reinforce the flat look. **Hover always darkens the resting surface** via `color-mix()`
+rather than jumping to a different `--theme-*` step — it's reliably darker in both light and dark
+mode. **`:focus-visible` is a separate token set**, not grouped with hover, since it's the one
+state that gets a real, independently-themeable indicator (its `outline-width`/`-offset` come from
+`--button-focus-ring-width`/`-offset`, not from here — see `theming-form-geometry-tokens.md`).
+
+Geometry and typography (`--button-*`) are separate, already-global tokens with real defaults —
+see `theming-form-geometry-tokens.md`. Not duplicated here. One geometry token worth calling out:
+`--button-min-height` defaults to `var(--input-min-height)`, so a button lines up height-wise with
+a text input/select/number field placed next to it (e.g. an inline "email + submit" pattern — see
+the `InlineWithTextInput` story). `box-sizing: content-box` means it's a floor, not a fixed height.
+
+### Primary
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--input-button-primary-surface` | `var(--theme-surface)` | Background (resting) |
+| `--input-button-primary-text` | `var(--theme-on-surface)` | Text colour (all states) |
+| `--input-button-primary-border` | the resolved surface above | Border colour (resting) — flat by default |
+| `--input-button-primary-ring` | `transparent` | Outline colour (resting) |
+| `--input-button-primary-surface-hover` | `color-mix(in oklab, surface 85%, black)` | Background on hover |
+| `--input-button-primary-border-hover` | the resolved hover surface above | Border colour on hover |
+| `--input-button-primary-ring-hover` | `transparent` | Outline colour on hover |
+| `--input-button-primary-border-focus` | `var(--theme-border-focus)` | Border colour on `:focus-visible` |
+| `--input-button-primary-ring-focus` | `var(--theme-ring)` | Outline colour on `:focus-visible` |
+
+### Secondary
+
+Same shape, falls back to the inverted-surface slots instead:
+
+| Token | Falls back to |
+|---|---|
+| `--input-button-secondary-surface` | `var(--theme-surface-inverted)` |
+| `--input-button-secondary-text` | `var(--theme-text-inverted)` |
+| `--input-button-secondary-border` | the resolved surface above (flat) |
+| `--input-button-secondary-ring` / `-ring-hover` | `transparent` |
+| `--input-button-secondary-surface-hover` | `color-mix(in oklab, surface 85%, black)` |
+| `--input-button-secondary-border-hover` | the resolved hover surface above |
+| `--input-button-secondary-border-focus` | `var(--theme-border-focus)` |
+| `--input-button-secondary-ring-focus` | `var(--theme-ring)` |
+
+### Tertiary
+
+Same shape again; resting surface is transparent by default in dark mode (see note below):
+
+| Token | Falls back to |
+|---|---|
+| `--input-button-tertiary-surface` | `light-dark(var(--slate-01), transparent)` |
+| `--input-button-tertiary-text` | `var(--theme-text)` |
+| `--input-button-tertiary-border` | the resolved surface above (flat) |
+| `--input-button-tertiary-ring` / `-ring-hover` | `transparent` |
+| `--input-button-tertiary-surface-hover` | `color-mix(in oklab, surface 85%, black)` |
+| `--input-button-tertiary-border-hover` | the resolved hover surface above |
+| `--input-button-tertiary-border-focus` | `var(--theme-border-focus)` |
+| `--input-button-tertiary-ring-focus` | `var(--theme-ring)` |
+
+> `--input-button-tertiary-surface`'s dark-mode default is literal `transparent`. `color-mix()`
+> still produces a correct darker hover from that — mixing `transparent` with `black` lowers the
+> alpha channel rather than the lightness, so hover reads as a faint dark tint over whatever's
+> behind the button, not a flat fill swap.
+
+`.is-pending` always dims the *primary* surface regardless of variant — a pre-existing quirk, not
+something this token set changes.
+
+`InputCopy` and `PricingCard` fall back through `--input-button-primary-*` for their own copy/CTA
+buttons (see their own `CONSUMER-STYLING.md`) rather than duplicating this chain.
+
+---
+
+## Global theming — app-level CSS file
+
+Set tokens on `:where(html)` in the consuming app's own theming file (e.g.
+`assets/styles/setup/03.theming/_button.css`). These apply to every `InputButtonCore` instance:
+
+```css
+:where(html) {
+  --input-button-primary-surface: var(--rose-09);
+  --input-button-primary-text: var(--rose-00);
+  /* Hover/border/ring all derive from --input-button-primary-surface automatically via
+     color-mix() — no need to also set -hover/-border/-ring unless you want a different
+     relationship than "same colour, darker". */
+}
+```
+
+Only declare the tokens you want to change — everything else keeps inheriting the shared
+`--theme-*` slots (or, for hover, keeps darkening whatever surface you did set).
+
+---
+
+## Per-instance overrides
+
+```vue
+<InputButtonCore variant="primary" button-text="Book now" style="--input-button-primary-surface: var(--gold-06);" />
+```
+
+To make hover lighten instead of darken for one instance, override the hover token directly rather
+than fighting the `color-mix()` default:
+
+```vue
+<InputButtonCore
+  variant="primary"
+  button-text="Book now"
+  style="--input-button-primary-surface-hover: var(--gold-04);"
+/>
+```

package/app/components/05.forms/input-button/InputButtonCore.vue

@@ -106,6 +106,7 @@ const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
     justify-content: center;
     align-items: center;
     box-sizing: content-box;
+    min-height: var(--button-min-height);
     border-radius: var(--button-border-radius);
     font-family: var(--font-family);
     padding-inline: var(--button-padding-inline);
@@ -121,60 +122,105 @@ const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
 
     /*
     * Theming
+    * Every colour is a public --input-button-{variant}-{property} token, inline-fallback to
+    * the shared theme slot (see theming-component-token-pattern.md for why: overriding one
+    * variant here never touches the --theme-* slots other components read).
+    *
+    * Flat by default: border defaults to the variant's own surface colour (so the resting state
+    * shows no visible edge) and outline defaults to fully transparent — outline is reserved for
+    * the focus-visible ring, not used to reinforce the flat look. Hover darkens the surface via
+    * color-mix (always darker, regardless of which direction the underlying theme ramp runs in
+    * light vs dark mode — no more "hover looks lighter" surprises) and carries the border along
+    * with it, still flat; outline stays transparent through hover too.
+    * focus-visible is deliberately its own block, not grouped with :hover — it's the one state
+    * that gets a real, separately-themeable a11y indicator, and its outline-width/-offset (set
+    * below, in Shared States) give it a visible ring regardless of the border/outline being
+    * invisible everywhere else.
+    * --_surface is a private local (not a public token) — it exists purely so -hover/-border/-ring
+    * can color-mix() off the SAME resolved value a consumer's --input-button-{variant}-surface
+    * override produces, without every derived token repeating that fallback chain itself.
     **/
-    background-color: var(--theme-surface);
-    color: var(--theme-on-surface);
-    border: var(--button-border-width) solid var(--theme-border);
-    outline: var(--button-outline-width) solid var(--theme-ring);
+    &.primary {
+      --_surface: var(--input-button-primary-surface, var(--theme-surface));
+      --_surface-hover: var(--input-button-primary-surface-hover, color-mix(in oklab, var(--_surface) 85%, black));
 
-    &:hover,
-    &:focus-visible {
-      background-color: var(--theme-surface-hover);
-      /* --theme-on-surface, not --theme-text: --theme-surface-hover's light-mode branch is a
-         dark step (by design — this button stays a bold colour even in light mode), and
-         --theme-text's light-mode branch is dark too (it's meant for text on a light surface
-         elsewhere, e.g. AlertContentInner). Pairing them made hover text invisible in light
-         mode. --theme-on-surface is a fixed light value regardless of scheme, matching how
-         AlertContentInner's own dismiss-button hover and .secondary:hover below already do it. */
-      color: var(--theme-on-surface);
-      border-color: var(--theme-border-focus);
-      outline-color: var(--theme-ring);
+      background-color: var(--_surface);
+      color: var(--input-button-primary-text, var(--theme-on-surface));
+      border: var(--button-border-width) solid var(--input-button-primary-border, var(--_surface));
+      outline: var(--button-outline-width) solid var(--input-button-primary-ring, transparent);
+
+      &:hover {
+        background-color: var(--_surface-hover);
+        border-color: var(--input-button-primary-border-hover, var(--_surface-hover));
+        outline-color: var(--input-button-primary-ring-hover, transparent);
+      }
+
+      &:focus-visible {
+        border-color: var(--input-button-primary-border-focus, var(--theme-border-focus));
+        outline-color: var(--input-button-primary-ring-focus, var(--theme-ring));
+      }
     }
 
     &.is-pending {
-      background-color: color-mix(in oklab, var(--theme-surface) 50%, transparent);
+      /* Always the primary surface regardless of variant — pre-existing behaviour, not
+         something this migration changes. */
+      background-color: color-mix(
+        in oklab,
+        var(--input-button-primary-surface, var(--theme-surface)) 50%,
+        transparent
+      );
     }
 
     &.secondary {
-      background-color: var(--theme-surface-inverted);
-      border: var(--button-border-width) solid var(--theme-border);
-      color: var(--theme-text-inverted);
-      outline: var(--button-outline-width) solid var(--theme-ring);
+      --_surface: var(--input-button-secondary-surface, var(--theme-surface-inverted));
+      --_surface-hover: var(
+        --input-button-secondary-surface-hover,
+        color-mix(in oklab, var(--_surface) 85%, black)
+      );
+
+      background-color: var(--_surface);
+      color: var(--input-button-secondary-text, var(--theme-text-inverted));
+      border: var(--button-border-width) solid var(--input-button-secondary-border, var(--_surface));
+      outline: var(--button-outline-width) solid var(--input-button-secondary-ring, transparent);
+
+      &:hover {
+        background-color: var(--_surface-hover);
+        border-color: var(--input-button-secondary-border-hover, var(--_surface-hover));
+        outline-color: var(--input-button-secondary-ring-hover, transparent);
+      }
 
-      &:hover,
       &:focus-visible {
-        background-color: var(--theme-surface);
-        color: var(--theme-on-surface);
-        border-color: var(--theme-border-focus);
-        outline-color: var(--theme-surface);
+        border-color: var(--input-button-secondary-border-focus, var(--theme-border-focus));
+        outline-color: var(--input-button-secondary-ring-focus, var(--theme-ring));
       }
     }
 
     &.tertiary {
-      background-color: light-dark(var(--slate-01), transparent);
-      border: var(--button-border-width) solid var(--theme-border);
-      color: var(--theme-text);
+      /* --_surface can resolve to literal transparent (dark mode default) — color-mix() still
+         darkens correctly here: mixing transparent with black lowers the alpha channel rather
+         than the lightness, so it reads as a faint dark tint over whatever's behind the button
+         instead of a flat fill. Same formula, no special-casing needed. */
+      --_surface: var(--input-button-tertiary-surface, light-dark(var(--slate-01), transparent));
+      --_surface-hover: var(
+        --input-button-tertiary-surface-hover,
+        color-mix(in oklab, var(--_surface) 85%, black)
+      );
+
+      background-color: var(--_surface);
+      color: var(--input-button-tertiary-text, var(--theme-text));
+      border: var(--button-border-width) solid var(--input-button-tertiary-border, var(--_surface));
+      outline: var(--button-outline-width) solid var(--input-button-tertiary-ring, transparent);
       text-decoration: underline;
-      outline: var(--button-outline-width) solid var(--theme-border-focus);
 
-      &:hover,
+      &:hover {
+        background-color: var(--_surface-hover);
+        border-color: var(--input-button-tertiary-border-hover, var(--_surface-hover));
+        outline-color: var(--input-button-tertiary-ring-hover, transparent);
+      }
+
       &:focus-visible {
-        background-color: var(--theme-surface-hover);
-        /* Same fix as the base :hover above — background goes dark in light mode, so text
-           needs to switch off --theme-text (dark in light mode) to stay visible. */
-        color: var(--theme-on-surface);
-        border-color: var(--theme-border-focus);
-        outline-color: var(--theme-border-focus);
+        border-color: var(--input-button-tertiary-border-focus, var(--theme-border-focus));
+        outline-color: var(--input-button-tertiary-ring-focus, var(--theme-ring));
       }
     }
 

package/app/components/05.forms/input-button/stories/InputButtonCore.stories.ts

@@ -1,6 +1,7 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
 import { ref } from "vue";
 import StorybookComponent from "../InputButtonCore.vue";
+import InputTextCore from "../../input-text/InputTextCore.vue";
 
 interface InputButtonCoreStoryArgs {
   type: "submit" | "button" | "reset";
@@ -240,7 +241,17 @@ const Template: StoryFn<InputButtonCoreStoryArgs> = (args) => ({
   },
   template: `
     <div style="display: flex; flex-direction: column; gap: 1rem; align-items: flex-start;margin: 36px;">
+      <!-- :key forces a remount when any slot-visibility arg changes. Verified the args
+           themselves ARE reactive here (a plain {{ args.useLeftSlot }} interpolation updates
+           live on toggle) — the bug is narrower: Vue's compiled-at-runtime string template
+           doesn't reliably re-evaluate a <template v-if="..."> conditionally attached to a named
+           slot when only the v-if's condition changes, on this component/Storybook combination.
+           Toggling a control changed the fallthrough attribute (confirmed via useleftslot="true"
+           in the rendered DOM) but never actually added/removed the slot content until a hard
+           refresh. Remounting sidesteps whatever the underlying slot-stability quirk is, rather
+           than chasing it further. -->
       <StorybookComponent
+        :key="[args.useLeftSlot, args.useLeftIcon, args.useRightSlot, args.useRightIcon, args.useIconOnlySlot, args.useIconOnly].join(',')"
         v-bind="args"
         @click="handleClick"
       >
@@ -302,3 +313,27 @@ NuxtIconOnlyComponent.args = {
   useIconOnly: true,
   iconOnlyName: "mdi:chevron-right-circle-outline",
 };
+
+// Composition check, not a props demo: confirms InputButtonCore's --button-min-height (defaults
+// to var(--input-min-height)) actually keeps it height-aligned with an inline text input, the
+// most common "usual suspect" pairing (e.g. newsletter signup, search bar). Textareas are the
+// deliberate exception to this alignment and aren't part of this story.
+const InlineTemplate: StoryFn = () => ({
+  components: { StorybookComponent, InputTextCore },
+  template: `
+    <div style="margin: 36px; max-width: 480px;">
+      <div style="display: flex; align-items: flex-start; gap: 0.8rem;">
+        <InputTextCore
+          id="inline-email"
+          name="email"
+          type="email"
+          placeholder="you@example.com"
+          style="flex: 1;"
+        />
+        <StorybookComponent type="submit" variant="primary" button-text="Subscribe" />
+      </div>
+    </div>
+  `,
+});
+
+export const InlineWithTextInput = InlineTemplate.bind({});