srcdev-nuxt-components 9.5.2 → 9.5.4

package/app/assets/styles/setup/03.theming/_theme-slots.css

@@ -1,21 +1,18 @@
 /* Theme semantic slots — 8 shared colour roles used by all themed components.
    Declared on the same selector as theme-ramp.css so the formula re-evaluates
-   per [data-theme] element rather than being inherited from html. */
+   per [data-theme] element rather than being inherited from html.
+   Light values only, no light-dark(): dark mode is the consumer app's call. */
 :where(html, [data-theme], [data-invalid]) {
-  --theme-surface: light-dark(var(--colour-theme-7), var(--colour-theme-9));
-  --theme-surface-inverted: light-dark(var(--colour-theme-9), var(--colour-theme-2));
-  --theme-surface-hover: light-dark(var(--colour-theme-9), var(--colour-theme-7));
-  --theme-accent: light-dark(var(--colour-theme-5), var(--colour-theme-4));
-  --theme-surface-subtle: light-dark(var(--colour-theme-1), var(--colour-theme-9));
-  --theme-border: light-dark(var(--colour-theme-6), var(--colour-theme-5));
-  --theme-border-focus: light-dark(var(--colour-theme-4), var(--colour-theme-3));
-  --theme-ring: light-dark(var(--colour-theme-1), var(--colour-theme-9));
+  --theme-surface: var(--colour-theme-7);
+  --theme-surface-inverted: var(--colour-theme-9);
+  --theme-surface-hover: var(--colour-theme-9);
+  --theme-accent: var(--colour-theme-5);
+  --theme-surface-subtle: var(--colour-theme-1);
+  --theme-border: var(--colour-theme-6);
+  --theme-border-focus: var(--colour-theme-4);
+  --theme-ring: var(--colour-theme-1);
   --theme-on-surface: var(--colour-theme-0);
-  --theme-text: light-dark(var(--colour-theme-9), var(--colour-theme-2));
-  /* Light-mode branch was --colour-theme-9 — identical to --theme-surface-inverted's own
-     light-mode branch (line 6), its only pairing (InputButton's .secondary, background +
-     color), so secondary-button text was invisible (dark-on-dark) in light mode. Should be a
-     light step to contrast against that dark inverted surface, matching how --theme-on-surface
-     (line 13) contrasts against --theme-surface the same way in both modes. */
-  --theme-text-inverted: light-dark(var(--colour-theme-0), var(--colour-theme-7));
+  --theme-text: var(--colour-theme-9);
+  /* Light step: pairs with the dark --theme-surface-inverted (InputButton .secondary). */
+  --theme-text-inverted: var(--colour-theme-0);
 }

package/app/assets/styles/setup/a11y/_variables.css

@@ -1,8 +1,8 @@
 :where(html) {
   --focus-box-shadow-colour-off: transparent;
-  --focus-box-shadow-colour-on: light-dark(var(--blue-10), var(--slate-00));
+  --focus-box-shadow-colour-on: var(--blue-10);
   --form-focus-box-shadow: 0 0 0 0.3rem;
 
   --box-shadow-off: 0 0 0 0.3rem transparent;
-  --box-shadow-on: 0 0 0 0.3rem light-dark(var(--blue-10), var(--slate-00));
+  --box-shadow-on: 0 0 0 0.3rem var(--blue-10);
 }

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

@@ -1,5 +1,8 @@
 import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { ref } from "vue";
 import PageRowComponent from "../PageRow.vue";
+import CanvasSwitcher from "../../canvas-switcher/CanvasSwitcher.vue";
+import type { MediaCanvas } from "~/types/components";
 
 interface PageRowArgs {
   tag: string;
@@ -47,7 +50,27 @@ export default {
     id: "",
     styleClassPassthrough: [],
   },
+  decorators: [
+    // PageRow sizes its tracks from 100% of its container, so a constrained wrapper stands in for a narrower viewport.
+    (story) => ({
+      components: { story, CanvasSwitcher },
+      setup() {
+        const canvasName = ref<MediaCanvas>("fullWidthCanvas");
+        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; outline: 1px dashed currentColor;">
+          <story />
+        </div>
+      `,
+    }),
+  ],
   parameters: {
+    // Storybook's default padded layout hides the viewport gutter and align edge-bleed.
+    layout: "fullscreen",
     docs: {
       description: {
         component:
@@ -118,26 +141,37 @@ InsetContent.parameters = {
 const NestingTemplate: StoryFn = () => ({
   components: { PageRowComponent },
   setup() {
-    return { sampleText };
+    const nested = [
+      { variant: "full", background: "#fca5a5", desc: "edge to edge" },
+      { variant: "popout", background: "#fdba74", desc: "max 1400px" },
+      { variant: "content", background: "#fde047", desc: "max 1064px" },
+      { variant: "inset-content", background: "#86efac", desc: "max 840px" },
+    ];
+    const chip =
+      "display: inline-block; margin-block-end: 8px; padding: 2px 8px; border-radius: 4px; background: rgba(0,0,0,0.75); color: white; font-family: monospace; font-size: 1.2rem;";
+    return { sampleText, nested, chip };
   },
   template: `
     <div style="min-height: 100vh;">
 
-      <PageRowComponent tag="section" variant="full" style="background: #1e3a5f; color: white; padding-block: 60px;">
+      <PageRowComponent tag="section" style="background: #1e3a5f; color: white; padding-block: 60px;">
+        <span :style="chip">outer PageRow (variant="content")</span>
         <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 tag="section" style="background: #0f172a; padding-block: 48px; display: grid; row-gap: 16px;">
+        <span :style="chip" style="background: white; color: #0f172a;">outer PageRow (dark background)</span>
+        <PageRowComponent
+          v-for="row in nested"
+          :key="row.variant"
+          :variant="row.variant"
+          :style="{ background: row.background, color: '#111827', paddingBlock: '24px' }"
+        >
+          <div>
+            <span :style="chip">nested variant="{{ row.variant }}"</span>
+            <p style="margin: 0; line-height: 1.6;">{{ row.desc }}: the background shows the track this nested PageRow occupies.</p>
+          </div>
         </PageRowComponent>
       </PageRowComponent>
 
@@ -152,7 +186,7 @@ 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.",
+        "The key composition pattern: an outer PageRow carries the full-width background, and nested PageRows pick a track via variant. Each nested row's background marks the track it occupies against the dark outer row. No extra wrapper divs needed.",
     },
   },
 };

package/app/components/01.atoms/text-blocks/eyebrow-text/CONSUMER-STYLING.md

@@ -8,8 +8,12 @@
 | `--eyebrow-text-large` | `1.4rem` | Font size for `font-size="large"` |
 | `--eyebrow-text-medium` | `1.2rem` | Font size for `font-size="medium"` (default) |
 | `--eyebrow-text-small` | `1rem` | Font size for `font-size="small"` |
+| `--eyebrow-text-font-family` | `inherit` | Font family |
+| `--eyebrow-text-font-style` | `italic` | Font style, e.g. `normal` for upright text |
+| `--eyebrow-text-font-weight` | `inherit` | Font weight |
+| `--eyebrow-text-letter-spacing` | `inherit` | Letter-spacing, e.g. `0.25em` for wide tracking |
 
-The library theme also sets all four on `:root` (`03.theming/_default.css` and
+The library theme also sets the colour and size tokens on `:root` (`03.theming/_default.css` and
 `05.typography/01.tokens/_reponsive-font-sizes.css`) with the same values.
 
 > Changed 2026-09-27: the component now carries those values as fallbacks too. Before, an app that

package/app/components/01.atoms/text-blocks/eyebrow-text/EyebrowText.vue

@@ -31,7 +31,10 @@ watch(
     text-transform: uppercase;
     background-clip: text;
     background-image: var(--eyebrow-text-bg-img, linear-gradient(135deg, #c2a770, #b4747e, #d1bd94));
-    font-style: italic;
+    font-family: var(--eyebrow-text-font-family, inherit);
+    font-style: var(--eyebrow-text-font-style, italic);
+    font-weight: var(--eyebrow-text-font-weight, inherit);
+    letter-spacing: var(--eyebrow-text-letter-spacing, inherit);
     color: transparent;
 
     &.large {

package/app/components/02.molecules/action-menu/stories/ActionMenu.stories.ts

@@ -218,7 +218,7 @@ export const InContext: Story = {
             align-items: center;
             gap: 1.2rem;
             padding: 1.2rem 1.6rem;
-            border-bottom: 0.1rem solid light-dark(#e5e7eb, #374151);
+            border-bottom: 0.1rem solid rgb(128 128 128 / 0.35);
           "
         >
           <div
@@ -226,7 +226,7 @@ export const InContext: Story = {
               width: 3.6rem;
               height: 3.6rem;
               border-radius: 50%;
-              background: light-dark(#e5e7eb, #374151);
+              background: rgb(128 128 128 / 0.35);
               display: grid;
               place-items: center;
               font-size: 1.4rem;
@@ -290,17 +290,17 @@ export const ItemCoreStandalone: Story = {
     template: `
       <div style="padding: 4rem; max-width: 32rem; margin: 0 auto;">
         <p style="margin: 0 0 1.2rem; font-size: 1.2rem; opacity: 0.5; text-transform: uppercase; letter-spacing: 0.08em;">Button items</p>
-        <div style="border: 0.1rem solid light-dark(#e5e7eb, #374151); border-radius: 0.8rem; overflow: hidden;">
+        <div style="border: 0.1rem solid rgb(128 128 128 / 0.35); border-radius: 0.8rem; overflow: hidden;">
           <ActionMenuItem
             label="Edit"
-            style="border-bottom: 0.1rem solid light-dark(#e5e7eb, #374151);"
+            style="border-bottom: 0.1rem solid rgb(128 128 128 / 0.35);"
             @click="lastClick = 'Edit'"
           >
             <template #icon><Icon name="lucide:pencil" /></template>
           </ActionMenuItem>
           <ActionMenuItem
             label="Duplicate"
-            style="border-bottom: 0.1rem solid light-dark(#e5e7eb, #374151);"
+            style="border-bottom: 0.1rem solid rgb(128 128 128 / 0.35);"
             @click="lastClick = 'Duplicate'"
           >
             <template #icon><Icon name="lucide:copy" /></template>
@@ -314,11 +314,11 @@ export const ItemCoreStandalone: Story = {
         </div>
 
         <p style="margin: 2.4rem 0 1.2rem; font-size: 1.2rem; opacity: 0.5; text-transform: uppercase; letter-spacing: 0.08em;">Link items</p>
-        <div style="border: 0.1rem solid light-dark(#e5e7eb, #374151); border-radius: 0.8rem; overflow: hidden;">
+        <div style="border: 0.1rem solid rgb(128 128 128 / 0.35); border-radius: 0.8rem; overflow: hidden;">
           <ActionMenuItem
             label="Internal link (/about)"
             href="/about"
-            style="border-bottom: 0.1rem solid light-dark(#e5e7eb, #374151);"
+            style="border-bottom: 0.1rem solid rgb(128 128 128 / 0.35);"
           >
             <template #icon><Icon name="lucide:arrow-up-right" /></template>
           </ActionMenuItem>

package/app/components/02.molecules/select-menu/CONSUMER-STYLING.md

@@ -14,6 +14,7 @@ global token so it matches the rest of the design system out of the box.
 | `--select-menu-trigger-padding-block` | `0.8rem` | Trigger vertical padding |
 | `--select-menu-trigger-padding-inline` | `1.2rem` | Trigger horizontal padding |
 | `--select-menu-trigger-border-width` | `0.1rem` | Trigger border thickness |
+| `--select-menu-trigger-border-width-underlined` | `var(--form-element-border-bottom-width-underlined, 0.3rem)` | Bottom border thickness in the `underlined` variant |
 | `--select-menu-trigger-border` | `var(--theme-border)` | Trigger border colour (rest state) |
 | `--select-menu-trigger-border-focus` | `var(--theme-border-focus)` | Trigger border colour on hover/focus |
 | `--select-menu-trigger-border-radius` | `0.5rem` | Trigger corner rounding |
@@ -54,6 +55,15 @@ global token so it matches the rest of the design system out of the box.
 
 ---
 
+## State hooks
+
+| Hook | Where | Meaning |
+|---|---|---|
+| `.normal` / `.underlined` | `.select-menu` root | The `inputVariant` prop. `underlined` removes the trigger's top and side borders and its corner radius, matching `InputSelect`'s underlined variant. |
+| `:has(.select-menu-popover:popover-open)` | `.select-menu` root | Menu open (rotates the chevron). |
+
+---
+
 ## Global theming
 
 Create `assets/styles/setup/07.components/select-menu.css` in the consuming app and set tokens

package/app/components/02.molecules/select-menu/SelectMenu.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="select-menu" :class="[elementClasses]" :style="`--_anchor-name: ${anchorName}`">
+  <div class="select-menu" :class="[inputVariant, elementClasses]" :style="`--_anchor-name: ${anchorName}`">
     <button
       ref="triggerRef"
       :popovertarget="menuId"
@@ -61,6 +61,7 @@
 
 <script setup lang="ts">
 import type { SelectMenuOption } from "~/types/components/select-menu";
+import type { InputUiVariant } from "~/types/forms/types.forms";
 
 interface Props {
   /** The full list of selectable options. */
@@ -79,6 +80,8 @@ interface Props {
   multiple?: boolean;
   /** In multiple mode, update the trigger text to a comma-separated list of the currently checked options instead of leaving it fixed on placeholder/label. No effect outside multiple mode. */
   showSelectionInTrigger?: boolean;
+  /** Trigger border style, matching InputSelect: `normal` (bordered box) or `underlined` (bottom border only). */
+  inputVariant?: InputUiVariant;
   styleClassPassthrough?: string | string[];
 }
 
@@ -89,6 +92,7 @@ const props = withDefaults(defineProps<Props>(), {
   showChevron: true,
   multiple: false,
   showSelectionInTrigger: false,
+  inputVariant: "normal",
   styleClassPassthrough: () => [],
 });
 
@@ -273,6 +277,16 @@ watch(
       }
     }
 
+    &.underlined .select-menu-trigger {
+      border-block-start-width: 0;
+      border-inline-width: 0;
+      border-block-end-width: var(
+        --select-menu-trigger-border-width-underlined,
+        var(--form-element-border-bottom-width-underlined, 0.3rem)
+      );
+      border-radius: 0;
+    }
+
     &:has(.select-menu-popover:popover-open) .select-menu-trigger-chevron {
       transform: rotate(180deg);
     }

package/app/components/02.molecules/select-menu/stories/SelectMenu.stories.ts

@@ -14,6 +14,7 @@ interface StoryArgs {
   showChevron?: boolean;
   multiple?: boolean;
   showSelectionInTrigger?: boolean;
+  inputVariant?: "normal" | "underlined";
   modelValue?: string | number | (string | number)[];
   styleClassPassthrough?: string | string[];
 }
@@ -57,6 +58,12 @@ const meta: Meta<StoryArgs> = {
       description: "In multiple mode, update the trigger text to a comma-separated list of the currently checked options instead of leaving it fixed on placeholder/label. No effect outside multiple mode.",
       table: { category: "Content" },
     },
+    inputVariant: {
+      control: { type: "select" },
+      options: ["normal", "underlined"],
+      description: "Trigger border style, matching InputSelect: bordered box or bottom border only.",
+      table: { category: "Styling" },
+    },
     styleClassPassthrough: {
       table: { disable: true },
     },
@@ -66,6 +73,7 @@ const meta: Meta<StoryArgs> = {
     showIcon: true,
     showLabel: true,
     showChevron: true,
+    inputVariant: "normal",
   },
   parameters: {
     docs: {
@@ -357,3 +365,30 @@ export const CustomTokens: Story = {
     `,
   }),
 };
+
+/**
+ * Underlined — bottom border only, matching InputSelect's `underlined` variant
+ * so a SelectMenu can sit next to underlined form fields.
+ */
+export const Underlined: Story = {
+  args: {
+    label: "Choose a service",
+    showIcon: false,
+    inputVariant: "underlined",
+  },
+  render: (args) => ({
+    components: { SelectMenu },
+    setup() {
+      const value = ref<string | undefined>(undefined);
+      return { args, value, serviceOptions };
+    },
+    template: `
+      <div style="padding: 4rem 8rem;">
+        <SelectMenu v-bind="args" v-model="value" :options="serviceOptions" />
+        <p style="margin: 1.6rem 0 0; font-size: 1.3rem; opacity: 0.6;">
+          modelValue: <strong>{{ value === undefined ? 'undefined' : value }}</strong>
+        </p>
+      </div>
+    `,
+  }),
+};

package/app/components/02.molecules/select-menu/tests/SelectMenu.spec.ts

@@ -89,6 +89,15 @@ describe("SelectMenu", () => {
       expect(wrapper.find(".select-menu-trigger").attributes("aria-haspopup")).toBe("listbox");
     });
 
+    it("applies the normal variant class by default and underlined when set", async () => {
+      wrapper = await createWrapper();
+      expect(wrapper.find(".select-menu").classes()).toContain("normal");
+
+      await wrapper.setProps({ inputVariant: "underlined" });
+      expect(wrapper.find(".select-menu").classes()).toContain("underlined");
+      expect(wrapper.find(".select-menu").classes()).not.toContain("normal");
+    });
+
     it("uses label prop as aria-label", async () => {
       wrapper = await createWrapper({ label: "Filter by service" });
       expect(wrapper.find(".select-menu-trigger").attributes("aria-label")).toBe("Filter by service");

package/app/components/02.molecules/select-menu/tests/__snapshots__/SelectMenu.spec.ts.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`SelectMenu > Snapshots > default 1`] = `
-"<div class="select-menu" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false">
+"<div class="select-menu normal" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false">
     <!--v-if--><span class="select-menu-trigger-label">Language</span><span class="iconify i-lucide:chevron-down select-menu-trigger-chevron" aria-hidden="true"></span>
   </button>
   <div id="select-menu-v-0-0" popover="" class="select-menu-popover">
@@ -15,7 +15,7 @@ exports[`SelectMenu > Snapshots > default 1`] = `
 `;
 
 exports[`SelectMenu > Snapshots > icon-only trigger 1`] = `
-"<div class="select-menu" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false"><span class="iconify i-flag:gb-4x3 select-menu-trigger-icon" aria-hidden="true"></span>
+"<div class="select-menu normal" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false"><span class="iconify i-flag:gb-4x3 select-menu-trigger-icon" aria-hidden="true"></span>
     <!--v-if-->
     <!--v-if-->
   </button>
@@ -30,7 +30,7 @@ exports[`SelectMenu > Snapshots > icon-only trigger 1`] = `
 `;
 
 exports[`SelectMenu > Snapshots > with a selected value 1`] = `
-"<div class="select-menu" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false"><span class="iconify i-flag:fr-4x3 select-menu-trigger-icon" aria-hidden="true"></span><span class="select-menu-trigger-label">Français</span><span class="iconify i-lucide:chevron-down select-menu-trigger-chevron" aria-hidden="true"></span></button>
+"<div class="select-menu normal" style="--_anchor-name: --select-menu-anchor-v-0-0;"><button popovertarget="select-menu-v-0-0" popovertargetaction="toggle" type="button" class="select-menu-trigger" aria-label="Language" aria-haspopup="listbox" aria-expanded="false"><span class="iconify i-flag:fr-4x3 select-menu-trigger-icon" aria-hidden="true"></span><span class="select-menu-trigger-label">Français</span><span class="iconify i-lucide:chevron-down select-menu-trigger-chevron" aria-hidden="true"></span></button>
   <div id="select-menu-v-0-0" popover="" class="select-menu-popover">
     <ul class="select-menu-list" role="listbox" aria-label="Language">
       <li class="select-menu-list-item" role="option" tabindex="-1" aria-selected="false"><span class="select-menu-item-check" aria-hidden="true"><!--v-if--></span><span class="iconify i-flag:gb-4x3 select-menu-item-icon" aria-hidden="true"></span><span class="select-menu-item-label">English</span></li>

package/app/components/03.organisms/google-reviews/CONSUMER-STYLING.md

@@ -0,0 +1,110 @@
+# GoogleReviews — Consumer Styling Guide
+
+`GoogleReviews` shows a place's Google reviews as a single horizontally scrolling row of
+`GoogleReviewCard`s, with a summary above and prev/next buttons plus the Google Maps attribution
+below. Both components read the same `--google-reviews-*` tokens, so setting them on an ancestor
+styles a standalone `GoogleReviewCard` too.
+
+## Public token API
+
+### Row (`GoogleReviews`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--google-reviews-gap` | `1.6rem` | Space between header, row and footer, and between cards |
+| `--google-reviews-card-width` | `min(32rem, 85%)` | Width of each card in the row |
+| `--google-reviews-scroll-padding` | `0` | Snap inset, e.g. to line cards up with a page gutter |
+| `--google-reviews-scrollbar-width` | `thin` | Row scrollbar: `auto`, `thin` or `none` (`none` hides it; the buttons and touch/keyboard scrolling still work) |
+| `--google-reviews-scrollbar-thumb-colour` | `var(--slate-04)` | Scrollbar thumb |
+| `--google-reviews-scrollbar-track-colour` | `transparent` | Scrollbar track |
+| `--google-reviews-summary-rating-font-size` | `2.4rem` | Overall rating number |
+| `--google-reviews-focus-outline-width` | `2px` | Focus ring on the scrollable row |
+| `--google-reviews-focus-outline-colour` | `var(--theme-border-focus)` | Focus ring colour |
+
+### Card (`GoogleReviewCard`)
+
+| Token | Default | Controls |
+|---|---|---|
+| `--google-reviews-card-gap` | `1.2rem` | Space between author, stars, text and link |
+| `--google-reviews-card-padding` | `2rem` | Card padding |
+| `--google-reviews-card-border-width` | `1px` | Card border width |
+| `--google-reviews-card-border-colour` | `transparent` | Card border colour |
+| `--google-reviews-card-border-radius` | `0.8rem` | Card corner radius |
+| `--google-reviews-card-surface` | `var(--theme-surface-subtle)` | Card background |
+| `--google-reviews-card-text-colour` | `var(--theme-text)` | Card text colour |
+| `--google-reviews-avatar-surface` | `var(--theme-surface)` | Initials avatar background (shown when a reviewer has no photo) |
+| `--google-reviews-avatar-text-colour` | `var(--theme-on-surface)` | Initials colour |
+| `--google-reviews-author-font-weight` | `600` | Reviewer name weight |
+| `--google-reviews-author-line-clamp` | `2` | Lines of reviewer name before it's cut off with an ellipsis (`1` for single-line ellipsis, `none` to show it all) |
+| `--google-reviews-text-line-height` | `1.5` | Review text line height |
+| `--google-reviews-text-line-clamp` | `5` | Lines of review text before it's cut off with an ellipsis (`none` to show it all) |
+| `--google-reviews-link-colour` | `inherit` | "Read on Google" link colour |
+
+### Shared
+
+| Token | Default | Controls |
+|---|---|---|
+| `--google-reviews-star-size` | `1.6rem` | Star font size (summary and cards) |
+| `--google-reviews-star-colour` | `var(--amber-05)` | Filled star colour |
+| `--google-reviews-star-empty-colour` | `var(--slate-03)` | Unfilled star colour |
+| `--google-reviews-meta-font-size` | `1.4rem` | Date, link, filter notice and attribution |
+| `--google-reviews-meta-text-colour` | `inherit` | Colour of the same |
+
+Private tokens (not public API): `--_rating` (set inline from the review's rating) and `--_fill`
+(the star fill percentage derived from it).
+
+## State hooks
+
+- No `data-*` state. The prev/next buttons are `InputButton`s with `readonly`/`aria-disabled` at
+  either end of the row, styled by `InputButton`'s own tokens.
+- Inner classes: `.google-reviews-header`, `.google-reviews-summary`,
+  `.google-reviews-summary-rating`, `.google-reviews-stars`, `.google-reviews-summary-link`,
+  `.google-reviews-filter-notice`, `.google-reviews-list`, `.google-reviews-item`,
+  `.google-reviews-footer`, `.google-reviews-controls`, `.google-reviews-prev`,
+  `.google-reviews-next`, `.google-reviews-attribution`.
+- Card classes: `.google-review-card`, `.google-review-card-author`,
+  `.google-review-card-author-name`,
+  `.google-review-card-time`, `.google-review-card-rating`, `.google-review-card-stars`,
+  `.google-review-card-text`, `.google-review-card-link`.
+
+## Row alignment
+
+Inside `GoogleReviews`, every card spans the list's five shared rows (name, date, rating, text,
+link) through `grid-template-rows: subgrid`, so each section lines up across the whole row
+however tall its neighbours are: a one-line name's date sits level with a two-line name's. The
+author block is itself a subgrid over the name and date rows, with the avatar spanning both.
+Sections sit in fixed rows, so a card with no date, text or link leaves the gap rather than
+shifting up. Spacing between sections is a top margin (`--google-reviews-card-gap`), not a grid
+gap, so the name and date stay close together. A standalone `GoogleReviewCard` uses
+`auto auto auto 1fr auto` instead (link pinned to the bottom). Content from the `card` slot
+spans all five rows as one block. Browsers
+without subgrid fall back to equal-height cards that aren't aligned section by section.
+
+## Stars
+
+Stars are the text `★★★★★` filled with a hard-stop gradient clipped to the text, so fractional
+ratings (4.6) show a partly filled star. They're `aria-hidden`; the rating is read out from
+visually hidden text (`ratingLabel`).
+
+## 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:** the card re-declares `--display-avatar-background` and `--display-avatar-text-colour` on its
+avatar, so setting those `DisplayAvatar` tokens on an ancestor has no effect here. Use
+`--google-reviews-avatar-surface` and `--google-reviews-avatar-text-colour` instead.
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root (`.google-reviews` or `.google-review-card`).
+`GoogleReviews` doesn't forward it to the cards it renders; set tokens on the root instead, or
+use the `card` slot to render `GoogleReviewCard` yourself with its own passthrough.
+
+## Notes
+
+Google's terms require the attribution text to stay visible and readable. Restyle it, but don't
+hide it, and keep the words "Google Maps" in `attributionText` when translating.