srcdev-nuxt-components 9.4.12 → 9.5.1

package/app/components/{01.atoms → 02.molecules}/display-avatar/tests/DisplayAvatar.spec.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import DisplayAvatar from "../DisplayAvatar.vue";
-import DisplayChip from "../../../02.molecules/display-chip/DisplayChip.vue";
+import DisplayChip from "../../display-chip/DisplayChip.vue";
 
 describe("DisplayAvatar", () => {
   // ─── Mount ───────────────────────────────────────────────────────────────
@@ -80,33 +80,33 @@ describe("DisplayAvatar", () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "John Doe" },
     });
-    expect(wrapper.find("span").text()).toBe("JD");
+    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("JD");
   });
 
   it("caps initials at two characters", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "Alice Bob Charlie" },
     });
-    expect(wrapper.find("span").text()).toBe("AB");
+    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("AB");
   });
 
   it("shows single initial for a single-word alt", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "Alice" },
     });
-    expect(wrapper.find("span").text()).toBe("A");
+    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("A");
   });
 
   it("shows text prop instead of alt-derived initials when text is set", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { alt: "John Doe", text: "?" },
     });
-    expect(wrapper.find("span").text()).toBe("?");
+    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("?");
   });
 
   it("shows empty fallback when neither src, text, nor alt are set", async () => {
     const wrapper = await mountSuspended(DisplayAvatar);
-    expect(wrapper.find("span").text()).toBe("");
+    expect(wrapper.find(".display-avatar > span:first-child").text()).toBe("");
   });
 
   // ─── Image ────────────────────────────────────────────────────────────────
@@ -115,26 +115,26 @@ describe("DisplayAvatar", () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { src: "/avatar.jpg" },
     });
-    expect(wrapper.find(".avatar-image").exists()).toBe(true);
+    expect(wrapper.find(".display-avatar-image").exists()).toBe(true);
   });
 
   it("does not render an image element when src is not provided", async () => {
     const wrapper = await mountSuspended(DisplayAvatar);
-    expect(wrapper.find(".avatar-image").exists()).toBe(false);
+    expect(wrapper.find(".display-avatar-image").exists()).toBe(false);
   });
 
-  it("falls back to 'Avatar' as alt text when src is set but alt is not", async () => {
+  it("uses an empty (decorative) alt when src is set but alt is not", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { src: "/avatar.jpg" },
     });
-    expect(wrapper.find(".avatar-image").attributes("alt")).toBe("Avatar");
+    expect(wrapper.find(".display-avatar-image").attributes("alt")).toBe("");
   });
 
   it("uses the alt prop as alt text on the image", async () => {
     const wrapper = await mountSuspended(DisplayAvatar, {
       props: { src: "/avatar.jpg", alt: "Profile picture" },
     });
-    expect(wrapper.find(".avatar-image").attributes("alt")).toBe("Profile picture");
+    expect(wrapper.find(".display-avatar-image").attributes("alt")).toBe("Profile picture");
   });
 
   // ─── Slots ────────────────────────────────────────────────────────────────
@@ -205,4 +205,36 @@ describe("DisplayAvatar", () => {
     expect(wrapper.classes()).not.toContain("online");
     expect(wrapper.classes()).toContain("offline");
   });
+
+  // ─── Migration 2026-09-27 ──────────────────────────────────────────────────
+
+  it("hides the initials from screen readers and announces the alt instead", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { alt: "John Doe" } });
+    expect(wrapper.find(".display-avatar > span:first-child").attributes("aria-hidden")).toBe("true");
+    expect(wrapper.find(".sr-only").text()).toBe("John Doe");
+  });
+
+  it("leaves text-only fallback readable when there is no alt", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { text: "?" } });
+    expect(wrapper.find(".display-avatar > span:first-child").attributes("aria-hidden")).toBeUndefined();
+    expect(wrapper.find(".sr-only").exists()).toBe(false);
+  });
+
+  it("does not render a stray style-class-passthrough attribute on a native root", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { styleClassPassthrough: ["online"] } });
+    expect(wrapper.attributes("style-class-passthrough")).toBeUndefined();
+  });
+
+  it("puts display-avatar, size and passthrough classes on the DisplayChip root", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, {
+      props: { chip: true, size: "lg", styleClassPassthrough: ["online"] },
+    });
+    expect(wrapper.classes()).toEqual(expect.arrayContaining(["display-chip", "display-avatar", "lg", "online"]));
+  });
+
+  it("updates the chip config when the chip prop changes", async () => {
+    const wrapper = await mountSuspended(DisplayAvatar, { props: { chip: true } });
+    await wrapper.setProps({ chip: { size: "20px", maskWidth: "2px", offset: "0px", angle: "0deg" } });
+    expect(wrapper.findComponent(DisplayChip).props("config")).toMatchObject({ size: "20px" });
+  });
 });

package/app/components/02.molecules/display-avatar/tests/__snapshots__/DisplayAvatar.spec.ts.snap

@@ -0,0 +1,11 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`DisplayAvatar > renders correct HTML structure (default) 1`] = `"<span class="display-avatar md"><span aria-hidden="true">JD</span><span class="sr-only">John Doe</span></span>"`;
+
+exports[`DisplayAvatar > renders correct HTML structure (with chip) 1`] = `
+"<span class="display-chip circle display-avatar md" style="--_chip-size: 12px; --_chip-mask-width: 4px; --_chip-offset: 0px; --_chip-angle: 90deg;"><span aria-hidden="true">JD</span><span class="sr-only">John Doe</span>
+<!--v-if-->
+<!--v-if--></span>"
+`;
+
+exports[`DisplayAvatar > renders correct HTML structure (with src) 1`] = `"<span class="display-avatar lg"><img data-nuxt-img="" srcset="/_ipx/_/avatar.jpg 1x, /_ipx/_/avatar.jpg 2x" alt="John Doe" class="display-avatar-image" src="/_ipx/_/avatar.jpg"></span>"`;

package/app/components/02.molecules/display-chip/CONSUMER-STYLING.md

@@ -0,0 +1,57 @@
+# DisplayChip — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-chip-colour-offline` | `slategrey` | Dot colour with no status class |
+| `--display-chip-colour-online` | `rgb(0, 255, 135)` | Dot colour with `.online` |
+| `--display-chip-colour-idle` | `rgb(255, 185, 51)` | Dot colour with `.idle` |
+| `--display-chip-colour-dnd` | `rgb(255, 40, 80)` | Dot colour with `.dnd` |
+| `--display-chip-text-colour` | `black` | Icon and label colour on the dot |
+
+Geometry (size, mask width, offset, angle) is set through the `config` prop, not tokens. Those
+values are written inline as private `--_chip-size`, `--_chip-mask-width`, `--_chip-offset` and
+`--_chip-angle`, which feed the private position maths (`--_mask-diameter`, `--_position-x`,
+`--_position-y`, `--_offset`, `--_circle-x`, `--_circle-y`) and the resolved `--_dot-colour`. None
+of these are public API.
+
+> Changed 2026-09-27: the status colours were unprefixed `--color-offline`, `--color-online`,
+> `--color-idle` and `--color-dnd`, and the geometry and maths vars were unprefixed too
+> (`--chip-size`, `--computed-*`, `--circle-*`). Generic names like these collided with any
+> consumer variable of the same name. The icon is now sized with `font-size` (its old
+> `width`/`height` were overridden by `@nuxt/icon`), and the icon/label colour is a token instead
+> of a hardcoded `black`.
+
+---
+
+## State hooks
+
+| Class | When |
+|---|---|
+| `.display-chip.circle`, `.square` | The `shape` prop (must match the slotted content's shape) |
+| `.online`, `.idle`, `.dnd` | Added by you through `style-class-passthrough`; no class means offline |
+
+Inner elements: the dot is `.display-chip::after`; `.chip-icon` and `.chip-label` (with
+`.length-1`/`.length-2`/`.length-3` for font-size stepping) sit on top of it. Every other direct
+child gets the cutout `mask-image`.
+
+> Changed 2026-09-27: root class renamed from `.display-chip-core`.
+
+---
+
+## 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`.
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.display-chip`. It's also how you set the
+status (`online`, `idle`, `dnd`). Reactive after mount. `DisplayAvatar` with `chip` renders this
+component as its root, so the same applies there.

package/app/components/02.molecules/display-chip/DisplayChip.vue

@@ -1,5 +1,5 @@
 <template>
-  <component :is="tag" class="display-chip-core" :class="[shape, elementClasses]" :style="chipStyles">
+  <component :is="tag" class="display-chip" :class="[shape, elementClasses]" :style="chipStyles">
     <slot name="default"></slot>
     <Icon v-if="config?.icon" :name="config.icon" class="chip-icon" />
     <span v-if="config?.label" class="chip-label" :class="`length-${config.label.length}`">{{ validatedLabel }}</span>
@@ -53,74 +53,84 @@ const validatedLabel = computed(() => {
 });
 
 const chipStyles = computed(() => ({
-  "--chip-size": props.config?.size,
-  "--chip-mask-width": props.config?.maskWidth,
-  "--chip-offset": props.config?.offset,
-  "--chip-angle": props.config?.angle,
+  "--_chip-size": props.config?.size,
+  "--_chip-mask-width": props.config?.maskWidth,
+  "--_chip-offset": props.config?.offset,
+  "--_chip-angle": props.config?.angle,
 }));
 </script>
 
 <style lang="css">
 @layer components {
-  .display-chip-core {
-    --computed-mask-diameter: calc(var(--chip-size) + (var(--chip-mask-width) * 2));
+  .display-chip {
+    --_mask-diameter: calc(var(--_chip-size) + (var(--_chip-mask-width) * 2));
+    --_dot-colour: var(--display-chip-colour-offline, slategrey);
+
+    position: relative;
+    display: inline-block;
 
     &.circle {
-      --computed-chip-offset: calc((100% / 2) + var(--chip-offset));
-      --computed-position-x: calc(var(--computed-chip-offset) * cos(var(--chip-angle) - 90deg) + (100% / 2));
-      --computed-position-y: calc(var(--computed-chip-offset) * sin(var(--chip-angle) - 90deg) + (100% / 2));
+      --_offset: calc((100% / 2) + var(--_chip-offset));
+      --_position-x: calc(var(--_offset) * cos(var(--_chip-angle) - 90deg) + (100% / 2));
+      --_position-y: calc(var(--_offset) * sin(var(--_chip-angle) - 90deg) + (100% / 2));
     }
 
     &.square {
-      --circle-x: calc(50% + (50% + var(--chip-offset) + (var(--chip-size) / 2)) * cos(var(--chip-angle) - 90deg));
-      --circle-y: calc(50% + (50% + var(--chip-offset) + (var(--chip-size) / 2)) * sin(var(--chip-angle) - 90deg));
-      --computed-position-x: clamp(calc(var(--chip-offset) * -1), var(--circle-x), calc(100% + var(--chip-offset)));
-      --computed-position-y: clamp(calc(var(--chip-offset) * -1), var(--circle-y), calc(100% + var(--chip-offset)));
+      --_circle-x: calc(50% + (50% + var(--_chip-offset) + (var(--_chip-size) / 2)) * cos(var(--_chip-angle) - 90deg));
+      --_circle-y: calc(50% + (50% + var(--_chip-offset) + (var(--_chip-size) / 2)) * sin(var(--_chip-angle) - 90deg));
+      --_position-x: clamp(calc(var(--_chip-offset) * -1), var(--_circle-x), calc(100% + var(--_chip-offset)));
+      --_position-y: clamp(calc(var(--_chip-offset) * -1), var(--_circle-y), calc(100% + var(--_chip-offset)));
     }
 
-    /* colors */
+    &.online {
+      --_dot-colour: var(--display-chip-colour-online, rgb(0, 255, 135));
+    }
 
-    --color-offline: slategrey;
-    --color-online: rgb(0, 255, 135);
-    --color-idle: rgb(255, 185, 51);
-    --color-dnd: rgb(255, 40, 80);
+    &.idle {
+      --_dot-colour: var(--display-chip-colour-idle, rgb(255, 185, 51));
+    }
 
-    position: relative;
-    display: inline-block;
+    &.dnd {
+      --_dot-colour: var(--display-chip-colour-dnd, rgb(255, 40, 80));
+    }
 
     &::after {
       content: "";
       aspect-ratio: 1;
-      background: var(--color-offline);
+      background: var(--_dot-colour);
       position: absolute;
-      width: var(--chip-size);
+      width: var(--_chip-size);
       border-radius: 100%;
       z-index: 1;
     }
+
+    &::after,
+    .chip-icon,
+    .chip-label {
+      top: calc(var(--_position-y) - (var(--_chip-size) / 2));
+      left: calc(var(--_position-x) - (var(--_chip-size) / 2));
+    }
+
     .chip-icon {
       position: absolute;
-      width: var(--chip-size);
-      height: var(--chip-size);
-      border-radius: 100%;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      color: black;
+      font-size: var(--_chip-size);
+      color: var(--display-chip-text-colour, black);
       z-index: 2;
     }
 
     .chip-label {
       --_font-size-adjust: 0.7;
+
       position: absolute;
-      width: var(--chip-size);
-      height: var(--chip-size);
+      width: var(--_chip-size);
+      height: var(--_chip-size);
       border-radius: 100%;
       display: flex;
       align-items: center;
       justify-content: center;
-      color: black;
+      color: var(--display-chip-text-colour, black);
       z-index: 2;
-      font-size: calc(var(--chip-size) * var(--_font-size-adjust));
+      font-size: calc(var(--_chip-size) * var(--_font-size-adjust));
       line-height: 1;
       letter-spacing: -0.05rem;
       user-select: none;
@@ -134,55 +144,12 @@ const chipStyles = computed(() => ({
       }
     }
 
-    & > * {
-      /*
-    create the cutout mask around the image,
-    it's just a radial gradient positioned at the same place as the
-    psuedo-element ::after
-    */
-
-      &:not(.chip-icon, .chip-label) {
-        mask-image: radial-gradient(
-          var(--computed-mask-diameter) var(--computed-mask-diameter) at var(--computed-position-x)
-            var(--computed-position-y),
-          transparent calc(50% - 0.5px),
-          black calc(50% + 0.5px)
-        );
-      }
-    }
-
-    &.circle {
-      &::after,
-      .chip-icon,
-      .chip-label {
-        top: calc(var(--computed-position-y) - (var(--chip-size) / 2));
-        left: calc(var(--computed-position-x) - (var(--chip-size) / 2));
-      }
-    }
-
-    &.square {
-      &::after,
-      .chip-icon,
-      .chip-label {
-        top: calc(var(--computed-position-y) - (var(--chip-size) / 2));
-        left: calc(var(--computed-position-x) - (var(--chip-size) / 2));
-      }
-    }
-
-    &.online {
-      &::after {
-        background-color: var(--color-online);
-      }
-    }
-    &.idle {
-      &::after {
-        background-color: var(--color-idle);
-      }
-    }
-    &.dnd {
-      &::after {
-        background-color: var(--color-dnd);
-      }
+    & > *:not(.chip-icon, .chip-label) {
+      mask-image: radial-gradient(
+        var(--_mask-diameter) var(--_mask-diameter) at var(--_position-x) var(--_position-y),
+        transparent calc(50% - 0.5px),
+        black calc(50% + 0.5px)
+      );
     }
   }
 }

package/app/components/02.molecules/display-chip/tests/DisplayChip.spec.ts

@@ -56,9 +56,9 @@ describe("DisplayChip", () => {
 
   // ─── Base class ───────────────────────────────────────────────────────────
 
-  it("always has the display-chip-core class", async () => {
+  it("always has the display-chip class", async () => {
     const wrapper = await mountSuspended(DisplayChip);
-    expect(wrapper.classes()).toContain("display-chip-core");
+    expect(wrapper.classes()).toContain("display-chip");
   });
 
   // ─── Shape ────────────────────────────────────────────────────────────────
@@ -83,19 +83,19 @@ describe("DisplayChip", () => {
       },
     });
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--chip-size")).toBe("16px");
-    expect(style.getPropertyValue("--chip-mask-width")).toBe("3px");
-    expect(style.getPropertyValue("--chip-offset")).toBe("4px");
-    expect(style.getPropertyValue("--chip-angle")).toBe("45deg");
+    expect(style.getPropertyValue("--_chip-size")).toBe("16px");
+    expect(style.getPropertyValue("--_chip-mask-width")).toBe("3px");
+    expect(style.getPropertyValue("--_chip-offset")).toBe("4px");
+    expect(style.getPropertyValue("--_chip-angle")).toBe("45deg");
   });
 
   it("sets default CSS custom properties when no config is provided", async () => {
     const wrapper = await mountSuspended(DisplayChip);
     const style = (wrapper.element as HTMLElement).style;
-    expect(style.getPropertyValue("--chip-size")).toBe("12px");
-    expect(style.getPropertyValue("--chip-mask-width")).toBe("4px");
-    expect(style.getPropertyValue("--chip-offset")).toBe("0px");
-    expect(style.getPropertyValue("--chip-angle")).toBe("90deg");
+    expect(style.getPropertyValue("--_chip-size")).toBe("12px");
+    expect(style.getPropertyValue("--_chip-mask-width")).toBe("4px");
+    expect(style.getPropertyValue("--_chip-offset")).toBe("0px");
+    expect(style.getPropertyValue("--_chip-angle")).toBe("90deg");
   });
 
   // ─── Label ────────────────────────────────────────────────────────────────

package/app/components/02.molecules/display-chip/tests/__snapshots__/DisplayChip.spec.ts.snap

@@ -1,12 +1,12 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`DisplayChip > renders correct HTML structure (default) 1`] = `"<span class="display-chip-core circle" style="--chip-size: 12px; --chip-mask-width: 4px; --chip-offset: 0px; --chip-angle: 90deg;"><!--v-if--><!--v-if--></span>"`;
+exports[`DisplayChip > renders correct HTML structure (default) 1`] = `"<span class="display-chip circle" style="--_chip-size: 12px; --_chip-mask-width: 4px; --_chip-offset: 0px; --_chip-angle: 90deg;"><!--v-if--><!--v-if--></span>"`;
 
-exports[`DisplayChip > renders correct HTML structure (square + styleClassPassthrough) 1`] = `"<span class="display-chip-core square online" style="--chip-size: 12px; --chip-mask-width: 4px; --chip-offset: 0px; --chip-angle: 90deg;"><!--v-if--><!--v-if--></span>"`;
+exports[`DisplayChip > renders correct HTML structure (square + styleClassPassthrough) 1`] = `"<span class="display-chip square online" style="--_chip-size: 12px; --_chip-mask-width: 4px; --_chip-offset: 0px; --_chip-angle: 90deg;"><!--v-if--><!--v-if--></span>"`;
 
 exports[`DisplayChip > renders correct HTML structure (with icon) 1`] = `
-"<span class="display-chip-core circle" style="--chip-size: 12px; --chip-mask-width: 4px; --chip-offset: 0px; --chip-angle: 90deg;"><span class="iconify i-mdi:check chip-icon" aria-hidden="true"></span>
+"<span class="display-chip circle" style="--_chip-size: 12px; --_chip-mask-width: 4px; --_chip-offset: 0px; --_chip-angle: 90deg;"><span class="iconify i-mdi:check chip-icon" aria-hidden="true"></span>
 <!--v-if--></span>"
 `;
 
-exports[`DisplayChip > renders correct HTML structure (with label) 1`] = `"<span class="display-chip-core circle" style="--chip-size: 12px; --chip-mask-width: 4px; --chip-offset: 0px; --chip-angle: 90deg;"><!--v-if--><span class="chip-label length-1">5</span></span>"`;
+exports[`DisplayChip > renders correct HTML structure (with label) 1`] = `"<span class="display-chip circle" style="--_chip-size: 12px; --_chip-mask-width: 4px; --_chip-offset: 0px; --_chip-angle: 90deg;"><!--v-if--><span class="chip-label length-1">5</span></span>"`;

package/app/components/02.molecules/display-theme-switch/CONSUMER-STYLING.md

@@ -1,14 +1,16 @@
 # DisplayThemeSwitch — Consumer Styling Guide
 
-## No tokens of its own — delegates entirely to TripleToggleSwitchCore
+## No tokens of its own — delegates entirely to TripleToggleSwitch
 
-`DisplayThemeSwitch` is a thin wrapper around `TripleToggleSwitchCore` (see
+`DisplayThemeSwitch` is a thin wrapper around `TripleToggleSwitch` (see
 `app/components/05.forms/triple-toggle-switch/CONSUMER-STYLING.md`) and declares no
 `--display-theme-switch-*` tokens of its own. Every colour token documented there
 (`--triple-toggle-switch-surface`, `--triple-toggle-switch-border`, `--triple-toggle-switch-marker-surface`,
 etc.) applies unchanged, since `DisplayThemeSwitch` renders that component directly with no
 intermediate styling layer.
 
+---
+
 ## `small` class — compact sizing
 
 Pass `"small"` via `styleClassPassthrough` for a more compact gap/padding/icon-size, useful in a
@@ -18,9 +20,9 @@ tight header/nav slot:
 <DisplayThemeSwitch style-class-passthrough="small" />
 ```
 
-This sets `TripleToggleSwitchCore`'s public `--triple-toggle-switch-gap`/`-padding`/
+This sets `TripleToggleSwitch`'s public `--triple-toggle-switch-gap`/`-padding`/
 `-option-padding`/`-icon-size` tokens to smaller values (`0.2rem`/`0.2rem`/`0.2rem`/`1.6rem` vs the
-default `0.4rem`/`0.4rem`/`0.4rem`/`2rem` — both already more compact than `TripleToggleSwitchCore`'s
+default `0.4rem`/`0.4rem`/`0.4rem`/`2rem` — both already more compact than `TripleToggleSwitch`'s
 own defaults of `1rem`/`0.6rem`/`0.5rem`/`2rem`). Override any of the four directly for a custom
 size instead of using `small`:
 
@@ -28,7 +30,26 @@ size instead of using `small`:
 <DisplayThemeSwitch style="--triple-toggle-switch-icon-size: 2.4rem;" />
 ```
 
+---
+
+## Local overrides
+
+There are no public tokens, so override the classes above with direct properties, scoped to an
+element you own (a page or section class, or a class added with `:style-class-passthrough`). Keep
+the block **unlayered** (no `@layer` wrapper) so it beats the library's `@layer components`. If your
+own file uses `<style scoped>`, selectors that reach inside the component need `:deep()`. Patterns
+and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** the colour tokens (`--triple-toggle-switch-surface`, `-border`, ...) work from any
+ancestor, but the four sizing tokens (`--triple-toggle-switch-gap`, `-padding`, `-option-padding`,
+`-icon-size`) are declared on this component's own root (that's how its default and `small` sizes
+work), so an ancestor value never reaches the toggle. Set those on the root itself: a class from
+`style-class-passthrough`, or inline `style` as shown above.
+
+---
+
 ## Class passthrough
 
 `styleClassPassthrough` also accepts any other class for layout purposes, alongside or instead of
 `small`.
+

package/app/components/02.molecules/display-theme-switch/DisplayThemeSwitch.vue

@@ -1,8 +1,9 @@
 <template>
   <ClientOnly>
-    <TripleToggleSwitchCore
+    <TripleToggleSwitch
       v-model="colorModeVal"
       v-model:field-data="sampleFieldData"
+      :aria-label="ariaLabel"
       :style-class-passthrough="[`colour-scheme-select`, elementClasses]"
     />
   </ClientOnly>
@@ -12,6 +13,7 @@
 import type { IFormMultipleOptions } from "~/types/forms/types.forms";
 interface Props {
   styleClassPassthrough?: string | string[];
+  ariaLabel?: string;
   systemLabel?: string;
   lightLabel?: string;
   darkLabel?: string;
@@ -22,6 +24,7 @@ interface Props {
 
 const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
+  ariaLabel: "Colour scheme",
   systemLabel: "System",
   lightLabel: "Light",
   darkLabel: "Dark",
@@ -74,16 +77,16 @@ watch(colorModeVal, (val) => {
 .colour-scheme-select {
   /* Everything DisplayThemeSwitch used to redeclare here beyond sizing (wrapper background/border/
      focus ring, marker border, option border/outline/focus/hover, option-icon colours, and the
-     system/light/dark marker gradients) was a byte-for-byte duplicate of TripleToggleSwitchCore's
+     system/light/dark marker gradients) was a byte-for-byte duplicate of TripleToggleSwitch's
      own defaults for the exact same selectors — a no-op at best, and for the ones that bypassed
-     TripleToggleSwitchCore's public --triple-toggle-switch-* tokens with a hardcoded literal
+     TripleToggleSwitch's public --triple-toggle-switch-* tokens with a hardcoded literal
      (background-color, border, focus outline, marker border, option border/hover/focus, icon
      colour) an active bug: a consumer setting e.g. --triple-toggle-switch-surface globally would
      have been silently overridden back to the hardcoded default by this block's higher
-     specificity. Removed 2026-09-20 — TripleToggleSwitchCore already owns all of that. Only the
-     genuine "small" sizing variant remains, now driving TripleToggleSwitchCore's own public
+     specificity. Removed 2026-09-20 — TripleToggleSwitch already owns all of that. Only the
+     genuine "small" sizing variant remains, now driving TripleToggleSwitch's own public
      sizing tokens instead of reaching into its private --_form-* and --_scheme-icon-font-size
-     locals directly (see TripleToggleSwitchCore's CONSUMER-STYLING.md). */
+     locals directly (see TripleToggleSwitch's CONSUMER-STYLING.md). */
   &.triple-toggle-switch {
     --triple-toggle-switch-gap: 0.4rem;
     --triple-toggle-switch-padding: 0.4rem;

package/app/components/02.molecules/display-theme-switch/stories/DisplayThemeSwitch.stories.ts

@@ -10,6 +10,11 @@ const meta: Meta<typeof DisplayThemeSwitch> = {
       description: "Extra classes — pass \"small\" for a compact size",
       table: { category: "Styling" },
     },
+    ariaLabel: {
+      control: "text",
+      description: "Accessible name for the radiogroup",
+      table: { category: "Labels" },
+    },
     systemLabel: {
       control: "text",
       description: "Accessible label for the system option",
@@ -45,7 +50,7 @@ const meta: Meta<typeof DisplayThemeSwitch> = {
     docs: {
       description: {
         component:
-          "A system/light/dark theme switch wrapping TripleToggleSwitchCore, wired to useSettingsStore. Colour and sizing are entirely delegated to TripleToggleSwitchCore's public --triple-toggle-switch-* tokens — see CONSUMER-STYLING.md.",
+          "A system/light/dark theme switch wrapping TripleToggleSwitch, wired to useSettingsStore. Colour and sizing are entirely delegated to TripleToggleSwitch's public --triple-toggle-switch-* tokens — see CONSUMER-STYLING.md.",
       },
     },
   },

package/app/components/02.molecules/display-theme-switch/tests/DisplayThemeSwitch.spec.ts

@@ -25,7 +25,7 @@ describe("DisplayThemeSwitch", () => {
     expect(wrapper.vm).toBeTruthy();
   });
 
-  it("renders TripleToggleSwitchCore with the colour-scheme-select class", async () => {
+  it("renders TripleToggleSwitch with the colour-scheme-select class", async () => {
     const wrapper = await mountSuspended(DisplayThemeSwitch);
     await nextTick();
     expect(wrapper.find(".colour-scheme-select").exists()).toBe(true);
@@ -65,6 +65,15 @@ describe("DisplayThemeSwitch", () => {
     expect(icons.some((c) => c?.includes("system"))).toBe(true);
   });
 
+  it("names the radiogroup with ariaLabel", async () => {
+    const wrapper = await mountSuspended(DisplayThemeSwitch);
+    await nextTick();
+    expect(wrapper.find('[role="radiogroup"]').attributes("aria-label")).toBe("Colour scheme");
+
+    await wrapper.setProps({ ariaLabel: "Thème" });
+    expect(wrapper.find('[role="radiogroup"]').attributes("aria-label")).toBe("Thème");
+  });
+
   it("applies the small class via styleClassPassthrough", async () => {
     const wrapper = await mountSuspended(DisplayThemeSwitch, {
       props: { styleClassPassthrough: "small" },

package/app/components/02.molecules/display-tooltip-defined/CONSUMER-STYLING.md

@@ -40,3 +40,14 @@ for a single field.
 This component also renders (and can override) every `--display-tooltip-*` token from the
 underlying `DisplayTooltip` — see its CONSUMER-STYLING.md for the full popover/trigger/close-button
 token API.
+
+---
+
+## 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`.
+

package/app/components/02.molecules/expandable/accordian/CONSUMER-STYLING.md

@@ -44,7 +44,15 @@ check any `.accordian-item.expanding-panel*` overrides still target the right cl
 
 ---
 
-## Page-scoped overrides
+## Local overrides
+
+There are no public tokens, so override the classes above with direct properties, scoped to an
+element you own (a page or section class, or a class added with `:style-class-passthrough`). Keep
+the block **unlayered** (no `@layer` wrapper) so it beats the library's `@layer components`. If your
+own file uses `<style scoped>`, selectors that reach inside the component need `:deep()`. Patterns
+and examples: `.claude/skills/component-local-style-override.md`.
+
+### Page or section
 
 No `:deep()` is required (component styles are unscoped).
 
@@ -60,9 +68,7 @@ No `:deep()` is required (component styles are unscoped).
 }
 ```
 
----
-
-## Per-instance overrides via styleClassPassthrough
+### One instance
 
 Use sparingly — prefer global or page-scoped CSS. `styleClassPassthrough` on `AccordianCore`
 targets the root `.display-accordian` element, not the individual panels (those already get
@@ -91,3 +97,4 @@ targets the root `.display-accordian` element, not the individual panels (those
   (see `ExpandingPanel`'s own docs for why: it's for a single panel overlaying trailing page
   content, not stacked/grouped panels). Use `ExpandingPanel`/`ExpandingPanelClassic` directly if
   you need an overlay panel.
+