srcdev-nuxt-components 9.1.28 → 9.1.30

package/.claude/skills/new-app-scaffold.md

@@ -0,0 +1,301 @@
+# New App Scaffold
+
+## Overview
+
+Scaffold a new Nuxt app that extends `srcdev-nuxt-components` as a layer. Use this skill when
+a user asks to initialise or set up a new consumer app from scratch.
+
+## Prerequisites
+
+- An empty (or near-empty) git repo exists at the target path
+- The user provides: repo path, package name, production domain, fonts, and whether to include
+  `nuxt-security` + `@nuxtjs/robots`
+
+## Steps
+
+### 1. Gather details
+
+Ask for (or confirm from context):
+
+| Detail | Example |
+|---|---|
+| Repo path | `/Users/name/websites/my-app` |
+| Package name | `my-app` (used in `package.json` and `bodyAttrs.class`) |
+| Production domain | `myapp.co.uk` |
+| Fonts | `Fraunces, Manrope` — assume bunny CDN unless stated otherwise |
+| Include security modules? | yes / no (nuxt-security + @nuxtjs/robots) |
+
+Check for any existing files (`.claude/`, `README.md`, design docs) before writing — read them
+to inform the CLAUDE.md and CSS tokens.
+
+### 2. Create `package.json`
+
+```json
+{
+  "name": "{name}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "clean": "rm -rf .nuxt && rm -rf .output && rm -rf node_modules && rm ./package-lock.json",
+    "cleanupandprepare": "npx nuxi cleanup && npx nuxi prepare",
+    "reinstall": "npm install",
+    "cleaninstall": "npm run clean && npm run reinstall",
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "setup:claude": "mkdir -p .claude/skills/srcdev-nuxt-components && cp -r node_modules/srcdev-nuxt-components/.claude/skills/. .claude/skills/srcdev-nuxt-components",
+    "postinstall": "NUXT_STANDALONE=true nuxt prepare && npm run setup:claude",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "@iconify-json/gravity-ui": "1.2.12",
+    "@iconify-json/ic": "1.2.4",
+    "@iconify-json/lucide": "1.2.101",
+    "@iconify-json/material-symbols": "1.2.65",
+    "@iconify-json/mdi": "1.2.3",
+    "modern-normalize": "3.0.1",
+    "nuxt-security": "2.5.1"
+  },
+  "devDependencies": {
+    "@nuxt/eslint": "1.15.2",
+    "@nuxt/scripts": "0.13.2",
+    "@nuxtjs/robots": "6.0.6",
+    "eslint": "10.2.0",
+    "nuxt": "4.4.2",
+    "srcdev-nuxt-components": "{latest version}"
+  }
+}
+```
+
+> **`setup:claude` script**: `mkdir -p` is required — the destination folder won't exist on a
+> fresh clone. The trailing `/.` on the source path copies contents into the destination rather
+> than nesting a `skills` subfolder inside it.
+
+### 3. Create `nuxt.config.ts`
+
+```ts
+const PROD_HOST = "{domain}"
+const canonicalHost = process.env.NUXT_PUBLIC_CANONICAL_HOST ?? "{name}.vercel.app"
+const isProduction = canonicalHost === PROD_HOST
+
+export default defineNuxtConfig({
+  debug: false,
+  devServer: { https: false },
+  compatibilityDate: "2025-08-04",
+  runtimeConfig: {
+    public: {
+      canonicalHost,
+      colourScheme: { enabled: false },
+    },
+  },
+  extends: ["srcdev-nuxt-components"],
+  modules: ["@nuxt/eslint", "@nuxt/scripts", "nuxt-security", "@nuxtjs/robots"],
+  robots: {
+    enabled: isProduction,
+    groups: [{ userAgent: ["*"], allow: ["/"] }],
+    sitemap: [`https://${PROD_HOST}/sitemap.xml`],
+  },
+  components: [{ path: "./components", pathPrefix: false }],
+  imports: { dirs: ["./stores"] },
+  devtools: { enabled: true },
+  app: {
+    head: {
+      htmlAttrs: { lang: "en" },
+      titleTemplate: "%s - {App Title}",
+      meta: [{ charset: "utf-8" }, { name: "viewport", content: "width=device-width, initial-scale=1" }],
+      link: [{ rel: "icon", href: "/icons/favicon.png" }],
+      bodyAttrs: { class: "{name}-body" },
+    },
+    pageTransition: { name: "page", mode: "out-in" },
+    layoutTransition: { name: "layout", mode: "out-in" },
+  },
+  css: ["srcdev-nuxt-components/app/assets/styles/main.css", "./app/assets/styles/main.css"],
+  fonts: {
+    assets: { prefix: "/_fonts" },
+    families: [
+      // Add chosen fonts here — provider: "bunny" for Google Fonts via bunny CDN
+      { name: "{Font}", weights: [300, 400, 500, 600, 700], styles: ["normal", "italic"], provider: "bunny", display: "optional" },
+    ],
+  },
+  typescript: {
+    includeWorkspace: true,
+    strict: true,
+    shim: true,
+    typeCheck: false,
+    tsConfig: { compilerOptions: { types: ["srcdev-nuxt-components"] } },
+  },
+  eslint: { config: {} },
+  security: {
+    headers: {
+      contentSecurityPolicy: {
+        "default-src": ["'self'"],
+        "script-src": ["'self'", "'unsafe-inline'", "'unsafe-eval'", "https://vercel.live"],
+        "style-src": ["'self'", "'unsafe-inline'"],
+        "script-src-attr": ["'self'", "'unsafe-inline'"],
+        "img-src": ["'self'", "data:"],
+        "connect-src": ["'self'", "https://api.iconify.design", "https://vercel.live"],
+        "frame-src": ["'self'", "https://vercel.live"],
+      },
+    },
+  },
+  vite: {
+    optimizeDeps: {
+      include: ["@oddbird/css-anchor-positioning", "@vue/devtools-core", "@vue/devtools-kit", "zod"],
+    },
+  },
+})
+```
+
+### 4. Create supporting config files
+
+**`tsconfig.json`**
+```json
+{
+  "extends": "./.nuxt/tsconfig.json",
+  "compilerOptions": { "strict": true }
+}
+```
+
+**`eslint.config.mjs`**
+```js
+// @ts-check
+import withNuxt from "./.nuxt/eslint.config.mjs"
+
+export default withNuxt({
+  files: ["**/*.vue"],
+  rules: {
+    "@stylistic/max-len": "off",
+    "vue/max-len": "off",
+    "vue/max-attributes-per-line": "off",
+    "vue/singleline-html-element-content-newline": "off",
+    "vue/html-closing-bracket-newline": "off",
+    "vue/html-self-closing": [
+      "error",
+      { html: { void: "always", normal: "never", component: "always" } },
+    ],
+    "@stylistic/member-delimiter-style": [
+      "error",
+      {
+        multiline: { delimiter: "semi", requireLast: true },
+        singleline: { delimiter: "semi", requireLast: false },
+        multilineDetection: "brackets",
+      },
+    ],
+  },
+})
+```
+
+**`.prettierrc`**
+```json
+{
+  "printWidth": 120,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "semi": false,
+  "vueIndentScriptAndStyle": false,
+  "htmlWhitespaceSensitivity": "ignore"
+}
+```
+
+**`.nvmrc`**
+```
+node 20
+```
+
+**`.gitignore`** — include `.output`, `.nuxt`, `.nitro`, `.cache`, `node_modules`, `.env`, `.DS_Store`, `.vercel`, `storybook-static`.
+
+### 5. Create app directory structure
+
+```
+app/
+├── assets/styles/
+│   └── main.css          ← brand tokens + font vars (loads after layer CSS)
+├── layouts/
+│   └── default.vue       ← minimal shell with <slot>
+├── pages/
+│   └── index.vue         ← placeholder home page with useSeoMeta
+└── error.vue             ← 404 / 500 handler with clearError redirect
+```
+
+**`app/assets/styles/main.css`** — declare brand CSS custom properties and set font-family:
+
+```css
+:root {
+  /* Add brand colour tokens */
+  --font-display: "{Display Font}", serif;
+  --font-body: "{Body Font}", sans-serif;
+  font-family: var(--font-body);
+}
+```
+
+**`app/layouts/default.vue`** — minimal:
+
+```vue
+<template>
+  <div class="layout-default">
+    <main><slot></slot></main>
+  </div>
+</template>
+```
+
+**`app/pages/index.vue`** — placeholder with `useSeoMeta`.
+
+**`app/error.vue`** — handle `statusCode` 404 vs 500, call `clearError({ redirect: "/" })`.
+
+### 6. Create `.claude/skills/.gitkeep`
+
+Ensures `.claude/skills/` exists in the repo on a fresh clone so `setup:claude` never errors.
+
+```bash
+mkdir -p .claude/skills && touch .claude/skills/.gitkeep
+```
+
+### 7. Create `CLAUDE.md`
+
+Brief project context file at repo root:
+
+```md
+# {App Title} — Claude Guidelines
+
+This app extends the `srcdev-nuxt-components` Nuxt layer.
+
+## Layer Skills
+
+Skills are copied into `.claude/skills/srcdev-nuxt-components/` during `npm install`.
+Run `npm run setup:claude` to refresh after a layer upgrade.
+
+## Project Context
+
+- **Design system**: `.claude/design.md` (if it exists)
+- **Production domain**: {domain}
+- **Fonts**: {fonts}
+
+## Key Conventions
+
+- Follow all guidelines in the layer's `CLAUDE.md`
+- CSS custom properties for all design tokens — no hardcoded values in component styles
+- Layer CSS loads first; `app/assets/styles/main.css` overrides
+```
+
+### 8. Confirm next step for the user
+
+Tell the user to run:
+
+```bash
+npm install
+```
+
+`postinstall` will run `nuxt prepare` and copy the layer skills automatically.
+
+## Notes
+
+- If the repo contains a `.claude/design.md`, read it before writing `main.css` — use any
+  brand colours or font choices from it to seed the CSS tokens.
+- If security modules are not wanted, omit `nuxt-security` from `dependencies` and remove it
+  from `modules` and the `security` config block in `nuxt.config.ts`. Same for `@nuxtjs/robots`.
+- The `colourScheme.enabled: false` default is correct for most consumer apps — enable only if
+  the app needs light/dark switching.
+- Check the latest `srcdev-nuxt-components` version on npm before writing `package.json`.

package/.claude/skills/setup-postinstall.md

@@ -0,0 +1,45 @@
+# Automate nuxt prepare and Claude Skills with postinstall
+
+## Overview
+
+Prevent two common "forgot to run after install" problems in a consuming app:
+
+1. `nuxt prepare` — generates Nuxt type declarations. Skipping it causes TypeScript errors after install or package updates.
+2. `npm run setup:claude` — copies the latest `srcdev-nuxt-components` skills into `.claude/skills/srcdev-nuxt-components/`. Skipping it leaves Claude working from stale skill docs after a package update.
+
+A `postinstall` script runs both automatically after every `npm install`.
+
+## Steps
+
+### 1. Add the scripts to package.json
+
+```json
+"scripts": {
+  "setup:claude": "cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components",
+  "postinstall": "nuxt prepare && npm run setup:claude"
+}
+```
+
+### 2. Check whether your app needs an env flag for nuxt prepare
+
+Some apps set an env var to switch `nuxt.config.ts` behaviour when running outside the full dev server (e.g. `NUXT_STANDALONE=true`). Check your own `nuxt.config.ts` — if it gates any config behind such a variable, add it to the `postinstall` command:
+
+```json
+"postinstall": "NUXT_STANDALONE=true nuxt prepare && npm run setup:claude"
+```
+
+If your `nuxt.config.ts` has no such conditional, plain `nuxt prepare` is sufficient.
+
+### 3. Run once manually to bootstrap
+
+```bash
+npm run setup:claude
+```
+
+From this point on, `npm install` and `npm ci` trigger both steps automatically.
+
+## Notes
+
+- Skills land in `.claude/skills/srcdev-nuxt-components/` — safe to re-run without overwriting your own project's skills.
+- `postinstall` also fires on `npm ci`, so CI environments get the skills too if they have a `.claude/` directory in the project.
+- If you do not want `postinstall` running in CI, guard it: `"postinstall": "[ \"$CI\" = \"true\" ] || (nuxt prepare && npm run setup:claude)"`.

package/.claude/skills/theming-override-default.md

@@ -241,6 +241,12 @@ The consuming app's CSS loads after the layer's, so your token overrides win via
 | 24px | 2.4rem |
 | 32px | 3.2rem |
 
+## Token reference
+
+See `CONSUMER-STYLING.md` in the layer package root for the full list of available tokens grouped
+by category. This is the authoritative reference when deciding which tokens to include in your
+override files.
+
 ## Notes
 
 - The `--slate-*` scale comes from the layer and does not need to be redefined — keep all neutral/background tokens pointing at `--slate-*`.

package/.claude/skills/theming-partial-override.md

@@ -0,0 +1,131 @@
+# Partial Token Override in a Consuming App
+
+## Overview
+
+Use this skill when you need to override a specific category of tokens (e.g. form inputs, buttons,
+colours) without replacing the entire default theme. The full token reference is in
+`CONSUMER-STYLING.md` at the root of the layer package.
+
+## How it works
+
+All library tokens are declared inside `@layer theming`. Any CSS written outside a layer wins
+automatically — no `!important` or specificity tricks required. Override files just need to be
+imported **after** the layer styles.
+
+## Steps
+
+### 1. Create your override file
+
+Create a CSS file for the category you want to override. Place it anywhere in your app's assets —
+`app/assets/styles/` is conventional.
+
+**Example: form input overrides**
+
+```css
+/* app/assets/styles/form-overrides.css */
+:root {
+  --theme-input-surface: oklch(0.98 0.005 250);
+  --theme-input-border: oklch(0.45 0.08 270);
+  --theme-input-border-focus: oklch(0.55 0.18 280);
+  --theme-input-outline-focus: oklch(0.55 0.18 280);
+  --theme-focus-visible-shadow: 0 0 0 2px oklch(0.80 0.12 280);
+  --theme-input-placeholder: oklch(0.60 0.02 255);
+  --theme-input-text-color-normal: oklch(0.20 0.02 255);
+}
+```
+
+**Example: add a red colour scale and remap accent tokens**
+
+```css
+/* app/assets/styles/red-palette.css */
+:root {
+  /* Red scale — 00 (lightest) to 10 (darkest) */
+  --red-00: oklch(0.99 0.005 20);
+  --red-01: oklch(0.96 0.020 20);
+  --red-02: oklch(0.90 0.055 20);
+  --red-03: oklch(0.82 0.105 20);
+  --red-04: oklch(0.72 0.155 20);
+  --red-05: oklch(0.62 0.185 20);
+  --red-06: oklch(0.53 0.185 20);
+  --red-07: oklch(0.44 0.165 20);
+  --red-08: oklch(0.36 0.140 20);
+  --red-09: oklch(0.28 0.110 20);
+  --red-10: oklch(0.20 0.080 20);
+
+  /* Remap semantic accent tokens to red */
+  --colour-text-accent: var(--red-08);
+  --colour-text-eyebrow: var(--red-08);
+  --colour-link-default: var(--red-09);
+  --colour-link-hover: var(--red-08);
+}
+```
+
+**Example: button overrides only**
+
+```css
+/* app/assets/styles/button-overrides.css */
+:root {
+  --theme-button-primary-surface: oklch(0.55 0.20 280);
+  --theme-button-primary-surface-hover: oklch(0.48 0.22 280);
+  --theme-button-primary-surface-active: oklch(0.42 0.22 280);
+  --theme-button-primary-text: oklch(1 0 0);
+  --theme-button-primary-text-hover: oklch(1 0 0);
+}
+```
+
+### 2. Register it in nuxt.config.ts
+
+Import your override file **after** the layer styles:
+
+```ts
+export default defineNuxtConfig({
+  extends: "srcdev-nuxt-components",
+  css: [
+    "~/assets/styles/form-overrides.css",   // or whichever file(s) you created
+  ],
+});
+```
+
+The layer's own CSS loads via the `extends` mechanism before app CSS, so your unlayered overrides
+always win.
+
+### 3. Dark mode (optional)
+
+If you need dark mode variants of your overrides, add them in the same file using the `html.dark`
+class selector:
+
+```css
+:root {
+  --theme-input-surface: oklch(0.98 0.005 250);
+}
+
+:where(html.dark) {
+  --theme-input-surface: oklch(0.15 0.02 255);
+}
+```
+
+## Scoped overrides (section or component level)
+
+To restrict an override to a specific section of the page, scope to a wrapper class instead of
+`:root`:
+
+```css
+.pricing-section {
+  --theme-button-primary-surface: oklch(0.55 0.20 140);  /* green for pricing CTA */
+}
+```
+
+## Token reference
+
+See `CONSUMER-STYLING.md` in the layer package for the full list of available tokens, grouped
+by category (typography, colours, form inputs, buttons, checkboxes, toggle, glass panel,
+StepperList).
+
+## Notes
+
+- Only override the tokens you actually need — unset tokens fall back to layer defaults.
+- Use oklch for all colour values. Use an oklch colour picker (e.g. oklch.com) to build scales.
+- For a full palette replacement (replacing the entire default theme), use
+  `theming-override-default.md` instead.
+- `--slate-*` neutral tokens come from the layer and do not need to be redefined unless you
+  genuinely want different neutrals.

package/.claude/skills/vue-video-autoplay.md

@@ -0,0 +1,74 @@
+# Vue Video Autoplay on Client-Side Navigation
+
+## Overview
+
+In Vue/Nuxt SPAs, binding `:src` directly on a `<video>` element silently skips the browser fetch when Vue patches the element during client-side navigation. The video appears but never loads — no network request is made. Use a `<source>` child element instead, combined with `:key` and an explicit `load()` call.
+
+## The problem
+
+When Vue patches an existing `<video>` DOM element (e.g. on route change), setting `src` via `:src` doesn't always trigger the browser to re-fetch the media resource. This fails silently — no console error, no network request, poster image just sits there.
+
+## The fix
+
+```vue
+<!-- ✅ Correct — src in <source> child -->
+<video
+  :key="src"
+  autoplay
+  muted
+  loop
+  playsinline
+  preload="auto"
+  :poster="poster"
+>
+  <source :src="src" type="video/mp4" />
+</video>
+
+<!-- ❌ Wrong — :src on <video> silently skips fetch on Vue patches -->
+<video autoplay muted loop playsinline preload="auto" :src="src"></video>
+```
+
+## Three things working together
+
+1. **`<source>` child** — the browser re-reads source children when `load()` is called, reliably initiating the fetch.
+2. **`:key="src"`** — forces Vue to unmount/remount the `<video>` element when the source changes (covers same-component src swaps).
+3. **Explicit `v.load()` call** — programmatically re-initiates fetching after mount and on src change. Do not rely on `autoplay` alone for client-side navigation.
+
+## Autoplay pattern for Nuxt components
+
+```ts
+const videoEl = shallowRef<HTMLVideoElement | null>(null);
+
+const tryPlay = async () => {
+  const v = videoEl.value;
+  if (!v) return;
+  v.muted = true; // required for programmatic autoplay in all browsers
+  try {
+    await v.play();
+  } catch {
+    // autoplay blocked — poster remains visible
+  }
+};
+
+const kickOffLoad = async () => {
+  await nextTick();
+  const v = videoEl.value;
+  if (!v) return;
+  v.load();
+  void tryPlay();
+};
+
+// Covers initial mount and src prop changes
+watch(() => props.src, () => void kickOffLoad(), { immediate: true, flush: "post" });
+
+// Covers keep-alive re-activation
+onActivated(() => void kickOffLoad());
+```
+
+Attach `@loadeddata="() => void tryPlay()"` and `@canplay="() => void tryPlay()"` to the `<video>` element as additional retry points once data arrives.
+
+## Notes
+
+- `preload="auto"` tells the browser to buffer eagerly — essential for autoplay reliability.
+- `v.muted = true` set programmatically (in addition to the `muted` attribute) works around a Safari bug where the attribute alone is insufficient for programmatic play.
+- This pattern applies to any Vue/Nuxt video component, not just background/ambient video.

package/README.md

@@ -8,7 +8,7 @@
 
 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.
 
-## Install Nuxt Forms layer
+## Install Nuxt Components layer
 
 ```bash
 npm install --save srcdev-nuxt-components
@@ -17,10 +17,7 @@ npm install --save srcdev-nuxt-components
 ```ts
 defineNuxtConfig({
   extends: "srcdev-nuxt-components",
-  css: [
-    "srcdev-nuxt-components/app/assets/styles/main.css",
-    "./app/assets/styles/main.css",
-  ],
+  css: ["srcdev-nuxt-components/app/assets/styles/main.css", "./app/assets/styles/main.css"],
 });
 ```
 
@@ -44,6 +41,34 @@ npm run setup:claude
 
 Skills are copied into `.claude/skills/srcdev-nuxt-components/` so they never conflict with or overwrite skills your own project defines. Re-running the script after a package update is safe.
 
+### Automate with postinstall (recommended)
+
+To ensure skills are always up to date and `nuxt prepare` is never forgotten, combine both into a `postinstall` script. npm runs this automatically after every `npm install`:
+
+```json
+"scripts": {
+  "setup:claude": "cp -r node_modules/srcdev-nuxt-components/.claude/skills .claude/skills/srcdev-nuxt-components",
+  "postinstall": "nuxt prepare && npm run setup:claude"
+}
+```
+
+> If your app uses a standalone env flag for `nuxt prepare` (e.g. `NUXT_STANDALONE=true`), include it in the `postinstall` command. This is project-specific — check your own `nuxt.config.ts` to confirm whether it is needed.
+
+---
+
+## Scaffolding a New App
+
+A Claude Code skill is included to scaffold a new Nuxt consumer app from scratch. It generates
+`package.json`, `nuxt.config.ts`, ESLint/Prettier config, the full `app/` directory structure,
+and a `CLAUDE.md` — all pre-wired to extend this layer correctly.
+
+**Trigger it by saying to Claude Code:**
+
+> "Scaffold a new layer consumer app. Repo: `/path/to/repo`, name: `my-app`, domain: `myapp.co.uk`, fonts: `Fraunces, Manrope`."
+
+The skill is available at `.claude/skills/new-app-scaffold.md` once copied into your project
+via `npm run setup:claude`.
+
 ---
 
 ## Consumer App Configuration