srcdev-nuxt-components 9.4.12 → 9.5.1

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

@@ -1,17 +1,5 @@
 # DisplayDialog — Consumer Styling Guide
 
-## Structural class names (2026-08-22)
-
-`DisplayDialog` renders `<dialog>` inline in the component tree, not via `<Teleport>` — so it's a
-genuine descendant of wherever it's used in the page, and any ancestor's CSS selectors reach it.
-Before 2026-08-22 its internal sections used bare generic class names (`.inner`, `.header`,
-`.footer`, `.col-left`, `.col-right`, `.dialog-content`) — a consumer app with its own `.header`/
-`.footer` layout classes (extremely common names) had its unlayered site CSS silently override the
-dialog's own footer layout (button alignment, padding) purely by class-name collision, since
-unlayered CSS always beats `@layer components` regardless of specificity. All six renamed to
-`.display-dialog-*` prefixed variants (`.display-dialog-inner`, `.display-dialog-header`, etc.) —
-update any consumer overrides written against the old names.
-
 ## Public token API
 
 All `--display-dialog-*` tokens are the stable override surface. Because dialogs are site-wide UI
@@ -32,9 +20,16 @@ file** rather than per-instance via `styleClassPassthrough`.
 | Token | Default | Controls |
 |---|---|---|
 | `--display-dialog-inner-border-radius` | `0.8rem` | Panel corner rounding |
-| `--display-dialog-inner-border` | `0.1rem solid light-dark(var(--slate-10), var(--slate-02))` | Panel border shorthand |
-| `--display-dialog-inner-outline` | `0.1rem solid light-dark(var(--slate-10), var(--slate-00))` | Panel outer outline (sits outside the border) |
-| `--display-dialog-inner-background` | `light-dark(var(--slate-00), var(--slate-10))` | Panel background colour |
+| `--display-dialog-inner-border` | `0.1rem solid var(--colour-text-default)` | Panel border shorthand |
+| `--display-dialog-inner-outline` | `0.1rem solid var(--colour-text-default)` | Panel outer outline (sits outside the border) |
+| `--display-dialog-inner-background` | `var(--page-bg)` | Panel background colour |
+
+> Changed 2026-09-27: the four panel tokens are now resolved on `.display-dialog-inner` (they were
+> resolved on the outer `.display-dialog`), so setting them on the panel itself, e.g. per variant
+> with `.display-dialog-inner.alert`, now works. Colour defaults no longer call `light-dark()`
+> (unsupported on older iPad Safari); they use the global scheme-aware `--colour-text-default` and
+> `--page-bg` instead, so they still follow light/dark mode (dark panel is now `--slate-08`, was
+> `--slate-10`).
 
 ### Header
 
@@ -46,9 +41,9 @@ file** rather than per-instance via `styleClassPassthrough`.
 | `--display-dialog-header-button-border` | `0.1rem solid transparent` | Close button border (resting) |
 | `--display-dialog-header-button-border-radius` | `0.4rem` | Close button corner rounding |
 | `--display-dialog-header-button-outline` | `0.1rem solid transparent` | Close button outline (resting) |
-| `--display-dialog-header-button-border-hover` | `0.1rem solid light-dark(var(--slate-08), var(--slate-04))` | Close button border on hover/focus |
-| `--display-dialog-header-button-outline-hover` | `0.1rem solid light-dark(var(--slate-08), var(--slate-04))` | Close button outline on hover/focus |
-| `--display-dialog-header-button-icon-color` | `light-dark(var(--slate-09), var(--slate-02))` | Close button icon colour |
+| `--display-dialog-header-button-border-hover` | `0.1rem solid var(--colour-text-default)` | Close button border on hover/focus |
+| `--display-dialog-header-button-outline-hover` | `0.1rem solid var(--colour-text-default)` | Close button outline on hover/focus |
+| `--display-dialog-header-button-icon-color` | `var(--colour-text-default)` | Close button icon colour |
 | `--display-dialog-header-button-icon-size` | `2.4rem` | Close button icon size |
 
 ### Content & footer
@@ -61,7 +56,29 @@ file** rather than per-instance via `styleClassPassthrough`.
 
 ---
 
-## Global theming — recommended approach
+## State hooks
+
+| Hook | Element | When |
+|---|---|---|
+| `[open]` | `.display-dialog` | Dialog is open |
+| `[justify-dialog="start|center|end"]` | `.display-dialog` | Horizontal placement of the panel |
+| `[align-dialog="start|center|end"]` | `.display-dialog` | Vertical placement of the panel |
+| `.dialog`, `.modal`, `.confirm`, `.alert`, `.fullscreen` | `.display-dialog-inner` | The resolved `variant` |
+| `[data-theme]` | `.display-dialog-header` | A `theme` is set: adds a `--theme-accent` bottom border and title colour |
+| `.allow-content-scroll` | `.display-dialog-content` | `allow-content-scroll` is on |
+
+Inner classes: `.display-dialog-inner` (panel), `.display-dialog-header`,
+`.display-dialog-col-left` (title), `.display-dialog-col-right`, `.display-dialog-close`,
+`.display-dialog-content`, `.display-dialog-footer`.
+
+> Changed 2026-08-22: these used to be bare generic names (`.inner`, `.header`, `.footer`,
+> `.col-left`, `.col-right`, `.dialog-content`). The dialog renders inline, not teleported, so a
+> consumer's own unlayered `.header`/`.footer` CSS silently restyled it. Update any overrides
+> written against the old names.
+
+---
+
+## Global theming
 
 Create `assets/styles/setup/07.components/display-dialog.css` in the consuming app and set tokens
 on `:root`. This applies to every `DisplayDialog` across the site.
@@ -83,17 +100,22 @@ on `:root`. This applies to every `DisplayDialog` across the site.
 
 ---
 
-## Per-variant overrides
+## 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`.
 
-The `fullscreen` variant bypasses `--_inner-border-radius`, `--_inner-border`, and
-`--_inner-outline` directly (setting them to `0`/`none`). To restyle the fullscreen panel,
-target the private tokens on `.display-dialog-inner.fullscreen`:
+### Per variant
+
+The panel tokens resolve on `.display-dialog-inner`, so set them on the variant class:
 
 ```css
 .display-dialog {
   .display-dialog-inner {
     &.confirm {
-      /* e.g. constrain confirm panel width further */
       max-width: 40rem;
     }
 
@@ -102,39 +124,17 @@ target the private tokens on `.display-dialog-inner.fullscreen`:
     }
 
     &.fullscreen {
-      /* private tokens are the only lever here */
-      --_inner-background: var(--brand-surface-alt);
+      --display-dialog-inner-background: var(--brand-surface-alt);
     }
   }
 }
 ```
 
----
-
-## Section targeting
-
-Target `.display-dialog-header`, `.display-dialog-content`, and `.display-dialog-footer` directly to adjust layout within the panel:
-
-```css
-.display-dialog {
-  .display-dialog-header {
-    border-bottom: 0.1rem solid var(--brand-border);
-  }
-
-  .display-dialog-content {
-    /* content area uses --display-dialog-content-padding */
-  }
-
-  .display-dialog-footer {
-    border-top: 0.1rem solid var(--brand-border);
-    justify-content: space-between; /* override default flex-end */
-  }
-}
-```
-
----
+**Caveat:** `fullscreen` forces its radius, border and outline to `0`/`none` on the panel itself,
+so `--display-dialog-inner-border-radius`, `-border` and `-outline` have no effect on that variant
+(its background still follows `--display-dialog-inner-background`).
 
-## Page-scoped overrides
+### Page or section
 
 Because `<DisplayDialog>` renders inside the page's DOM tree (even though it is `position: fixed`),
 you can scope overrides to a specific page without affecting the rest of the site:
@@ -153,9 +153,7 @@ you can scope overrides to a specific page without affecting the rest of the sit
 }
 ```
 
----
-
-## Per-instance overrides via styleClassPassthrough
+### One instance
 
 Use sparingly — prefer global or page-scoped CSS for dialogs. When a single instance genuinely
 needs a different look, pass a modifier class and target it alongside `.display-dialog`:
@@ -173,3 +171,33 @@ needs a different look, pass a modifier class and target it alongside `.display-
   }
 }
 ```
+
+---
+
+## Recipe: section targeting
+
+Target `.display-dialog-header`, `.display-dialog-content`, and `.display-dialog-footer` directly to adjust layout within the panel:
+
+```css
+.display-dialog {
+  .display-dialog-header {
+    border-bottom: 0.1rem solid var(--brand-border);
+  }
+
+  .display-dialog-content {
+    /* content area uses --display-dialog-content-padding */
+  }
+
+  .display-dialog-footer {
+    border-top: 0.1rem solid var(--brand-border);
+    justify-content: space-between; /* override default flex-end */
+  }
+}
+```
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `<dialog class="display-dialog">`, so tokens
+set on a passthrough class land for the whole dialog (see **One instance** above).

package/app/components/01.atoms/display-dialog/DisplayDialog.vue

@@ -4,7 +4,7 @@
     :class="[elementClasses]"
     :role="isAlert ? 'alertdialog' : undefined"
     :aria-modal="true"
-    :aria-labelledby="hasTitle ? dialogTitleId : undefined"
+    :aria-labelledby="hasTitle() ? dialogTitleId : undefined"
     :align-dialog="resolved.alignDialog"
     :justify-dialog="resolved.justifyDialog"
     :open
@@ -18,7 +18,7 @@
     >
       <div class="display-dialog-inner" :class="[resolved.variant]">
         <div class="display-dialog-header" :data-theme="resolved.theme">
-          <div v-if="hasTitle" :id="dialogTitleId" class="display-dialog-col-left">
+          <div v-if="hasTitle()" :id="dialogTitleId" class="display-dialog-col-left">
             <slot name="dialogTitle"></slot>
           </div>
 
@@ -29,19 +29,19 @@
               @click.prevent="closeDialog()"
             >
               <Icon :name="resolved.closeIcon" class="icon" />
-              <span class="sr-only">Close</span>
+              <span class="sr-only">{{ resolved.closeLabel }}</span>
             </button>
           </div>
         </div>
         <div
-          v-if="hasContent"
+          v-if="hasContent()"
           class="display-dialog-content"
           :class="[{ 'allow-content-scroll': resolved.allowContentScroll }]"
           :tabindex="resolved.allowContentScroll ? 0 : undefined"
         >
           <slot name="dialogContent"></slot>
         </div>
-        <div v-if="hasFooter" class="display-dialog-footer">
+        <div v-if="hasFooter()" class="display-dialog-footer">
           <slot name="actionButtonLeft"></slot>
           <slot name="actionButtonRight"></slot>
         </div>
@@ -64,6 +64,7 @@ interface Props {
   dataDialogId: string;
   theme?: SemanticTheme;
   closeIcon?: string;
+  closeLabel?: string;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -75,6 +76,7 @@ const props = withDefaults(defineProps<Props>(), {
   allowContentScroll: undefined,
   theme: undefined,
   closeIcon: undefined,
+  closeLabel: undefined,
 });
 
 const appConfig = useAppConfig();
@@ -89,10 +91,16 @@ const resolved = computed(() => {
     allowContentScroll: props.allowContentScroll ?? config?.allowContentScroll ?? false,
     theme: props.theme ?? config?.theme,
     closeIcon: props.closeIcon ?? config?.closeIcon ?? "bitcoin-icons:cross-filled",
+    closeLabel: props.closeLabel ?? config?.closeLabel ?? "Close",
   } as const;
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const isAlert = computed(() => resolved.value.variant === "alert");
 const dialogTitleId = useId();
@@ -104,9 +112,9 @@ const closeDialog = () => {
 };
 
 const slots = useSlots();
-const hasTitle = computed(() => !!slots.dialogTitle);
-const hasContent = computed(() => !!slots.dialogContent);
-const hasFooter = computed(() => !!(slots.actionButtonLeft || slots.actionButtonRight));
+const hasTitle = () => !!slots.dialogTitle;
+const hasContent = () => !!slots.dialogContent;
+const hasFooter = () => !!(slots.actionButtonLeft || slots.actionButtonRight);
 
 const { lock, unlock } = useBodyLock();
 let hasLocked = false;
@@ -129,48 +137,29 @@ onUnmounted(() => {
 <style lang="css">
 @layer components {
   .display-dialog {
-    --_backdrop-blur: var(--display-dialog-backdrop-blur, blur(0.5rem));
-    --_backdrop-background: var(--display-dialog-backdrop-background, rgba(0, 0, 0, 0.5));
-    --_z-index: var(--display-dialog-z-index, 999999);
     --_transition-duration: var(--display-dialog-transition-duration, 200ms);
 
-    --_inner-border-radius: var(--display-dialog-inner-border-radius, 0.8rem);
-    --_inner-border: var(--display-dialog-inner-border, 0.1rem solid light-dark(var(--slate-10), var(--slate-02)));
-    --_inner-outline: var(--display-dialog-inner-outline, 0.1rem solid light-dark(var(--slate-10), var(--slate-00)));
-    --_inner-background: var(--display-dialog-inner-background, light-dark(var(--slate-00), var(--slate-10)));
-
-    --_header-padding: var(--display-dialog-header-padding, 1.2rem);
-    --_header-button-margin: var(--display-dialog-header-button-margin, 0);
-    --_header-button-padding: var(--display-dialog-header-button-padding, 0.4rem);
-    --_header-button-border: var(--display-dialog-header-button-border, 0.1rem solid transparent);
-    --_header-button-border-radius: var(--display-dialog-header-button-border-radius, 0.4rem);
-    --_header-button-outline: var(--display-dialog-header-button-outline, 0.1rem solid transparent);
     --_header-button-border-hover: var(
       --display-dialog-header-button-border-hover,
-      0.1rem solid light-dark(var(--slate-08), var(--slate-04))
+      0.1rem solid var(--colour-text-default)
     );
     --_header-button-outline-hover: var(
       --display-dialog-header-button-outline-hover,
-      0.1rem solid light-dark(var(--slate-08), var(--slate-04))
+      0.1rem solid var(--colour-text-default)
     );
     --_header-button-icon-color: var(
       --display-dialog-header-button-icon-color,
-      light-dark(var(--slate-09), var(--slate-02))
+      var(--colour-text-default)
     );
-    --_header-button-icon-size: var(--display-dialog-header-button-icon-size, 2.4rem);
-
-    --_content-padding: var(--display-dialog-content-padding, 1.2rem);
-    --_footer-gap: var(--display-dialog-footer-gap, 1.2rem);
-    --_footer-padding: var(--display-dialog-footer-padding, 1.2rem);
 
     position: fixed;
     left: 0;
     top: 0;
     width: 100%;
     height: 100%;
-    backdrop-filter: var(--_backdrop-blur);
-    background-color: var(--_backdrop-background);
-    z-index: var(--_z-index);
+    backdrop-filter: var(--display-dialog-backdrop-blur, blur(0.5rem));
+    background-color: var(--display-dialog-backdrop-background, rgba(0, 0, 0, 0.5));
+    z-index: var(--display-dialog-z-index, 999999);
     opacity: 0;
     border: none;
     padding: 0;
@@ -217,12 +206,16 @@ onUnmounted(() => {
     }
 
     .display-dialog-inner {
+      --_inner-border-radius: var(--display-dialog-inner-border-radius, 0.8rem);
+      --_inner-border: var(--display-dialog-inner-border, 0.1rem solid var(--colour-text-default));
+      --_inner-outline: var(--display-dialog-inner-outline, 0.1rem solid var(--colour-text-default));
+
       display: grid;
       grid-template-rows: auto 1fr auto;
       border-radius: var(--_inner-border-radius);
       border: var(--_inner-border);
       outline: var(--_inner-outline);
-      background-color: var(--_inner-background);
+      background-color: var(--display-dialog-inner-background, var(--page-bg));
       height: initial;
       width: 100vw;
       overflow: hidden;
@@ -259,7 +252,7 @@ onUnmounted(() => {
       .display-dialog-header {
         display: flex;
         align-items: center;
-        padding: var(--_header-padding);
+        padding: var(--display-dialog-header-padding, 1.2rem);
 
         &[data-theme] {
           border-block-end: 0.2rem solid var(--theme-accent);
@@ -281,11 +274,11 @@ onUnmounted(() => {
             display: block flex;
             align-items: center;
             justify-content: center;
-            margin: var(--_header-button-margin);
-            padding: var(--_header-button-padding);
-            border: var(--_header-button-border);
-            border-radius: var(--_header-button-border-radius);
-            outline: var(--_header-button-outline);
+            margin: var(--display-dialog-header-button-margin, 0);
+            padding: var(--display-dialog-header-button-padding, 0.4rem);
+            border: var(--display-dialog-header-button-border, 0.1rem solid transparent);
+            border-radius: var(--display-dialog-header-button-border-radius, 0.4rem);
+            outline: var(--display-dialog-header-button-outline, 0.1rem solid transparent);
 
             transition:
               border-color var(--_transition-duration),
@@ -301,7 +294,7 @@ onUnmounted(() => {
             .icon {
               color: var(--_header-button-icon-color);
               display: block;
-              font-size: var(--_header-button-icon-size);
+              font-size: var(--display-dialog-header-button-icon-size, 2.4rem);
             }
           }
         }
@@ -309,7 +302,7 @@ onUnmounted(() => {
 
       .display-dialog-content {
         overflow: hidden;
-        padding: var(--_content-padding);
+        padding: var(--display-dialog-content-padding, 1.2rem);
 
         &.allow-content-scroll {
           overflow-y: auto;
@@ -321,9 +314,9 @@ onUnmounted(() => {
 
       .display-dialog-footer {
         display: flex;
-        gap: var(--_footer-gap);
+        gap: var(--display-dialog-footer-gap, 1.2rem);
         justify-content: flex-end;
-        padding: var(--_footer-padding);
+        padding: var(--display-dialog-footer-padding, 1.2rem);
       }
     }
   }

package/app/components/01.atoms/display-dialog/stories/DisplayDialog.stories.ts

@@ -7,6 +7,9 @@ type StoryArgs = {
   allowContentScroll: boolean;
   justifyDialog: "start" | "center" | "end";
   alignDialog: "start" | "center" | "end";
+  theme: "" | "info" | "success" | "warning" | "error";
+  closeIcon: string;
+  closeLabel: string;
 };
 
 export default {
@@ -36,6 +39,22 @@ export default {
       description: "Vertical position of the dialog panel within the overlay",
       table: { category: "Layout" },
     },
+    theme: {
+      control: { type: "select" },
+      options: ["", "info", "success", "warning", "error"],
+      description: "Semantic theme: accent border and title colour on the header",
+      table: { category: "Appearance" },
+    },
+    closeIcon: {
+      control: { type: "text" },
+      description: "Icon name for the close button",
+      table: { category: "Appearance" },
+    },
+    closeLabel: {
+      control: { type: "text" },
+      description: "Screen-reader label for the close button (override for localisation)",
+      table: { category: "Accessibility" },
+    },
     styleClassPassthrough: { table: { disable: true } },
     lockViewport: { table: { disable: true } },
     dataDialogId: { table: { disable: true } },
@@ -45,6 +64,9 @@ export default {
     allowContentScroll: false,
     justifyDialog: "center",
     alignDialog: "center",
+    theme: "",
+    closeIcon: "bitcoin-icons:cross-filled",
+    closeLabel: "Close",
   },
   parameters: {
     docs: {
@@ -77,6 +99,9 @@ const Template: StoryFn<StoryArgs> = (args) => ({
         :allow-content-scroll="args.allowContentScroll"
         :justify-dialog="args.justifyDialog"
         :align-dialog="args.alignDialog"
+        :theme="args.theme || undefined"
+        :close-icon="args.closeIcon"
+        :close-label="args.closeLabel"
         :lock-viewport="false"
         data-dialog-id="storybook-dialog"
       >

package/app/components/01.atoms/display-dialog/tests/DisplayDialog.spec.ts

@@ -230,6 +230,16 @@ describe("DisplayDialog", () => {
     expect(wrapper.emitted("update:modelValue")?.[0]).toEqual([false]);
   });
 
+  it("uses \"Close\" as the close button's screen-reader label by default", async () => {
+    const wrapper = await mountSuspended(DisplayDialog, { props: { dataDialogId: "test" } });
+    expect(wrapper.find(".display-dialog-close .sr-only").text()).toBe("Close");
+  });
+
+  it("uses the closeLabel prop for the close button's screen-reader label", async () => {
+    const wrapper = await mountSuspended(DisplayDialog, { props: { dataDialogId: "test", closeLabel: "Fermer" } });
+    expect(wrapper.find(".display-dialog-close .sr-only").text()).toBe("Fermer");
+  });
+
   // ─── styleClassPassthrough ────────────────────────────────────────────────
 
   it("applies a styleClassPassthrough string", async () => {
@@ -239,6 +249,15 @@ describe("DisplayDialog", () => {
     expect(wrapper.classes()).toContain("my-class");
   });
 
+  it("updates classes when styleClassPassthrough changes", async () => {
+    const wrapper = await mountSuspended(DisplayDialog, {
+      props: { dataDialogId: "test", styleClassPassthrough: ["original"] },
+    });
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+
   it("applies multiple styleClassPassthrough classes from an array", async () => {
     const wrapper = await mountSuspended(DisplayDialog, {
       props: { dataDialogId: "test", styleClassPassthrough: ["class-a", "class-b"] },
@@ -332,6 +351,7 @@ describe("DisplayDialog", () => {
             lockViewport: false,
             allowContentScroll: true,
             theme: "info" as SemanticTheme,
+            closeLabel: "Schliessen",
             closeIcon: "heroicons:x-mark",
           },
         },
@@ -340,6 +360,7 @@ describe("DisplayDialog", () => {
         props: { dataDialogId: "test" },
         slots: { dialogContent: "<p>Content</p>" },
       });
+      expect(wrapper.find(".display-dialog-close .sr-only").text()).toBe("Schliessen");
       expect(wrapper.find(".display-dialog-inner").classes()).toContain("modal");
       expect(wrapper.attributes("align-dialog")).toBe("end");
       expect(wrapper.attributes("justify-dialog")).toBe("start");

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

@@ -0,0 +1,112 @@
+# DisplayPill — Consumer Styling Guide
+
+> **Changed 2026-09-27**: tokens renamed from `--theme-pill-*` to `--display-pill-*`, and `bg`/`color`
+> to `background`/`text-colour`, and `padding-x`/`padding-y` to `padding-inline`/`padding-block` (`--theme-pill-bg` → `--display-pill-background`,
+> `--theme-pill-primary-color` → `--display-pill-primary-text-colour`, etc.). The `--theme-` prefix
+> read as a global theme slot and clashed with the library's real `--theme-*` tokens.
+
+## Public token API
+
+### Colour
+
+Each variant resolves its colour as **variant token → base token → variant default**, so setting
+the base token restyles every variant, and a variant token still wins for that one variant.
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-pill-background` | `var(--slate-01)` | Background (the `default` variant, and the fallback for every other variant) |
+| `--display-pill-text-colour` | `var(--slate-09)` | Text/icon colour (same fallback role) |
+| `--display-pill-primary-background` / `-text-colour` | `var(--blue-01)` / `var(--blue-09)` | `primary` variant |
+| `--display-pill-success-background` / `-text-colour` | `var(--green-01)` / `var(--green-10)` | `success` variant |
+| `--display-pill-warning-background` / `-text-colour` | `var(--orange-01)` / `var(--orange-10)` | `warning` variant |
+| `--display-pill-danger-background` / `-text-colour` | `var(--red-01)` / `var(--red-10)` | `danger` variant |
+| `--display-pill-neutral-background` / `-text-colour` | `var(--slate-08)` / `var(--slate-03)` | `neutral` variant (dark) |
+| `--display-pill-focus-ring` | `var(--theme-border-focus)` | `:focus-visible` outline on `button`/`a` pills |
+
+> **Changed 2026-09-27**: variants used to read only their own tokens, so a base `bg`/`color`
+> override never reached a non-default variant. That's why `ServiceSummary`'s and `ServiceDetail`'s
+> pill tokens (their pills are `neutral`) had never applied. The `warning` variant read a
+> `--yellow-*` ramp that doesn't exist, so it always showed its hardcoded hex fallbacks; it now uses
+> the `orange` ramp the warning theme moved to.
+
+### Border, outline and shape
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-pill-border-colour` | `transparent` | Border colour |
+| `--display-pill-border-width` | `0.1rem` | Border width |
+| `--display-pill-border-style` | `solid` | Border style |
+| `--display-pill-border-radius` | `100vw` | Radius (100vw is always a full pill) |
+| `--display-pill-outline` | `none` | Decorative outline (shorthand) on every pill |
+| `--display-pill-outline-offset` | `0` | Offset for that outline |
+
+### Size
+
+| Token | Default (`sm` / `md` / `lg`) | Controls |
+|---|---|---|
+| `--display-pill-font-size` / `-sm` / `-lg` | `1rem` / `1.2rem` / `1.4rem` | Text size |
+| `--display-pill-icon-size` / `-sm` / `-lg` | `1.2rem` / `1.4rem` / `1.6rem` | Icon size (`font-size` on `.display-pill-icon`); also the unit all spacing below scales from |
+| `--display-pill-font-weight` | `500` | Text weight |
+
+The unsuffixed token is the `md` value; `-sm`/`-lg` apply to those sizes.
+
+> **Changed 2026-09-27**: the icon-size tokens were declared but never used, so icons weren't
+> sized. The icon slot is now wrapped in `.display-pill-icon`, which sets its `font-size`.
+
+### Spacing
+
+Padding and gap are the pill's icon size times a ratio, so every size (and any custom icon size)
+keeps the same proportions. Tune a **ratio** to change spacing across all sizes, or set the
+**absolute** token to pin one length (it then applies to every size).
+
+| Ratio token | Default | Result (`sm` / `md` / `lg`) | Absolute override | Controls |
+|---|---|---|---|---|
+| `--display-pill-padding-inline-ratio` | `0.7` | ≈ `0.84` / `0.98` / `1.12rem` | `--display-pill-padding-inline` | `padding-inline` (both sides of a label-only pill; the non-icon side otherwise) |
+| `--display-pill-padding-inline-icon-ratio` | `0.4` | ≈ `0.48` / `0.56` / `0.64rem` | `--display-pill-padding-inline-icon` | `padding-inline` on the icon side (both sides of an icon-only pill), tighter because icons carry their own whitespace |
+| `--display-pill-padding-block-ratio` | `0.3` | ≈ `0.36` / `0.42` / `0.48rem` | `--display-pill-padding-block` | `padding-block` |
+| `--display-pill-gap-ratio` | `0.35` | ≈ `0.42` / `0.49` / `0.56rem` | `--display-pill-gap` | Gap between icon and label |
+
+> **Changed 2026-09-27**: spacing used to be hand-set per size (`--display-pill-padding-inline-sm`,
+> `-lg`, etc., now removed). It's now derived from the icon size; results are within about 0.1rem
+> of the old values, except `lg` block padding (`0.6rem` → `0.48rem`), which was out of proportion.
+
+Private tokens (not public API): `--_background`, `--_text-colour`, `--_font-size`, `--_padding-inline`,
+`--_padding-block`, `--_padding-inline-icon` (derived from `--_icon-size`), `--_icon-size`, swapped by the size and variant classes.
+
+## State hooks
+
+- Size class: `.sm`, `.md`, `.lg`. Variant class: `.default`, `.primary`, `.success`, `.warning`,
+  `.danger`, `.neutral`. `.is-reversed` when `reversed`.
+- `data-icon-position`: `start` (icon before the text), `end` (`reversed`), `only` (icon with no
+  label or text), or absent (no icon). It picks which side gets `--display-pill-padding-inline-icon`.
+- Classes: `.display-pill` (root), `.display-pill-icon` (icon slot wrapper, only when used),
+  `.display-pill-label` (only with the `label` prop).
+- `button`/`a` roots get a pointer cursor and a `:focus-visible` outline.
+
+> **Changed 2026-09-27**: `.pill-label` → `.display-pill-label`.
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the
+component need `:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** components that render pills set some of these tokens themselves, so an ancestor value
+won't reach those pills. `ServiceSummary` and `ServiceDetail` set `--display-pill-background`,
+`-text-colour` and `-border-colour` on their pill rows; use their own `--service-*-pill-*` tokens.
+
+## Recipe: outlined pills
+
+```css
+.tag-list {
+  --display-pill-background: transparent;
+  --display-pill-text-colour: currentColor;
+  --display-pill-border-colour: currentColor;
+}
+```
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root. Reachable in normal use.