srcdev-nuxt-components 9.6.4 → 9.6.6

package/app/components/02.molecules/progress-tracker/tests/__snapshots__/ProgressTracker.spec.ts.snap

@@ -0,0 +1,46 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ProgressTracker > renders correct HTML structure 1`] = `
+"<div class="progress-tracker">
+  <div class="progress-tracker-header">
+    <p class="progress-tracker-label" aria-live="polite" tabindex="-1">Step 2 of 3</p>
+    <div class="progress-tracker-bar" role="progressbar" aria-valuemin="0" aria-valuemax="3" aria-valuenow="1" aria-valuetext="Step 2 of 3" style="--_progress-tracker-progress: 0.3333333333333333;"><span class="progress-tracker-bar-fill"></span></div>
+  </div>
+  <ol role="list" class="stepper-list has-connectors progress-tracker-list">
+    <li class="stepper-list-item has-indicator indicator-top indicator-disc" style="--_connector-left: 0px; --_connector-top: 0px; --_connector-height: 0px;">
+      <div class="stepper-list__indicator-custom"><span class="progress-tracker-indicator is-done" aria-hidden="true"><span class="iconify i-lucide:check progress-tracker-indicator-icon" aria-hidden="true"></span></span></div>
+      <div class="stepper-list-content">
+        <div class="progress-tracker-step is-done">
+          <h3 id="v-0-0-step-0" class="progress-tracker-title" tabindex="-1">Create your account<span class="sr-only">, Completed</span></h3>
+          <p class="progress-tracker-body">Enter your email and choose a password.</p>
+          <!--v-if-->
+        </div>
+      </div>
+    </li>
+    <li class="stepper-list-item has-indicator indicator-top indicator-disc" style="--_connector-left: 0px; --_connector-top: 0px; --_connector-height: 0px;">
+      <div class="stepper-list__indicator-custom"><span class="progress-tracker-indicator is-current" aria-hidden="true">2</span></div>
+      <div class="stepper-list-content">
+        <div class="progress-tracker-step is-current">
+          <h3 id="v-0-0-step-1" class="progress-tracker-title" tabindex="-1" aria-current="step">Verify your email
+            <!--v-if-->
+          </h3>
+          <p class="progress-tracker-body">Click the link we sent to your inbox.</p>
+          <!--v-if-->
+        </div>
+      </div>
+    </li>
+    <li class="stepper-list-item has-indicator indicator-top indicator-disc">
+      <div class="stepper-list__indicator-custom"><span class="progress-tracker-indicator is-upcoming" aria-hidden="true">3</span></div>
+      <div class="stepper-list-content">
+        <div class="progress-tracker-step is-upcoming">
+          <h3 id="v-0-0-step-2" class="progress-tracker-title" tabindex="-1">Choose a plan
+            <!--v-if-->
+          </h3>
+          <!--v-if-->
+          <!--v-if-->
+        </div>
+      </div>
+    </li>
+  </ol>
+</div>"
+`;

package/app/components/02.molecules/social-icons-list/CONSUMER-STYLING.md

@@ -2,18 +2,68 @@
 
 ## Public token API
 
+### List
+
+| Token | Default | Controls |
+|---|---|---|
+| `--social-icons-list-gap` | `1.2rem` | Gap between items |
+
+### Link (the tile)
+
 | Token | Default | Controls |
 |---|---|---|
-| `--social-icons-list-icon-size` | `2.4rem` | Icon size (applied as `font-size`) |
-| `--social-icons-list-gap` | `1.2rem` | Gap between icons |
-| `--social-icons-list-icon-colour` | `currentColor` | Colour of mono icons (sets that draw in `currentColor`, e.g. `mdi:instagram`). No effect on `logos:` icons, whose colours are fixed in the SVG |
+| `--social-icons-list-link-padding` | `0` | Padding inside each link: set it to turn links into tiles or pills |
+| `--social-icons-list-link-gap` | `0.8rem` | Gap between the icon and the visible label |
+| `--social-icons-list-link-border` | `none` | Border shorthand |
+| `--social-icons-list-link-radius` | `0` | Corner radius (the focus outline follows it) |
+| `--social-icons-list-link-background` | `transparent` | Background |
+| `--social-icons-list-link-background-hover` | the resting background | Background on hover/focus |
+| `--social-icons-list-link-shadow` | `none` | Box shadow |
+| `--social-icons-list-link-shadow-hover` | the resting shadow | Box shadow on hover/focus (a glow) |
 | `--social-icons-list-hover-scale` | `1.15` | Scale on hover/focus (no scaling under `prefers-reduced-motion: reduce`) |
 | `--social-icons-list-hover-opacity` | `0.85` | Opacity on hover/focus |
+| `--social-icons-list-focus-ring-colour` | `var(--theme-ring, currentColor)` | Keyboard focus outline colour |
+
+### Icon
 
-The focus outline uses `--theme-ring`, falling back to `currentColor`. `logos:` icons carry their own brand colours. Some are dark (`logos:instagram-icon`, `logos:x`,
-`logos:github-icon`) and vanish on a dark background: use a mono icon there (`mdi:instagram`,
-`bi:instagram`, ...) and colour it with `--social-icons-list-icon-colour`.
+| Token | Default | Controls |
+|---|---|---|
+| `--social-icons-list-icon-size` | `2.4rem` | Icon size (a `font-size` on the icon wrapper) |
+| `--social-icons-list-icon-colour` | `currentColor` | Colour of mono icons (sets that draw in `currentColor`, e.g. `bi:instagram`). No effect on `logos:` icons, whose colours are fixed in the SVG |
+| `--social-icons-list-icon-colour-hover` | the resting icon colour | Mono icon colour on hover/focus |
+| `--social-icons-list-icon-wrapper-padding` | `0` | Padding around the icon's fixed `1em` square: uniform padding with a background and `50%` radius gives a circle, whatever the `icon` slot holds |
+| `--social-icons-list-icon-wrapper-border` | `none` | Border shorthand around the icon |
+| `--social-icons-list-icon-wrapper-radius` | `0` | Corner radius of the icon wrapper |
+| `--social-icons-list-icon-wrapper-background` | `transparent` | Background behind the icon |
+
+### Label (`show-label` or the `label` slot)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--social-icons-list-label-colour` | `currentColor` | Label text colour (set on the link) |
+| `--social-icons-list-label-font-size` | `var(--step-4, 1.6rem)` | Label font size |
+| `--social-icons-list-label-font-weight` | `600` | Label font weight |
 
+### Brand colour (data, not a default)
+
+`--social-icons-list-brand-colour` is set inline on each `.social-icons-list-item` from that item's
+`brandColour`. The component doesn't use it; it's there so your tokens can (hover colour, glow,
+circle fill). See the caveat under Local overrides.
+
+`logos:` icons carry their own brand colours. Some are dark (`logos:instagram-icon`, `logos:x`,
+`logos:github-icon`) and vanish on a dark background: use a mono icon there (`bi:instagram`,
+`mdi:instagram`, ...) and colour it with `--social-icons-list-icon-colour`.
+
+> Changed 2026-10-16: the inner classes were renamed so they can't collide with a site's own
+> `.social-icon` styles: `.social-icon-item` is now `.social-icons-list-item`, `.social-icon-link` is
+> `.social-icons-list-link` and `.social-icon` is `.social-icons-list-icon`. Update any selector that
+> used the old names. The icon now sits in a `.social-icons-list-icon-wrapper` span, which carries
+> the icon size (so a missing icon still leaves a focus target). New: the link, icon wrapper and
+> label tokens above, `--social-icons-list-focus-ring-colour` (the outline read `--theme-ring`
+> directly), and per-item `--social-icons-list-brand-colour`. Items whose href isn't http(s),
+> mailto, tel or site-relative are skipped. The focus outline's fixed `2px` radius is now
+> `--social-icons-list-link-radius` (default `0`).
+>
 > Changed 2026-10-14: new `--social-icons-list-icon-colour` token for mono icons.
 >
 > Changed 2026-09-28: `--theme-social-icon-size` and `--theme-social-icon-gap` were renamed to
@@ -27,8 +77,10 @@ No private `--_` tokens.
 
 ## State hooks
 
-Inner classes: `.social-icon-item` (each `<li>`), `.social-icon-link` (the `<a>`, opens in a new
-tab), `.social-icon` (the icon, `aria-hidden`).
+Inner classes: `.social-icons-list-item` (each `<li>`, carries `--social-icons-list-brand-colour`),
+`.social-icons-list-link` (the `<a>`, opens in a new tab), `.social-icons-list-icon-wrapper` (the
+`aria-hidden` span around the icon or the `icon` slot), `.social-icons-list-icon` (the default
+icon), `.social-icons-list-label` (visible text, only with `show-label` or the `label` slot).
 
 ---
 
@@ -40,6 +92,43 @@ 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`.
 
+**Caveat:** a token whose value reads `--social-icons-list-brand-colour` must be set on
+`.social-icons-list-item` (or deeper), not on the list or an ancestor. A `var()` inside a custom
+property resolves on the element that declares it, and the brand colour only exists on each item,
+so set on the root it finds nothing and falls back to the default.
+
+```css
+.my-section .social-icons-list-item {
+  --social-icons-list-icon-colour-hover: var(--social-icons-list-brand-colour);
+}
+```
+
+---
+
+## Recipes
+
+Four looks built only from the tokens above and consumer CSS, each on a class passed through
+`style-class-passthrough`. The full CSS is in `stories/social-icons-list-recipes.css` next to the
+component, and each has a Storybook story (`Recipe: …`). All use mono `bi:` icons plus a
+`brandColour` per item.
+
+- **Mono tiles, brand colour on hover**: tile tokens (`link-padding`, `-radius`, `-background`,
+  `-background-hover`), then `--social-icons-list-icon-colour-hover: var(--social-icons-list-brand-colour)`
+  on `.social-icons-list-item`.
+- **Dark dock with glow**: the dock is the list root (padding, border, radius and
+  `inline-size: fit-content` on your class), dark tiles inside, and
+  `--social-icons-list-link-shadow-hover` mixed from the brand colour on `.social-icons-list-item`.
+  Black brand colours (X, TikTok) don't show on a dark dock: give those items a light or accent
+  `brandColour` there.
+- **Labelled pills**: `show-label`, a pill link (`link-padding`, `-border`, `99rem` radius), and the
+  icon wrapper as a brand-coloured circle (`icon-wrapper-padding`, `50%` radius,
+  `icon-wrapper-background` from the brand colour on the item).
+- **Overlapping stack**: circles from the icon wrapper tokens, a negative `margin-inline-start` on
+  every `.social-icons-list-item + .social-icons-list-item`, reset on the list's `:hover` and
+  `:focus-within` so keyboard users get the fan-out too. Put the transition inside
+  `@media (prefers-reduced-motion: no-preference)`. A "Follow us" caption is your own text beside
+  the component.
+
 ---
 
 ## Class passthrough

package/app/components/02.molecules/social-icons-list/SocialIconsList.vue

@@ -1,35 +1,64 @@
 <template>
-  <ul class="social-icons-list" :class="[elementClasses]" :aria-label="label">
-    <li v-for="item in items" :key="item.networkName" class="social-icon-item">
+  <ul class="social-icons-list" :class="[elementClasses]" role="list" :aria-label="label">
+    <li v-for="entry in entries" :key="entry.key" class="social-icons-list-item" :style="brandStyle(entry.item)">
       <a
-        :href="`${item.baseHref}${item.profileId}`"
-        class="social-icon-link"
-        :aria-label="linkLabel(item)"
+        :href="entry.href"
+        class="social-icons-list-link"
+        :aria-label="linkLabel(entry.item)"
         rel="noopener noreferrer"
         target="_blank"
       >
-        <Icon :name="item.iconName" class="social-icon" aria-hidden="true" />
+        <span class="social-icons-list-icon-wrapper" aria-hidden="true">
+          <slot name="icon" :item="entry.item">
+            <Icon :name="entry.item.iconName" class="social-icons-list-icon" />
+          </slot>
+        </span>
+        <span v-if="hasLabel()" class="social-icons-list-label">
+          <slot name="label" :item="entry.item">{{ entry.item.networkName }}</slot>
+        </span>
       </a>
     </li>
   </ul>
 </template>
 
 <script setup lang="ts">
-import type { ISocialIcon } from "~/types/components/social-icons-list.d";
+import type { ISocialIcon, SocialIconsListSlots } from "~/types/components/social-icons-list.d";
 
 interface Props {
   items: ISocialIcon[];
   label?: string;
   linkLabelTemplate?: string;
+  showLabel?: boolean;
   styleClassPassthrough?: string | string[];
 }
 
 const props = withDefaults(defineProps<Props>(), {
   label: "Social media profiles",
   linkLabelTemplate: "{network} profile (opens in a new tab)",
+  showLabel: false,
   styleClassPassthrough: () => [],
 });
 
+const slots = defineSlots<SocialIconsListSlots>();
+
+const SAFE_HREF = /^(https?:|mailto:|tel:|\/(?!\/))/i;
+
+const entries = computed(() =>
+  props.items.flatMap((item, index) => {
+    const href = `${item.baseHref}${item.profileId}`.trim();
+    if (!SAFE_HREF.test(href)) {
+      if (import.meta.dev) console.warn(`[SocialIconsList] Skipped "${item.networkName}": unsafe href "${href}".`);
+      return [];
+    }
+    return [{ item, href, key: `${index}-${item.networkName}` }];
+  })
+);
+
+const hasLabel = () => props.showLabel || !!slots.label;
+
+const brandStyle = (item: ISocialIcon) =>
+  item.brandColour ? { "--social-icons-list-brand-colour": item.brandColour } : undefined;
+
 const linkLabel = (item: ISocialIcon) => item.label ?? props.linkLabelTemplate.replace("{network}", item.networkName);
 
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
@@ -52,37 +81,74 @@ watch(
     padding: 0;
     margin: 0;
 
-    .social-icon-item {
+    .social-icons-list-item {
       display: flex;
+      min-inline-size: 0;
 
-      .social-icon-link {
+      .social-icons-list-link {
         display: flex;
         align-items: center;
-        justify-content: center;
+        gap: var(--social-icons-list-link-gap, 0.8rem);
+        min-inline-size: 0;
+        padding: var(--social-icons-list-link-padding, 0);
+        border: var(--social-icons-list-link-border, none);
+        border-radius: var(--social-icons-list-link-radius, 0);
+        background: var(--social-icons-list-link-background, transparent);
+        box-shadow: var(--social-icons-list-link-shadow, none);
+        color: var(--social-icons-list-label-colour, currentColor);
         text-decoration: none;
         transition:
           transform 200ms ease,
-          opacity 200ms ease;
+          opacity 200ms ease,
+          background-color 200ms ease,
+          box-shadow 200ms ease;
 
         &:hover,
         &:focus-visible {
           transform: scale(var(--social-icons-list-hover-scale, 1.15));
           opacity: var(--social-icons-list-hover-opacity, 0.85);
+          background: var(--social-icons-list-link-background-hover, var(--social-icons-list-link-background, transparent));
+          box-shadow: var(--social-icons-list-link-shadow-hover, var(--social-icons-list-link-shadow, none));
 
           @media (prefers-reduced-motion: reduce) {
             transform: none;
           }
+
+          .social-icons-list-icon {
+            color: var(--social-icons-list-icon-colour-hover, var(--social-icons-list-icon-colour, currentColor));
+          }
         }
 
         &:focus-visible {
-          outline: 2px solid var(--theme-ring, currentColor);
+          outline: 2px solid var(--social-icons-list-focus-ring-colour, var(--theme-ring, currentColor));
           outline-offset: 3px;
-          border-radius: 2px;
         }
 
-        .social-icon {
+        .social-icons-list-icon-wrapper {
+          display: flex;
+          flex-shrink: 0;
+          align-items: center;
+          justify-content: center;
+          box-sizing: content-box;
+          inline-size: 1em;
+          block-size: 1em;
+          padding: var(--social-icons-list-icon-wrapper-padding, 0);
+          border: var(--social-icons-list-icon-wrapper-border, none);
+          border-radius: var(--social-icons-list-icon-wrapper-radius, 0);
+          background: var(--social-icons-list-icon-wrapper-background, transparent);
           font-size: var(--social-icons-list-icon-size, 2.4rem);
+        }
+
+        .social-icons-list-icon {
           color: var(--social-icons-list-icon-colour, currentColor);
+          transition: color 200ms ease;
+        }
+
+        .social-icons-list-label {
+          min-inline-size: 0;
+          overflow-wrap: anywhere;
+          font-size: var(--social-icons-list-label-font-size, var(--step-4, 1.6rem));
+          font-weight: var(--social-icons-list-label-font-weight, 600);
         }
       }
     }

package/app/components/02.molecules/social-icons-list/stories/SocialIconsList.stories.ts

@@ -1,6 +1,10 @@
+import { ref } from "vue";
 import SocialIconsList from "../SocialIconsList.vue";
+import CanvasSwitcher from "../../../01.atoms/canvas-switcher/CanvasSwitcher.vue";
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
 import type { ISocialIcon } from "~/types/components/social-icons-list.d";
+import type { MediaCanvas } from "~/types/components";
+import "./social-icons-list-recipes.css";
 
 const sampleItems: ISocialIcon[] = [
   {
@@ -42,7 +46,7 @@ const meta: Meta<typeof SocialIconsList> = {
     items: {
       control: "object",
       description:
-        "Array of social network items. Each item requires networkName, iconName (Iconify logos: collection), baseHref, and profileId.",
+        "Array of social network items. Each item needs networkName, iconName (any Iconify icon), baseHref and profileId; the link is baseHref + profileId. Items whose href isn't http(s), mailto, tel or site-relative are skipped.",
     },
     label: {
       control: "text",
@@ -52,6 +56,10 @@ const meta: Meta<typeof SocialIconsList> = {
       control: "text",
       description: "aria-label for each link; {network} is replaced with the item's networkName",
     },
+    showLabel: {
+      control: "boolean",
+      description: "Show each item's networkName as visible text after the icon (or fill the `label` slot)",
+    },
     styleClassPassthrough: {
       control: "object",
       description: "Additional CSS classes applied to the root element",
@@ -61,8 +69,18 @@ const meta: Meta<typeof SocialIconsList> = {
     items: sampleItems,
     label: "Social media profiles",
     linkLabelTemplate: "{network} profile (opens in a new tab)",
+    showLabel: false,
     styleClassPassthrough: ["m-40"],
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A wrapping row of icon links to social profiles, built from the `items` array (`ISocialIcon`: `networkName`, `iconName`, `baseHref`, `profileId`, optional `label`). " +
+          "Links open in a new tab and are named from `linkLabelTemplate` or each item's `label`; `label` names the list; `showLabel` (or the scoped `label` slot) adds visible text, and the scoped `icon` slot replaces the icon. An item's optional `brandColour` is exposed as `--social-icons-list-brand-colour` for recipes. Size, tiles, hover and focus come from `--social-icons-list-*` tokens; the Recipe stories show four alternative looks built only from tokens and consumer CSS.",
+      },
+    },
+  },
 };
 
 export default meta;
@@ -91,6 +109,9 @@ export const LargeIcons: Story = {
     },
     template: `<SocialIconsList v-bind="args" style="--social-icons-list-icon-size: 4rem;" />`,
   }),
+  parameters: {
+    docs: { description: { story: "`--social-icons-list-icon-size: 4rem` set on the component." } },
+  },
 };
 
 /** Single network — only one item in the list. */
@@ -102,7 +123,7 @@ export const SingleNetwork: Story = {
         networkName: "Instagram",
         iconName: "logos:instagram-icon",
         baseHref: "https://www.instagram.com/",
-        profileId: "luxurylocs",
+        profileId: "yourprofile",
       },
     ],
   },
@@ -114,3 +135,210 @@ export const SingleNetwork: Story = {
     template: `<SocialIconsList v-bind="args" />`,
   }),
 };
+
+const stressItems: ISocialIcon[] = [
+  ...sampleItems,
+  { networkName: "Instagram", iconName: "logos:instagram-icon", baseHref: "https://www.instagram.com/", profileId: "second-account" },
+  {
+    networkName: "LinkedIn",
+    iconName: "logos:linkedin-icon",
+    baseHref: "https://www.linkedin.com/in/",
+    profileId: "a-very-long-profile-identifier-without-any-spaces-at-all-in-it-1234567890",
+  },
+  { networkName: "Pinterest", iconName: "logos:pinterest", baseHref: "https://www.pinterest.com/", profileId: "" },
+  { networkName: "Unknown icon", iconName: "logos:this-icon-does-not-exist", baseHref: "https://example.com/", profileId: "x" },
+  { networkName: "<script>alert('xss')</script>", iconName: "mdi:web", baseHref: "https://example.com/", profileId: "html" },
+  { networkName: "إنستغرام", iconName: "mdi:instagram", baseHref: "https://www.instagram.com/", profileId: "rtl", label: "ملفنا على إنستغرام" },
+  { networkName: "Unsafe", iconName: "mdi:alert", baseHref: "javascript:", profileId: "alert(1)" },
+  { networkName: "Email", iconName: "mdi:email", baseHref: "mailto:", profileId: "hello@example.com" },
+  { networkName: "Phone", iconName: "mdi:phone", baseHref: "tel:", profileId: "+441234567890" },
+  ...Array.from({ length: 10 }, (_, i) => ({
+    networkName: `Network ${i + 1}`,
+    iconName: "mdi:web",
+    baseHref: "https://example.com/",
+    profileId: `profile-${i + 1}`,
+  })),
+];
+
+/**
+ * Stress test — duplicate networks, unbroken and empty profile IDs, a missing icon, HTML-like and
+ * right-to-left names, an unsafe href and twenty-plus items, inside the CanvasSwitcher.
+ */
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  args: {
+    items: stressItems,
+    label: "Datenschutzfreundliche Profile in sozialen Netzwerken unseres Unternehmens",
+    linkLabelTemplate: "Unser {network}-Profil (öffnet sich in einem neuen Tab)",
+    styleClassPassthrough: [],
+  },
+  decorators: [
+    (story, context) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>(context.parameters.initialCanvas ?? "mobileCanvas");
+        return { canvasName };
+      },
+      template: `
+        <div style="padding: 1.2rem 1.6rem; border-block-end: 1px solid currentColor;">
+          <CanvasSwitcher v-model:canvas-name="canvasName" />
+        </div>
+        <div :class="canvasName" style="margin-inline: auto; padding: 2rem; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
+  render: (args) => ({
+    components: { SocialIconsList },
+    setup() {
+      return { args };
+    },
+    template: `<SocialIconsList v-bind="args" />`,
+  }),
+  parameters: {
+    initialCanvas: "mobileCanvas",
+    docs: {
+      description: {
+        story:
+          "Check at every canvas width: the row wraps and never overflows the dashed box. Both Instagram accounts render (they used to share a `:key`). " +
+          "The `javascript:` item is skipped, so there's no 'Unsafe' link; mailto and tel links stay. The unknown icon still leaves a 1em focus target; tab through to check the focus ring on every link. " +
+          "Inspect the links for the German template, the Arabic `label` override, and the HTML-like name rendered as plain text in its `aria-label`.",
+      },
+    },
+  },
+};
+
+// ─── Recipes ─────────────────────────────────────────────────────────────────
+// Each look is tokens plus consumer CSS on a passthrough class: see social-icons-list-recipes.css
+// and the Recipes section of CONSUMER-STYLING.md.
+
+const brandItems: ISocialIcon[] = [
+  { networkName: "Facebook", iconName: "bi:facebook", baseHref: "https://www.facebook.com/", profileId: "yourprofile", brandColour: "#1877f2" },
+  { networkName: "X", iconName: "bi:twitter-x", baseHref: "https://x.com/", profileId: "yourhandle", brandColour: "#000000" },
+  { networkName: "Instagram", iconName: "bi:instagram", baseHref: "https://www.instagram.com/", profileId: "yourprofile", brandColour: "#e1306c" },
+  { networkName: "YouTube", iconName: "bi:youtube", baseHref: "https://www.youtube.com/@", profileId: "yourchannel", brandColour: "#ff0000" },
+  { networkName: "TikTok", iconName: "bi:tiktok", baseHref: "https://www.tiktok.com/@", profileId: "yourprofile", brandColour: "#000000" },
+];
+
+// Black brand colours vanish on a dark dock, so X and TikTok glow in their light/accent colours there.
+const darkBrandItems: ISocialIcon[] = brandItems.map((item) =>
+  item.networkName === "X"
+    ? { ...item, brandColour: "#ffffff" }
+    : item.networkName === "TikTok"
+      ? { ...item, brandColour: "#25f4ee" }
+      : item
+);
+
+const recipeStory = (panelStyle: string, before = ""): Story["render"] => (args) => ({
+  components: { SocialIconsList },
+  setup() {
+    return { args, panelStyle };
+  },
+  template: `
+    <div :style="'display: flex; align-items: center; justify-content: center; gap: 1.6rem; flex-wrap: wrap; min-block-size: 24rem; padding: 4rem 2.4rem; border-radius: 2.4rem; font-family: sans-serif; ' + panelStyle">
+      ${before}
+      <SocialIconsList v-bind="args" />
+    </div>
+  `,
+});
+
+/** Mono icons on soft tiles; each icon takes its item's brandColour on hover or keyboard focus. */
+export const RecipeMonoTiles: Story = {
+  name: "Recipe: Mono Tiles",
+  args: { items: brandItems, styleClassPassthrough: ["demo-social-mono-tiles"] },
+  render: recipeStory("background: #ffffff;"),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Mono `bi:` icons, tile tokens (`--social-icons-list-link-padding`, `-radius`, `-background`, `-background-hover`) and " +
+          "`--social-icons-list-icon-colour-hover: var(--social-icons-list-brand-colour)` set on `.social-icons-list-item`.",
+      },
+    },
+  },
+};
+
+/** A dark dock around dark tiles; the hovered or focused tile glows in its brand colour. */
+export const RecipeDarkDock: Story = {
+  name: "Recipe: Dark Dock with Glow",
+  args: { items: darkBrandItems, styleClassPassthrough: ["demo-social-dark-dock"] },
+  render: recipeStory("background: #16171b;"),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The dock is the list root itself (padding, border, radius and `inline-size: fit-content` on the passthrough class). The glow is " +
+          "`--social-icons-list-link-shadow-hover` built from the brand colour with `color-mix()`. X and TikTok use white and cyan here, since black wouldn't show.",
+      },
+    },
+  },
+};
+
+/** Visible labels with the icon in a brand-coloured circle. */
+export const RecipeLabelledPills: Story = {
+  name: "Recipe: Labelled Pills",
+  args: { items: brandItems, showLabel: true, styleClassPassthrough: ["demo-social-pills"] },
+  render: recipeStory("background: #f5f4f0;"),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`show-label` adds each `networkName` as visible text; the circle is the icon wrapper (`--social-icons-list-icon-wrapper-padding`, `-radius`, " +
+          "and `-background` from the brand colour). The links keep their `aria-label`, which contains the visible name (WCAG 2.5.3).",
+      },
+    },
+  },
+};
+
+/** Overlapping circles that fan out when the row is hovered or a link has keyboard focus. */
+export const RecipeOverlappingStack: Story = {
+  name: "Recipe: Overlapping Stack",
+  args: { items: brandItems, styleClassPassthrough: ["demo-social-stack"] },
+  render: recipeStory(
+    "background: #ffffff;",
+    `<span style="font-size: 1.6rem; font-weight: 600; color: #4a4b52;">Follow us</span>`
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Negative `margin-inline-start` on every item after the first, reset on `:hover`/`:focus-within` of the list, so keyboard users get the fan-out too " +
+          "(no transition under reduced motion). \"Follow us\" is the consumer's own text beside the component, not part of it.",
+      },
+    },
+  },
+};
+
+/** The scoped `icon` and `label` slots: custom markup per item. */
+export const CustomSlots: Story = {
+  name: "Custom Slots",
+  args: { items: brandItems, styleClassPassthrough: ["demo-social-pills"] },
+  render: (args) => ({
+    components: { SocialIconsList },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="padding: 4rem 2.4rem; border-radius: 2.4rem; background: #f5f4f0; font-family: sans-serif;">
+        <SocialIconsList v-bind="args">
+          <template #icon="{ item }">
+            <span style="font-size: 0.8em; font-weight: 700; color: #ffffff; line-height: 1;">{{ Array.from(item.networkName)[0] }}</span>
+          </template>
+          <template #label="{ item }">
+            {{ item.networkName }} <small style="font-weight: 400;">@{{ item.profileId }}</small>
+          </template>
+        </SocialIconsList>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "The `icon` slot replaces the icon inside the wrapper (here the network's first letter), and the `label` slot replaces the visible text " +
+          "(filling it shows the label without `show-label`). Both receive `{ item }`. Slot content sits inside the link, so keep it non-interactive.",
+      },
+    },
+  },
+};