srcdev-nuxt-components 9.5.3 → 9.5.5

package/.vscode/srcdev-component-input-otp.code-snippets

@@ -0,0 +1,47 @@
+{
+  "SRCDEV InputOtp Basic": {
+    "description": "Bare InputOtp one-time-code boxes (no legend/description/error wrapper)",
+    "scope": "vue,html",
+    "body": [
+      "<InputOtp",
+      "  id=\"$1otp\"",
+      "  v-model=\"$2code\"",
+      "  name=\"$3code\"",
+      "  :length=\"${4:6}\"",
+      "  group-label=\"$5Verification code\"",
+      "/>"
+    ]
+  },
+  "SRCDEV InputOtpField Basic": {
+    "description": "InputOtpField: labelled one-time-code field with description and error support",
+    "scope": "vue,html",
+    "body": [
+      "<InputOtpField",
+      "  v-model=\"$1code\"",
+      "  name=\"$2code\"",
+      "  label=\"$3Verification code\"",
+      "  :length=\"${4:6}\"",
+      "  autofocus",
+      "  :error-message=\"$5errors.code\"",
+      "  :field-has-error=\"!!$5errors.code\"",
+      "  @complete=\"$6onComplete\"",
+      ">",
+      "  <template #descriptionText>$7Enter the code we sent to your email.</template>",
+      "</InputOtpField>"
+    ]
+  },
+  "SRCDEV InputOtp CSS Override": {
+    "description": "CSS override scaffold for InputOtp tokens",
+    "scope": "css",
+    "body": [
+      ".$1my-page {",
+      "  --input-otp-gap: $2;",
+      "  --input-otp-box-inline-size: $3;",
+      "  --input-otp-box-block-size: $4;",
+      "  --input-otp-font-size: $5;",
+      "  --input-otp-border: $6;",
+      "  --input-otp-border-focus: $7;",
+      "}"
+    ]
+  }
+}

package/.vscode/srcdev-component-select-menu.code-snippets

@@ -35,6 +35,19 @@
       "/>"
     ]
   },
+  "SRCDEV SelectMenu Underlined": {
+    "description": "SelectMenu — text + chevron with an underlined trigger, matching InputSelect's underlined variant",
+    "scope": "vue,html",
+    "body": [
+      "<SelectMenu",
+      "  v-model=\"${1:filterValue}\"",
+      "  :options=\"${2:filterOptions}\"",
+      "  label=\"${3:Choose a service}\"",
+      "  :show-icon=\"false\"",
+      "  input-variant=\"underlined\"",
+      "/>"
+    ]
+  },
   "SRCDEV SelectMenu Multi-Select": {
     "description": "SelectMenu — checkbox-per-option multi-select, v-model is an array",
     "scope": "vue,html",

package/README.md

@@ -6,7 +6,7 @@
 
 ## NOTE
 
-Althought this repo is public and feel free to do what you wish with it, this has been developed for use with websites we develop.
+Although this repo is public and feel free to do what you wish with it, this has been developed for use with websites we develop.
 
 ## Install Nuxt Components layer
 
@@ -58,7 +58,7 @@ To ensure skills are always up to date, VSCode snippets are installed, and `nuxt
 2. `nuxt prepare` — generates Nuxt type declarations
 3. `setup:claude` — copies skills into `.claude/skills/srcdev-nuxt-components/`
 
-> **Note**: The snippet copy must run from your consumer app's postinstall, not the layer's. npm doesn't invoke postinstall hooks for dependencies, so each consumer app is responsible for copying snippets into its own `.vscode/` folder. If your app uses a standalone env flag for `nuxt prepare` (e.g. `NUXT_STANDALONE=true`), add it before `nuxt prepare`. This is project-specific — check your own `nuxt.config.ts` to confirm whether it is needed.
+> **Note**: The snippet copy must run from your consumer app's postinstall, not the layer's. npm doesn't invoke postinstall hooks for dependencies, so each consumer app is responsible for copying snippets into its own `.vscode/` folder. Don't set `SRCDEV_STANDALONE` in a consumer app: that flag is only for running this layer on its own (it enables dev-only modules and the ramp watcher).
 
 ---
 
@@ -77,6 +77,31 @@ via `npm run setup:claude`.
 
 ---
 
+## Components
+
+Components live in `app/components/`, grouped into tiers:
+
+| Folder         | Storybook title prefix |
+| -------------- | ---------------------- |
+| `01.atoms`     | `Atoms/`               |
+| `02.molecules` | `Molecules/`           |
+| `03.organisms` | `Organisms/`           |
+| `04.templates` | `Templates/`           |
+| `05.forms`     | `Forms/`               |
+
+Components are auto-imported with `pathPrefix: false`, so the tier folder never appears in the tag name.
+
+**Naming**: a bare form control is `<Name>` (e.g. `InputNumber`) and its labelled wrapper is `<Name>Field` (e.g. `InputNumberField`). Older `Core` / `Default` / `WithLabel` suffixes are being renamed to this convention; see `.claude/skills/component-naming.md` for the backlog.
+
+Each component ships with:
+
+- **`CONSUMER-STYLING.md`** next to the `.vue` file, listing its public CSS custom properties and how to override them
+- **a Storybook story**, the only place components are demonstrated (this repo has no demo pages)
+- **a skill doc** in `.claude/skills/components/`, copied into your app by `npm run setup:claude`
+- **a VS Code snippet** in `.vscode/srcdev-component-{name}.code-snippets`, copied into your app by `postinstall`
+
+---
+
 ## Consumer App Configuration
 
 Configuration options for apps extending this layer. All options go in the consumer's `nuxt.config.ts` under `runtimeConfig.public` and can also be set via environment variable.
@@ -108,6 +133,40 @@ When disabled, no `data-color-scheme` attribute is set on `<html>` and `useColou
 
 > See [.claude/skills/colour-scheme-disable.md](.claude/skills/colour-scheme-disable.md) for the full guide.
 
+### Analytics
+
+Call `useAnalytics()` from a layout, page or component and use `trackEvent(name, params)` to fire events. Only Google Analytics (GA4) is implemented today; call sites never name the provider, so adding another later won't change them.
+
+```ts
+// nuxt.config.ts
+runtimeConfig: {
+  public: {
+    analytics: {
+      provider: "google-analytics",
+      googleAnalytics: { id: "G-XXXXXXXXXX" },
+    },
+  },
+},
+```
+
+Or via environment variable:
+
+```bash
+NUXT_PUBLIC_ANALYTICS_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX
+```
+
+With no ID set, `trackEvent` does nothing.
+
+### WhatsApp
+
+`useWhatsApp().openWhatsApp(fields)` opens a WhatsApp chat pre-filled with the given label/value pairs. Set the number in international format, without `+` or spaces:
+
+```bash
+NUXT_PUBLIC_WHATSAPP_NUMBER=447700900000
+```
+
+Without a number it logs a warning and does nothing.
+
 ---
 
 ## Colour System
@@ -131,7 +190,8 @@ computes the scale from the two params:
 Scale direction: **00 = lightest, 10 = darkest**. Chroma tapers at both ends and peaks at step 06.
 
 Nine semantic slots (`--theme-surface`, `--theme-accent`, `--theme-text`, `--theme-ring`, etc.) are derived from the
-scale using `light-dark()` and are shared by all components. Theme variants (`data-theme="success"`,
+scale and are shared by all components. They ship light values only (no `light-dark()`, which older iPad
+Safari lacks); dark mode is left to the consuming app, see `.claude/skills/theming-dark-mode.md`. Theme variants (`data-theme="success"`,
 `"warning"`, `"error"`) swap `--theme-hue` and `--theme-chroma` on their element; the formula
 re-evaluates locally so each themed element gets its own full palette without affecting the page.
 
@@ -222,8 +282,8 @@ In your `app/assets/styles/setup/02.colours/index.css` (create if it doesn't exi
   --theme-chroma: var(--palette-gold-chroma);
 
   /* Page-level tokens — readable named steps, not raw oklch */
-  --colour-text-accent: light-dark(var(--gold-09), var(--gold-04));
-  --colour-text-eyebrow: light-dark(var(--gold-09), var(--gold-04));
+  --colour-text-accent: var(--gold-09);
+  --colour-text-eyebrow: var(--gold-09);
 }
 ```
 
@@ -270,45 +330,13 @@ npm run check:ramps      # CI: fail if generated CSS is out of date
 | Full ramp architecture, formula details, hue drift      | `.claude/skills/theming-colour-ramps.md`     |
 | Full palette swap for a consumer app                    | `.claude/skills/theming-override-default.md` |
 | Partial token override (palette shift, buttons, inputs) | `.claude/skills/theming-partial-override.md` |
+| Add a dark scheme (layer ships light values only)       | `.claude/skills/theming-dark-mode.md`        |
 | Disable light/dark mode support                         | `.claude/skills/colour-scheme-disable.md`    |
 
 Skills are available in your project after running `npm run setup:claude`.
 
 ---
 
-## Known Build / Production Issues
-
-### `ERR_MODULE_NOT_FOUND: vue/index.mjs` — 500 on every request (Node 22)
-
-**Symptom**: After `npm run build`, running `node .output/server/index.mjs` returns HTTP 500 on every page. The terminal shows:
-
-```text
-Error [ERR_MODULE_NOT_FOUND]: Cannot find module
-  '.output/server/node_modules/vue/index.mjs'
-Did you mean to import
-  '.output/server/node_modules/.nitro/vue@3.5.34/dist/vue.cjs.prod.js'?
-```
-
-**Root cause**: Nitro's dependency tracer externalises `vue` and copies it to `.output/server/node_modules/vue/`, but only traces the CJS build (`dist/vue.cjs.prod.js`). Vue's `package.json` exports map resolves the `"import"` + `"node"` condition (used by Node 22 when importing from an ES module) to `./index.mjs` — a file that was never copied. This is a Nitro tracing bug exposed by Node 22's stricter ESM condition matching, made more likely by `vue.runtimeCompiler: true` (which changes how Nuxt aliases Vue at build time, causing Nitro to fall back to externalising it as a node_modules package).
-
-**Fix** (already applied in this repo's `nuxt.config.ts`):
-
-```ts
-nitro: {
-  externals: {
-    inline: ["vue", "@vue/runtime-core", "@vue/runtime-dom", "@vue/reactivity", "@vue/shared", "@vue/server-renderer"],
-  },
-},
-```
-
-This tells Nitro to bundle these packages inline rather than externalise them, which sidesteps the runtime resolution entirely.
-
-**Consumer apps**: This config is not gated behind `isStandalone`, so it is inherited automatically by any app that extends this layer. No consumer-side action is required.
-
-**When it's safe to remove**: If a future Nitro release fixes the dependency tracer so that all export-condition files are copied correctly, the `inline` list can be removed. Verify by checking that `.output/server/node_modules/vue/index.mjs` exists after a clean build without the config.
-
----
-
 ## Development Environment (`.vscode`)
 
 The `.vscode` directory contains Visual Studio Code configuration files to ensure a consistent development experience across the project:
@@ -428,7 +456,7 @@ npm run test:update
 
 ### Visual Regression Tests (Playwright)
 
-Runs pixel-level screenshot comparisons against Storybook. Requires Storybook to be running first.
+Runs pixel-level screenshot comparisons against Storybook. Requires Storybook to be running first. Coverage is currently limited to a few components (`InputButton`, `HeroText`, `EyebrowText`, `ContentDocs`); specs live in each component's `playwright/` folder as `*.playwright.ts`.
 
 ```bash
 # 1. Start Storybook
@@ -462,12 +490,13 @@ npx playwright show-report
 
 ## Storybook
 
-Storybook is used for isolated component development and as the target for visual regression tests. It runs as a separate Vite-based dev server.
+Storybook (v10, via `@nuxtjs/storybook`) is the only demo surface for this library, and the target for visual regression tests. The deployed build is at [storybook.srcdev.co.uk](https://storybook.srcdev.co.uk).
 
 ### Scripts
 
 ```bash
-# Start Storybook dev server (http://localhost:6006)
+# Start Storybook dev server (http://localhost:6006). `npm run dev` does the same after
+# regenerating the colour ramps; there is no `nuxt dev` entry point.
 npm run storybook
 
 # Build a static Storybook (outputs to storybook-static/)
@@ -483,6 +512,16 @@ npm run storybook:cache:clean
 > After clearing the cache, restart with `npm run storybook`. The cache clear is particularly
 > useful when changes inside `@layer` CSS blocks are not reflected in the running dev server.
 
+### MCP server for AI agents
+
+`@storybook/addon-mcp` exposes the stories over MCP while the dev server is running, so a coding agent can look up components, their props and story examples instead of guessing. The endpoint is `http://localhost:6006/mcp`. To connect Claude Code:
+
+```bash
+claude mcp add --transport http storybook http://localhost:6006/mcp
+```
+
+See the [Storybook MCP docs](https://storybook.js.org/docs/next/ai/mcp/overview) for other clients.
+
 ### Fonts
 
 `@nuxt/fonts` is disabled in Storybook (detected via `process.env.STORYBOOK` in `nuxt.config.ts`).
@@ -492,5 +531,6 @@ Fonts are served instead from local files in `.storybook/public/_fonts/`, declar
 | ---------------- | ------ | -------------------------------------------- |
 | Poppins          | TTF    | `.storybook/public/_fonts/poppins/`          |
 | Playfair Display | woff2  | `.storybook/public/_fonts/playfair-display/` |
+| Mono MMM 5       | TTF    | `public/fonts/`                              |
 
 To add a new font, see [.claude/skills/storybook-add-font.md](.claude/skills/storybook-add-font.md).

package/app/assets/styles/setup/01.config/_head.css

@@ -1,15 +1,6 @@
 html {
-  color-scheme: light dark;
   interpolate-size: allow-keywords;
 
-  &[data-color-scheme="light"] {
-    color-scheme: light;
-  }
-
-  &[data-color-scheme="dark"] {
-    color-scheme: dark;
-  }
-
   font-size: 62.5%;
 
   transition:

package/app/assets/styles/setup/03.theming/_default.css

@@ -6,10 +6,10 @@
   /* ===========================================
      GENERIC BODY VARIABLES
      =========================================== */
-  --page-bg: light-dark(var(--slate-00), var(--slate-08));
-  --colour-text-default: light-dark(var(--slate-09), var(--slate-01));
-  --colour-text-accent: light-dark(var(--blue-09), var(--blue-05));
-  --colour-text-eyebrow: light-dark(var(--blue-09), var(--blue-05));
+  --page-bg: var(--slate-00);
+  --colour-text-default: var(--slate-09);
+  --colour-text-accent: var(--blue-09);
+  --colour-text-eyebrow: var(--blue-09);
 
   /* ===========================================
      HERO / EYEBROW TEXT VARIABLES
@@ -21,46 +21,46 @@
      STEPPER LIST VARIABLES
      =========================================== */
   --stepper-list-counter-circle-background: transparent;
-  --stepper-list-counter-circle-text: light-dark(var(--blue-09), var(--blue-02));
-  --stepper-list-counter-circle-border: light-dark(var(--blue-09), var(--blue-02));
-  --stepper-list-counter-disc-background: light-dark(var(--blue-01), var(--blue-02));
+  --stepper-list-counter-circle-text: var(--blue-09);
+  --stepper-list-counter-circle-border: var(--blue-09);
+  --stepper-list-counter-disc-background: var(--blue-01);
   --stepper-list-counter-disc-text: var(--blue-09);
-  --stepper-list-counter-disc-border: light-dark(var(--blue-01), var(--blue-02));
+  --stepper-list-counter-disc-border: var(--blue-01);
   --stepper-list-counter-square-background: transparent;
-  --stepper-list-counter-square-text: light-dark(var(--blue-09), var(--blue-02));
-  --stepper-list-counter-square-border: light-dark(var(--blue-09), var(--blue-02));
-  --stepper-list-connector-color: light-dark(var(--blue-01), var(--blue-02));
-  --stepper-list-icon-color: light-dark(var(--blue-09), var(--blue-02));
+  --stepper-list-counter-square-text: var(--blue-09);
+  --stepper-list-counter-square-border: var(--blue-09);
+  --stepper-list-connector-color: var(--blue-01);
+  --stepper-list-icon-color: var(--blue-09);
 
   /* ===========================================
      TREATMENT CONSULTANT VARIABLES
      =========================================== */
-  --treatment-consultant-primary-colour: light-dark(var(--amber-05), var(--amber-02));
-  --treatment-consultant-primary-foreground: light-dark(var(--amber-09), var(--amber-02));
-  --treatment-consultant-muted-colour: light-dark(var(--amber-03), var(--amber-05));
-  --treatment-consultant-muted-foreground: light-dark(var(--amber-07), var(--amber-05));
-  --treatment-consultant-background: light-dark(var(--amber-01), var(--amber-10));
-  --treatment-consultant-foreground: light-dark(var(--amber-09), var(--amber-02));
-  --treatment-consultant-border-colour: light-dark(var(--blue-02), var(--amber-03));
-  --treatment-consultant-checked-surface-colour: light-dark(var(--green-03), var(--green-10));
-  --treatment-consultant-checked-stroke-colour: light-dark(var(--green-09), var(--green-03));
-  --treatment-consultant-conflict-surface-colour: light-dark(var(--sunset-03), var(--sunset-09));
-  --treatment-consultant-conflict-stroke-colour: light-dark(var(--sunset-09), var(--sunset-03));
+  --treatment-consultant-primary-colour: var(--amber-05);
+  --treatment-consultant-primary-foreground: var(--amber-09);
+  --treatment-consultant-muted-colour: var(--amber-03);
+  --treatment-consultant-muted-foreground: var(--amber-07);
+  --treatment-consultant-background: var(--amber-01);
+  --treatment-consultant-foreground: var(--amber-09);
+  --treatment-consultant-border-colour: var(--blue-02);
+  --treatment-consultant-checked-surface-colour: var(--green-03);
+  --treatment-consultant-checked-stroke-colour: var(--green-09);
+  --treatment-consultant-conflict-surface-colour: var(--sunset-03);
+  --treatment-consultant-conflict-stroke-colour: var(--sunset-09);
 
   /* ===========================================
      ANCHOR LINK VARIABLES
      =========================================== */
-  --colour-link-default: light-dark(var(--blue-10), var(--blue-02));
-  --colour-link-hover: light-dark(var(--blue-09), var(--blue-03));
+  --colour-link-default: var(--blue-10);
+  --colour-link-hover: var(--blue-09);
 
   /* ===========================================
      STRUCTURAL INPUT TOKENS
      Neutral slate surface — independent of theme colour
      =========================================== */
-  --theme-input-surface: light-dark(var(--slate-00), var(--slate-10));
-  --theme-input-surface-hover: light-dark(var(--slate-01), var(--slate-09));
-  --theme-input-text-color-normal: light-dark(var(--slate-09), var(--slate-01));
-  --theme-input-placeholder: light-dark(var(--slate-05), var(--slate-04));
+  --theme-input-surface: var(--slate-00);
+  --theme-input-surface-hover: var(--slate-01);
+  --theme-input-text-color-normal: var(--slate-09);
+  --theme-input-placeholder: var(--slate-05);
   --theme-checkbox-symbol-surface: var(--theme-input-surface);
   --input-error-margin-block-start: 0.25rem;
 }

package/app/assets/styles/setup/03.theming/_error.css

@@ -8,7 +8,7 @@
      These are always error-red regardless of nesting context.
      =========================================== */
   --input-error-color: white;
-  --theme-error-surface: light-dark(var(--red-06), var(--red-07));
-  --theme-error-border: light-dark(var(--red-06), var(--red-07));
-  --theme-error-outline: light-dark(var(--red-01), var(--red-05));
+  --theme-error-surface: var(--red-06);
+  --theme-error-border: var(--red-06);
+  --theme-error-outline: var(--red-01);
 }

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/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 |
@@ -48,12 +49,30 @@ global token so it matches the rest of the design system out of the box.
 | `--select-menu-item-text-color` | `var(--theme-text)` | Option label colour |
 | `--select-menu-item-font-size` | `1.5rem` | Option label font size |
 | `--select-menu-item-surface-hover` | `var(--theme-input-surface-hover)` | Option row background on hover/focus |
+| `--select-menu-item-surface-selected` | `var(--theme-surface-subtle)` | Background of selected/checked option rows (hover/focus still wins) |
+| `--select-menu-item-text-color-selected` | `--select-menu-item-text-color` | Selected row label colour (the checkmark follows via `currentcolor`) |
+| `--select-menu-item-font-weight` | inherited | Option row font weight |
+| `--select-menu-item-font-weight-selected` | `--select-menu-item-font-weight` | Selected row font weight; the popover reserves the bolder width, so selecting doesn't resize it |
+| `--select-menu-item-border-width` | `0` | Block (top/bottom) border width on **every** row, so a selected border never shifts layout |
+| `--select-menu-item-border` | `transparent` | Resting row border colour |
+| `--select-menu-item-border-selected` | `--select-menu-item-border` | Selected row border colour. Two adjacent selected rows show both borders where they meet |
+| `--select-menu-item-text-color-hover` | the row's current colour | Label colour on hover/focus. Unset, a selected row keeps its selected colour |
+| `--select-menu-item-border-hover` | the row's current border | Border colour on hover/focus. Unset, a selected row keeps its selected border |
 | `--select-menu-item-check-size` | `1.6rem` | Checkmark icon box size |
 | `--select-menu-item-check-color` | `currentcolor` | Checkmark icon colour |
 | `--select-menu-item-icon-size` | `1.8rem` | Per-option icon size |
 
 ---
 
+## 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
@@ -174,4 +193,3 @@ story.
   the bottom of the viewport (`position-try-fallbacks: flip-block`).
 - **Chevron rotation** is pure CSS via `:has(.select-menu-popover:popover-open)` — no JS state
   needed for the visual, though `isOpen` is still tracked internally to drive `aria-expanded`.
-

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"
@@ -41,6 +41,7 @@
           role="option"
           tabindex="-1"
           :aria-selected="isSelected(option)"
+          :data-label="option.label"
           @click="selectOption(option)"
         >
           <span class="select-menu-item-check" aria-hidden="true">
@@ -61,6 +62,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 +81,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 +93,7 @@ const props = withDefaults(defineProps<Props>(), {
   showChevron: true,
   multiple: false,
   showSelectionInTrigger: false,
+  inputVariant: "normal",
   styleClassPassthrough: () => [],
 });
 
@@ -273,6 +278,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);
     }
@@ -329,15 +344,50 @@ watch(
           gap: var(--select-menu-item-gap, 0.8rem);
           padding-block: var(--select-menu-item-padding-block, 1rem);
           padding-inline: var(--select-menu-item-padding-inline, 1.2rem);
+          --_text-color: var(--select-menu-item-text-color, var(--theme-text));
+          --_border: var(--select-menu-item-border, transparent);
+
           cursor: pointer;
-          color: var(--select-menu-item-text-color, var(--theme-text));
+          color: var(--_text-color);
           font-family: var(--font-family);
           font-size: var(--select-menu-item-font-size, 1.5rem);
-          transition: background-color var(--select-menu-transition-duration, 200ms) ease;
+          /* No fallback: unset means invalid at computed time, so the weight inherits. */
+          font-weight: var(--select-menu-item-font-weight);
+          border-block: var(--select-menu-item-border-width, 0) solid var(--_border);
+          transition:
+            background-color var(--select-menu-transition-duration, 200ms) ease,
+            border-color var(--select-menu-transition-duration, 200ms) ease,
+            color var(--select-menu-transition-duration, 200ms) ease;
+
+          /* Reserves the selected label width so a bolder selected weight doesn't resize the popover. */
+          &::after {
+            content: attr(data-label);
+            grid-column: 3;
+            grid-row: 1;
+            block-size: 0;
+            overflow: hidden;
+            visibility: hidden;
+            white-space: nowrap;
+            font-weight: var(--select-menu-item-font-weight-selected, var(--select-menu-item-font-weight));
+          }
+
+          &[aria-selected="true"] {
+            --_text-color: var(
+              --select-menu-item-text-color-selected,
+              var(--select-menu-item-text-color, var(--theme-text))
+            );
+            --_border: var(--select-menu-item-border-selected, var(--select-menu-item-border, transparent));
+
+            background-color: var(--select-menu-item-surface-selected, var(--theme-surface-subtle));
+            font-weight: var(--select-menu-item-font-weight-selected, var(--select-menu-item-font-weight));
+          }
 
+          /* Hover falls back to the row's current state, so an unset hover token keeps a selected row's colours. */
           &:hover,
           &:focus-visible {
             background-color: var(--select-menu-item-surface-hover, var(--theme-input-surface-hover));
+            color: var(--select-menu-item-text-color-hover, var(--_text-color));
+            border-color: var(--select-menu-item-border-hover, var(--_border));
           }
 
           &:focus-visible {
@@ -372,6 +422,7 @@ watch(
 
           .select-menu-item-label {
             grid-column: 3;
+            grid-row: 1;
             white-space: nowrap;
             overflow: hidden;
             text-overflow: ellipsis;