srcdev-nuxt-components 9.4.6 → 9.4.8

package/.claude/skills/components/column-flow-grid.md

@@ -0,0 +1,93 @@
+---
+name: ColumnFlowGrid
+description: ColumnFlowGrid CSS multi-column (columns) text-flow layout — named dynamic slots (no count/data prop), itemMinWidth/gap/unit sizing, CSS token API. Not a true masonry — see MasonryGrid for that.
+type: reference
+---
+
+# ColumnFlowGrid
+
+## Overview
+
+`ColumnFlowGrid` lays out slot content using CSS `columns` (the "multi-column" text-flow module —
+the same mechanism newspaper-style text layouts use). Every slot is wrapped in a
+`.column-flow-grid-item` div with `break-inside: avoid` so an item never splits across columns.
+
+**Renamed from `MasonryGrid`** during this compliance pass — despite the old name, this component
+doesn't do anything masonry-specific: it's CSS `columns` and nothing else, with items simply
+flowing into whichever column is currently shortest **in DOM order**, not reordered for reading.
+See **Which one do I want?** below.
+
+## Which one do I want? (`ColumnFlowGrid` vs `MasonryGrid`)
+
+| | Technique | DOM/reading order | Column heights | Resize behaviour |
+|---|---|---|---|---|
+| `ColumnFlowGrid` | CSS `columns` | Column-major (as authored) | Uneven, CSS-native column-fill | Instant, native — no JS |
+| `MasonryGrid` | JS-measured, greedy shortest-column packing | Natural (as authored — no reorder needed) | Uneven, genuinely bin-packed | Animated (items slide into new positions) |
+
+Use **`ColumnFlowGrid`** when you just want cheap CSS-only column flow and don't need real
+masonry packing or a resize animation — nothing here is measured or JS-driven at all, so it's the
+lighter option. Use **`MasonryGrid`** (`.claude/skills/components/masonry-grid.md`) for genuine
+Pinterest-style packing (each item placed into whichever column is currently shortest) with
+animated reflow on resize.
+
+`MasonryGridOrdered` (a third, JS-measured sibling that predated this pair) has been retired — its
+implementation was absorbed into `MasonryGrid` directly. See `masonry-grid.md`'s migration history
+note for details.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
+| `itemMinWidth` | `number` | `300` | Minimum column width in pixels — drives `columns: auto <value>px`. |
+| `gap` | `number` | `1.2` | Gap between columns/items, in `unit`. |
+| `unit` | `string` | `"rem"` | CSS unit applied to `gap`. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slot API
+
+Any named slot is accepted — there are no declared slot names, and **no count/data prop to keep
+in sync**. The component iterates `$slots` and wraps each in a `.column-flow-grid-item`:
+
+```vue
+<ColumnFlowGrid>
+  <template #item-1>...</template>
+  <template #item-2>...</template>
+  <template #item-3>...</template>
+</ColumnFlowGrid>
+```
+
+Slot names can be anything (`item-1`/`item-2` is just a convention, matching `AutoGrid`).
+
+## Basic usage
+
+```vue
+<ColumnFlowGrid :item-min-width="280" :gap="1.6">
+  <template v-for="(photo, i) in photos" :key="photo.id" #[`item-${i}`]>
+    <img :src="photo.src" :alt="photo.alt" />
+  </template>
+</ColumnFlowGrid>
+```
+
+## CSS Token Customization
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--column-flow-grid-item-border-colour` | `var(--theme-border)` | Outline colour around each item |
+| `--column-flow-grid-item-padding` | `1.2rem` | Inner padding of each item |
+
+Column width and gap are controlled via the `itemMinWidth`/`gap`/`unit` props, not CSS custom
+properties, since they need JS-computed values rather than being purely CSS-driven. See
+`CONSUMER-STYLING.md` in the component folder.
+
+## Notes
+
+- **Renamed from `MasonryGrid`** (2026-09-13) — see **Which one do I want?** above for why. If you
+  have consumer code importing this as `MasonryGrid`, it needs updating to `ColumnFlowGrid`; the
+  props and behaviour are otherwise unchanged. CSS classes/tokens were renamed to match
+  (`masonry-grid-*` → `column-flow-grid-*`).
+- **Column count is not fixed**: `columns: auto <itemMinWidth>` lets the browser decide how many
+  columns fit — there's no `columnCount` prop. Use `itemMinWidth` to influence it.
+- Item ordering is left-to-right by column-fill in `columns` layout (an item goes into the current
+  shortest column), not top-to-bottom reading order — be aware of this if visual order matters for
+  the specific content being laid out. This is the exact distinction `MasonryGrid` exists to solve.

package/.claude/skills/components/entry-animation.md

@@ -0,0 +1,88 @@
+# EntryAnimation Component
+
+## Overview
+
+`EntryAnimation` wraps slot content in a configurable tag and applies one of three CSS
+scroll-driven entry-animation utility classes (`entry-slide-in`, `entry-zoom-reveal`,
+`entry-exit-blur` — see `.claude/skills/css-animation-utilities.md`). It has no styling of its
+own beyond applying the class; the animation keyframes/timeline live in the shared
+`06.utility-classes/animations` stylesheet.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:animation-type`, `:skip-animation`.
+
+| Prop (template form)       | Type                                                    | Default          | Notes                                                                 |
+| --------------------------- | -------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------- |
+| `:tag`                      | `"div" \| "section" \| "article" \| "aside"`             | `"div"`           | Root element tag.                                                     |
+| `:animation-type`           | `"entry-slide-in" \| "entry-zoom-reveal" \| "entry-exit-blur"` | `"entry-slide-in"` | Which utility animation class to apply.                              |
+| `:skip-animation`           | `boolean`                                                 | `false`           | Renders with no animation class at all — see **Skipping the animation** below. |
+| `:style-class-passthrough`  | `string \| string[]`                                      | `[]`              | Extra CSS classes applied to the root element; always applied regardless of `skipAnimation`. |
+
+---
+
+## Slots
+
+| Slot      | Notes                                  |
+| --------- | ---------------------------------------- |
+| `default` | The content to animate in.               |
+
+---
+
+## Skipping the animation
+
+The common case in a `v-for` loop over a list of cards/sections is that the **first** item is
+already above the fold — animating it in only delays content the visitor can already see when the
+page loads. Before `skipAnimation` existed, the only way to handle this was swapping the whole
+component out for a plain tag per-item:
+
+```vue
+<!-- ❌ Old workaround — loses tag/styleClassPassthrough consistency for item 0 -->
+<component :is="index === 0 ? 'div' : EntryAnimation">
+  ...
+</component>
+```
+
+Use `skip-animation` instead — it keeps the same component, tag, and `styleClassPassthrough` for
+every item, it just omits the animation class for the ones that don't need it:
+
+```vue
+<EntryAnimation
+  v-for="(item, index) in items"
+  :key="item.id"
+  :skip-animation="index === 0"
+  animation-type="entry-slide-in"
+>
+  <template #default>
+    <!-- item content -->
+  </template>
+</EntryAnimation>
+```
+
+---
+
+## CSS Token Customization
+
+None — this component has no `--entry-animation-*` tokens or CSS of its own. The animation
+keyframes, timing, and `prefers-reduced-motion` guard live in the shared utility class
+(`entry-slide-in`/`entry-zoom-reveal`/`entry-exit-blur`), not in this component.
+
+---
+
+## Accessibility
+
+- All three animation utility classes are already scoped inside `@media (prefers-reduced-motion:
+  no-preference)` at the CSS level — a visitor with reduced motion enabled sees the content with no
+  animation, same as `skip-animation`. `skip-animation` is for a layout/UX decision (already
+  visible above the fold), not a substitute for the reduced-motion guard.
+
+---
+
+## Notes
+
+- **No animation reactivity**: `animationType`/`skipAnimation` are read once at mount to toggle the
+  utility class — changing either prop after mount does not currently re-toggle the class. This
+  matches the component's existing usage pattern (animation type is always set once per instance,
+  never swapped at runtime); flag it if a future consumer needs runtime toggling.

package/.claude/skills/components/header-block.md

@@ -0,0 +1,92 @@
+---
+name: HeaderBlock
+description: HeaderBlock semantic-vs-visual heading wrapper — tagLevel/classLevel decoupling, page-heading-N global utility classes, id for aria-labelledby pairing, styleClassPassthrough
+type: reference
+---
+
+# HeaderBlock
+
+## Overview
+
+`HeaderBlock` decouples a heading's **semantic level** (which `<h1>`-`<h6>` tag is rendered, for
+document structure and accessibility) from its **visual size** (which `.page-heading-1`–
+`.page-heading-6` global utility class is applied, for how big it reads on the page). These are
+controlled by two independent props, `tagLevel` and `classLevel` — a component can be a semantic
+`<h2>` (correct in the document outline) styled at the `page-heading-1` size (the biggest visual
+size), or vice versa.
+
+Use this whenever a page's visual hierarchy doesn't match its logical structure — e.g. a hero
+section's heading needs to be the largest thing on the page but the page already has an `<h1>`
+elsewhere, so the hero heading should be an `<h2>` styled at `page-heading-1` size.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tagLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` (or the numeric string equivalent) | `1` | Which `<h{n}>` tag is rendered. Out-of-range values fall back to `1`. |
+| `classLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` (or the numeric string equivalent) | `1` | Which `.page-heading-{n}` utility class is applied — independent of `tagLevel`. Out-of-range values fall back to `1`. |
+| `id` | `string \| null` | `null` | Rendered as the `id` attribute — bind a wrapping landmark's `aria-labelledby` target here (see "Pairing with a section's aria-labelledby" below). |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slots
+
+Default slot — the heading content. Can contain nested markup (e.g. a `<span>` for partial
+highlighting), not just plain text.
+
+## Basic usage
+
+```vue
+<HeaderBlock :tag-level="1" :class-level="1">Page title</HeaderBlock>
+```
+
+## Decoupled semantic/visual example
+
+```vue
+<!-- Hero heading: visually the biggest thing on the page, but semantically an h2 because
+     the page's real h1 lives elsewhere (e.g. in SiteHeader's branding). -->
+<HeaderBlock :tag-level="2" :class-level="1">Welcome</HeaderBlock>
+```
+
+## Pairing with a section's aria-labelledby
+
+A `<section>`/`<article>`/`<aside>` landmark needs `aria-labelledby` pointing at the `id` of a real
+heading to have an accessible name. Bind the same id to both:
+
+```vue
+<section aria-labelledby="pricing-heading">
+  <HeaderBlock id="pricing-heading" :tag-level="2" :class-level="1">Pricing</HeaderBlock>
+</section>
+```
+
+Several components in this library (`PageRow`, `LayoutGridByCols`/`LayoutGridByWidth`,
+`ProfileSection`, `ServiceSummary`, `ServiceDetail`, `PageHeroHighlights`) already generate this id
+automatically via the `useAriaLabelledById` composable and expose it as a `heading-id` slot prop —
+when composing inside one of those, bind `HeaderBlock`'s `id` to that slot prop instead of writing
+your own id:
+
+```vue
+<PageRow tag="section" v-slot="{ headingId }">
+  <HeaderBlock :id="headingId" :tag-level="2" :class-level="1">Pricing</HeaderBlock>
+</PageRow>
+```
+
+## Styling
+
+`HeaderBlock` has no CSS of its own — `classLevel` applies one of the global
+`.page-heading-1`–`.page-heading-6` utility classes defined in
+`app/assets/styles/setup/05.typography/02.utility-classes/_font-classes-page-heading.css`, each
+setting `font-size` from a shared fluid type-scale token (`--step-3` through `--step-8`). All six
+levels also reset `margin-block`/`padding-block` to `0rem` (deliberately, so a consumer adds
+spacing themselves rather than fighting the browser's own varying per-level heading margins). See
+`CONSUMER-STYLING.md` in this component's folder — overriding those tokens/values affects every
+`page-heading-*` element site-wide, not just one `HeaderBlock` instance; use
+`styleClassPassthrough` to customise a single instance.
+
+## Migration note (2026-09-15)
+
+Previously lived at `app/components/typography/HeaderBlock.vue` with an inline `defineProps<{...}>()`
+type literal (no `withDefaults`) instead of the standard `interface Props` + `withDefaults` pattern.
+Moved to `01.atoms/text-blocks/header-block/`, alongside `EyebrowText`/`HeroText`/`LinkText`. Also
+added the `id` prop in the same pass — several sections need their heading to carry a specific id
+for `aria-labelledby`, and `HeaderBlock` had no explicit way to receive one (matching `PageRow`'s
+existing `id?: string | null` + `:id` convention).

package/.claude/skills/components/input-copy.md

@@ -13,6 +13,8 @@
 | Prop (template form)       | Type                   | Default          | Notes                                                        |
 | -------------------------- | ---------------------- | ---------------- | ------------------------------------------------------------ |
 | `:value`                   | `string`               | (required)       | The text to copy to clipboard (e.g., license key, API token).|
+| `:id`                      | `string`               | auto-generated   | Id applied to the input. Only pass one if something needs to target this input directly. |
+| `:name`                    | `string`               | falls back to `id` | Name applied to the input. Falls back to the resolved `id` (auto-generated or explicit) when not provided. |
 | `:label`                   | `string`               | (optional)       | Short label for the field; used in aria-label if ariaLabel not set. |
 | `:aria-label`              | `string`               | (optional)       | Custom aria-label for the input; overrides label.           |
 | `:description`             | `string`               | (optional)       | Helper text displayed below the input.                       |

package/.claude/skills/components/input-text-core.md

@@ -0,0 +1,186 @@
+# InputTextCore Component
+
+## Overview
+
+`InputTextCore` is the low-level native `<input>` primitive for the `05.forms` text-input family.
+It renders a single styled text-like input with left/right icon slots, focus/dirty state models,
+and numeric-pattern validation for `inputmode="numeric"`. It has no label, description, or error
+message rendering of its own — those are composed by the wrapper variants below.
+
+Most consumers should reach for one of the **Variants** rather than `InputTextCore` directly.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:input-variant`, `:aria-describedby`.
+
+| Prop (template form)       | Type                                                         | Default     | Notes                                                                 |
+| --------------------------- | ------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------- |
+| `:type`                     | `"text" \| "email" \| "password" \| "number" \| "tel" \| "url" \| "date"` | `"text"`    | Native input type.                                                     |
+| `:inputmode`                | `"text" \| "email" \| "tel" \| "url" \| "search" \| "numeric" \| "none" \| "decimal"` | `"text"`    | Sets virtual keyboard hint; `"numeric"` also enables pattern validation. |
+| `:maxlength`                | `number`                                                      | `255`       | Native `maxlength`.                                                   |
+| `:min`                      | `string \| number`                                            | (optional)  | Passed straight through to the native input — e.g. earliest allowed date for `type="date"`, or lowest number for `type="number"`. Use an ISO date string (`"2026-01-01"`) for `type="date"`. |
+| `:max`                      | `string \| number`                                            | (optional)  | Same as `min`, for the upper bound.                                   |
+| `:id`                       | `string`                                                      | (required)  | Applied to the native input.                                          |
+| `:name`                     | `string`                                                      | (required)  | Applied to the native input.                                          |
+| `:required`                 | `boolean`                                                     | `false`     | Native `required`.                                                    |
+| `:placeholder`              | `string`                                                      | `""`        | Native placeholder.                                                   |
+| `:field-has-error`          | `boolean`                                                     | `false`     | Drives `.error` class, `aria-invalid`, and forces `theme` to `"error"`. |
+| `:style-class-passthrough`  | `string \| string[]`                                          | `[]`        | Extra CSS classes applied to the wrapper.                             |
+| `:theme`                    | `FormUiTheme`                                                 | `"default"` | Overridden to `"error"` internally when `fieldHasError` is true.       |
+| `:aria-describedby`         | `string`                                                      | `""`        | Forwarded to the native input.                                        |
+| `:input-variant`            | `"normal" \| "outlined" \| "underlined"`                      | `"normal"`  | Visual style — border box vs. underline.                              |
+
+### v-models
+
+| Model             | Type      | Notes                                                     |
+| ----------------- | --------- | ---------------------------------------------------------- |
+| `v-model`          | `string`  | The input value.                                            |
+| `v-model:is-dirty` | `boolean` | Set to `true` once the wrapper variant detects a non-empty value at mount or on change. |
+| `v-model:is-active`| `boolean` | Tracks focus state (`focusin`/`focusout`).                   |
+
+---
+
+## Slots
+
+| Slot    | Notes                                                                 |
+| ------- | ---------------------------------------------------------------------- |
+| `left`  | Rendered before the input, inside the bordered wrapper (e.g. an icon or `InputButtonCore variant="inline"`). |
+| `right` | Rendered after the input, inside the bordered wrapper.                 |
+
+---
+
+## CSS Token Customization
+
+All `--input-text-*` tokens can be overridden at global, page, or instance scope, each falling back
+to the shared `--theme-*`/`--theme-input-*` tokens every other themed form component also uses. See
+`CONSUMER-STYLING.md` in the component directory for the full token table.
+
+**Common tokens:**
+- `--input-text-surface` — wrapper background
+- `--input-text-border` / `--input-text-border-hover` / `--input-text-border-focus` — border/outline colour
+- `--input-text-color` — input text colour
+- `--input-text-placeholder-color` — placeholder colour
+
+---
+
+## Using `min`/`max` for a native date picker
+
+`type="date"` plus `min`/`max` is the standard way to stop the browser's native date picker from
+offering dates outside an allowed range — e.g. preventing a booking date in the past:
+
+```vue
+<InputTextCore
+  id="appointment-date"
+  name="appointmentDate"
+  type="date"
+  v-model="appointmentDate"
+  :min="new Date().toISOString().split('T')[0]"
+  max="2027-12-31"
+/>
+```
+
+`min`/`max` are passed straight through with no validation of their own — the browser enforces the
+range in its native picker/typed-entry UI. Pair with server-side validation; a native `min`/`max`
+constraint is a UX affordance, not a substitute for validating the submitted value.
+
+---
+
+## Variants
+
+The `variants/` folder composes `InputTextCore` with `InputLabel`, `InputDescription`, and
+`InputError` for the common "labelled field" case. Each forwards `min`/`max` straight through if
+you pass them.
+
+### InputTextWithLabel
+
+The general-purpose labelled text field — supports every `InputTypesText` value including
+`"date"`.
+
+```vue
+<InputTextWithLabel
+  v-model="appointmentDate"
+  id="appointment-date"
+  name="appointmentDate"
+  type="date"
+  label="Appointment date"
+  :min="new Date().toISOString().split('T')[0]"
+  max="2027-12-31"
+  :error-message="errors.appointmentDate"
+  :field-has-error="!!errors.appointmentDate"
+/>
+```
+
+Props: same `type`/`inputmode`/`maxlength`/`min`/`max`/`name`/`placeholder`/`label`/`errorMessage`/
+`fieldHasError`/`required`/`styleClassPassthrough`/`theme`/`inputVariant` as `InputTextCore`, plus
+`label: string` (required) and `errorMessage: object | string` (required — pass `""` if unused).
+Slots: `left`, `right`, `descriptionHtml`, `descriptionText`.
+
+### InputPasswordWithLabel
+
+Adds a show/hide toggle button (`InputButtonCore variant="inline"` in the `right` slot) that swaps
+`type` between `"password"` and `"text"`.
+
+```vue
+<InputPasswordWithLabel
+  v-model="password"
+  name="password"
+  label="Password"
+  :error-message="errors.password"
+  :field-has-error="!!errors.password"
+  show-password-text="Show password"
+  hide-password-text="Hide password"
+/>
+```
+
+Extra props: `showPasswordText` (default `"Show password"`) and `hidePasswordText` (default
+`"Hide password"`) — the toggle button's accessible name in each state. Pass translated strings
+here for a non-English consumer app; there is no built-in i18n framework dependency.
+
+### InputTextAsNumberWithLabel
+
+A numeric stepper: left/right `InputButtonCore variant="inline"` buttons decrement/increment the
+value by `step`, disabled once `min`/`max` is reached.
+
+```vue
+<InputTextAsNumberWithLabel
+  v-model="quantity"
+  name="quantity"
+  label="Quantity"
+  :min="1"
+  :max="99"
+  :step="1"
+  step-down-text="Decrease quantity"
+  step-up-text="Increase quantity"
+>
+  <template #left>−</template>
+  <template #right>+</template>
+</InputTextAsNumberWithLabel>
+```
+
+Extra props: `min: number` (required), `max: number` (required), `step?: number` (default `1`),
+`stepDownText`/`stepUpText` (default `"Step down"`/`"Step up"`) — the decrement/increment buttons'
+accessible names. Requires `left`/`right` slot content for the step icons (no default icon).
+
+---
+
+## Accessibility
+
+- `field-has-error` sets `aria-invalid="true"` and forces the error theme, independent of what
+  `theme` was passed.
+- `inputmode="numeric"` adds a `pattern="[0-9]+"` and blocks non-numeric `beforeinput` edits that
+  would fail it.
+- Focus is tracked via native `focusin`/`focusout`, not a custom keyboard handler — `:focus-visible`
+  styling is preserved.
+- The password/number variants give their icon-only toggle/step buttons a real accessible name via
+  `InputButtonCore`'s `buttonText` (visually hidden via `.sr-only` when an icon-only slot is used).
+
+---
+
+## Notes
+
+- **No built-in label/error rendering**: `InputTextCore` alone renders no `<label>` or error text —
+  use a variant, or compose your own wrapper the same way they do.
+- **`min`/`max` need matching `type`**: they're inert on `type="text"`/`"email"`/etc. — only
+  `"date"` and `"number"` (native range-constrained types) act on them.

package/.claude/skills/components/masonry-grid.md

@@ -0,0 +1,153 @@
+---
+name: MasonryGrid
+description: MasonryGrid — real measured-height masonry layout (greedy shortest-column packing, animated resize), named dynamic slots, itemMinWidth/gap/fixedWidth/justify, CSS token API
+type: reference
+---
+
+# MasonryGrid
+
+## Overview
+
+`MasonryGrid` is a genuine masonry layout: each item is measured (its real rendered height) and
+placed into whichever column is currently shortest — a greedy bin-pack, the same technique
+Pinterest-style layouts use. This is different from (and better than) laying items out with CSS
+`columns`, which just fills one column's accumulated height before starting the next and has no
+awareness of "shortest column."
+
+Because placement follows natural DOM order directly (item 1 gets measured and placed first, then
+item 2, etc.), there's no reordering trick needed to keep visual and reading order in sync — DOM
+order *is* the packing order, so a screen reader or `Tab` key always encounters items 1, 2, 3...
+in the order they were authored, regardless of which column each one's height ends up landing it
+in visually.
+
+**History**: this component absorbed the implementation from `MasonryGridOrdered` (now retired —
+see **Migration history** below), replacing a CSS-`columns`-based reorder trick this component
+used previously (see `git log` / `ColumnFlowGrid`'s history for that era).
+
+## When to use this vs. `ColumnFlowGrid`
+
+- Use **`ColumnFlowGrid`** (`.claude/skills/components/column-flow-grid.md`) when you don't need
+  true masonry packing or animated reflow — a lighter CSS `columns`-only layout, no JS
+  measurement, no resize animation.
+- Use **`MasonryGrid`** when you want genuine Pinterest-style packing with items animating into
+  new positions on resize.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
+| `itemMinWidth` | `number` | `300` | Minimum tile width in pixels — also the fixed tile width when `fixedWidth` is set. |
+| `gap` | `number` | `12` | Gap between tiles in pixels. |
+| `fixedWidth` | `boolean` | `false` | Keep every tile at exactly `itemMinWidth` instead of stretching to fill each column. |
+| `justify` | `"left" \| "center" \| "right"` | `"left"` | How the block of tiles aligns within the wrapper — only visible when `fixedWidth` is set (tiles otherwise stretch to fill the full width, so there's nothing to align). |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slot API
+
+Any named slot is accepted — there are no declared slot names, and **no count/data prop to keep
+in sync**. Give slots in whatever order you want them read/tabbed through:
+
+```vue
+<MasonryGrid>
+  <template #item-1>...</template>
+  <template #item-2>...</template>
+  <template #item-3>...</template>
+</MasonryGrid>
+```
+
+## Basic usage
+
+```vue
+<MasonryGrid :item-min-width="280" :gap="16">
+  <template v-for="(photo, i) in photos" :key="photo.id" #[`item-${i}`]>
+    <img :src="photo.src" :alt="photo.alt" />
+  </template>
+</MasonryGrid>
+```
+
+### Fixed-width, centered
+
+```vue
+<MasonryGrid :fixed-width="true" justify="center" :item-min-width="240">
+  <template v-for="(card, i) in cards" :key="card.id" #[`item-${i}`]>
+    <Card v-bind="card" />
+  </template>
+</MasonryGrid>
+```
+
+## CSS Token Customization
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--masonry-grid-item-border-colour` | `var(--theme-border)` | Outline colour around each item |
+| `--masonry-grid-item-padding` | `1.2rem` | Inner padding of each item |
+| `--masonry-grid-transition-duration` | `0.3s` | How long an item takes to slide into its new position on resize |
+
+Column width, gap, fixed-width mode, and alignment are controlled via props, not CSS custom
+properties, since column count and item positions are computed in JS from measured pixel values.
+See `CONSUMER-STYLING.md` in the component folder.
+
+## Accessibility
+
+- The resize/reflow animation (`--masonry-grid-transition-duration`) is wrapped in
+  `@media (prefers-reduced-motion: no-preference)` — a visitor with reduced motion enabled sees
+  items snap to their new position with no transition.
+- DOM/tab order always matches slot authoring order (see Overview) — no additional ARIA is needed
+  to communicate item order.
+
+## Notes
+
+- **How positioning works**: on mount and on every measured resize, each item is read (`item.
+  offsetHeight`) in DOM order and placed at the top of whichever column currently has the least
+  accumulated height, via inline `--_position-top`/`--_position-left`/`--_element-width` custom
+  properties the component sets directly (not part of the public token API — these are internal
+  positioning state, not a styling surface). Column steps are computed in real pixels
+  (`itemWidth + gap`) rather than equal percentage slots of the container — a percentage slot only
+  matches the item's actual width when the item stretches to fill it (the default, non-`fixedWidth`
+  case); with `fixedWidth`, `justify`'s left/center/right offset is also computed here in JS
+  (`(wrapperWidth - totalContentWidth) / 2` for `center`, etc.), not via CSS `justify-content` —
+  that property has no effect on children once `position: absolute` takes them out of grid flow,
+  so it doesn't work here regardless of how it's set.
+- **Single-column fallback**: below the width needed for a second `itemMinWidth` column plus gap,
+  items render in normal CSS Grid flow (no absolute positioning) at a single, always-full-width
+  column (`grid-template-columns: 1fr`, ignoring `itemMinWidth` entirely) — there's nothing to
+  pack with only one column, so it always just fills the container rather than applying
+  `itemMinWidth`'s floor. `itemMinWidth` starts governing column width only once there's an actual
+  multi-column choice to make (two columns up).
+- **Column count is a JS estimate**: `Math.floor(measuredWidth / (itemMinWidth + gap))`. This
+  drives an underlying CSS Grid (`grid-template-columns`, with `768px`/`1024px`/`1280px` container
+  query breakpoints) as a no-JS-yet initial layout, which JS then overrides with absolute
+  positioning once it has real measurements — so there's no flash of unstyled/overlapping content
+  before the first `updateGrid()` run.
+- **Images without explicit dimensions** will change height after they load, but nothing currently
+  re-triggers a re-pack when that happens (only container resize does) — a known limitation
+  inherited from the original implementation. Set explicit `width`/`height` on images inside slots
+  to avoid this, or file a follow-up if it becomes a real problem.
+- **Migration history**: this component's algorithm was ported from `MasonryGridOrdered`
+  (`app/components/masonry-grid-ordered/MasonryGridOrdered.vue`), which is now retired along with
+  its `MasonryGridOrderedGridExperiment` sibling (an abandoned, more fragile alternative that
+  inferred CSS Grid's own auto-placement via `index % columnCount` rather than genuine shortest-
+  column packing — never used it). The port modernized typed props (dropped the unused
+  `mobilePreferredColCount` prop, and the CSS-string-with-validator `justify` prop became a real
+  union type), promoted CSS custom properties to a proper public token API, added
+  `prefers-reduced-motion` handling (missing before), and removed a redundant second
+  `useResizeObserver` call that duplicated the one `useElementSize` already sets up internally. It
+  also replaced `MasonryGrid`'s own previous CSS-`columns`-based reorder-trick implementation,
+  which is now `ColumnFlowGrid` (`.claude/skills/components/column-flow-grid.md`). No known
+  consumer app was using any of the old APIs/names.
+- **Found after the port, via manual testing**: the original's `--_position-left` used equal
+  percentage slots (`minIndex * (100 / columnCount)%`) for every mode. That's fine when items
+  stretch to fill their slot, but with `fixedWidth` the item is narrower than its slot, so the
+  unused slot space showed up as a much bigger gap than the `gap` prop actually specified — it
+  visually looked like `justify-content: space-between`. Also, the CSS `justify-content` the port
+  initially added (see above) turned out to be entirely dead: it has no effect on children once
+  `position: absolute` removes them from grid flow, so `justify` never did anything either.
+  Fixed by computing both column steps and the `justify` offset in real pixels in JS (see **How
+  positioning works** above) instead of relying on CSS for either.
+- **Found after that, testing narrow/mobile viewports**: the single-column CSS fallback template
+  was `minmax(itemMinWidth, 1fr)`, same as every other breakpoint — on a container narrower than
+  `itemMinWidth`, that floor fought the container instead of just filling it, producing a
+  non-full-width, misaligned single column. Fixed by making the single-column template a plain
+  `1fr` unconditionally (see **Single-column fallback** above) — `itemMinWidth` never had a
+  multi-column decision to inform in that case anyway.