srcdev-nuxt-components 9.6.0 → 9.6.1

package/app/components/01.atoms/display-pill/stories/DisplayPill.stories.ts

@@ -1,6 +1,10 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { computed } from "vue";
 import StorybookComponent from "../DisplayPill.vue";
 
+type LineClamp = "none" | "1" | "2" | "3";
+
+// labelLineClamp is story-only: it drives a CSS token, not a DisplayPill prop. See its argTypes entry.
 type StoryArgs = {
   tag: "span" | "div" | "button" | "a";
   label: string;
@@ -8,12 +12,32 @@ type StoryArgs = {
   variant: "default" | "primary" | "success" | "warning" | "danger" | "neutral";
   reversed: boolean;
   showIcon: boolean;
+  labelLineClamp: LineClamp;
+  ring?: boolean;
 };
 
 export default {
   title: "Atoms/DisplayPill",
   component: StorybookComponent,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Used for the neutral duration and price pills in [ServiceSummary](?path=/story/organisms-services-service-summary--default) " +
+          "and [ServiceDetail](?path=/story/organisms-services-service-detail--default), which restyle them through their own pill tokens.",
+      },
+    },
+  },
   argTypes: {
+    labelLineClamp: {
+      control: "select",
+      options: ["none", "1", "2", "3"] satisfies LineClamp[],
+      description:
+        "**Story control, not a prop.** Sets the `--display-pill-label-line-clamp` CSS token on a wrapper so you can try it here. " +
+        "To use it in an app, set the token in your own CSS, e.g. `.tag-list { --display-pill-label-line-clamp: none; }`. " +
+        "`1` (the default) is single-line ellipsis, `none` lets a long label wrap.",
+      table: { category: "CSS tokens (story only, set in your CSS)", defaultValue: { summary: "1" } },
+    },
     tag: {
       control: { type: "inline-radio" },
       options: ["span", "div", "button", "a"],
@@ -58,16 +82,30 @@ export default {
     variant: "default",
     reversed: false,
     showIcon: true,
+    labelLineClamp: "1",
   },
 } as Meta<StoryArgs>;
 
+// Links open in the Storybook manager (target="_top"), not inside the preview iframe.
+const usedByNote = `
+  <p style="margin: 0; flex-basis: 100%; text-align: center; font-size: 1.4rem;">
+    In use: the duration and price pills in the
+    <a href="/?path=/story/organisms-services-service-summary--default" target="_top">ServiceSummary</a> and
+    <a href="/?path=/story/organisms-services-service-detail--default" target="_top">ServiceDetail</a> stories.
+  </p>
+`;
+
+const tokenStyles = (args: StoryArgs) =>
+  computed(() => ({ "--display-pill-label-line-clamp": args.labelLineClamp }));
+
 const Template: StoryFn<StoryArgs> = (args) => ({
   components: { StorybookComponent },
   setup() {
-    return { args };
+    return { args, tokenStyles: tokenStyles(args) };
   },
   template: `
-    <div style="display: flex; align-items: center; justify-content: center; min-height: 100vh; gap: 1.6rem; flex-wrap: wrap;">
+    <div :style="tokenStyles" style="display: flex; align-items: center; align-content: center; justify-content: center; min-height: 100vh; gap: 1.6rem; flex-wrap: wrap;">
+      ${usedByNote}
       <StorybookComponent
         :tag="args.tag"
         :label="args.label"
@@ -90,10 +128,11 @@ const variants = ["default", "primary", "success", "warning", "danger", "neutral
 export const AllVariants: StoryFn<StoryArgs> = (args) => ({
   components: { StorybookComponent },
   setup() {
-    return { args, variants };
+    return { args, variants, tokenStyles: tokenStyles(args) };
   },
   template: `
-    <div style="display: flex; align-items: center; justify-content: center; min-height: 100vh; gap: 1.6rem; flex-wrap: wrap;">
+    <div :style="tokenStyles" style="display: flex; align-items: center; align-content: center; justify-content: center; min-height: 100vh; gap: 1.6rem; flex-wrap: wrap;">
+      ${usedByNote}
       <StorybookComponent
         v-for="variant in variants"
         :key="variant"
@@ -112,30 +151,215 @@ export const AllVariants: StoryFn<StoryArgs> = (args) => ({
 });
 AllVariants.argTypes = { variant: { table: { disable: true } }, label: { table: { disable: true } } };
 
-export const OutlinedViaBaseTokens: StoryFn<StoryArgs> = (args) => ({
+// Each variant keeps its own text colour, so currentColor borders follow the variant. Neutral's text is a light
+// step (it's the dark, inverted pill), so it's darkened here to stay visible once its background is transparent.
+const tokenShowcase =
+  (tokens: string, argTokens: (args: StoryArgs) => Record<string, string> = () => ({})): StoryFn<StoryArgs> =>
+  (args) => ({
   components: { StorybookComponent },
   setup() {
-    return { args, variants };
+    return { args, variants, argStyles: computed(() => argTokens(args)) };
   },
   template: `
-    <div
-      style="
-        display: flex; align-items: center; justify-content: center; min-height: 100vh; gap: 1.6rem; flex-wrap: wrap;
-        --display-pill-background: transparent;
-        --display-pill-text-colour: #1e293b;
-        --display-pill-border-colour: currentColor;
-      "
-    >
-      <StorybookComponent v-for="variant in variants" :key="variant" :label="variant" :size="args.size" :variant="variant" />
+    <div :style="argStyles" style="display: flex; align-items: center; justify-content: center; min-height: 100vh; gap: 1.6rem; flex-wrap: wrap; ${tokens}">
+      <StorybookComponent
+        v-for="variant in variants"
+        :key="variant"
+        :tag="args.tag"
+        :label="variant"
+        :size="args.size"
+        :variant="variant"
+        :reversed="args.reversed"
+      >
+        <template v-if="args.showIcon" #icon>
+          <Icon name="material-symbols:check-circle-outline" />
+        </template>
+      </StorybookComponent>
     </div>
   `,
 });
+
+const showcaseArgTypes = {
+  variant: { table: { disable: true } },
+  label: { table: { disable: true } },
+  labelLineClamp: { table: { disable: true } },
+};
+
+export const OutlinedViaBaseTokens = tokenShowcase(`
+  --display-pill-background: transparent;
+  --display-pill-border-width: 0.2rem;
+  --display-pill-border-colour: var(--slate-05);
+  --display-pill-primary-border-colour: var(--blue-06);
+  --display-pill-success-border-colour: var(--status-success);
+  --display-pill-warning-border-colour: var(--status-warning);
+  --display-pill-danger-border-colour: var(--status-danger);
+  --display-pill-neutral-border-colour: var(--slate-08);
+  --display-pill-neutral-text-colour: var(--slate-08);
+`);
 OutlinedViaBaseTokens.storyName = "Outlined (base tokens override every variant)";
+OutlinedViaBaseTokens.argTypes = showcaseArgTypes;
 OutlinedViaBaseTokens.parameters = {
   docs: {
     description: {
       story:
-        "Setting only the base --display-pill-background/-text-colour/-border-colour on an ancestor restyles every variant. A variant-specific token (e.g. --display-pill-success-background) would still win for that variant.",
+        "A transparent base --display-pill-background on an ancestor clears every variant's fill; --display-pill-border-colour sets a base border, " +
+        "and the per-variant --display-pill-<variant>-border-colour tokens give each variant its own mid-step status colour while the text keeps its darker step. " +
+        "--display-pill-neutral-text-colour darkens the neutral pill, whose default text is light because it's normally a dark, inverted pill.",
+    },
+  },
+};
+
+// A 2px ring in each variant's light -02 step, toggled by the story-only ring control.
+const ring02Tokens: Record<string, string> = {
+  "--display-pill-ring-width": "0.2rem",
+  "--display-pill-ring-colour": "var(--slate-02)",
+  "--display-pill-primary-ring-colour": "var(--blue-02)",
+  "--display-pill-success-ring-colour": "var(--green-02)",
+  "--display-pill-warning-ring-colour": "var(--orange-02)",
+  "--display-pill-danger-ring-colour": "var(--red-02)",
+  "--display-pill-neutral-ring-colour": "var(--slate-02)",
+};
+
+const ringArgTypes = {
+  ...showcaseArgTypes,
+  ring: {
+    control: "boolean" as const,
+    description:
+      "**Story control, not a prop.** Sets `--display-pill-ring-width: 0.2rem` and `--display-pill-<variant>-ring-colour` to each variant's `-02` step " +
+      "(`var(--blue-02)`, `var(--green-02)`...) on a wrapper. In an app, set the same tokens in your CSS, e.g. `.tag-list { --display-pill-ring-width: 0.2rem; }`.",
+    table: { category: "CSS tokens (story only, set in your CSS)", defaultValue: { summary: "off" } },
+  },
+};
+
+const ringArgTokens = (args: StoryArgs): Record<string, string> => (args.ring ? ring02Tokens : {});
+
+export const OutlinedMonochrome = tokenShowcase(`
+  --display-pill-background: transparent;
+  --display-pill-border-colour: currentColor;
+  --display-pill-text-colour: var(--slate-07);
+  --display-pill-primary-text-colour: var(--blue-07);
+  --display-pill-success-text-colour: var(--green-07);
+  --display-pill-warning-text-colour: var(--orange-07);
+  --display-pill-danger-text-colour: var(--red-07);
+  --display-pill-neutral-text-colour: var(--slate-10);
+`, ringArgTokens);
+OutlinedMonochrome.storyName = "Outlined monochrome (mid-step colours)";
+OutlinedMonochrome.args = { ring: false };
+OutlinedMonochrome.argTypes = ringArgTypes;
+OutlinedMonochrome.parameters = {
+  docs: {
+    description: {
+      story:
+        "Border and text share one colour per variant (--display-pill-border-colour: currentColor on a transparent background). " +
+        "The default text steps (-09/-10) are near-black in every hue, so outlined like this the variants look alike. " +
+        "Each text token is lifted to its -07 step (all at 48% lightness, so contrast stays even across variants); the border follows because it's currentColor. " +
+        "default and neutral are both slate, so neutral uses the darker -10 step to stay distinct.",
+    },
+  },
+};
+
+export const RingedTwoTone = tokenShowcase(`
+  --display-pill-border-width: 0.1rem;
+  --display-pill-border-colour: currentColor;
+  --display-pill-ring-width: 0.2rem;
+`, ringArgTokens);
+RingedTwoTone.storyName = "Ringed (dark border, light ring, per variant)";
+RingedTwoTone.args = { ring: false };
+RingedTwoTone.argTypes = ringArgTypes;
+RingedTwoTone.parameters = {
+  docs: {
+    description: {
+      story:
+        "A 1px border in the variant's dark text colour (--display-pill-border-colour: currentColor) inside a 2px ring in the variant's light background colour " +
+        "(--display-pill-ring-width: 0.2rem; --display-pill-ring-colour defaults to the pill's background). The neutral pill is inverted, so its border is light and its ring dark. " +
+        "The ring control (a CSS token, not a prop) swaps the ring to each variant's -02 step, a shade darker than the fill, so it reads as a separate ring. " +
+        "The ring is a box-shadow, so it takes no layout space: leave room around ringed pills with gap or margin.",
+    },
+  },
+};
+
+const longGerman = "Haarverlängerungsberatungstermin";
+
+type StressCase = {
+  key: string;
+  caption: string;
+  label?: string;
+  slotHtml?: string;
+  icon?: string;
+  variant?: string;
+  size?: "sm" | "md" | "lg";
+  tag?: "span" | "button" | "a";
+  reversed?: boolean;
+  dir?: "rtl";
+};
+
+const stressCases: StressCase[] = [
+  { key: "german", caption: "Long German words", label: `${longGerman} und ${longGerman}`, icon: "material-symbols:schedule-outline" },
+  { key: "url", caption: "Unbroken URL", label: "https://example.com/a/very/long/path/that/never/breaks/anywhere/at/all" },
+  { key: "price", caption: "Long price (reversed)", label: "Ab 1.250,00 € pro Sitzung", icon: "material-symbols:sell-outline", reversed: true },
+  { key: "emoji", caption: "Emoji first", label: "👩‍👩‍👧‍👦🇬🇧🇫🇷 Family plan", variant: "primary" },
+  { key: "html", caption: "HTML-like text", label: "<script>alert('xss')</script>", variant: "danger" },
+  { key: "rtl", caption: "Right-to-left", label: "تسريحات شعر جديدة لموسم الخريف", icon: "material-symbols:check-circle-outline", dir: "rtl", variant: "success" },
+  { key: "accents", caption: "Descenders and accents", label: "Ägypten · gypsy · ÇĄĘ · Ýjqpg", variant: "warning", size: "lg" },
+  { key: "single", caption: "Single character", label: "A", variant: "neutral" },
+  { key: "empty", caption: "Empty label (renders nothing)", label: "" },
+  { key: "blank", caption: "Whitespace label + icon (icon-only)", label: "   ", icon: "material-symbols:star-outline", variant: "primary" },
+  { key: "brokenIcon", caption: "Broken icon name", label: "Missing icon", icon: "material-symbols:this-icon-does-not-exist" },
+  { key: "slot", caption: "Long default slot", slotHtml: `<strong>Pro</strong> plan with ${longGerman}`, icon: "material-symbols:star", variant: "primary" },
+  { key: "invalidVariant", caption: "Unknown variant from a CMS", label: "variant: info", variant: "info" },
+  { key: "button", caption: "Button, small", label: `Filter: ${longGerman}`, tag: "button", size: "sm" },
+  { key: "link", caption: "Link, large", label: `${longGerman}${longGerman}`, tag: "a", size: "lg", variant: "neutral" },
+];
+
+const stressWidths = ["32rem", "16rem", "8rem"];
+
+export const StressTest: StoryFn<StoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    return { stressCases, stressWidths, tokenStyles: tokenStyles(args) };
+  },
+  template: `
+    <div :style="tokenStyles" style="display: grid; gap: 2.4rem; padding: 3.2rem 2rem; font: 1.2rem sans-serif;">
+      <div style="display: grid; grid-template-columns: 16rem repeat(3, max-content); gap: 1.2rem 2.4rem; align-items: start;">
+        <span></span>
+        <strong v-for="width in stressWidths" :key="width">{{ width }} wide</strong>
+        <template v-for="item in stressCases" :key="item.key">
+          <span style="overflow-wrap: anywhere;">{{ item.caption }}</span>
+          <div
+            v-for="width in stressWidths"
+            :key="width"
+            :dir="item.dir"
+            :style="{ inlineSize: width, outline: '1px dashed currentColor', padding: '0.4rem' }"
+          >
+            <StorybookComponent
+              :label="item.label"
+              :variant="item.variant"
+              :size="item.size ?? 'md'"
+              :tag="item.tag ?? 'span'"
+              :href="item.tag === 'a' ? '#' : undefined"
+              :reversed="item.reversed ?? false"
+            >
+              <template v-if="item.icon" #icon><Icon :name="item.icon" /></template>
+              <template v-if="item.slotHtml" #default><span v-html="item.slotHtml"></span></template>
+            </StorybookComponent>
+          </div>
+        </template>
+      </div>
+    </div>
+  `,
+});
+StressTest.storyName = "Stress Test (Worst-Case Data)";
+StressTest.parameters = {
+  controls: { include: ["labelLineClamp"] },
+  docs: {
+    description: {
+      story:
+        "Hostile labels at three container widths: long German words, an unbroken URL, a long reversed price, emoji, HTML-like and right-to-left text, " +
+        "descenders and accents, a single character, empty and whitespace-only labels, a broken icon name, a long default slot, an unknown variant, " +
+        "and small button and large link pills. Check that no pill grows past its dashed box, long text ends in an ellipsis on one line, " +
+        "descenders and accents aren't clipped, the empty label renders no pill, the whitespace label becomes an icon-only pill, " +
+        "the unknown variant falls back to the default colours, and the icon never shrinks. " +
+        "Set the labelLineClamp control (a CSS token, not a prop) to none to see long labels wrap instead.",
     },
   },
 };

package/app/components/01.atoms/display-pill/tests/DisplayPill.spec.ts

@@ -64,14 +64,32 @@ describe("DisplayPill", () => {
     expect(wrapper.find(".display-pill-label").text()).toBe("Active");
   });
 
-  it("renders default slot when no label prop is set", async () => {
+  it("renders default slot inside .display-pill-label when no label prop is set", async () => {
     const wrapper = await mountSuspended(DisplayPill, {
       slots: { default: "<strong class='custom'>Custom</strong>" },
     });
-    expect(wrapper.find(".custom").exists()).toBe(true);
+    expect(wrapper.find(".display-pill-label .custom").exists()).toBe(true);
+  });
+
+  it("treats a whitespace-only label as no label and falls back to the default slot", async () => {
+    const wrapper = await mountSuspended(DisplayPill, {
+      props: { label: "   " },
+      slots: { default: "<strong class='custom'>Custom</strong>" },
+    });
+    expect(wrapper.find(".display-pill-label .custom").exists()).toBe(true);
+  });
+
+  it.each(["", "   "])("renders no label element for label=%j with no default slot", async (label) => {
+    const wrapper = await mountSuspended(DisplayPill, { props: { label } });
     expect(wrapper.find(".display-pill-label").exists()).toBe(false);
   });
 
+  it("renders a label with HTML-like text as text, not markup", async () => {
+    const wrapper = await mountSuspended(DisplayPill, { props: { label: "<b>bold</b>" } });
+    expect(wrapper.find(".display-pill-label").text()).toBe("<b>bold</b>");
+    expect(wrapper.find("b").exists()).toBe(false);
+  });
+
   it("does not render default slot when label prop is set", async () => {
     const wrapper = await mountSuspended(DisplayPill, {
       props: { label: "Active" },
@@ -92,43 +110,46 @@ describe("DisplayPill", () => {
 
   // ─── Size ─────────────────────────────────────────────────────────────────
 
-  it("applies md size class by default", async () => {
+  it("sets data-size='md' by default", async () => {
     const wrapper = await mountSuspended(DisplayPill);
-    expect(wrapper.classes()).toContain("md");
+    expect(wrapper.attributes("data-size")).toBe("md");
   });
 
-  it.each(["sm", "md", "lg"] as const)("applies %s size class when size='%s'", async (size) => {
+  it.each(["sm", "md", "lg"] as const)("sets data-size='%s' when size='%s'", async (size) => {
     const wrapper = await mountSuspended(DisplayPill, { props: { size } });
-    expect(wrapper.classes()).toContain(size);
+    expect(wrapper.attributes("data-size")).toBe(size);
+    expect(wrapper.classes()).not.toContain(size);
   });
 
   // ─── Variant ──────────────────────────────────────────────────────────────
 
-  it("applies default variant class by default", async () => {
+  it("sets data-variant='default' by default", async () => {
     const wrapper = await mountSuspended(DisplayPill);
-    expect(wrapper.classes()).toContain("default");
+    expect(wrapper.attributes("data-variant")).toBe("default");
   });
 
   it.each(["default", "primary", "success", "warning", "danger", "neutral"] as const)(
-    "applies %s variant class when variant='%s'",
+    "sets data-variant='%s' when variant='%s'",
     async (variant) => {
       const wrapper = await mountSuspended(DisplayPill, { props: { variant } });
-      expect(wrapper.classes()).toContain(variant);
+      expect(wrapper.attributes("data-variant")).toBe(variant);
+      expect(wrapper.classes()).not.toContain(variant);
     }
   );
 
   // ─── Reversed ─────────────────────────────────────────────────────────────
 
-  it("does not apply is-reversed class by default", async () => {
+  it("does not set data-reversed by default", async () => {
     const wrapper = await mountSuspended(DisplayPill);
-    expect(wrapper.classes()).not.toContain("is-reversed");
+    expect(wrapper.attributes("data-reversed")).toBeUndefined();
   });
 
-  it("applies is-reversed class when reversed=true", async () => {
+  it("sets data-reversed when reversed=true", async () => {
     const wrapper = await mountSuspended(DisplayPill, {
       props: { reversed: true },
     });
-    expect(wrapper.classes()).toContain("is-reversed");
+    expect(wrapper.attributes("data-reversed")).toBeDefined();
+    expect(wrapper.classes()).not.toContain("is-reversed");
   });
 
   // ─── styleClassPassthrough ────────────────────────────────────────────────
@@ -219,6 +240,14 @@ describe("DisplayPill", () => {
     expect(wrapper.attributes("data-icon-position")).toBe("only");
   });
 
+  it("sets data-icon-position='only' when the label is whitespace", async () => {
+    const wrapper = await mountSuspended(DisplayPill, {
+      props: { label: "  " },
+      slots: { icon: "<span>●</span>" },
+    });
+    expect(wrapper.attributes("data-icon-position")).toBe("only");
+  });
+
   it("treats default slot text as a label for icon position", async () => {
     const wrapper = await mountSuspended(DisplayPill, {
       slots: { icon: "<span>●</span>", default: "Pro plan" },

package/app/components/01.atoms/display-pill/tests/__snapshots__/DisplayPill.spec.ts.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`DisplayPill > renders correct HTML structure (default) 1`] = `"<span class="display-pill md default"><!--v-if--><span class="display-pill-label">Status</span></span>"`;
+exports[`DisplayPill > renders correct HTML structure (default) 1`] = `"<span class="display-pill" data-size="md" data-variant="default"><!--v-if--><span class="display-pill-label">Status</span></span>"`;
 
-exports[`DisplayPill > renders correct HTML structure (reversed) 1`] = `"<span class="display-pill md default is-reversed" data-icon-position="end"><span class="display-pill-icon"><span class="icon">✓</span></span><span class="display-pill-label">Status</span></span>"`;
+exports[`DisplayPill > renders correct HTML structure (reversed) 1`] = `"<span class="display-pill" data-size="md" data-variant="default" data-reversed="true" data-icon-position="end"><span class="display-pill-icon"><span class="icon">✓</span></span><span class="display-pill-label">Status</span></span>"`;
 
-exports[`DisplayPill > renders correct HTML structure (with icon slot) 1`] = `"<span class="display-pill lg success" data-icon-position="start"><span class="display-pill-icon"><span class="icon">✓</span></span><span class="display-pill-label">Status</span></span>"`;
+exports[`DisplayPill > renders correct HTML structure (with icon slot) 1`] = `"<span class="display-pill" data-size="lg" data-variant="success" data-icon-position="start"><span class="display-pill-icon"><span class="icon">✓</span></span><span class="display-pill-label">Status</span></span>"`;

package/app/components/01.atoms/tabbed-content/CONSUMER-STYLING.md

@@ -0,0 +1,201 @@
+# TabbedContent — Consumer Styling Guide
+
+> **Renamed 2026-10-07**: `TabsCore` → `TabbedContent`. Root class `.tabs-core` → `.tabbed-content`,
+> and every inner class moved under the component prefix (see State hooks). Token names are
+> unchanged (`--tabs-*`).
+
+## Public token API
+
+Colour defaults come from the `--theme-*` slots, so the component follows the site theme out of the
+box.
+
+> **Changed 2026-10-07**: colour defaults moved from fixed `--slate-*` steps to `--theme-*` slots.
+> The content panel used to default to a dark `--slate-09` background with no text colour, so
+> consumer text rendered dark on dark; it's now a light `--theme-surface-subtle` panel with
+> `--theme-text`. The active highlight is `--theme-surface` (bold) with `--theme-on-surface` text,
+> the underline is `--theme-accent`. To keep the old look, set the tokens below to the previous
+> `--slate-*` values.
+
+### Tab row
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tabs-nav-border` | `0.1rem solid color-mix(in oklch, var(--theme-text) 20%, transparent)` | Border between the tab row and the panels (bottom on `axis="x"`, left on `axis="y"`) |
+| `--tabs-axis-y-gap` | `2em` | Gap between the tab column and the panels on `axis="y"` |
+| `--tabs-axis-y-list-max-inline-size` | `50%` | Widest the tab column may get on `axis="y"`; long labels wrap inside it |
+
+### Tab triggers
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tabs-list-item-colour` | `var(--theme-text)` | Text colour of an inactive trigger |
+| `--tabs-list-item-opacity` | `0.7` | Opacity of an inactive trigger |
+| `--tabs-list-item-colour-selected` | falls back to `--tabs-active-indicator-text-colour` | Text colour of the active trigger |
+| `--tabs-list-item-text-transform` | `uppercase` | `text-transform` of trigger labels |
+| `--tabs-list-item-font-weight` | `500` | Font weight of trigger labels |
+| `--tabs-list-item-padding-block` | `1em` | Vertical padding of a trigger |
+| `--tabs-list-item-padding-inline` | `2em` | Horizontal padding of a trigger |
+| `--tabs-list-item-max-inline-size` | `24rem` | Widest a trigger may get on `axis="x"`; longer labels wrap inside it |
+| `--tabs-list-item-colour-transition-duration` | `100ms` | Transition of the trigger text colour |
+| `--tabs-list-item-focus-outline-offset` | `-0.2rem` | Focus outline offset on a trigger |
+| `--tabs-focus-ring-width` | `0.2rem` | Focus outline width on triggers and panels |
+| `--tabs-focus-ring-colour` | `var(--theme-border-focus)` | Focus outline colour on triggers and panels |
+
+> **Changed 2026-10-07**: the focus outline used `--theme-ring`, the lightest theme step, which
+> was close to invisible on a light page. It now defaults to `--theme-border-focus` behind the new
+> `--tabs-focus-ring-colour` token. `--tabs-list-item-focus-outline-width` is replaced by
+> `--tabs-focus-ring-width`.
+
+### Moving indicators
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tabs-hover-indicator-colour` | `var(--theme-surface-subtle)` | Background of the hover highlight (`trackHover`) |
+| `--tabs-hover-indicator-text-colour` | `var(--theme-text)` | Text colour of a hovered trigger; keep it in contrast with the hover background |
+| `--tabs-active-indicator-colour` | `var(--theme-surface)` | Background of the active highlight (`trackActive`) |
+| `--tabs-active-indicator-text-colour` | `var(--theme-on-surface)` | Text colour of the active trigger; keep it in contrast with the active background |
+| `--tabs-underline-indicator-colour` | `var(--theme-accent)` | Colour of the underline/sideline (`trackIndicator`) |
+| `--tabs-underline-indicator-height` | `0.4rem` | Thickness of the underline (`axis="x"`), also its width on `axis="y"` |
+| `--tabs-hover-underline-indicator-colour` | `--tabs-underline-indicator-colour` | Colour of the thin underline/sideline that follows the hovered tab (`trackHover` and `trackIndicator`) |
+| `--tabs-hover-underline-indicator-height` | `0.1rem` | Its thickness; `0` hides it. Sits under the active underline where they overlap |
+
+### More menu (`overflowMode="menu"`, `axis="x"`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tabs-more-margin-inline-start` | `auto` | Pushes the More button to the end of the tab row; `0` keeps it straight after the last visible tab |
+| `--tabs-more-trigger-padding-inline` | `1.2em` | Horizontal padding of the More button (vertical padding follows `--tabs-list-item-padding-block`); its colours follow the trigger tokens |
+| `--tabs-more-icon-size` | `1.25em` | More button icon size (the `⋯` state) |
+| `--tabs-more-chevron-size` | `1em` | Chevron after the active tab's label on the More button (flips while the menu is open) |
+| `--tabs-more-popover-surface` | `var(--page-bg, var(--theme-surface-subtle))` | Menu background |
+| `--tabs-more-popover-text-colour` | `var(--theme-text)` | Menu text colour |
+| `--tabs-more-popover-border` | `0.1rem solid color-mix(in oklch, var(--theme-text) 20%, transparent)` | Menu border (shorthand) |
+| `--tabs-more-popover-border-radius` | `0.6rem` | Menu corner radius |
+| `--tabs-more-popover-shadow` | `0 0.4rem 1.6rem rgb(0 0 0 / 12%)` | Menu shadow |
+| `--tabs-more-popover-min-inline-size` | `16rem` | Narrowest the menu gets (widest is `--tabs-list-item-max-inline-size`, capped to the viewport) |
+| `--tabs-more-popover-max-block-size` | `70vh` | Tallest the menu gets before it scrolls |
+| `--tabs-more-popover-distance` | `0.4rem` | Gap between the More button and the menu |
+| `--tabs-more-popover-transition-duration` | `200ms` | Menu fade |
+| `--tabs-more-popover-z-index` | `999999` | Stacking where the menu can't use the top layer (Safari 16) |
+| `--tabs-more-item-padding-block` / `-inline` | `0.8em` / `1.2em` | Menu row padding |
+| `--tabs-more-item-surface-hover` | `color-mix(in oklch, var(--theme-text) 8%, transparent)` | Menu row background on hover/focus |
+| `--tabs-more-item-colour-selected` | `var(--theme-accent)` | Text colour of the menu row for the active tab |
+
+### Panels
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tabs-content-background-colour` | `var(--theme-surface-subtle)` | Panel background |
+| `--tabs-content-text-colour` | `var(--theme-text)` | Panel text colour |
+| `--tabs-content-border-width` | `0.1rem` | Panel border width |
+| `--tabs-content-border-colour` | `color-mix(in oklch, var(--theme-text) 20%, transparent)` | Panel border colour |
+| `--tabs-content-border-radius` | `0` | Panel corner radius |
+
+### Private tokens
+
+`--_focus-ring` (composed from the two focus tokens), and the runtime values `useTabs` writes from
+measured layout, per indicator (`active` / `hovered`): `--_{kind}-start` / `--_{kind}-end` (edge
+insets from the bar's start and end along the axis), `--_{kind}-duration`,
+`--_{kind}-start-delay` / `--_{kind}-end-delay`; each indicator reads them through its own
+`--_start` / `--_end` / `--_duration` / `--_start-delay` / `--_end-delay`. Not public API; use the
+`transitionDuration` prop for indicator speed (one edge moves for that long, then the other).
+
+> **Changed 2026-10-08**: indicators were a bar-wide box moved with `translate` and sized with
+> `scale` (`--_x-*`, `--_width-*`, `--_y-*`, a shared `--_transition-duration`), with a timer
+> to "settle" after a stretch. Rightward moves changed both properties at once and could visibly
+> step backwards. Each edge is now its own `left`/`right` (`top`/`bottom` on `axis="y"`) inset:
+> the edge in the direction of travel moves first and the trailing edge follows after one
+> duration, so the movement is the same both ways, with no timer.
+
+---
+
+## State hooks
+
+| Hook | Where | Meaning |
+|---|---|---|
+| `.axis-x` / `.axis-y` | root `.tabbed-content` | The `axis` prop |
+| `.overflow-menu` / `.overflow-scroll` | root | The `overflowMode` prop |
+| `.tabbed-content-bar` | wraps the tablist, the More menu and the indicators | Carries `--tabs-nav-border`; scrolls sideways with `overflowMode="scroll"` |
+| `.tabbed-content-list` | `role="tablist"` | The tab row/column |
+| `.tabbed-content-trigger[hidden]` | trigger | Collapsed into the More menu |
+| `.tabbed-content-more` / `.is-idle` | More menu wrapper | Idle (measured but invisible) while every tab fits |
+| `.tabbed-content-more-trigger` / `.is-active` | More button | `.is-active` while the active tab is one of the collapsed ones: the button shows that tab's label (`.tabbed-content-more-label`) and a chevron instead of `⋯`, takes the normal tab padding, and the indicators sit on it |
+| `.tabbed-content-more-popover` | menu popover | Open: `:popover-open`, or `.tabbed-content-more-popover-open` without the Popover API (style the two in separate rules) |
+| `.tabbed-content-more-item[aria-checked="true"]` | menu row | The active tab's row |
+| `.tabbed-content-trigger` | each `role="tab"` button | A tab trigger |
+| `.tabbed-content-trigger[aria-selected="true"]` | trigger | The active tab |
+| `.tracks-active` | root | `trackActive` is on: label colour follows `[data-under-active]` instead of `aria-selected` |
+| `[data-under-active]` | trigger, More button | The active highlight covers at least half of it right now (updated every frame while it slides) |
+| `.tabbed-content-indicator-hover` / `-active` / `-underline` / `-underline-hover` | inside `.tabbed-content-bar` | The moving indicators, rendered only when their `track*` prop is on (`-underline-hover` needs both `trackHover` and `trackIndicator`) |
+| `.tabbed-content-panels` | panel wrapper | Background, border and text colour live here |
+| `.tabbed-content-panel` / `[hidden]` | each `role="tabpanel"` | A panel; inactive ones carry `hidden` |
+
+> **Changed 2026-10-07**: `.tabs-list` → `.tabbed-content-list` (now a `<div>`, was a `<ul>` with
+> `<li>`s), `.tabs-list-item` → `.tabbed-content-trigger`, `.nav__hovered` / `.nav__active` /
+> `.nav__active-indicator` → `.tabbed-content-indicator-hover` / `-active` / `-underline`,
+> `.tab-content-wrapper` → `.tabbed-content-panels`, `.tab-content` → `.tabbed-content-panel`.
+> Inactive panels use the `hidden` attribute instead of inline `display: none` and `aria-hidden`.
+
+---
+
+## Tab-label text colour tracks the indicator behind it
+
+Hover and active can have different backgrounds, so the trigger label has a text-colour token per
+state. If you override either indicator background, override its matching text-colour token too:
+
+```css
+.my-page {
+  --tabs-hover-indicator-colour: gold;
+  --tabs-hover-indicator-text-colour: black;
+  --tabs-active-indicator-colour: navy;
+  --tabs-active-indicator-text-colour: white;
+}
+```
+
+With `trackActive` on, label colour follows what's actually behind each tab while the active
+highlight slides: a tab it covers by at least half (`[data-under-active]`) takes the active text
+colour, and the newly selected tab keeps its resting colour until the highlight reaches it. So a
+jump from tab 1 to tab 5 never puts dark text on the dark highlight, or light text on the light
+row. With `trackActive` off there's no moving highlight, and `aria-selected` sets the colour as
+before.
+
+> **Changed 2026-10-08**: passed-over labels used to keep their resting colour while the active
+> highlight slid under them (dark on dark), and the selected tab turned light before the
+> highlight arrived (light on light).
+
+---
+
+## Indicator visibility is prop-driven
+
+Whether each indicator renders is set by `trackHover` / `trackActive` / `trackIndicator`, not
+tokens. They can change after mount.
+
+---
+
+## 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` classes land on the root `.tabbed-content`, so tokens set on that class
+reach every part of the component.
+
+> **Changed 2026-10-07**: passthrough classes used to land on the tab list, not the root, so tokens
+> set on them never reached the panels.
+
+---
+
+## Notes
+
+- **Dark mode**: defaults are light-only, like the rest of the library. Override the `--theme-*`
+  slots (or these tokens) in your own dark scheme; `light-dark()` in your own override values is
+  fine, it's only kept out of the library's defaults.
+- **Right-to-left**: indicators are positioned from measured `offsetLeft`, so they line up in RTL,
+  but arrow keys aren't mirrored (ArrowRight always moves to the next tab in DOM order).