# Layout catalogue schema

`data/layouts.json` contains versioned composition specifications. `scripts/build-layout-catalog.mjs` is the authored source and deterministic generator. It also generates `docs/layout-catalog.md`. Edit the source, then regenerate; do not hand-edit the generated catalogue.

## Root

| Field | Meaning |
| --- | --- |
| `$schema` | Relative path to the JSON Schema |
| `schemaVersion` | Contract version, currently `1.0.0` |
| `attribution` | Studio, author, role and website |
| `counts` | Actual layouts, families and section types |
| `defaults` | Minimal palette, motion and sound policy |
| `breakpoints` | Recipe breakpoints, independent of the generic CSS grid |
| `layouts` | Array of 200 materialized recipe objects |

## Layout

Stable `id` values use `sds-{family}-{two-digit-number}`. `name` is human-readable; `slug` is a display convenience. Use IDs for references rather than assuming display names never change. `family` and `siteTypes` support broad filtering, but the important selection fields are `intent`, `useWhen`, `avoidWhen`, content budgets and actual available content.

`pageSequence` includes navigation, ordered section type keys and footer. `sections` materializes each content section in that exact order. Navigation/footer are shared page responsibilities, not section objects. Repeated section types get distinct IDs. `status:"specification"` and `implementation` make the deliverable boundary explicit.

`preview`, when present, is the relative path to a runnable HTML composition scaffold. These previews use explicitly labeled sample content and illustrative generated images. They implement the specified reading sequence and responsive spans, but are not finished websites, working business applications or individually accessibility-audited releases. Rebuild them with `node scripts/build-layout-previews.mjs` after regenerating catalogue data.

`recommendedBrief` is editorial guidance, not an object to paste into the legacy brief API. `palette` and the explanatory heritage value are deliberately plain-language recommendations. Only supported `data-sds-*` values belong in markup.

## Section

Each section has an ID, `type`, `title`, `purpose` and `elements`. `columns` gives grid counts and intended spans at desktop/tablet/mobile. Desktop spans sum to twelve. Tablet spans may exceed eight across the list and therefore wrap to a new row. Mobile spans are all one in source order. Centered types such as `[2,8,2]` include spatial margin lanes; create grid offsets rather than empty semantic elements.

`contentBudget` gives recommended words, heading length and item ranges. These are planning targets, not hard validation limits. The root layout budget totals section targets, not a claim about a rendered page's actual word count.

`image` defines ratio, requirement, fit, mobile crop and alt direction. The layout's `images` budget counts media-bearing section slots, not the exact number of images in a gallery; item ranges may require more actual files. A code/chart specimen may be rendered as native HTML/SVG rather than a bitmap. Do not invent a photograph where the content calls for a real specimen.

`motionSlots`, `soundSlots` and `lottieSlots` are optional opportunities. Empty sound slots mean no suggested cue. A Lottie slot defines placement/role/fallback, not a filename. Accessibility and quality gates must be checked in the actual implementation.

## Example selection

```js
const catalog = await fetch('/system/data/layouts.json').then(r => r.json());
const candidates = catalog.layouts.filter(layout =>
  layout.siteTypes.includes('nonprofit') &&
  layout.contentBudget.words < 1100
);
const chosen = candidates.find(layout => layout.id === 'sds-nonprofit-04');
// Read chosen.sections; compose semantic HTML and local responsive CSS.
// The data does not render a finished page by itself.
```

Serve `data/` at the path you actually use; the example assumes a copied `/system/data/` directory. Do not treat selected recipes as permission for business deployment. Read [LICENSE](../LICENSE).

## Validation scope

The generator rejects duplicate IDs, duplicate ordered page sequences, unknown section types and invalid desktop span totals, and expects exactly 200 recipes. The JSON Schema describes the shape. Neither check replaces visual, keyboard, screen-reader, image, audio or content review. See [quality](quality.md).
