srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/01.atoms/display-pill/DisplayPill.vue

@@ -3,9 +3,13 @@
     :is="tag"
     class="display-pill"
     :class="[size, variant, { 'is-reversed': reversed }, elementClasses]"
+    :type="tag === 'button' ? 'button' : undefined"
+    :data-icon-position="iconPosition()"
   >
-    <slot name="icon"></slot>
-    <span v-if="label" class="pill-label">{{ label }}</span>
+    <span v-if="slots.icon" class="display-pill-icon">
+      <slot name="icon"></slot>
+    </span>
+    <span v-if="label" class="display-pill-label">{{ label }}</span>
     <slot v-else name="default"></slot>
   </component>
 </template>
@@ -29,47 +33,75 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
+const slots = useSlots();
+
+// A function, not a computed: slots aren't reactive, so a cached value goes stale when a slot is toggled.
+const iconPosition = () => {
+  if (!slots.icon) return undefined;
+  if (!props.label && !slots.default) return "only";
+  return props.reversed ? "end" : "start";
+};
+
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 watch(
   () => props.styleClassPassthrough,
-  () => {
-    resetElementClasses(props.styleClassPassthrough);
-  }
+  () => resetElementClasses(props.styleClassPassthrough)
 );
 </script>
 
 <style lang="css">
 @layer components {
   .display-pill {
-    --_bg: var(--theme-pill-bg, var(--slate-01));
-    --_color: var(--theme-pill-color, var(--slate-09));
-    --_border-color: var(--theme-pill-border-color, transparent);
-    --_border-width: var(--theme-pill-border-width, 1px);
-    --_border-style: var(--theme-pill-border-style, solid);
-    /* 100vw always resolves to the correct pill radius regardless of element size */
-    --_border-radius: var(--theme-pill-border-radius, 100vw);
-    --_outline: var(--theme-pill-outline, none);
-    --_outline-offset: var(--theme-pill-outline-offset, 0px);
-    --_gap: var(--theme-pill-gap, 0.5rem);
-    --_font-size: var(--theme-pill-font-size, 1.2rem);
-    --_font-weight: var(--theme-pill-font-weight, 500);
-    --_padding-x: var(--theme-pill-padding-x, 1rem);
-    --_padding-y: var(--theme-pill-padding-y, 0.4rem);
-    --_icon-size: var(--theme-pill-icon-size, 1.4rem);
+    --_background: var(--display-pill-background, var(--slate-01));
+    --_text-colour: var(--display-pill-text-colour, var(--slate-09));
+    --_font-size: var(--display-pill-font-size, 1.2rem);
+    --_icon-size: var(--display-pill-icon-size, 1.4rem);
+
+    /* Spacing scales with the icon size, so each size only sets font and icon size. */
+    --_padding-inline: var(
+      --display-pill-padding-inline,
+      calc(var(--_icon-size) * var(--display-pill-padding-inline-ratio, 0.7))
+    );
+    --_padding-inline-icon: var(
+      --display-pill-padding-inline-icon,
+      calc(var(--_icon-size) * var(--display-pill-padding-inline-icon-ratio, 0.4))
+    );
+    --_padding-block: var(
+      --display-pill-padding-block,
+      calc(var(--_icon-size) * var(--display-pill-padding-block-ratio, 0.3))
+    );
 
     display: inline-flex;
     align-items: center;
-    gap: var(--_gap);
-    padding: var(--_padding-y) var(--_padding-x);
-    border-radius: var(--_border-radius);
-    border: var(--_border-width) var(--_border-style) var(--_border-color);
-    outline: var(--_outline);
-    outline-offset: var(--_outline-offset);
-    background-color: var(--_bg);
-    color: var(--_color);
+    gap: var(--display-pill-gap, calc(var(--_icon-size) * var(--display-pill-gap-ratio, 0.35)));
+    padding-block: var(--_padding-block);
+    padding-inline: var(--_padding-inline);
+
+    /* Icons carry their own whitespace, so the icon side gets less padding. */
+    &[data-icon-position="start"] {
+      padding-inline: var(--_padding-inline-icon) var(--_padding-inline);
+    }
+
+    &[data-icon-position="end"] {
+      padding-inline: var(--_padding-inline) var(--_padding-inline-icon);
+    }
+
+    &[data-icon-position="only"] {
+      padding-inline: var(--_padding-inline-icon);
+    }
+
+    border: var(--display-pill-border-width, 0.1rem) var(--display-pill-border-style, solid)
+      var(--display-pill-border-colour, transparent);
+    /* 100vw always resolves to a full pill radius regardless of element size */
+    border-radius: var(--display-pill-border-radius, 100vw);
+    outline: var(--display-pill-outline, none);
+    outline-offset: var(--display-pill-outline-offset, 0);
+    background-color: var(--_background);
+    color: var(--_text-colour);
+    font-family: inherit;
     font-size: var(--_font-size);
-    font-weight: var(--_font-weight);
+    font-weight: var(--display-pill-font-weight, 500);
     line-height: 1;
     white-space: nowrap;
     width: fit-content;
@@ -78,56 +110,62 @@ watch(
 
     &:is(button, a) {
       cursor: pointer;
+
+      &:focus-visible {
+        outline: 0.2rem solid var(--display-pill-focus-ring, var(--theme-border-focus));
+        outline-offset: 0.2rem;
+      }
     }
 
     &.is-reversed {
       flex-direction: row-reverse;
     }
 
-    .pill-label {
+    .display-pill-icon {
+      display: inline-flex;
+      align-items: center;
+      font-size: var(--_icon-size);
+    }
+
+    .display-pill-label {
       display: inline-flex;
       align-items: center;
     }
 
-    /* Sizes */
     &.sm {
-      --_font-size: var(--theme-pill-font-size-sm, 1rem);
-      --_padding-x: var(--theme-pill-padding-x-sm, 0.8rem);
-      --_padding-y: var(--theme-pill-padding-y-sm, 0.3rem);
-      --_icon-size: var(--theme-pill-icon-size-sm, 1.2rem);
+      --_font-size: var(--display-pill-font-size-sm, 1rem);
+      --_icon-size: var(--display-pill-icon-size-sm, 1.2rem);
     }
 
     &.lg {
-      --_font-size: var(--theme-pill-font-size-lg, 1.4rem);
-      --_padding-x: var(--theme-pill-padding-x-lg, 1.2rem);
-      --_padding-y: var(--theme-pill-padding-y-lg, 0.6rem);
-      --_icon-size: var(--theme-pill-icon-size-lg, 1.6rem);
+      --_font-size: var(--display-pill-font-size-lg, 1.4rem);
+      --_icon-size: var(--display-pill-icon-size-lg, 1.6rem);
     }
 
-    /* Variants */
+    /* Variant token, then the base token, then the variant's own default. */
     &.primary {
-      --_bg: var(--theme-pill-primary-bg, var(--blue-01));
-      --_color: var(--theme-pill-primary-color, var(--blue-09));
+      --_background: var(--display-pill-primary-background, var(--display-pill-background, var(--blue-01)));
+      --_text-colour: var(--display-pill-primary-text-colour, var(--display-pill-text-colour, var(--blue-09)));
     }
 
     &.success {
-      --_bg: var(--theme-pill-success-bg, var(--green-01));
-      --_color: var(--theme-pill-success-color, var(--green-10));
+      --_background: var(--display-pill-success-background, var(--display-pill-background, var(--green-01)));
+      --_text-colour: var(--display-pill-success-text-colour, var(--display-pill-text-colour, var(--green-10)));
     }
 
     &.warning {
-      --_bg: var(--theme-pill-warning-bg, var(--yellow-08, #fef9c3));
-      --_color: var(--theme-pill-warning-color, var(--yellow-03, #a16207));
+      --_background: var(--display-pill-warning-background, var(--display-pill-background, var(--orange-01)));
+      --_text-colour: var(--display-pill-warning-text-colour, var(--display-pill-text-colour, var(--orange-10)));
     }
 
     &.danger {
-      --_bg: var(--theme-pill-danger-bg, var(--red-01));
-      --_color: var(--theme-pill-danger-color, var(--red-10));
+      --_background: var(--display-pill-danger-background, var(--display-pill-background, var(--red-01)));
+      --_text-colour: var(--display-pill-danger-text-colour, var(--display-pill-text-colour, var(--red-10)));
     }
 
     &.neutral {
-      --_bg: var(--theme-pill-neutral-bg, var(--slate-08));
-      --_color: var(--theme-pill-neutral-color, var(--slate-03));
+      --_background: var(--display-pill-neutral-background, var(--display-pill-background, var(--slate-08)));
+      --_text-colour: var(--display-pill-neutral-text-colour, var(--display-pill-text-colour, var(--slate-03)));
     }
   }
 }

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

@@ -76,9 +76,7 @@ const Template: StoryFn<StoryArgs> = (args) => ({
         :reversed="args.reversed"
       >
         <template v-if="args.showIcon" #icon>
-          <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
-            <circle cx="12" cy="12" r="5" />
-          </svg>
+          <Icon name="material-symbols:check-circle-outline" />
         </template>
       </StorybookComponent>
     </div>
@@ -86,3 +84,58 @@ const Template: StoryFn<StoryArgs> = (args) => ({
 });
 
 export const Default = Template.bind({});
+
+const variants = ["default", "primary", "success", "warning", "danger", "neutral"] as const;
+
+export const AllVariants: StoryFn<StoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    return { args, variants };
+  },
+  template: `
+    <div style="display: flex; align-items: center; justify-content: center; min-height: 100vh; gap: 1.6rem; flex-wrap: wrap;">
+      <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>
+  `,
+});
+AllVariants.argTypes = { variant: { table: { disable: true } }, label: { table: { disable: true } } };
+
+export const OutlinedViaBaseTokens: StoryFn<StoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    return { args, variants };
+  },
+  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>
+  `,
+});
+OutlinedViaBaseTokens.storyName = "Outlined (base tokens override every variant)";
+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.",
+    },
+  },
+};

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

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import DisplayPill from "../DisplayPill.vue";
+import { defineComponent, nextTick, ref } from "vue";
 
 describe("DisplayPill", () => {
   // ─── Mount ───────────────────────────────────────────────────────────────
@@ -56,11 +57,11 @@ describe("DisplayPill", () => {
 
   // ─── Label ────────────────────────────────────────────────────────────────
 
-  it("renders label text inside .pill-label", async () => {
+  it("renders label text inside .display-pill-label", async () => {
     const wrapper = await mountSuspended(DisplayPill, {
       props: { label: "Active" },
     });
-    expect(wrapper.find(".pill-label").text()).toBe("Active");
+    expect(wrapper.find(".display-pill-label").text()).toBe("Active");
   });
 
   it("renders default slot when no label prop is set", async () => {
@@ -68,7 +69,7 @@ describe("DisplayPill", () => {
       slots: { default: "<strong class='custom'>Custom</strong>" },
     });
     expect(wrapper.find(".custom").exists()).toBe(true);
-    expect(wrapper.find(".pill-label").exists()).toBe(false);
+    expect(wrapper.find(".display-pill-label").exists()).toBe(false);
   });
 
   it("does not render default slot when label prop is set", async () => {
@@ -76,7 +77,7 @@ describe("DisplayPill", () => {
       props: { label: "Active" },
       slots: { default: "<strong class='custom'>Custom</strong>" },
     });
-    expect(wrapper.find(".pill-label").exists()).toBe(true);
+    expect(wrapper.find(".display-pill-label").exists()).toBe(true);
     expect(wrapper.find(".custom").exists()).toBe(false);
   });
 
@@ -156,4 +157,103 @@ describe("DisplayPill", () => {
     expect(wrapper.classes()).not.toContain("featured");
     expect(wrapper.classes()).toContain("highlighted");
   });
+
+  // ─── Migration 2026-09-27 ──────────────────────────────────────────────────
+
+  it("wraps icon slot content in .display-pill-icon", async () => {
+    const wrapper = await mountSuspended(DisplayPill, {
+      props: { label: "Status" },
+      slots: { icon: "<span class='dot'>●</span>" },
+    });
+    expect(wrapper.find(".display-pill-icon .dot").exists()).toBe(true);
+  });
+
+  it("does not render the icon wrapper without an icon slot", async () => {
+    const wrapper = await mountSuspended(DisplayPill, { props: { label: "Status" } });
+    expect(wrapper.find(".display-pill-icon").exists()).toBe(false);
+  });
+
+  it("gives a button pill type=button so it can't submit a form", async () => {
+    const wrapper = await mountSuspended(DisplayPill, { props: { tag: "button", label: "Filter" } });
+    expect(wrapper.attributes("type")).toBe("button");
+  });
+
+  it("does not set type on non-button pills", async () => {
+    const wrapper = await mountSuspended(DisplayPill, { props: { tag: "a", label: "Link" } });
+    expect(wrapper.attributes("type")).toBeUndefined();
+  });
+
+  it("passes href through to an anchor pill", async () => {
+    const wrapper = await mountSuspended(DisplayPill, {
+      props: { tag: "a", label: "Link" },
+      attrs: { href: "/tags/new" },
+    });
+    expect(wrapper.attributes("href")).toBe("/tags/new");
+  });
+
+  // ─── Icon position (drives icon-side padding) ─────────────────────────────
+
+  it("sets no data-icon-position without an icon", async () => {
+    const wrapper = await mountSuspended(DisplayPill, { props: { label: "Status" } });
+    expect(wrapper.attributes("data-icon-position")).toBeUndefined();
+  });
+
+  it("sets data-icon-position='start' for an icon before the label", async () => {
+    const wrapper = await mountSuspended(DisplayPill, {
+      props: { label: "Status" },
+      slots: { icon: "<span>●</span>" },
+    });
+    expect(wrapper.attributes("data-icon-position")).toBe("start");
+  });
+
+  it("sets data-icon-position='end' when reversed", async () => {
+    const wrapper = await mountSuspended(DisplayPill, {
+      props: { label: "Status", reversed: true },
+      slots: { icon: "<span>●</span>" },
+    });
+    expect(wrapper.attributes("data-icon-position")).toBe("end");
+  });
+
+  it("sets data-icon-position='only' for an icon with no label or text", async () => {
+    const wrapper = await mountSuspended(DisplayPill, { 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" },
+    });
+    expect(wrapper.attributes("data-icon-position")).toBe("start");
+  });
+
+  it("updates data-icon-position when reversed changes", async () => {
+    const wrapper = await mountSuspended(DisplayPill, {
+      props: { label: "Status" },
+      slots: { icon: "<span>●</span>" },
+    });
+    await wrapper.setProps({ reversed: true });
+    expect(wrapper.attributes("data-icon-position")).toBe("end");
+  });
+
+  it("drops data-icon-position when the icon slot is removed after mount", async () => {
+    const Host = defineComponent({
+      components: { DisplayPill },
+      setup() {
+        const showIcon = ref(true);
+        return { showIcon };
+      },
+      template: `
+        <DisplayPill label="Status">
+          <template v-if="showIcon" #icon><span>●</span></template>
+        </DisplayPill>
+      `,
+    });
+    const wrapper = await mountSuspended(Host);
+    const pill = () => wrapper.find(".display-pill");
+    expect(pill().attributes("data-icon-position")).toBe("start");
+    (wrapper.vm as unknown as { showIcon: boolean }).showIcon = false;
+    await nextTick();
+    expect(pill().attributes("data-icon-position")).toBeUndefined();
+    expect(pill().find(".display-pill-icon").exists()).toBe(false);
+  });
 });

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"><span class="pill-label">Status</span></span>"`;
+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 (reversed) 1`] = `"<span class="display-pill md default is-reversed"><span class="icon">✓</span><span class="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 (with icon slot) 1`] = `"<span class="display-pill lg success"><span class="icon">✓</span><span class="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>"`;

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

@@ -6,9 +6,12 @@
 |---|---|---|
 | `--display-tooltip-padding-block` | `0.8rem` | Vertical padding around the trigger row |
 | `--display-tooltip-trigger-gap` | `0.8rem` | Space between `triggerContent` slot and the trigger button |
-| `--display-tooltip-trigger-icon-box-size` | `2rem` | Trigger icon's box width/height |
-| `--display-tooltip-trigger-icon-font-size` | `1.8rem` | Trigger icon glyph size |
+| `--display-tooltip-trigger-icon-box-size` | `1.6rem` | Trigger icon width/height |
 | `--display-tooltip-trigger-icon-colour` | `var(--theme-text)` | Trigger icon colour |
+| `--display-tooltip-trigger-padding` | `0rem` | Space between the icon and the trigger button edge (single length, see note) |
+| `--display-tooltip-trigger-border-width` | `0.1rem` | Trigger button border width |
+| `--display-tooltip-trigger-border-colour` | `transparent` | Trigger button border colour |
+| `--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 |
@@ -44,8 +47,24 @@ Or scope to a single instance via `styleClassPassthrough`:
 <DisplayTooltip style-class-passthrough="promo-tooltip">...</DisplayTooltip>
 ```
 
+---
+
+## 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`.
+
+---
+
 ## Notes
 
+- 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
+  breaks that calculation, and the button is square anyway.
 - Built on the native Popover API (`popover`/`popovertarget`) and CSS anchor-positioning
   (`anchor-name`/`position-anchor`/`anchor()`) — check current browser support before relying on
   it where broad support is a hard requirement.
@@ -60,3 +79,4 @@ Or scope to a single instance via `styleClassPassthrough`:
   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.
+

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

@@ -64,37 +64,38 @@ watch(
 
         &.hide {
           width: 0;
+          padding: 0;
+          border-width: 0;
           overflow: hidden;
           opacity: 0;
         }
 
         .display-tooltip-trigger-icon {
-          display: inline-flex;
-          align-items: center;
-          justify-content: center;
-          width: var(--display-tooltip-trigger-icon-box-size, 2rem);
-          height: var(--display-tooltip-trigger-icon-box-size, 2rem);
+          width: var(--_trigger-icon-size);
+          height: var(--_trigger-icon-size);
           color: var(--display-tooltip-trigger-icon-colour, var(--theme-text));
-          font-size: var(--display-tooltip-trigger-icon-font-size, 1.8rem);
-          line-height: var(--display-tooltip-trigger-icon-box-size, 2rem);
         }
       }
     }
 
     .display-tooltip-trigger-button {
+      --_trigger-icon-size: var(--display-tooltip-trigger-icon-box-size, 1.6rem);
+      --_trigger-padding: var(--display-tooltip-trigger-padding, 0rem);
+      --_trigger-border-width: var(--display-tooltip-trigger-border-width, 0.1rem);
+
       all: unset;
       aspect-ratio: 1 / 1;
-      width: 2.4rem;
+      padding: var(--_trigger-padding);
       display: grid;
       place-items: center;
 
+      border: var(--_trigger-border-width) solid
+        var(--display-tooltip-trigger-border-colour, transparent);
+      border-radius: var(--display-tooltip-trigger-border-radius, 100vw);
       outline: var(--display-tooltip-trigger-outline-width, 0.1rem) solid transparent;
       anchor-name: var(--_anchor-name);
-
-      @supports (corner-shape: squircle) {
-        corner-shape: squircle;
-        border-radius: 50%;
-      }
+      /* Centres the button on the first line of trigger text */
+      translate: 0 calc((1lh - var(--_trigger-icon-size) - 2 * (var(--_trigger-padding) + var(--_trigger-border-width))) / 2);
 
       &:hover {
         cursor: pointer;
@@ -104,7 +105,7 @@ watch(
       &:hover,
       &:focus-visible {
         outline-color: var(--display-tooltip-trigger-outline-colour-hover, var(--theme-ring));
-        outline-offset: 0.2rem;
+        outline-offset: 0.1rem;
       }
     }
 
@@ -119,10 +120,7 @@ watch(
       color: var(--display-tooltip-popover-text-colour, var(--slate-09));
       background-color: var(--display-tooltip-popover-background-colour, var(--slate-00));
       border-radius: var(--display-tooltip-popover-border-radius, 0.8rem);
-      box-shadow: var(
-        --display-tooltip-popover-shadow,
-        0 0.4rem 1.6rem rgba(0, 0, 0, 0.12)
-      );
+      box-shadow: var(--display-tooltip-popover-shadow, 0 0.4rem 1.6rem rgba(0, 0, 0, 0.12));
 
       position-anchor: var(--_anchor-name);
       margin: 0;
@@ -158,14 +156,8 @@ watch(
           &:hover,
           &:focus {
             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)
-            );
+            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));
             outline-offset: 0.2rem;
           }
         }

package/app/components/01.atoms/glass-panel/CONSUMER-STYLING.md

@@ -0,0 +1,91 @@
+# GlassPanel — Consumer Styling Guide
+
+`GlassPanel` is a container with a frosted-glass look: translucent background, blurred and
+saturated backdrop, thin border, soft shadow, and an angled highlight across the top-left.
+The effect only reads as glass when the panel sits over an image, gradient or other
+textured background. Over a flat colour it looks like a plain translucent card.
+
+## Public token API
+
+Every token has a built-in default (the light-mode glass values), so the panel works without any
+setup.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--glass-panel-bg` | `rgba(255, 255, 255, 0.55)` | Background. Keep some transparency or the blur behind it won't show |
+| `--glass-panel-border-width` | `1px` | Border width |
+| `--glass-panel-border-color` | `rgba(255, 255, 255, 0.8)` | Border colour |
+| `--glass-panel-border-radius` | `1rem` | Corner radius (the highlight follows it) |
+| `--glass-panel-shadow` | `0 8px 32px rgba(0, 0, 0, 0.08), 0 2px 8px rgba(0, 0, 0, 0.04)` | `box-shadow` value |
+| `--glass-panel-backdrop-filter` | `blur(14px) saturate(180%)` | `backdrop-filter` value. `none` turns the frosting off |
+| `--glass-panel-highlight` | `rgba(255, 255, 255, 0.9)` | Colour at the start of the highlight gradient |
+| `--glass-panel-highlight-angle` | `135deg` | Direction of the highlight gradient |
+| `--glass-panel-highlight-stop` | `55%` | Where the highlight fades to transparent |
+
+> **Changed 2026-09-26**: the defaults used to be set globally in `03.theming/_default.css` with
+> `light-dark()`, which older iPad Safari doesn't support (the panel lost its background, border,
+> shadow and highlight there). They now live in the component as light-mode values only. **There
+> is no built-in dark-mode glass any more.** For a dark page, set your own values, e.g. the
+> previous dark defaults:
+>
+> ```css
+> [data-color-scheme="dark"] {
+>   --glass-panel-bg: rgba(12, 12, 20, 0.45);
+>   --glass-panel-border-color: rgba(255, 255, 255, 0.07);
+>   --glass-panel-shadow: 0 8px 32px rgba(0, 0, 0, 0.5), 0 2px 8px rgba(0, 0, 0, 0.3);
+>   --glass-panel-highlight: rgba(255, 255, 255, 0.04);
+> }
+> ```
+>
+> (Using `light-dark()` in your own app CSS is also fine if your audience's browsers support it.)
+
+---
+
+## Global theming
+
+```css
+:where(html) {
+  --glass-panel-bg: oklch(98% 0.005 15 / 0.6);
+  --glass-panel-border-color: oklch(100% 0 0 / 0.75);
+  --glass-panel-highlight: oklch(100% 0 0 / 0.85);
+}
+```
+
+---
+
+## 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`.
+
+### Page or section
+
+```css
+.pricing-page {
+  .glass-panel {
+    --glass-panel-border-radius: 2.4rem;
+    --glass-panel-backdrop-filter: blur(24px) saturate(140%);
+  }
+}
+```
+
+---
+
+## Class passthrough
+
+`:style-class-passthrough` (string or string array) adds classes to the root `.glass-panel`.
+
+---
+
+## Layout notes
+
+- `overflow: hidden` is set on the root, so anything that needs to escape the panel (tooltips,
+  dropdowns, PendingEffect borders on buttons inside it) must be portalled or given room.
+- The highlight is a `::before` layer behind the panel's content (`z-index: -1` inside an
+  `isolation: isolate` root), so it tints the background but never washes out text, and
+  `pointer-events: none` means it never blocks clicks. The root is its own stacking context, so a
+  `z-index` on something inside the panel can't lift it above elements outside the panel.
+