srcdev-nuxt-components 9.1.49 → 9.1.51

package/app/components/01.atoms/page-row/stories/PageRow.stories.ts

@@ -0,0 +1,311 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import PageRowComponent from "../PageRow.vue";
+
+interface PageRowArgs {
+  tag: string;
+  variant: string;
+  align?: "start" | "end";
+  id?: string;
+  styleClassPassthrough: string[];
+}
+
+export default {
+  title: "Atoms/Layouts/PageRow",
+  component: PageRowComponent,
+  argTypes: {
+    variant: {
+      control: { type: "select" },
+      options: ["full", "popout", "content", "inset-content"],
+      description: "Grid column track the element occupies when nested inside another PageRow",
+      table: { category: "Layout" },
+    },
+    align: {
+      control: { type: "select" },
+      options: [undefined, "start", "end"],
+      description: "Bleeds the element to the viewport edge on one side while keeping the opposite boundary at the variant track. Has no effect on variant=\"full\".",
+      table: { category: "Layout" },
+    },
+    tag: {
+      control: { type: "select" },
+      options: ["div", "section", "article", "header", "footer", "main", "nav"],
+      description: "Semantic HTML element to render as",
+      table: { category: "Semantic" },
+    },
+    id: {
+      control: { type: "text" },
+      description: "id attribute for the element",
+      table: { category: "HTML" },
+    },
+    styleClassPassthrough: {
+      table: { disable: true },
+    },
+  },
+  args: {
+    variant: "content",
+    align: undefined,
+    tag: "div",
+    id: "",
+    styleClassPassthrough: [],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A page layout primitive built on CSS Grid named lines. Each PageRow is both a grid container and a grid item — nest them to compose full-width backgrounds with constrained inner content.",
+      },
+    },
+  },
+} as Meta<PageRowArgs>;
+
+const sampleText =
+  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.";
+
+// ===== SINGLE ROW STORIES =====
+
+const SingleTemplate: StoryFn<PageRowArgs> = (args) => ({
+  components: { PageRowComponent },
+  setup() {
+    return { args, sampleText };
+  },
+  template: `
+    <div style="min-height: 100vh; background: linear-gradient(45deg, #f0f9ff 0%, #e0f2fe 100%);">
+      <PageRowComponent
+        :tag="args.tag"
+        :variant="args.variant"
+        :align="args.align || undefined"
+        :id="args.id || undefined"
+        :style-class-passthrough="args.styleClassPassthrough"
+        :is-landmark="args.isLandmark"
+      >
+        <div style="padding: 24px; background: white; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); margin-block: 20px;">
+          <h2 style="margin: 0 0 12px; color: #374151; font-size: 18px;">variant="{{ args.variant }}"<span v-if="args.align"> align="{{ args.align }}"</span></h2>
+          <p style="margin: 0; color: #6b7280; line-height: 1.6;">{{ sampleText }}</p>
+        </div>
+      </PageRowComponent>
+    </div>
+  `,
+});
+
+export const Default = SingleTemplate.bind({});
+Default.args = {};
+
+export const Full = SingleTemplate.bind({});
+Full.args = { variant: "full" };
+Full.parameters = {
+  docs: { description: { story: "Full track (1fr) — extends edge to edge when nested in another PageRow." } },
+};
+
+export const Popout = SingleTemplate.bind({});
+Popout.args = { variant: "popout" };
+Popout.parameters = {
+  docs: { description: { story: "Popout track (max 1400px) — wider than content, useful for imagery or callouts." } },
+};
+
+export const Content = SingleTemplate.bind({});
+Content.args = { variant: "content" };
+Content.parameters = {
+  docs: { description: { story: "Content track (max 1064px) — optimal reading width. The default variant." } },
+};
+
+export const InsetContent = SingleTemplate.bind({});
+InsetContent.args = { variant: "inset-content" };
+InsetContent.parameters = {
+  docs: { description: { story: "Inset content track (max 840px) — narrower width for focused reading." } },
+};
+
+// ===== NESTING PATTERN =====
+
+const NestingTemplate: StoryFn = () => ({
+  components: { PageRowComponent },
+  setup() {
+    return { sampleText };
+  },
+  template: `
+    <div style="min-height: 100vh;">
+
+      <PageRowComponent tag="section" variant="full" style="background: #1e3a5f; color: white; padding-block: 60px;">
+        <h1 style="margin: 0 0 16px; font-size: 2.4rem;">Full-width background, constrained content</h1>
+        <p style="margin: 0; opacity: 0.85; line-height: 1.7;">{{ sampleText }}</p>
+      </PageRowComponent>
+
+      <PageRowComponent tag="section" style="background: #f0fdf4; padding-block: 48px;">
+        <PageRowComponent variant="content">
+          <h2 style="margin: 0 0 12px; font-size: 1.8rem; color: #166534;">Nested: content inside a content row</h2>
+          <p style="margin: 0; color: #15803d; line-height: 1.7;">{{ sampleText }}</p>
+        </PageRowComponent>
+        <PageRowComponent variant="popout" style="margin-block: 24px; background: #dcfce7; border-radius: 6px; padding: 24px;">
+          <p style="margin: 0; color: #166534;">Popout child breaking out to 1400px</p>
+        </PageRowComponent>
+        <PageRowComponent variant="inset-content">
+          <p style="margin: 0; color: #15803d; font-style: italic; line-height: 1.7;">Inset content (840px) for a focused quote or aside.</p>
+        </PageRowComponent>
+      </PageRowComponent>
+
+    </div>
+  `,
+});
+
+export const NestingPattern = NestingTemplate.bind({});
+NestingPattern.parameters = {
+  docs: {
+    description: {
+      story:
+        "The key composition pattern: nest a full-width outer PageRow (for backgrounds/borders) with inner PageRows at narrower variants. No extra wrapper divs needed.",
+    },
+  },
+};
+
+// ===== WIDTH COMPARISON =====
+
+const ComparisonTemplate: StoryFn = () => ({
+  components: { PageRowComponent },
+  setup() {
+    const tracks = [
+      { variant: "full", label: "full", color: "#ef4444", desc: "1fr — edge to edge" },
+      { variant: "popout", label: "popout", color: "#f97316", desc: "max 1400px" },
+      { variant: "content", label: "content", color: "#eab308", desc: "max 1064px" },
+      { variant: "inset-content", label: "inset-content", color: "#22c55e", desc: "max 840px" },
+    ];
+    return { tracks };
+  },
+  template: `
+    <div style="background: #f8fafc; padding-block: 32px;">
+      <PageRowComponent>
+        <h2 style="margin: 0 0 8px; color: #374151;">Track width comparison</h2>
+        <p style="margin: 0 0 32px; color: #6b7280;">Resize the viewport to see how each track adapts.</p>
+      </PageRowComponent>
+
+      <PageRowComponent v-for="track in tracks" :key="track.variant">
+        <PageRowComponent :variant="track.variant" style="margin-block: 8px;">
+          <div
+            :style="{
+              background: track.color,
+              color: 'white',
+              padding: '16px 20px',
+              borderRadius: '6px',
+              display: 'flex',
+              justifyContent: 'space-between',
+              alignItems: 'center',
+            }"
+          >
+            <strong>{{ track.label }}</strong>
+            <span style="opacity: 0.85; font-size: 0.875rem;">{{ track.desc }}</span>
+          </div>
+        </PageRowComponent>
+      </PageRowComponent>
+    </div>
+  `,
+});
+
+export const WidthComparison = ComparisonTemplate.bind({});
+WidthComparison.parameters = {
+  docs: {
+    description: {
+      story: "Side-by-side comparison of all four main track widths.",
+    },
+  },
+};
+
+// ===== ALIGNMENT =====
+
+const AlignTemplate: StoryFn = () => ({
+  components: { PageRowComponent },
+  setup() {
+    return { sampleText };
+  },
+  template: `
+    <div style="background: #f8fafc; padding-block: 32px; overflow-x: hidden;">
+      <PageRowComponent>
+        <h2 style="margin: 0 0 8px; color: #374151;">align prop — edge bleed</h2>
+        <p style="margin: 0 0 32px; color: #6b7280;">
+          combine <code>variant</code> with <code>align</code> to bleed one side to the viewport edge
+          while keeping the opposite boundary at the track line.
+        </p>
+      </PageRowComponent>
+
+      <PageRowComponent style="margin-block: 8px;">
+        <PageRowComponent variant="content" align="start"
+          style="background: #fde68a; padding: 20px; border-radius: 0 6px 6px 0;">
+          <strong>variant="content" align="start"</strong>
+          <p style="margin: 8px 0 0;">full-start → content-end</p>
+        </PageRowComponent>
+      </PageRowComponent>
+
+      <PageRowComponent style="margin-block: 8px;">
+        <PageRowComponent variant="content" align="end"
+          style="background: #a5f3fc; padding: 20px; border-radius: 6px 0 0 6px;">
+          <strong>variant="content" align="end"</strong>
+          <p style="margin: 8px 0 0;">content-start → full-end</p>
+        </PageRowComponent>
+      </PageRowComponent>
+
+      <PageRowComponent style="margin-block: 8px;">
+        <PageRowComponent variant="popout" align="start"
+          style="background: #bbf7d0; padding: 20px; border-radius: 0 6px 6px 0;">
+          <strong>variant="popout" align="start"</strong>
+          <p style="margin: 8px 0 0;">full-start → popout-end</p>
+        </PageRowComponent>
+      </PageRowComponent>
+
+      <PageRowComponent style="margin-block: 8px;">
+        <PageRowComponent variant="inset-content" align="end"
+          style="background: #e9d5ff; padding: 20px; border-radius: 6px 0 0 6px;">
+          <strong>variant="inset-content" align="end"</strong>
+          <p style="margin: 8px 0 0;">inset-content-start → full-end</p>
+        </PageRowComponent>
+      </PageRowComponent>
+    </div>
+  `,
+});
+
+export const Alignment = AlignTemplate.bind({});
+Alignment.parameters = {
+  docs: {
+    description: {
+      story:
+        "Use align=\"start\" or align=\"end\" to bleed a PageRow to the left or right viewport edge while respecting the variant track boundary on the opposite side. Typical use: asymmetric imagery, pull-quotes, or decorative panels.",
+    },
+  },
+};
+
+// ===== ACCESSIBILITY =====
+
+const A11yTemplate: StoryFn = () => ({
+  components: { PageRowComponent },
+  template: `
+    <div style="display: flex; flex-direction: column; gap: 24px; padding-block: 32px;">
+
+      <PageRowComponent tag="section" style="background: #dbeafe; padding-block: 24px;">
+        <template #default="{ headingId }">
+          <h2 :id="headingId" style="margin: 0 0 8px; color: #1e40af;">Section with aria-labelledby</h2>
+          <p style="margin: 0; color: #3b82f6;">
+            The <code>&lt;section&gt;</code> element receives <code>aria-labelledby</code> automatically,
+            pointing to the heading via the <code>headingId</code> slot prop.
+          </p>
+        </template>
+      </PageRowComponent>
+
+      <PageRowComponent tag="div" style="background: #f3f4f6; padding-block: 24px;">
+        <template #default="{ headingId }">
+          <h2 :id="headingId" style="margin: 0 0 8px; color: #374151;">div — no aria-labelledby</h2>
+          <p style="margin: 0; color: #6b7280;">
+            Non-landmark tags (<code>div</code>, <code>header</code>, <code>footer</code>, <code>nav</code>)
+            do not receive <code>aria-labelledby</code>. The <code>headingId</code> slot prop is still
+            provided but unused.
+          </p>
+        </template>
+      </PageRowComponent>
+
+    </div>
+  `,
+});
+
+export const AriaLabelledBy = A11yTemplate.bind({});
+AriaLabelledBy.parameters = {
+  docs: {
+    description: {
+      story:
+        "section, main, article, and aside receive aria-labelledby automatically. Use the headingId slot prop on the first heading inside the PageRow to complete the association.",
+    },
+  },
+};

package/app/components/01.atoms/page-row/tests/PageRow.spec.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import PageRow from "../PageRow.vue";
+
+const mockElementClasses = { value: "" };
+const mockUseStyleClassPassthrough = vi.fn(() => ({
+  elementClasses: mockElementClasses,
+}));
+
+vi.mock("#imports", () => ({
+  useStyleClassPassthrough: mockUseStyleClassPassthrough,
+}));
+
+describe("PageRow", () => {
+  let wrapper: Awaited<ReturnType<typeof mountSuspended>>;
+
+  const createWrapper = async (props = {}, slots = {}) => {
+    wrapper = await mountSuspended(PageRow, {
+      props: { ...props },
+      slots,
+    });
+    return wrapper;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockElementClasses.value = "";
+  });
+
+  afterEach(() => {
+    wrapper?.unmount();
+  });
+
+  describe("Rendering", () => {
+    it("mounts without error", async () => {
+      await createWrapper();
+      expect(wrapper.find(".page-row").exists()).toBe(true);
+    });
+
+    it("renders as a div by default", async () => {
+      await createWrapper();
+      expect(wrapper.element.tagName.toLowerCase()).toBe("div");
+    });
+
+    it("renders slot content directly inside the root element", async () => {
+      await createWrapper({}, { default: "<p>Hello</p>" });
+      expect(wrapper.find(".page-row p").exists()).toBe(true);
+      expect(wrapper.find(".page-row p").text()).toBe("Hello");
+    });
+
+    it("has no intermediate wrapper elements", async () => {
+      await createWrapper({}, { default: "<span>Content</span>" });
+      const inner = wrapper.find(".page-row span");
+      expect(inner.element.parentElement?.classList.contains("page-row")).toBe(true);
+    });
+  });
+
+  describe("Props — tag", () => {
+    it.each([["section"], ["article"], ["header"], ["footer"], ["main"], ["nav"]] as const)(
+      "renders as <%s>",
+      async (tag) => {
+        await createWrapper({ tag });
+        expect(wrapper.element.tagName.toLowerCase()).toBe(tag);
+      }
+    );
+  });
+
+  describe("Props — variant", () => {
+    it("applies content class by default", async () => {
+      await createWrapper();
+      expect(wrapper.classes()).toContain("content");
+    });
+
+    it.each(["full", "popout", "content", "inset-content"])("applies variant class %s", async (variant) => {
+      await createWrapper({ variant });
+      expect(wrapper.classes()).toContain(variant);
+    });
+  });
+
+  describe("Props — id", () => {
+    it("does not render id attribute by default", async () => {
+      await createWrapper();
+      expect(wrapper.attributes("id")).toBeUndefined();
+    });
+
+    it("renders the id attribute when provided", async () => {
+      await createWrapper({ id: "hero-section" });
+      expect(wrapper.attributes("id")).toBe("hero-section");
+    });
+  });
+
+  describe("Props — styleClassPassthrough", () => {
+    it("forwards string class via elementClasses", async () => {
+      mockElementClasses.value = "custom-class";
+      await createWrapper({ styleClassPassthrough: "custom-class" });
+      expect(wrapper.classes()).toContain("custom-class");
+    });
+
+    it("forwards array classes via elementClasses", async () => {
+      await createWrapper({ styleClassPassthrough: ["class-a", "class-b"] });
+      expect(wrapper.classes()).toContain("class-a");
+      expect(wrapper.classes()).toContain("class-b");
+    });
+  });
+
+  describe("Props — align", () => {
+    it("does not set data-align attribute by default", async () => {
+      await createWrapper();
+      expect(wrapper.attributes("data-align")).toBeUndefined();
+    });
+
+    it("sets data-align=start when align is start", async () => {
+      await createWrapper({ align: "start" });
+      expect(wrapper.attributes("data-align")).toBe("start");
+    });
+
+    it("sets data-align=end when align is end", async () => {
+      await createWrapper({ align: "end" });
+      expect(wrapper.attributes("data-align")).toBe("end");
+    });
+
+    it("combines variant and align on the same element", async () => {
+      await createWrapper({ variant: "content", align: "start" });
+      expect(wrapper.classes()).toContain("content");
+      expect(wrapper.attributes("data-align")).toBe("start");
+    });
+  });
+
+  describe("Accessibility — aria-labelledby", () => {
+    it("does not set aria-labelledby on non-landmark tags", async () => {
+      await createWrapper({ tag: "div" });
+      expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
+    });
+
+    it.each(["section", "main", "article", "aside"] as const)(
+      "sets aria-labelledby on <%s>",
+      async (tag) => {
+        await createWrapper({ tag });
+        expect(wrapper.attributes("aria-labelledby")).toBeTruthy();
+      }
+    );
+
+    it("does not set aria-labelledby on header, footer, nav", async () => {
+      for (const tag of ["header", "footer", "nav"] as const) {
+        await createWrapper({ tag });
+        expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
+        wrapper.unmount();
+      }
+    });
+
+    it("exposes headingId as a slot prop", async () => {
+      let slotHeadingId: string | undefined;
+      await createWrapper(
+        { tag: "section" },
+        {
+          default: (slotProps: { headingId: string }) => {
+            slotHeadingId = slotProps.headingId;
+            return "<h2>Title</h2>";
+          },
+        }
+      );
+      expect(slotHeadingId).toBeTruthy();
+      expect(wrapper.attributes("aria-labelledby")).toBe(slotHeadingId);
+    });
+
+    it("preserves ARIA attributes on slot content", async () => {
+      await createWrapper({}, { default: '<nav aria-label="Main navigation">Nav</nav>' });
+      expect(wrapper.find("nav").attributes("aria-label")).toBe("Main navigation");
+    });
+  });
+
+  describe("CSS classes", () => {
+    it("always includes the page-row base class", async () => {
+      await createWrapper();
+      expect(wrapper.classes()).toContain("page-row");
+    });
+
+    it("includes both base class and variant class", async () => {
+      await createWrapper({ variant: "full" });
+      expect(wrapper.classes()).toContain("page-row");
+      expect(wrapper.classes()).toContain("full");
+    });
+
+    it("includes elementClasses from styleClassPassthrough alongside other classes", async () => {
+      await createWrapper({ variant: "popout", styleClassPassthrough: ["extra-class"] });
+      expect(wrapper.classes()).toContain("page-row");
+      expect(wrapper.classes()).toContain("popout");
+      expect(wrapper.classes()).toContain("extra-class");
+    });
+  });
+});

package/app/components/02.molecules/navigation/tab-navigation/CONSUMER-STYLING.md

@@ -0,0 +1,145 @@
+# TabNavigation — Consumer Styling Guide
+
+## Public token API
+
+All `--tab-nav-*` tokens are the stable override surface. Set them at any scope (global, page, or
+instance) without touching the component itself.
+
+### Horizontal nav
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tab-nav-link-color` | `var(--slate-01, currentColor)` | Link text colour (rest state) |
+| `--tab-nav-link-hover-color` | `var(--slate-04, currentColor)` | Link text colour on hover |
+| `--tab-nav-link-active-color` | `var(--slate-01, currentColor)` | Link text colour when route is active |
+| `--tab-nav-link-size` | `1.6rem` | Link font size |
+| `--tab-nav-link-weight` | `400` | Link font weight |
+| `--tab-nav-link-tracking` | `0.06em` | Link letter spacing |
+| `--tab-nav-gap` | `2.2rem` | Gap between nav items |
+| `--tab-nav-transition` | `250ms ease` | Colour transition on hover/active |
+
+### Indicator decorators
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tab-nav-decorator-indicator-color` | `var(--slate-01, currentColor)` | Active-item underline bar colour |
+| `--tab-nav-decorator-hovered-bg` | `transparent` | Background fill pill that follows the pointer |
+
+### Mobile panel
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tab-nav-panel-bg` | `var(--page-bg, #1a1614)` | Panel background colour |
+| `--tab-nav-panel-border-color` | `color-mix(in oklch, var(--slate-01, #c0847a) 35%, transparent)` | Border between nav bar and open panel |
+| `--tab-nav-panel-item-border` | `color-mix(in oklch, var(--slate-01, white) 8%, transparent)` | Divider between panel items |
+| `--tab-nav-panel-link-color` | `var(--slate-01, currentColor)` | Panel link text colour |
+| `--tab-nav-panel-link-hover-color` | `var(--slate-04, currentColor)` | Panel link text colour on hover |
+| `--tab-nav-panel-link-active-color` | `var(--slate-01, currentColor)` | Panel active link colour |
+| `--tab-nav-panel-padding-block` | `1.4rem` | Panel link vertical padding |
+| `--tab-nav-panel-padding-inline` | `1.5rem` | Panel link horizontal padding |
+| `--tab-nav-panel-slide-duration` | `350ms` | Panel open/close animation duration |
+| `--tab-nav-panel-slide-easing` | `cubic-bezier(0.4, 0, 0.2, 1)` | Panel open/close easing |
+
+### Burger button
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tab-nav-burger-color` | `var(--slate-01, currentColor)` | Burger bar colour |
+| `--tab-nav-burger-width` | `22px` | Width of each burger bar |
+| `--tab-nav-burger-height` | `1.5px` | Height of each burger bar |
+| `--tab-nav-burger-gap` | `5px` | Gap between burger bars |
+| `--tab-nav-burger-transition` | `300ms ease` | Burger open/close animation |
+
+### Backdrop
+
+| Token | Default | Controls |
+|---|---|---|
+| `--tab-nav-backdrop-bg` | `oklch(0% 0 0 / 55%)` | Backdrop overlay background colour |
+| `--tab-nav-backdrop-blur` | `3px` | Backdrop blur amount |
+| `--tab-nav-backdrop-duration` | `350ms` | Backdrop fade duration |
+
+---
+
+## Global theming — app-level CSS file
+
+Create `assets/styles/setup/07.components/tab-navigation.css` in the consuming app and set tokens
+on `:root`. These values apply to every `TabNavigation` instance across the site.
+
+```css
+/* assets/styles/setup/07.components/tab-navigation.css */
+:root {
+  --tab-nav-link-color: var(--brand-text);
+  --tab-nav-link-hover-color: var(--brand-text-muted);
+  --tab-nav-link-active-color: var(--brand-accent);
+  --tab-nav-decorator-indicator-color: var(--brand-accent);
+  --tab-nav-decorator-hovered-bg: oklch(from var(--brand-accent) l c h / 0.1);
+  --tab-nav-gap: 3rem;
+}
+```
+
+---
+
+## Page-scoped overrides
+
+Override tokens for a single page by scoping them under a page wrapper. No `:deep()` is required
+(component styles are unscoped).
+
+```css
+/* In the consuming page's unscoped <style> block */
+.about-page {
+  .tab-navigation {
+    --tab-nav-link-color: var(--brand-warm-text);
+    --tab-nav-decorator-indicator-color: var(--brand-warm-accent);
+    --tab-nav-gap: 4rem;
+  }
+}
+```
+
+---
+
+## Per-instance overrides via inline style
+
+```vue
+<TabNavigation
+  :nav-item-data="navData"
+  style="
+    --tab-nav-decorator-indicator-color: oklch(65% 0.2 230);
+    --tab-nav-link-active-color: oklch(65% 0.2 230);
+    --tab-nav-gap: 3rem;
+  "
+/>
+```
+
+---
+
+## Per-instance overrides via styleClassPassthrough
+
+```vue
+<TabNavigation :nav-item-data="navData" :style-class-passthrough="['brand-nav']" />
+```
+
+```css
+.tab-navigation.brand-nav {
+  --tab-nav-decorator-indicator-color: var(--brand-accent);
+  --tab-nav-decorator-hovered-bg: oklch(from var(--brand-accent) l c h / 0.1);
+  --tab-nav-link-active-color: var(--brand-accent);
+  --tab-nav-link-size: 1.4rem;
+  --tab-nav-link-tracking: 0.08em;
+}
+```
+
+---
+
+## Notes
+
+- The active underline indicator and hover pill use CSS Anchor Positioning. They animate via
+  `left`/`right` transitions, so `transition` on `.nav__active-indicator` and `.nav__hovered` is
+  handled internally — only set `--tab-nav-transition` to control the link colour fade.
+- `--tab-nav-decorator-hovered-bg: transparent` (the default) hides the hover pill entirely; set
+  a semi-transparent colour to enable it.
+- Panel and burger tokens only take visual effect when the nav has collapsed to the burger state
+  (i.e. when the nav list overflows its container).
+- `--tab-nav-panel-bg` should match `--page-bg` so the panel blends with the page background in
+  the collapsed state.
+- The backdrop (`--tab-nav-backdrop-*`) appears behind the open panel and above page content at
+  `z-index: 10`. It teleports to `<body>` so it is unaffected by parent stacking contexts.