srcdev-nuxt-components 9.6.12 → 9.6.14

package/app/components/01.atoms/display-tooltip/CONSUMER-STYLING.md

@@ -2,6 +2,12 @@
 
 ## Public token API
 
+Private tokens (`--_anchor-name`, `--_trigger-icon-size`, `--_trigger-padding`,
+`--_trigger-border-width`, and the script-written `--_anchor-top`, `--_anchor-right`,
+`--_anchor-left-inverse`) are not public API.
+
+### Trigger
+
 | Token | Default | Controls |
 |---|---|---|
 | `--display-tooltip-padding-block` | `0.8rem` | Vertical padding around the trigger row |
@@ -14,10 +20,15 @@
 | `--display-tooltip-trigger-border-radius` | `100vw` | Trigger button corner radius (circular by default) |
 | `--display-tooltip-trigger-outline-width` | `0.1rem` | Trigger button focus/hover outline width |
 | `--display-tooltip-trigger-outline-colour-hover` | `var(--theme-ring)` | Trigger button outline colour on hover/focus-visible |
-| `--display-tooltip-popover-width` | `30rem` | Popover panel width |
+
+### Popover panel
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-tooltip-popover-width` | `30rem` | Popover panel width (capped at `100vw - 3.2rem`) |
 | `--display-tooltip-popover-padding` | `1.2rem` | Popover panel content padding |
 | `--display-tooltip-popover-content-gap` | `1.2rem` | Gap between stacked children in the `tooltipContent` slot |
-| `--display-tooltip-popover-font-size` | `1.4rem` | Popover text size (`DisplayTooltipDefined` sets its own per-element sizes) |
+| `--display-tooltip-popover-font-size` | `1.4rem` | Popover text size (`DisplayTooltipRich` sets its own per-element sizes) |
 | `--display-tooltip-popover-line-height` | `1.4` | Popover text line height |
 | `--display-tooltip-popover-outline-width` | `0.1rem` | Popover panel outline (border) width |
 | `--display-tooltip-popover-outline-colour` | `var(--slate-02)` | Popover panel outline (border) colour |
@@ -27,29 +38,61 @@
 | `--display-tooltip-popover-shadow` | `0 0.4rem 1.6rem rgba(0,0,0,.12)` | Popover panel elevation shadow |
 | `--display-tooltip-popover-offset` | `0.1rem` | Gap between the trigger and the popover panel |
 | `--display-tooltip-popover-z-index` | `999999` | Panel stacking order in browsers without CSS anchor positioning. Ignored where the panel renders in the top layer |
-| `--display-tooltip-close-button-colour` | `var(--slate-09)` | Close button text colour (used by `DisplayTooltipDefined`) |
+
+The panel uses the neutral `--slate-*` scale rather than `--theme-*`, like `PopOver`: a tooltip
+reads as a neutral overlay whatever the surrounding theme.
+
+### Close button (`.display-tooltip-close-button`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-tooltip-close-button-colour` | `var(--slate-09)` | Close button text colour |
 | `--display-tooltip-close-button-border-width` | `0.1rem` | Close button border width |
 | `--display-tooltip-close-button-border-colour` | `var(--slate-03)` | Close button border colour |
 | `--display-tooltip-close-button-outline-width` | `0.1rem` | Close button outline width |
 | `--display-tooltip-close-button-outline-colour` | `transparent` | Close button outline colour at rest (no permanent ring) |
-| `--display-tooltip-close-button-border-colour-hover` | `var(--slate-06)` | Close button border colour on hover/focus |
-| `--display-tooltip-close-button-outline-colour-hover` | `var(--slate-06)` | Close button outline colour on hover/focus |
+| `--display-tooltip-close-button-border-colour-hover` | `var(--slate-06)` | Close button border colour on hover/focus-visible |
+| `--display-tooltip-close-button-outline-colour-hover` | `var(--slate-06)` | Close button outline colour on hover/focus-visible |
 | `--display-tooltip-close-button-padding` | `0.4rem 1rem` | Close button padding |
 
+`DisplayTooltipRich` renders this button. A plain `DisplayTooltip` gets the same styling by
+giving its own close button the `display-tooltip-close-button` class inside `tooltipContent`.
+
+> Changed 2026-10-18: `--display-tooltip-close-button-outline-colour` was documented but never read
+> (the resting outline was hardcoded `transparent`); it now works. The hover styles apply on
+> `:focus-visible` instead of `:focus`, so a mouse click no longer leaves the ring on.
+
+---
+
+## State hooks
+
+| Hook | Element | When |
+|---|---|---|
+| `[data-hidden]` | `.display-tooltip-trigger-button` | `hide-trigger` is set: the button collapses to zero width, leaves the tab order and is `aria-hidden` |
+| `:popover-open` | `.display-tooltip-popover` | Panel open (Popover API) |
+| `.display-tooltip-popover-open` | `.display-tooltip-popover` | Panel open without the Popover API (Safari 16) |
+| `[data-placement="left"]` | `.display-tooltip-popover` | Fallback placement flipped to the left of the trigger |
+
+Inner classes: `.display-tooltip` (root), `.display-tooltip-trigger-wrapper`,
+`.display-tooltip-trigger-button`, `.display-tooltip-trigger-icon`, `.display-tooltip-popover`,
+`.display-tooltip-popover-content`.
+
+> Changed 2026-10-18: the root class was `.display-tooltip-core` and is now `.display-tooltip`, and
+> the hidden trigger's `.hide` class is now `[data-hidden]` (a bare `.hide` collided with consumers'
+> utility classes). Update overrides written against the old names. Token names are unchanged.
+
+---
+
+## Global theming
+
 ```css
-.my-page {
+:where(html) {
   --display-tooltip-popover-background-colour: #1a1a1a;
   --display-tooltip-popover-text-colour: white;
   --display-tooltip-popover-outline-colour: transparent;
 }
 ```
 
-Or scope to a single instance via `styleClassPassthrough`:
-
-```vue
-<DisplayTooltip style-class-passthrough="promo-tooltip">...</DisplayTooltip>
-```
-
 ---
 
 ## Local overrides
@@ -62,12 +105,24 @@ Set the tokens above on an element you own (a page or section class, or a class
 
 ---
 
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.display-tooltip`, so tokens set on a
+passthrough class reach the trigger and the panel:
+
+```vue
+<DisplayTooltip style-class-passthrough="promo-tooltip">...</DisplayTooltip>
+```
+
+---
+
 ## Notes
 
 - Direct children of the `tooltipContent` slot have their block margins reset to `0` (inside
   `:where()`, so any margin you set on them still wins): the gap token is the only spacing between
   them. Before 2026-10-05 a slotted `<p>` kept its browser `1em` margins on top of the padding.
-
+- Long unbroken text wraps (`overflow-wrap: anywhere`) in both the trigger row and the panel, and
+  the trigger button never shrinks, so a long label stays beside it in a narrow column.
 - The trigger button is vertically centred on the first line of `triggerContent` text, using
   `--display-tooltip-trigger-icon-box-size`, `-padding` and `-border-width` to work out its height.
   Give `--display-tooltip-trigger-padding` a single length (e.g. `0.4rem`): a two-value shorthand
@@ -80,15 +135,6 @@ Set the tokens above on an element you own (a page or section class, or a class
   containing `:popover-open` is dropped whole where unsupported), isn't in the top layer (so the
   z-index token applies), and an ancestor with `transform`, `filter` or `contain` can misplace it.
   The trigger's `aria-expanded` tracks the open state in every browser.
-- The `.display-tooltip-close-button` styled here is rendered by `DisplayTooltipDefined`, not this
-  component directly — `DisplayTooltip` only provides the `tooltipContent` slot, so a plain
-  `DisplayTooltip` usage supplies its own close affordance if it wants one (give it
-  `style="align-self: flex-end;"` or a class to right-align it within the content's flex column,
-  same as `DisplayTooltipDefined` does internally).
 - 2026-09-07: default colours switched from raw `light-dark(black, white)` to the library's
-  neutral `--slate-*` scale, and `.display-tooltip-popover-content` gained default `padding`,
-  `display: flex; flex-direction: column;`, and `gap` (previously unstyled, meaning content sat
-  flush against the panel edges) plus the popover gained a default elevation `box-shadow`
-  (previously none) — the out-of-the-box look was flat and under-styled before this. All of these
-  remain overridable via the tokens above.
-
+  neutral `--slate-*` scale, and the panel gained default padding, a flex column with a gap, and a
+  default elevation shadow.

package/app/components/01.atoms/display-tooltip/DisplayTooltip.vue

@@ -1,23 +1,26 @@
 <template>
   <div
     ref="rootRef"
-    class="display-tooltip-core"
+    class="display-tooltip"
     :class="[elementClasses]"
     :style="{ '--_anchor-name': tooltipAnchorName }"
   >
-    <div class="display-tooltip-trigger-wrapper body-md">
+    <div class="display-tooltip-trigger-wrapper">
       <slot v-if="$slots.triggerContent" name="triggerContent"></slot>
       <button
         ref="triggerRef"
         :popovertarget="tooltipId"
         popovertargetaction="toggle"
+        type="button"
         class="display-tooltip-trigger-button"
-        :class="{ hide: hideTrigger }"
+        :data-hidden="hideTrigger ? '' : undefined"
+        :tabindex="hideTrigger ? -1 : undefined"
+        :aria-hidden="hideTrigger ? 'true' : undefined"
         :aria-label="triggerAriaLabel"
         :aria-expanded="isOpen"
         @click="handleTriggerClick"
       >
-        <Icon name="fa7-solid:circle-question" class="display-tooltip-trigger-icon" aria-hidden="true" />
+        <Icon :name="triggerIcon" class="display-tooltip-trigger-icon" aria-hidden="true" />
       </button>
     </div>
     <div
@@ -44,6 +47,8 @@ interface Props {
   hideTrigger?: boolean;
   /** aria-label on the trigger button — override for localisation. */
   triggerAriaLabel?: string;
+  /** Iconify name for the trigger button icon. */
+  triggerIcon?: string;
   styleClassPassthrough?: string | string[];
 }
 
@@ -51,10 +56,12 @@ const props = withDefaults(defineProps<Props>(), {
   tooltipId: "",
   hideTrigger: false,
   triggerAriaLabel: "Toggle the popover",
+  triggerIcon: "fa7-solid:circle-question",
   styleClassPassthrough: () => [],
 });
 
-const tooltipId = computed(() => (props.tooltipId.length ? props.tooltipId : `nuxt-tooltip-${useId()}`));
+const generatedTooltipId = `nuxt-tooltip-${useId()}`;
+const tooltipId = computed(() => props.tooltipId || generatedTooltipId);
 const tooltipAnchorName = `--tooltip-anchor-${useId()}`;
 
 const rootRef = ref<HTMLElement | null>(null);
@@ -84,18 +91,22 @@ watch(
 
 <style lang="css">
 @layer components {
-  .display-tooltip-core {
+  .display-tooltip {
     padding-block: var(--display-tooltip-padding-block, 0.8rem);
     position: relative;
 
     .display-tooltip-trigger-wrapper {
       display: inline-flex;
       align-items: flex-start;
+      max-inline-size: 100%;
+      overflow-wrap: anywhere;
 
       .display-tooltip-trigger-button {
-        margin-left: var(--display-tooltip-trigger-gap, 0.8rem);
+        flex: none;
+        margin-inline-start: var(--display-tooltip-trigger-gap, 0.8rem);
 
-        &.hide {
+        &[data-hidden] {
+          margin-inline-start: 0;
           width: 0;
           padding: 0;
           border-width: 0;
@@ -132,7 +143,6 @@ watch(
 
       &:hover {
         cursor: pointer;
-        text-decoration: underline;
       }
 
       &:hover,
@@ -146,7 +156,8 @@ watch(
       display: none;
       position: absolute;
       border: none;
-      width: var(--display-tooltip-popover-width, 30rem);
+      width: min(var(--display-tooltip-popover-width, 30rem), calc(100vw - 3.2rem));
+      overflow-wrap: anywhere;
 
       outline: var(--display-tooltip-popover-outline-width, 0.1rem) solid
         var(--display-tooltip-popover-outline-colour, var(--slate-02));
@@ -188,13 +199,14 @@ watch(
           color: var(--display-tooltip-close-button-colour, var(--slate-09));
           border: var(--display-tooltip-close-button-border-width, 0.1rem) solid
             var(--display-tooltip-close-button-border-colour, var(--slate-03));
-          outline: var(--display-tooltip-close-button-outline-width, 0.1rem) solid transparent;
+          outline: var(--display-tooltip-close-button-outline-width, 0.1rem) solid
+            var(--display-tooltip-close-button-outline-colour, transparent);
 
           font-weight: 600;
           padding: var(--display-tooltip-close-button-padding, 0.4rem 1rem);
 
           &:hover,
-          &:focus {
+          &:focus-visible {
             text-decoration: underline;
             border-color: var(--display-tooltip-close-button-border-colour-hover, var(--slate-06));
             outline-color: var(--display-tooltip-close-button-outline-colour-hover, var(--slate-06));

package/app/components/01.atoms/display-tooltip/stories/DisplayTooltip.stories.ts

@@ -12,19 +12,31 @@ const meta: Meta<typeof DisplayTooltip> = {
     },
     hideTrigger: {
       control: "boolean",
-      description: "Visually hides the trigger button (kept in the DOM) — e.g. while an equivalent trigger is provided via the triggerContent slot.",
+      description: "Visually hides the trigger button and removes it from the tab order and accessibility tree. It stays in the DOM as the panel's anchor, for a panel opened by your own `popovertarget` button.",
+      table: { category: "Basic" },
+    },
+    triggerAriaLabel: {
+      control: "text",
+      description: "aria-label on the trigger button (override for localisation)",
+      table: { category: "Accessibility" },
+    },
+    triggerIcon: {
+      control: "text",
+      description: "Iconify name for the trigger button icon",
       table: { category: "Basic" },
     },
     styleClassPassthrough: { table: { disable: true } },
   },
   args: {
     hideTrigger: false,
+    triggerAriaLabel: "Toggle the popover",
+    triggerIcon: "fa7-solid:circle-question",
   },
   parameters: {
     docs: {
       description: {
         component:
-          "A trigger button that opens an anchor-positioned popover panel, built on the native Popover API and CSS anchor-positioning. See DisplayTooltipDefined for a structured title/body/action content variant.",
+          "A trigger button that opens an anchor-positioned popover panel, built on the native Popover API and CSS anchor positioning (with fallbacks for Safari 16-18). Slots: `triggerContent` (a label before the button) and `tooltipContent` (the panel, with a scoped `close()`). Props set the trigger's icon (`triggerIcon`) and accessible name (`triggerAriaLabel`). DisplayTooltipRich builds on this with a structured title, body and close button: see its stories.",
       },
     },
   },
@@ -92,3 +104,78 @@ export const CustomColours: Story = {
     `,
   }),
 };
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    triggerAriaLabel: "Weitereinformationenzudieserangabeanzeigenundausblenden 😀",
+  },
+  render: (args) => ({
+    components: { DisplayTooltip },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="display: grid; gap: 2.4rem; padding: 2.4rem; font-size: 1.4rem;">
+        <p style="margin: 0;">A long unbroken label in a narrow column: the label wraps and the button stays beside its first line.</p>
+        <div style="inline-size: 16rem; outline: 0.1rem dashed currentColor;">
+          <DisplayTooltip v-bind="args">
+            <template #triggerContent>
+              <span>Lieferkostenundversandbedingungenfürauslandsbestellungen</span>
+            </template>
+            <template #tooltipContent>
+              <p>Short content.</p>
+            </template>
+          </DisplayTooltip>
+        </div>
+
+        <p style="margin: 0;">Long unbroken popover content with emoji, HTML-like text and right-to-left text: the panel stays within the viewport width and wraps.</p>
+        <DisplayTooltip v-bind="args">
+          <template #triggerContent>
+            <span>😀 &lt;b&gt;not bold&lt;/b&gt;</span>
+          </template>
+          <template #tooltipContent>
+            <p>https://example.invalid/a/very/long/unbroken/url/that/never/offers/a/break/opportunity/anywhere</p>
+            <p>Kostenloselieferungbeibestellungenübereinenbestimmtenmindestbestellwert 😀</p>
+            <p>&lt;script&gt;alert("x")&lt;/script&gt; renders as text.</p>
+            <p dir="rtl">التوصيل مجاني للطلبات التي تزيد عن خمسين جنيهًا.</p>
+          </template>
+        </DisplayTooltip>
+
+        <p style="margin: 0;">Many paragraphs: the panel grows to its content's height.</p>
+        <DisplayTooltip v-bind="args">
+          <template #tooltipContent>
+            <p v-for="n in 8" :key="n">Paragraph {{ n }}: Lorem ipsum odor amet, consectetuer adipiscing elit.</p>
+          </template>
+        </DisplayTooltip>
+
+        <p style="margin: 0;">Empty <code>tooltipContent</code> and a single-character label: the panel is just its padding.</p>
+        <DisplayTooltip v-bind="args">
+          <template #triggerContent><span>x</span></template>
+          <template #tooltipContent></template>
+        </DisplayTooltip>
+
+        <p style="margin: 0;">A broken <code>triggerIcon</code> name: the button keeps its size and stays focusable.</p>
+        <DisplayTooltip v-bind="args" trigger-icon="not-a-set:not-an-icon">
+          <template #tooltipContent><p>Opened from an empty button.</p></template>
+        </DisplayTooltip>
+
+        <p style="margin: 0;">Right-aligned at the edge of the canvas: the panel flips to the left of the trigger.</p>
+        <div style="display: flex; justify-content: flex-end;">
+          <DisplayTooltip v-bind="args">
+            <template #tooltipContent><p>Flipped to fit.</p></template>
+          </DisplayTooltip>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      story: { inline: false, height: "900px" },
+      description: {
+        story:
+          "Worst-case content. Open each tooltip and check: long unbroken labels wrap without pushing the button out of a narrow column, panel content wraps and the panel never gets wider than the viewport, HTML-like text renders as text, an empty panel collapses to its padding, a broken icon name leaves an empty but focusable button, and a trigger at the right edge opens its panel to the left. Tab through: every trigger is reachable and shows a focus ring. The long `triggerAriaLabel` is only the buttons' accessible name, so it never shows on screen.",
+      },
+    },
+  },
+};

package/app/components/01.atoms/display-tooltip/tests/DisplayTooltip.spec.ts

@@ -1,69 +1,116 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import DisplayTooltip from "../DisplayTooltip.vue";
 
+const mounted: { unmount: () => void }[] = [];
+
+const mountTooltip = async (options: Parameters<typeof mountSuspended<typeof DisplayTooltip>>[1] = {}) => {
+  const wrapper = await mountSuspended(DisplayTooltip, options);
+  mounted.push(wrapper);
+  return wrapper;
+};
+
 describe("DisplayTooltip", () => {
+  afterEach(() => {
+    mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+    vi.restoreAllMocks();
+  });
+
   it("mounts without error", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip);
+    const wrapper = await mountTooltip();
     expect(wrapper.vm).toBeTruthy();
   });
 
   it("renders correct HTML structure", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip, { props: { tooltipId: "fixed-id" } });
+    const wrapper = await mountTooltip({ props: { tooltipId: "fixed-id" } });
     expect(wrapper.html()).toMatchSnapshot();
   });
 
   it("generates a tooltip id when none is provided", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip);
+    const wrapper = await mountTooltip();
     const button = wrapper.find(".display-tooltip-trigger-button");
     expect(button.attributes("popovertarget")).toMatch(/^nuxt-tooltip-/);
   });
 
   it("uses the given tooltipId", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip, { props: { tooltipId: "my-tooltip" } });
+    const wrapper = await mountTooltip({ props: { tooltipId: "my-tooltip" } });
     const button = wrapper.find(".display-tooltip-trigger-button");
     expect(button.attributes("popovertarget")).toBe("my-tooltip");
     expect(wrapper.find(".display-tooltip-popover").attributes("id")).toBe("my-tooltip");
   });
 
   it("does not render triggerContent slot content when unused", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip);
+    const wrapper = await mountTooltip();
     expect(wrapper.find(".slot-trigger").exists()).toBe(false);
   });
 
   it("renders the triggerContent slot", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip, {
+    const wrapper = await mountTooltip({
       slots: { triggerContent: "<span class='slot-trigger'>Label</span>" },
     });
     expect(wrapper.find(".slot-trigger").text()).toBe("Label");
   });
 
   it("renders the tooltipContent slot", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip, {
+    const wrapper = await mountTooltip({
       slots: { tooltipContent: "<p class='slot-content'>Helpful info</p>" },
     });
     expect(wrapper.find(".display-tooltip-popover .slot-content").text()).toBe("Helpful info");
   });
 
-  it("applies the hide class to the trigger button when hideTrigger is true", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip, { props: { hideTrigger: true } });
-    expect(wrapper.find(".display-tooltip-trigger-button").classes()).toContain("hide");
+  it("hides the trigger from view, the tab order and the accessibility tree when hideTrigger is true", async () => {
+    const wrapper = await mountTooltip({ props: { hideTrigger: true } });
+    const button = wrapper.find(".display-tooltip-trigger-button");
+    expect(button.attributes("data-hidden")).toBeDefined();
+    expect(button.attributes("tabindex")).toBe("-1");
+    expect(button.attributes("aria-hidden")).toBe("true");
   });
 
-  it("does not apply the hide class by default", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip);
-    expect(wrapper.find(".display-tooltip-trigger-button").classes()).not.toContain("hide");
+  it("leaves the trigger visible and focusable by default", async () => {
+    const wrapper = await mountTooltip();
+    const button = wrapper.find(".display-tooltip-trigger-button");
+    expect(button.attributes("data-hidden")).toBeUndefined();
+    expect(button.attributes("tabindex")).toBeUndefined();
+    expect(button.attributes("aria-hidden")).toBeUndefined();
+  });
+
+  it("renders the trigger as type=\"button\" so it never submits a surrounding form", async () => {
+    const wrapper = await mountTooltip();
+    expect(wrapper.find(".display-tooltip-trigger-button").attributes("type")).toBe("button");
+  });
+
+  it("uses the triggerIcon prop for the trigger icon", async () => {
+    const wrapper = await mountTooltip({ props: { triggerIcon: "lucide:info" } });
+    expect(wrapper.find(".display-tooltip-trigger-icon").classes().join(" ")).toContain("lucide:info");
+  });
+
+  it("uses triggerAriaLabel for the trigger's accessible name", async () => {
+    const wrapper = await mountTooltip({ props: { triggerAriaLabel: "Plus d'informations" } });
+    expect(wrapper.find(".display-tooltip-trigger-button").attributes("aria-label")).toBe("Plus d'informations");
+  });
+
+  it("keeps the generated id stable and follows tooltipId changes", async () => {
+    const wrapper = await mountTooltip();
+    const button = wrapper.find(".display-tooltip-trigger-button");
+    const generated = button.attributes("popovertarget");
+
+    await wrapper.setProps({ tooltipId: "custom" });
+    expect(button.attributes("popovertarget")).toBe("custom");
+    expect(wrapper.find(".display-tooltip-popover").attributes("id")).toBe("custom");
+
+    await wrapper.setProps({ tooltipId: "" });
+    expect(button.attributes("popovertarget")).toBe(generated);
   });
 
   it("applies styleClassPassthrough classes", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip, {
+    const wrapper = await mountTooltip({
       props: { styleClassPassthrough: ["custom-class"] },
     });
     expect(wrapper.classes()).toContain("custom-class");
   });
 
   it("resets classes when styleClassPassthrough prop changes", async () => {
-    const wrapper = await mountSuspended(DisplayTooltip, {
+    const wrapper = await mountTooltip({
       props: { styleClassPassthrough: ["initial-class"] },
     });
     expect(wrapper.classes()).toContain("initial-class");
@@ -83,7 +130,7 @@ describe("DisplayTooltip", () => {
     });
 
     it("opens and closes from the trigger", async () => {
-      const wrapper = await mountSuspended(DisplayTooltip);
+      const wrapper = await mountTooltip();
       const trigger = wrapper.find(".display-tooltip-trigger-button");
       const popover = wrapper.find(".display-tooltip-popover");
 
@@ -97,7 +144,7 @@ describe("DisplayTooltip", () => {
     });
 
     it("passes a close function to the tooltipContent slot", async () => {
-      const wrapper = await mountSuspended(DisplayTooltip, {
+      const wrapper = await mountTooltip({
         slots: {
           tooltipContent: `<template #tooltipContent="{ close }"><button class="custom-close" @click="close">Done</button></template>`,
         },

package/app/components/01.atoms/display-tooltip/tests/__snapshots__/DisplayTooltip.spec.ts.snap

@@ -1,9 +1,9 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`DisplayTooltip > renders correct HTML structure 1`] = `
-"<div class="display-tooltip-core" style="--_anchor-name: --tooltip-anchor-v-0-0;">
-  <div class="display-tooltip-trigger-wrapper body-md">
-    <!--v-if--><button popovertarget="fixed-id" popovertargetaction="toggle" class="display-tooltip-trigger-button" aria-label="Toggle the popover" aria-expanded="false"><span class="iconify i-fa7-solid:circle-question display-tooltip-trigger-icon" aria-hidden="true"></span></button>
+"<div class="display-tooltip" style="--_anchor-name: --tooltip-anchor-v-0-1;">
+  <div class="display-tooltip-trigger-wrapper">
+    <!--v-if--><button popovertarget="fixed-id" popovertargetaction="toggle" type="button" class="display-tooltip-trigger-button" aria-label="Toggle the popover" aria-expanded="false"><span class="iconify i-fa7-solid:circle-question display-tooltip-trigger-icon" aria-hidden="true"></span></button>
   </div>
   <div id="fixed-id" popover="" class="display-tooltip-popover">
     <div class="display-tooltip-popover-content"></div>

package/app/components/01.atoms/navigation/skip-links/CONSUMER-STYLING.md

@@ -2,23 +2,63 @@
 
 ## Public token API
 
+No private `--_` tokens.
+
+### Panel (`.skip-links__nav`)
+
 | Token | Default | Controls |
 |---|---|---|
-| `--skip-links-z-index` | `1000` | Stacking context of the revealed skip-nav panel |
+| `--skip-links-z-index` | `999999` | Stacking order of the revealed panel |
 | `--skip-links-gap` | `0.2rem` | Gap between stacked skip links |
-| `--skip-links-background-colour` | `black` | Skip-nav panel background |
-| `--skip-links-border-colour` | `white` | Skip-nav panel border colour |
-| `--skip-links-border-width` | `1px` | Skip-nav panel border width |
-| `--skip-links-padding` | `0.2rem` | Skip-nav panel padding |
-| `--skip-links-text-colour` | `white` | Skip link text colour |
-| `--skip-links-link-padding-block` | `0.8rem` | Skip link vertical padding |
-| `--skip-links-link-padding-inline` | `1.2rem` | Skip link horizontal padding |
-| `--skip-links-transition-duration` | `0.3s` | Duration of the reveal transition when a link is focused |
-| `--skip-links-focus-outline-width` | `2px` | Focus outline width on a skip link |
-| `--skip-links-focus-outline-colour` | `white` | Focus outline colour on a skip link |
+| `--skip-links-background-colour` | `var(--theme-surface-inverted)` | Panel background |
+| `--skip-links-border-colour` | `var(--theme-on-surface)` | Panel border colour |
+| `--skip-links-border-width` | `1px` | Panel border width |
+| `--skip-links-padding` | `0.2rem` | Panel padding |
+| `--skip-links-transition-duration` | `0.3s` | Duration of the reveal transition (off under `prefers-reduced-motion`) |
+
+### Links (`.skip-links__link`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--skip-links-text-colour` | `var(--theme-on-surface)` | Link text colour |
+| `--skip-links-link-padding-block` | `0.8rem` | Link vertical padding |
+| `--skip-links-link-padding-inline` | `1.2rem` | Link horizontal padding |
+| `--skip-links-focus-outline-width` | `2px` | Focus outline width |
+| `--skip-links-focus-outline-colour` | `var(--theme-on-surface)` | Focus outline colour |
+
+> Changed 2026-10-18: the colours used to be hardcoded `black` (background) and `white` (text,
+> border, focus ring). They now default to the darkest theme step (`--theme-surface-inverted`) and
+> `--theme-on-surface`, keeping the high contrast while following the site's `data-theme` palette.
+> Set the four colour tokens to `black`/`white` to get the old look back. `--skip-links-z-index`
+> went from `1000` to `999999`, the library's overlay default, so the panel shows above sticky
+> headers.
+
+---
+
+## State hooks
+
+| Hook | Element | When |
+|---|---|---|
+| `:focus-within` | `.skip-links__nav` | A skip link has focus: the panel is revealed |
+
+Inner classes: `.skip-links` (root), `.skip-links__home` (only when the `homeLink` slot is used),
+`.skip-links__nav`, `.skip-links__link`.
+
+The panel is hidden with `opacity`, `transform` and `pointer-events`, not `display` or
+`visibility`, so the links stay in the tab order. It's positioned below the root
+(`top: 100%; inset-inline-start: 0`), so in a right-to-left page it drops from the right edge. It
+sizes to its longest link but never exceeds the viewport width (`100vw - 3.2rem`); longer labels
+wrap. The `<nav>` isn't rendered at all when no link has both an `href` and a `label`.
+
+> Changed 2026-10-18: links used to be `white-space: nowrap`, so a long label ran off-screen, and
+> the panel was anchored with a physical `left: 0`.
+
+---
+
+## Global theming
 
 ```css
-.my-page {
+:where(html) {
   --skip-links-background-colour: #111;
   --skip-links-border-colour: #ffd700;
   --skip-links-focus-outline-colour: #ffd700;
@@ -27,13 +67,6 @@
 
 ---
 
-## Links are prop-driven
-
-The set of skip links is provided via the `links` prop (`{ href, label }[]`), not slots — see the
-skill doc for the default value and localisation notes.
-
----
-
 ## Local overrides
 
 Set the tokens above on an element you own (a page or section class, or a class added with
@@ -42,3 +75,16 @@ Set the tokens above on an element you own (a page or section class, or a class
 `<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 `.skip-links`, so tokens set on a passthrough
+class reach the panel and the links.
+
+---
+
+## Notes
+
+- The links are prop-driven (`links: { href, label }[]`), not slots: see the skill doc for the
+  default value and localisation.