srcdev-nuxt-components 9.4.12 → 9.5.1

package/app/components/05.forms/input-checkbox/stories/MultipleCheckboxes.stories.ts

@@ -0,0 +1,104 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { ref } from "vue";
+import StorybookComponent from "../MultipleCheckboxes.vue";
+import type { IFormMultipleOptions, InputUiVariant, OptionsLayout } from "~/types/forms/types.forms.d";
+
+interface MultipleCheckboxesStoryArgs {
+  name: string;
+  legend: string;
+  errorMessage: string;
+  required: boolean;
+  fieldHasError: boolean;
+  isButton: boolean;
+  isPill: boolean;
+  optionsLayout: OptionsLayout;
+  direction: "row" | "row-reverse";
+  displayAsDisc: boolean;
+  inputVariant: InputUiVariant;
+}
+
+export default {
+  title: "Components/Forms/Input Checkbox/MultipleCheckboxes",
+  component: StorybookComponent,
+  argTypes: {
+    name: { control: "text", table: { category: "Basic" } },
+    legend: { control: "text", table: { category: "Basic" } },
+    errorMessage: { control: "text", table: { category: "Basic" } },
+    required: { control: "boolean", table: { category: "Basic" } },
+    fieldHasError: { control: "boolean", table: { category: "States" } },
+    isButton: { control: "boolean", table: { category: "Styling" } },
+    isPill: { control: "boolean", description: "Only with isButton", table: { category: "Styling" } },
+    optionsLayout: {
+      control: { type: "select" },
+      options: ["equal-widths", "inline", "block"],
+      table: { category: "Styling" },
+    },
+    direction: {
+      control: { type: "select" },
+      options: ["row", "row-reverse"],
+      description: "Only with isButton",
+      table: { category: "Styling" },
+    },
+    displayAsDisc: { control: "boolean", table: { category: "Styling" } },
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    name: "services",
+    legend: "Services of interest",
+    errorMessage: "Choose at least one service",
+    required: false,
+    fieldHasError: false,
+    isButton: false,
+    isPill: false,
+    optionsLayout: "equal-widths",
+    direction: "row",
+    displayAsDisc: false,
+    inputVariant: "normal",
+  },
+} as Meta<MultipleCheckboxesStoryArgs>;
+
+const Template: StoryFn<MultipleCheckboxesStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref<string[]>([]);
+    const fieldData = ref<IFormMultipleOptions>({
+      data: [
+        { id: "1", name: "services", value: "cut", label: "Cut" },
+        { id: "2", name: "services", value: "colour", label: "Colour" },
+        { id: "3", name: "services", value: "balayage", label: "Balayage" },
+        { id: "4", name: "services", value: "styling", label: "Styling" },
+        { id: "5", name: "services", value: "treatment", label: "Conditioning treatment" },
+      ],
+      total: 5,
+      skip: 0,
+      limit: 10,
+    });
+    return { args, modelValue, fieldData };
+  },
+  template: `
+    <div style="margin: 36px; max-width: 560px;">
+      <StorybookComponent v-bind="args" v-model="modelValue" v-model:field-data="fieldData">
+        <template #descriptionText>Select all that apply.</template>
+      </StorybookComponent>
+      <p style="margin-top: 2rem; font-family: monospace;">modelValue: {{ JSON.stringify(modelValue) }}</p>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+
+export const Buttons = Template.bind({});
+Buttons.args = { isButton: true, optionsLayout: "inline" };
+
+export const Pills = Template.bind({});
+Pills.args = { isButton: true, isPill: true, optionsLayout: "inline" };
+
+export const Block = Template.bind({});
+Block.args = { optionsLayout: "block" };
+
+export const ErrorState = Template.bind({});
+ErrorState.args = { fieldHasError: true };

package/app/components/05.forms/input-checkbox/stories/SingleCheckbox.stories.ts

@@ -0,0 +1,75 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { ref } from "vue";
+import StorybookComponent from "../SingleCheckbox.vue";
+import type { InputUiVariant } from "~/types/forms/types.forms.d";
+
+interface SingleCheckboxStoryArgs {
+  name: string;
+  legend: string;
+  label: string;
+  errorMessage: string;
+  required: boolean;
+  fieldHasError: boolean;
+  inputVariant: InputUiVariant;
+}
+
+export default {
+  title: "Components/Forms/Input Checkbox/SingleCheckbox",
+  component: StorybookComponent,
+  argTypes: {
+    name: { control: "text", table: { category: "Basic" } },
+    legend: { control: "text", table: { category: "Basic" } },
+    label: { control: "text", table: { category: "Basic" } },
+    errorMessage: { control: "text", table: { category: "Basic" } },
+    required: { control: "boolean", table: { category: "Basic" } },
+    fieldHasError: { control: "boolean", table: { category: "States" } },
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "outlined", "underlined"],
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    name: "terms",
+    legend: "Terms and conditions",
+    label: "I agree to the terms",
+    errorMessage: "You must agree to the terms",
+    required: true,
+    fieldHasError: false,
+    inputVariant: "normal",
+  },
+} as Meta<SingleCheckboxStoryArgs>;
+
+const Template: StoryFn<SingleCheckboxStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref(false);
+    return { args, modelValue };
+  },
+  template: `
+    <div style="margin: 36px; max-width: 480px;">
+      <StorybookComponent v-bind="args" v-model="modelValue" />
+      <p style="margin-top: 2rem; font-family: monospace;">modelValue: {{ modelValue }}</p>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});
+
+export const ErrorState = Template.bind({});
+ErrorState.args = { fieldHasError: true };
+
+export const RichLabel: StoryFn<SingleCheckboxStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref(false);
+    return { args, modelValue };
+  },
+  template: `
+    <div style="margin: 36px; max-width: 480px;">
+      <StorybookComponent v-bind="args" v-model="modelValue">
+        <template #labelContent>I agree to the <a href="#">terms and conditions</a></template>
+      </StorybookComponent>
+    </div>
+  `,
+});

package/app/components/05.forms/input-checkbox/tests/MultipleCheckboxes.spec.ts

@@ -1,22 +1,19 @@
 // https://nuxt.com/docs/getting-started/testing#unit-testing
 import type { VueWrapper } from "@vue/test-utils";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
-import { ref } from "vue";
 import type { FormUiTheme, OptionsLayout } from "~/types/forms/types.forms";
 import ComponentUnderTest from "../MultipleCheckboxes.vue";
 import tagsData from "./data/tags.json";
 
 const initialPropsData = {
   dataTestid: "multiple-checkboxes",
-  id: "tags",
   name: "tags",
   legend: "Choose tags (as checkboxes)",
   required: true,
-  label: "Check between 3 and 8 tags",
-  placeholder: "eg. Type something here",
   isButton: true,
   errorMessage: "Please select between 3 and 8 tags",
   fieldHasError: false,
+  modelValue: [] as string[],
   fieldData: tagsData,
   optionsLayout: "inline" as OptionsLayout,
   styleClassPassthrough: ["testClass"],
@@ -25,7 +22,6 @@ const initialPropsData = {
 
 const initialSlots = {
   checkedIcon: () => ``,
-  itemIcon: () => `<Icon name="material-symbols:add-2" class="icon" />`,
 };
 
 let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
@@ -46,56 +42,98 @@ describe("MultipleCheckboxes Component", () => {
     expect(wrapper).toBeTruthy();
   });
 
-  it("renders properly", async () => {
+  it("renders the data-testid and applies styleClassPassthrough to the fieldset", async () => {
     wrapper = await wrapperFactory();
-    const dataTestIdElem = wrapper.attributes("data-testid");
-    expect(dataTestIdElem).toBe(initialPropsData.dataTestid);
-    // The styleClassPassthrough is applied to the FormFieldset component, not the root
-    expect(wrapper.find(".form-fieldset").classes()).toContain("testClass");
+    expect(wrapper.attributes("data-testid")).toBe(initialPropsData.dataTestid);
+    const fieldset = wrapper.find(".form-fieldset");
+    expect(fieldset.classes()).toContain("multiple-checkboxes-fieldset");
+    expect(fieldset.classes()).toContain("testClass");
   });
 
-  it("updates checkbox modelValue when items clicked", async () => {
-    const modelValue = ref<string[]>([]);
-    const propsData = {
-      modelValue,
-    };
-    wrapper = await wrapperFactory(propsData);
-    const checkboxElements = wrapper.findAll('input[type="checkbox"]');
-
-    /*
-     * Test the first checkbox checked
-     **/
-    const firstCheckbox = checkboxElements[0];
-    expect(firstCheckbox).toBeDefined();
-    expect(firstCheckbox!.attributes("aria-checked")).toBe("false");
-    const firstCheckboxTrueValue = firstCheckbox!.attributes("true-value");
-
-    await firstCheckbox!.trigger("click");
-
-    expect(wrapper.emitted()).toHaveProperty("update:modelValue");
-    const firstEmittedEvents = wrapper.emitted("update:modelValue");
-    if (firstEmittedEvents && firstEmittedEvents[0]) {
-      expect(firstEmittedEvents[0]).includes(firstCheckboxTrueValue);
-    }
-
-    expect(firstCheckbox!.attributes("aria-checked")).toBe("true");
-
-    /*
-     * Test the second checkbox chekced
-     **/
-    const secondCheckbox = checkboxElements[1];
-    expect(secondCheckbox).toBeDefined();
-    expect(secondCheckbox!.attributes("aria-checked")).toBe("false");
-    const secondCheckboxTrueValue = secondCheckbox!.attributes("true-value");
-
-    await secondCheckbox!.trigger("click");
-
-    expect(wrapper.emitted()).toHaveProperty("update:modelValue");
-    const secondEmittedEvents = wrapper.emitted("update:modelValue");
-    if (secondEmittedEvents && secondEmittedEvents[0]) {
-      expect(secondEmittedEvents[1]).includes(secondCheckboxTrueValue);
-    }
-
-    expect(secondCheckbox!.attributes("aria-checked")).toBe("true");
+  it("renders the legend", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("legend").text()).toBe(initialPropsData.legend);
+  });
+
+  it("renders one checkbox per fieldData item", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.findAll('input[type="checkbox"]').length).toBe(tagsData.data.length);
+  });
+
+  it("uses the button presentation when isButton is true", async () => {
+    wrapper = await wrapperFactory({ isButton: true });
+    expect(wrapper.findAll(".input-checkbox-radio-button").length).toBe(tagsData.data.length);
+  });
+
+  it("uses the labelled presentation when isButton is false", async () => {
+    wrapper = await wrapperFactory({ isButton: false });
+    expect(wrapper.find(".input-checkbox-radio-button").exists()).toBe(false);
+    expect(wrapper.findAll(".input-checkbox-radio-field").length).toBe(tagsData.data.length);
+  });
+
+  it("renders optionsLayout as data-options-layout on the items container", async () => {
+    wrapper = await wrapperFactory({ optionsLayout: "block" as OptionsLayout });
+    expect(wrapper.find(".multiple-checkboxes-items").attributes("data-options-layout")).toBe("block");
+  });
+
+  it("does not put native required on each checkbox in the group", async () => {
+    wrapper = await wrapperFactory({ required: true, isButton: false });
+    const checkboxes = wrapper.findAll('input[type="checkbox"]');
+    checkboxes.forEach((checkbox) => {
+      expect(checkbox.attributes("required")).toBeUndefined();
+    });
+  });
+
+  it("gives each checkbox an id derived from name and value", async () => {
+    wrapper = await wrapperFactory();
+    const first = wrapper.find('input[type="checkbox"]');
+    expect(first.attributes("id")).toBe(`tags-${tagsData.data[0]!.value}`);
+  });
+
+  it("adds each clicked value to the model", async () => {
+    wrapper = await wrapperFactory({
+      "onUpdate:modelValue": (value: string[]) => wrapper.setProps({ modelValue: value }),
+    });
+    const checkboxes = wrapper.findAll('input[type="checkbox"]');
+
+    await checkboxes[0]!.setValue(true);
+    expect(wrapper.props("modelValue")).toEqual([tagsData.data[0]!.value]);
+    expect((checkboxes[0]!.element as HTMLInputElement).checked).toBe(true);
+
+    await checkboxes[1]!.setValue(true);
+    expect(wrapper.props("modelValue")).toEqual([tagsData.data[0]!.value, tagsData.data[1]!.value]);
+    expect((checkboxes[1]!.element as HTMLInputElement).checked).toBe(true);
+  });
+
+  it("removes a value from the model when unchecked", async () => {
+    wrapper = await wrapperFactory({
+      modelValue: [tagsData.data[0]!.value],
+      "onUpdate:modelValue": (value: string[]) => wrapper.setProps({ modelValue: value }),
+    });
+    const first = wrapper.find('input[type="checkbox"]');
+    expect((first.element as HTMLInputElement).checked).toBe(true);
+
+    await first.setValue(false);
+    expect(wrapper.props("modelValue")).toEqual([]);
+  });
+
+  it("shows the error message and marks the fieldset invalid when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true });
+    const error = wrapper.find(".input-error-message");
+    expect(error.attributes("data-visible")).toBeDefined();
+    expect(error.text()).toContain(initialPropsData.errorMessage);
+    expect(wrapper.find(".form-fieldset").attributes("aria-invalid")).toBe("true");
+  });
+
+  it("points each checkbox's aria-describedby at the error message when in error", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true, isButton: false });
+    const errorId = wrapper.find(".input-error-message").attributes("id");
+    expect(errorId).toBeTruthy();
+    expect(wrapper.find('input[type="checkbox"]').attributes("aria-describedby")).toContain(errorId);
+  });
+
+  it("hides the error message when fieldHasError is false", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: false });
+    expect(wrapper.find(".input-error-message").attributes("data-visible")).toBeUndefined();
   });
 });

package/app/components/05.forms/input-checkbox/tests/SingleCheckbox.spec.ts

@@ -0,0 +1,112 @@
+import type { VueWrapper } from "@vue/test-utils";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import ComponentUnderTest from "../SingleCheckbox.vue";
+
+const initialPropsData = {
+  name: "terms",
+  legend: "Terms and conditions",
+  label: "I agree to the terms",
+  errorMessage: "You must agree to the terms",
+  fieldHasError: false,
+  modelValue: false as string | number | boolean,
+};
+
+let wrapper: VueWrapper<InstanceType<typeof ComponentUnderTest>>;
+const wrapperFactory = (propsData = {}, slotsData = {}) =>
+  mountSuspended(ComponentUnderTest, {
+    attachTo: document.body,
+    props: { ...initialPropsData, ...propsData },
+    slots: slotsData,
+  });
+
+describe("SingleCheckbox Component", () => {
+  it("Mounts", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper).toBeTruthy();
+  });
+
+  it("defaults data-testid to single-checkbox", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.attributes("data-testid")).toBe("single-checkbox");
+  });
+
+  it("applies styleClassPassthrough to the fieldset, not the error message", async () => {
+    wrapper = await wrapperFactory({ styleClassPassthrough: ["testClass"] });
+    const fieldset = wrapper.find(".form-fieldset");
+    expect(fieldset.classes()).toContain("single-checkbox-fieldset");
+    expect(fieldset.classes()).toContain("testClass");
+    expect(wrapper.find(".input-error-message").classes()).not.toContain("testClass");
+  });
+
+  it("renders the legend and label", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find("legend").text()).toBe(initialPropsData.legend);
+    expect(wrapper.text()).toContain(initialPropsData.label);
+  });
+
+  it("renders labelContent slot in place of the label prop", async () => {
+    wrapper = await wrapperFactory({}, { labelContent: () => "Custom label content" });
+    expect(wrapper.text()).toContain("Custom label content");
+  });
+
+  it("renders a single checkbox", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.findAll('input[type="checkbox"]').length).toBe(1);
+  });
+
+  it("puts native required on the checkbox when required is true", async () => {
+    wrapper = await wrapperFactory({ required: true });
+    expect(wrapper.find('input[type="checkbox"]').attributes("required")).toBeDefined();
+  });
+
+  it("toggles the model between trueValue and falseValue", async () => {
+    wrapper = await wrapperFactory({
+      "onUpdate:modelValue": (value: boolean) => wrapper.setProps({ modelValue: value }),
+    });
+    const checkbox = wrapper.find('input[type="checkbox"]');
+
+    await checkbox.setValue(true);
+    expect(wrapper.props("modelValue")).toBe(true);
+    expect((checkbox.element as HTMLInputElement).checked).toBe(true);
+
+    await checkbox.setValue(false);
+    expect(wrapper.props("modelValue")).toBe(false);
+    expect((checkbox.element as HTMLInputElement).checked).toBe(false);
+  });
+
+  it("emits custom trueValue and falseValue", async () => {
+    wrapper = await wrapperFactory({
+      modelValue: "no",
+      trueValue: "yes",
+      falseValue: "no",
+      "onUpdate:modelValue": (value: string) => wrapper.setProps({ modelValue: value }),
+    });
+    const checkbox = wrapper.find('input[type="checkbox"]');
+
+    await checkbox.setValue(true);
+    expect(wrapper.props("modelValue")).toBe("yes");
+
+    await checkbox.setValue(false);
+    expect(wrapper.props("modelValue")).toBe("no");
+  });
+
+  it("shows the error message and marks the fieldset invalid when fieldHasError is true", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true });
+    const error = wrapper.find(".input-error-message");
+    expect(error.attributes("data-visible")).toBeDefined();
+    expect(error.text()).toContain(initialPropsData.errorMessage);
+    expect(wrapper.find(".form-fieldset").attributes("aria-invalid")).toBe("true");
+  });
+
+  it("points the checkbox's aria-describedby at the error message when in error", async () => {
+    wrapper = await wrapperFactory({ fieldHasError: true });
+    const errorId = wrapper.find(".input-error-message").attributes("id");
+    expect(errorId).toBeTruthy();
+    expect(wrapper.find('input[type="checkbox"]').attributes("aria-describedby")).toContain(errorId);
+  });
+
+  it("hides the error message when fieldHasError is false", async () => {
+    wrapper = await wrapperFactory();
+    expect(wrapper.find(".input-error-message").attributes("data-visible")).toBeUndefined();
+  });
+});

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

@@ -1,46 +1,121 @@
-# InputCheckboxRadioCore / InputCheckboxRadioButton — Consumer Styling Guide
+# InputCheckboxRadio / InputCheckboxRadioField / InputCheckboxRadioButton — Consumer Styling Guide
 
-## Public token API
+Three components share this folder and its tokens:
+
+- `InputCheckboxRadio`: the bare control (the square or circle over a hidden native input).
+- `InputCheckboxRadioField`: the control plus a text label, used by `SingleCheckbox` and the
+  non-button mode of `MultipleCheckboxes`/`MultipleRadiobuttons`.
+- `InputCheckboxRadioButton`: the whole option drawn as a button or pill (`is-button` mode of
+  those group components).
+
+> **Renamed 2026-09-27**: `InputCheckboxRadioCore` → `InputCheckboxRadio`,
+> `InputCheckboxRadioWithLabel` → `InputCheckboxRadioField`. Classes changed with them, see
+> **State hooks**. Token names are unchanged.
 
-Every colour token below is `var(--input-checkbox-*, {default})` — set the `--input-checkbox-*`
-name to override just this component; leave it unset and it inherits the shared `--theme-*` slot
-(or `--theme-checkbox-symbol-surface`/`--theme-input-surface` family) every other themed component
-also falls back to. See `theming-component-token-pattern.md` for why this two-tier shape exists.
+## Public token API
 
-Defaults are unchanged from before this migration — this is a token-rename pass (giving each
-property its own override point), not a redesign, unlike `InputButtonCore`'s flat/darker-hover
-treatment. Geometry (`--input-checked-element-size`, `--form-element-*`, etc.) is separate and
-untouched — see `theming-form-geometry-tokens.md`.
+Colour tokens fall back to the shared `--theme-*` slots, so overriding one only affects these
+components. See `theming-component-token-pattern.md` for the two-tier shape. Geometry tokens
+(`--input-checked-element-size`, `--form-element-*`, etc.) are shared by every form control and
+declared in `04.elements/forms/03.generic-input-geometry.css`; see `theming-form-geometry-tokens.md`.
 
-### The control itself (`InputCheckboxRadioCore` — the square/circle)
+### The control (`InputCheckboxRadio`, `.input-checkbox-radio`)
 
-| Token | Falls back to | Controls |
+| Token | Default | Controls |
 |---|---|---|
 | `--input-checkbox-surface` | `var(--theme-checkbox-symbol-surface)` | Background |
 | `--input-checkbox-border` | `var(--theme-border)` | Border colour |
-| `--input-checkbox-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (non-button style only — see note) |
-| `--input-checkbox-icon-color` | `var(--theme-text)` | Checked-state icon colour |
+| `--input-checkbox-border-focus` | `var(--theme-border-focus)` | Outline colour on `:focus-visible` (not in button mode, the button draws its own) |
+| `--input-checkbox-icon-color` | `var(--theme-text)` | Checked icon colour |
+| `--input-checkbox-transition-duration` | `var(--theme-form-transition-duration)` (`0.2s`) | Border/background and icon fade transitions, all three components |
+
+Shared geometry it reads: `--input-checked-element-size` (box size, `3rem`),
+`--input-checked-icon-size` (checked icon `font-size`, `2.6rem`), `--form-input-border-radius`
+(checkbox corners), `--form-element-outline-width*`/`--form-element-outline-offset-focus`.
+
+### The labelled field (`InputCheckboxRadioField`, `.input-checkbox-radio-field`)
 
-> The `:focus-visible` outline only applies to the plain checkbox/radio style
-> (`:not(.button)`) — `InputCheckboxRadioButton`'s pill/button style has its own focus treatment,
-> below, via `:has(.input-checkbox-radio-core:focus-visible)` on the outer label.
+| Token | Default | Controls |
+|---|---|---|
+| `--input-checkbox-label-color` | `inherit` | Label text colour |
+| `--input-checkbox-label-padding-block` | shared geometry, `0.8rem` | Label block padding |
+| `--input-checkbox-label-padding-inline` | shared geometry, `1.2rem` | Label inline padding |
+
+Also reads `--input-checked-icon-gap` (control to label gap) and `--input-min-height`.
 
-### The pill/button style (`InputCheckboxRadioButton` — e.g. a "Services of interest" option list)
+### The button style (`InputCheckboxRadioButton`, `.input-checkbox-radio-button`)
 
-| Token | Falls back to | Controls |
+| Token | Default | Controls |
 |---|---|---|
 | `--input-checkbox-button-surface` | `var(--theme-input-surface)` | Background (resting) |
-| `--input-checkbox-button-border` | `var(--theme-border)` | Border colour (resting and hover — unchanged between the two by default) |
+| `--input-checkbox-button-border` | `var(--theme-border)` | Border colour |
 | `--input-checkbox-button-surface-hover` | `var(--theme-input-surface-hover)` | Background on hover |
 | `--input-checkbox-button-ring-hover` | `var(--theme-ring)` | Outline colour on hover |
 | `--input-checkbox-button-surface-focus` | `var(--theme-surface-subtle)` | Background when the inner control has `:focus-visible` |
 | `--input-checkbox-button-ring-focus` | `var(--theme-border-focus)` | Outline colour when the inner control has `:focus-visible` |
-| `--input-checkbox-button-label-color` | `var(--colour-text-default)` | Option label text colour |
-| `--input-checkbox-button-icon-color` | `var(--theme-text)` | Trailing decorator icon colour (the `+` in the corner) |
+| `--input-checkbox-button-label-color` | `var(--theme-text)` | Option label colour |
+| `--input-checkbox-button-icon-color` | `var(--theme-text)` | Trailing decorator icon colour |
+| `--input-checkbox-button-border-radius` | `0.4rem` | Corner radius |
+| `--input-checkbox-button-border-radius-pill` | `100vw` | Corner radius with `is-pill` |
+| `--input-checkbox-button-gap` | `1rem` | Gap between control, label and icon |
+| `--input-checkbox-button-padding-block` | `0.4rem` | Block padding |
+| `--input-checkbox-button-padding-inline` | `1.2rem` | Inline padding |
+| `--input-checkbox-button-label-padding-block` | `0.8rem` | Label block padding |
+| `--input-checkbox-button-label-padding-inline` | `0.8rem` | Label inline padding |
+
+Also reads `--input-checkbox-decorator-icon-size` (decorator icon `font-size`, `2rem`) and
+`--input-font-size` (label).
+
+Private (not public API): `--_transition-duration` (the control's resolved duration, shared by two
+transitions), `--_icon-size` (the button shrinks the inner control's checked icon through it) and
+`--_white-space` (the button label's wrapping, swapped by `data-options-layout="inline"`).
+
+> **Changed 2026-09-27**:
+>
+> - The button's radius, gap and paddings were hardcoded; they're now tokens with the same defaults.
+> - `--input-checkbox-button-label-color` fell back to `--colour-text-default`; it now falls back
+>   to `--theme-text` like every other text colour here.
+> - `--input-checkbox-decorator-icon-size` and the button's shrunken checked icon were applied as
+>   `width`/`height`, which `@nuxt/icon` silently overrides (pitfall #24). They're now `font-size`,
+>   so both tokens take effect for the first time: the `+` renders at `2rem` and the checked icon
+>   inside a button at `--input-checked-icon-size` minus `0.8rem`.
+> - `--input-checkbox-label-color` is new (was unstyled, so `inherit`).
 
 ---
 
-## Global theming — app-level CSS file
+## State hooks
+
+| Attribute | On | When |
+|---|---|---|
+| `data-type="checkbox" \| "radio"` | `.input-checkbox-radio` | Always |
+| `data-input-variant="normal" \| "outlined" \| "underlined"` | `.input-checkbox-radio` | Always (`underlined` squares off a checkbox) |
+| `data-theme` | `.input-checkbox-radio`, `.input-checkbox-radio-button` | Always, mirrors `theme` |
+| `data-button` | `.input-checkbox-radio` | Rendered inside `InputCheckboxRadioButton` |
+| `data-display-as-disc` | `.input-checkbox-radio` | `display-as-disc` (rounds a checkbox, button mode only) |
+| `data-invalid` | all three roots | The field has an error |
+| `data-pill` | `.input-checkbox-radio-button` | `is-pill` |
+| `data-direction="row" \| "row-reverse"` | `.input-checkbox-radio-button` | Always, mirrors `direction` |
+| `data-options-layout` | `.input-checkbox-radio-button` | Always, mirrors `options-layout` (`inline` stops the label wrapping) |
+
+Inner elements: `.input-checkbox-radio-icon-slot` (holds the `checkedIcon` slot or the default
+`.input-checkbox-radio-icon`), `.input-checkbox-radio-input` (the hidden native input),
+`.input-checkbox-radio-field-label`, `.input-checkbox-radio-button-label`,
+`.input-checkbox-radio-button-icon`.
+
+> **Changed 2026-09-27**: state used to be bare classes (`.checkbox`, `.radio`, `.button`,
+> `.display-as-disc`, `.normal`/`.underlined` on the control; `.error`, `.inline`, `.is-pill` on
+> the label/button), which collide with common consumer CSS (an unlayered `.error` or `.button`
+> rule would restyle these). Select on the attributes above. Class renames:
+> `.input-checkbox-radio-wrapper` → `.input-checkbox-radio`, `.input-checkbox-radio-core` →
+> `.input-checkbox-radio-input`, `.input-checked-icon-slot`/`-checked` →
+> `.input-checkbox-radio-icon-slot`/`.input-checkbox-radio-icon`, `.input-checkbox-radio-with-label`
+> → `.input-checkbox-radio-field`, `.input-checkbox-radio-label` → `.input-checkbox-radio-field-label`,
+> `.input-checkbox-radio-options-button[-label]` → `.input-checkbox-radio-button[-label]`,
+> `.decorator-icon` → `.input-checkbox-radio-button-icon`.
+
+---
+
+## Global theming
 
 ```css
 :where(html) {
@@ -50,19 +125,24 @@ untouched — see `theming-form-geometry-tokens.md`.
 }
 ```
 
-Only declare the tokens you want to change — everything else keeps inheriting the shared
-`--theme-*`/`--theme-input-*` tokens.
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat**: `MultipleCheckboxes`, `MultipleRadiobuttons` and `SingleCheckbox` don't forward
+`style-class-passthrough` to these components (theirs lands on the fieldset), so set tokens on
+the group's own passthrough class or a wrapper you own.
 
 ---
 
-## Per-instance overrides
+## Class passthrough
 
-```vue
-<InputCheckboxRadioButton
-  id="balayage"
-  type="checkbox"
-  name="services"
-  label="Balayage"
-  style="--input-checkbox-button-surface-hover: var(--gold-08);"
-/>
-```
+Each component's `:style-class-passthrough` (string or string array) adds classes to its own root:
+`.input-checkbox-radio` for the control, the `<label>` for the Field and the Button. Reachable only
+when you use them directly; the group components don't forward it.