srcdev-nuxt-components 9.0.5 → 9.0.7

package/.claude/skills/components/eyebrow-text.md

@@ -4,6 +4,17 @@
 
 `EyebrowText` renders a short uppercase label — typically used above a heading to provide context or categorisation. It outputs a single string with configurable tag, size, and colour via CSS custom properties.
 
+## Before Adding to a Page
+
+Always ask the user for the following before placing the component:
+
+1. **`textContent`** — what is the label text? (passed as-is — do not pre-uppercase)
+2. **`fontSize`** — which size? (`large` | `medium` | `small`) — default is `medium`
+3. **`tag`** — does it need to be inline? If yes, use `span`. Otherwise `p` or `div` (default).
+4. **`styleClassPassthrough`** — any extra classes to add? (layout, spacing, custom styling hooks)
+
+Do not assume placeholder text or default content.
+
 ## Props
 
 | Prop | Type | Default | Required |
@@ -59,6 +70,7 @@ Define these CSS custom properties in your consuming app to control sizes.
 ## Styling
 
 Key CSS custom properties:
+
 - `--colour-text-eyebrow` — text colour (defaults to an accent/muted tone)
 
 Text is always `text-transform: uppercase` — do not pass pre-uppercased strings, as this makes content harder to edit and search.

package/.claude/skills/components/hero-text.md

@@ -4,6 +4,18 @@
 
 `HeroText` renders a styled heading with support for mixed text styling (normal/accent segments), configurable font size, layout axis, and an optional icon. It uses Playfair Display font with italic variation for accent segments.
 
+## Before Adding to a Page
+
+Always ask the user for the following before placing the component:
+
+1. **`tag`** — what heading level? (`h1` | `h2` | `h3` | `h4` | `h5` | `h6`)
+2. **Text segments** — for each segment, what is the text and should it be `normal` (default) or `accent` (italic, `--colour-text-accent` colour)?
+3. **`axis`** — should segments sit inline (`horizontal`, default) or stack in a column (`vertical`)?
+4. **`fontSize`** — which size? (`display` | `title` | `heading` | `subheading` | `label`) — default is `title`
+5. **`styleClassPassthrough`** — any extra classes to add? (layout, spacing, custom styling hooks)
+
+Do not assume placeholder text or default content.
+
 ## Props
 
 | Prop | Type | Default | Required |
@@ -87,6 +99,7 @@ Define these CSS custom properties in your consuming app to control sizes.
 Override via `styleClassPassthrough` or a parent HOC `<style>` block targeting `.hero-text`.
 
 Key CSS custom properties:
+
 - `--colour-text-accent` — colour applied to `.accent` spans and the icon
 - `--hero-text-{scale}` — font size per scale value
 

package/.claude/skills/components/layout-row.md

@@ -0,0 +1,204 @@
+# LayoutRow Component
+
+## Overview
+
+`LayoutRow` is a CSS grid-based layout wrapper that controls how wide its content sits within the page. It uses a named-column grid system (full → popout → content → inset-content) so content can be precisely placed at different widths without custom CSS. It is the primary layout primitive for page sections.
+
+---
+
+## How to use this skill
+
+When a developer asks to add a `LayoutRow`, follow the interactive flow below. Do not skip to writing code — work through the questions first to ensure the right variant is chosen. Developers unfamiliar with this system will not know what the options mean without guidance.
+
+---
+
+## Step 1 — Read the current context
+
+Before asking anything, read the file the developer is working in and any parent components or pages to determine:
+
+1. **Is this LayoutRow inside another LayoutRow?**
+   - If yes, note the parent's `variant`. The inner grid resets relative to the parent's inner width, not the page. Warn the developer (see side effects below).
+   - If no, this is page-level — the grid spans the full viewport.
+
+2. **What is the effective current max width?**
+   Report this before asking any questions. Examples:
+   - "This row will sit at **page level** — the grid spans the full viewport width."
+   - "This row is nested inside a `LayoutRow variant="content"` — its maximum available width is **1064px**, not the full viewport."
+   - "This row is nested inside `variant="inset-content"` — maximum available width is **840px**."
+
+3. **What content is already nearby?** Note any sibling LayoutRows, headings, or components to give context for alignment.
+
+---
+
+## Step 2 — Ask what the row will contain
+
+Ask the developer what is going in this row. Do not assume. Examples to listen for:
+
+| Content type | Suggested variant |
+|---|---|
+| Hero, banner, full-bleed image or video | `full` or `full-content` |
+| Coloured background band containing constrained content | `full` wrapping inner `content` |
+| Card grid, media grid, feature row | `popout` |
+| Standard page section (text + components) | `content` |
+| Long-form article, blog post, form | `inset-content` |
+| Sidebar or aside | `inset-content` |
+
+Give a suggestion based on their answer, but confirm before proceeding.
+
+---
+
+## Step 3 — Present the width and margin consequences
+
+Once you have a candidate variant (or 2–3 options), show the developer exactly what they will get at common viewport widths. Use this reference table:
+
+### Approximate rendered widths by variant
+
+| Viewport | `inset-content` | `content` | `popout` | `full` |
+|----------|----------------|-----------|----------|--------|
+| 375px (mobile) | ~355px | ~355px | ~355px | 375px |
+| 768px (tablet) | ~748px | ~748px | ~748px | 768px |
+| 1080px | **840px** | ~1060px | ~1060px | 1080px |
+| 1280px | **840px** | **1064px** | ~1260px | 1280px |
+| 1440px | **840px** | **1064px** | **1400px** | 1440px |
+| 1920px | **840px** | **1064px** | **1400px** | 1920px |
+
+> Bold = the variant has reached its maximum and is now letterboxed. Below that threshold it fills the available width minus the minimum gutter (default `1rem` = 10px each side).
+
+### Approximate margin (space each side at wider viewports)
+
+| Variant | @ 1080px | @ 1280px | @ 1440px | @ 1920px |
+|---------|---------|---------|---------|---------|
+| `inset-content` | ~120px | ~220px | ~300px | ~540px |
+| `content` | ~10px | ~108px | ~188px | ~428px |
+| `popout` | ~10px | ~10px | ~20px | ~260px |
+| `full` | 0 | 0 | 0 | 0 |
+
+Phrase this conversationally. For example:
+> "With `content`, your section will max out at **1064px** wide. On a 1440px screen that leaves about **188px of margin on each side**. On a 1280px screen it's tighter — around **108px** each side. Does that sound right for what you're building?"
+
+If they want more breathing room → suggest `inset-content`.
+If they want the content to feel wider → suggest `popout`.
+
+---
+
+## Step 4 — Flag side effects for the chosen variant
+
+Before writing code, flag any relevant consequences:
+
+**`full` or `full-width`** — Content is completely edge-to-edge with no gutter at any viewport width. If text is placed directly inside without a nested layout wrapper it will touch screen edges on mobile. Suggest `full-content` or a nested `content` LayoutRow for the text.
+
+**`full-content`** — Adds `--minimum-content-padding` (default `1rem` = 10px) as inline padding. Still full-bleed visually at most viewport sizes. Good for coloured bands.
+
+**`full-content-nopad`** — Truly zero padding. Only use if the child component manages its own edge spacing.
+
+**`popout`** — At viewports below ~1400px the popout track shrinks. Between 1280–1440px the margin is very small (~10–20px each side). If the design needs consistent breathing room at 1280px, `content` may be a better choice.
+
+**`inset-content` or `content` nested inside a `full` LayoutRow** — This is a common and valid pattern: `full` gives edge-to-edge background, the inner row constrains the text/content. Confirm this is intentional if you see it.
+
+**Nested LayoutRow (any variant)** — The inner grid takes the parent's `.layout-row-inner` width as 100%. The `full` variant of the inner LayoutRow will only be as wide as the parent's inner column, not the viewport. Warn the developer if this is surprising.
+
+**`-start` / `-end` variants** — These only set `grid-column-start` or `grid-column-end`, not both. Content will stretch to the opposite edge of the grid unless the other end is also constrained. Best for intentional asymmetric designs.
+
+---
+
+## Step 5 — Confirm the remaining props
+
+Once the variant is agreed, ask about:
+
+1. **`tag`** — what HTML element? Default is `div`. Common choices:
+   - `section` — for a thematic page section (most common)
+   - `article` — for self-contained content
+   - `header` / `footer` — for page-level header/footer rows
+   - `main` — for the primary content area (only once per page)
+   - `nav` — for navigation rows
+
+2. **`id`** — needed if this section is a scroll target, skip-link destination, or anchor in navigation. Ask if unsure.
+
+3. **`isLandmark`** — default `false`. Only set `true` if the row is a navigable landmark that needs keyboard focus. Usually `tag="section"` is sufficient — `isLandmark` is rarely needed.
+
+4. **`styleClassPassthrough`** — any extra classes for spacing, background colour, etc.?
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| `variant` | see variant list | — | **yes** |
+| `tag` | `"div" \| "section" \| "article" \| "aside" \| "header" \| "footer" \| "main" \| "nav" \| "ul" \| "ol"` | `"div"` | no |
+| `id` | `string` | `null` | no |
+| `isLandmark` | `boolean` | `false` | no |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | no |
+| `dataTestid` | `string` | `"layout-row"` | no |
+
+All valid `variant` values:
+`full` · `full-start` · `full-end` · `popout` · `popout-start` · `popout-end` · `content` · `content-start` · `content-end` · `inset-content` · `inset-content-start` · `inset-content-end` · `full-width` · `full-content` · `full-content-nopad`
+
+---
+
+## Usage examples
+
+### Standard section
+
+```vue
+<LayoutRow variant="content" tag="section">
+  <p>Sits within the 1064px content track with ~188px margin at 1440px.</p>
+</LayoutRow>
+```
+
+### Full-bleed hero, text constrained inside
+
+```vue
+<LayoutRow variant="full" tag="section">
+  <!-- Background is edge-to-edge -->
+  <LayoutRow variant="content">
+    <HeroText tag="h1" :textContent="[{ text: 'Welcome' }]" />
+  </LayoutRow>
+</LayoutRow>
+```
+
+### Coloured band (full width + safe padding)
+
+```vue
+<LayoutRow variant="full-content" tag="section" :styleClassPassthrough="['bg-brand']">
+  <p>Full-width background, content padded by --minimum-content-padding.</p>
+</LayoutRow>
+```
+
+### Long-form article body
+
+```vue
+<LayoutRow variant="inset-content" tag="article">
+  <p>Comfortable reading column at 840px max.</p>
+</LayoutRow>
+```
+
+### Feature / card grid (popout)
+
+```vue
+<LayoutRow variant="popout" tag="section">
+  <!-- Card grid, image gallery, etc. -->
+</LayoutRow>
+```
+
+---
+
+## CSS custom properties
+
+Override in consuming app to adjust all track sizes globally:
+
+| Property | Default | Effect |
+|----------|---------|--------|
+| `--popout-max-width` | `1400px` | Maximum width of the popout track |
+| `--content-max-width` | `1064px` | Maximum width of the content track |
+| `--inset-content-max-width` | `840px` | Maximum width of the inset-content track |
+| `--minimum-content-padding` | `1rem` (10px) | Minimum gutter at small viewports |
+
+---
+
+## Notes
+
+- Auto-imported in Nuxt — no import needed.
+- `.layout-row-inner` has `container-type: inline-size` — children can use CSS container queries.
+- The `full`, `full-content`, and `full-width` variants all map to `grid-column: full` — the difference is only whether inline padding is applied.
+- `isLandmark` adds `tabindex="0"` and `aria-label="Layout Row Landmark"`. Prefer a semantic `tag` over this prop where possible.

package/.claude/skills/index.md

@@ -27,6 +27,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
 └── components/
     ├── eyebrow-text.md         — EyebrowText props, usage patterns, styling
     ├── hero-text.md            — HeroText props, usage patterns, styling
+    ├── layout-row.md           — LayoutRow variant guide, width/margin decisions, usage patterns
     └── link-text.md            — LinkText props, slots, usage patterns, styling
 ```
 

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

@@ -229,6 +229,18 @@ export default defineNuxtConfig({
 
 The consuming app's CSS loads after the layer's, so your token overrides win via the cascade.
 
+## rem sizing
+
+`html` has `font-size: 62.5%` set in `app/assets/styles/setup/01.config/_head.css`, making `1rem = 10px`. Use this when writing any rem values in your theme or component styles:
+
+| px   | rem    |
+| ---- | ------ |
+| 8px  | 0.8rem |
+| 12px | 1.2rem |
+| 16px | 1.6rem |
+| 24px | 2.4rem |
+| 32px | 3.2rem |
+
 ## Notes
 
 - The `--slate-*` scale comes from the layer and does not need to be redefined — keep all neutral/background tokens pointing at `--slate-*`.

package/README.md

@@ -17,9 +17,15 @@ 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",
+  ],
 });
 ```
 
+> **Note**: The layer CSS is not automatically included when installed from `node_modules`. You must explicitly add it to the `css` array as shown above. The second entry (`./app/assets/styles/main.css`) is your app's own stylesheet for overrides — create it if it doesn't exist.
+
 ## Claude Code Skills
 
 This package ships Claude Code skills — reference docs for components and development tasks — in the `.claude/` directory.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.0.5",
+  "version": "9.0.7",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",