stylegallery 0.1.0

package/quality/gates/rationale.md

@@ -0,0 +1,53 @@
+---
+type: Quality Gate
+title: Rationale Gate
+description: Decision-rationale contract for quality gate judgments.
+---
+
+# Rationale Gate
+
+The rationale gate records why a claim is accepted, rejected, blocked, or deferred.
+
+## Required Rationale
+
+Record:
+
+- the question being decided;
+- considered options;
+- criteria used to compare options;
+- selected option;
+- warrant connecting evidence to the decision;
+- counterclaim or limitation;
+- debt, owner, and review trigger when accepted.
+
+## Evidence
+
+Useful rationale evidence includes:
+
+- structured claim records;
+- local repository constraints;
+- cited design-rationale, HCI, accessibility, or tooling sources;
+- rendered evidence;
+- accessibility evidence;
+- task or persona review;
+- user or participant evidence when the claim requires it.
+
+## Blocking Conditions
+
+Block a rationale when:
+
+- it hides a tradeoff;
+- it lists sources without saying what each source can and cannot support;
+- it accepts accessibility debt without affected users and a review trigger;
+- it reopens layout scope without naming the local repo rule being changed.
+
+## Boundary
+
+Rationale does not need to be long. It needs to make the claim, warrant, evidence, and limitation inspectable.
+
+When a rationale contains a high-impact design claim, route it through the [structured quality claim template](../claims.md#claim-record-template) or link to an existing claim record.
+
+## IA Navigation
+
+Parent: [Gate Contracts](index.md).
+Next: [Evidence References](../evidence/index.md) when a gate needs admissible support.

package/quality/gates/visual-evidence.md

@@ -0,0 +1,47 @@
+---
+type: Quality Gate
+title: Visual Evidence Gate
+description: Rendered evidence requirements and limits for visual QA claims.
+---
+
+# Visual Evidence Gate
+
+Visual QA evidence precedes visual judgment.
+
+## Scope
+
+Use this gate when a claim depends on rendered output, visual state, hierarchy, surface treatment, motion, or responsive visual behavior.
+
+## Accepted Evidence
+
+- screenshots across required viewports and states;
+- visual diffs against an approved baseline;
+- Storybook or equivalent state-level captures;
+- reduced-motion before/after evidence when motion is declared;
+- notes that identify what changed, what was expected, and what remains interpretive.
+
+## Required Boundary Language
+
+- Screenshot diffs show rendered change, not usability.
+- A stable visual diff does not prove accessibility.
+- Generated images, GPT Image references, and screenshots are not accessibility proof.
+- A visual QA pass does not prove brand fit or aesthetic quality.
+- Visual review must cite the principle, task, state, or brief it evaluates.
+
+## Blocking Conditions
+
+Block a rendered-evidence claim when:
+
+- no capture exists for the state being discussed;
+- an unapproved visual diff changes a declared contract;
+- a screenshot hides essential text, focus, state, or overflow evidence;
+- the claim uses rendered stability to erase accessibility or task failures.
+
+## Boundary
+
+Visual QA creates evidence. The design claim gate decides whether that evidence supports the claim.
+
+## IA Navigation
+
+Parent: [Gate Contracts](index.md).
+Next: [Evidence References](../evidence/index.md) when a gate needs admissible support.

package/quality/index.md

@@ -0,0 +1,55 @@
+# Quality Gates
+
+`quality/` is shared StyleGallery infrastructure for deciding whether Layout, Motion, Design Engineering, Game UI, and Platform Guides claims are admissible.
+
+This shared layer does not make the repository a visual design system. Layout pattern files still own spatial structure only; domain guidance cannot bypass these gates. Quality gates explain how claims are framed, what evidence can support them, and when review or debt is required.
+
+The [Consumer Reference Receiver Contract](../consumer-reference/contract.md) is adjacent shared infrastructure: it routes an optional consumer-owned record without turning Quality or Layout into owners of profile values.
+
+## Concepts
+
+- [Quality principles](principles.md) - Principles shared by the quality gate layer.
+- [Controlled vocabulary](../guides/vocabulary.md) - Canonical terms for claims, gates, warrants, boundaries, evidence families, harmony, and debt.
+- [Structured quality claims](claims.md) - Claim-record template, high-impact scope, and low-risk prose boundary.
+- [Gate index](gates/index.md) - Gate contracts for layout, design claims, visual evidence, accessibility evidence, and rationale.
+- [Evidence index](evidence/index.md) - Reference sources and evidence boundaries for design-side claims.
+- [Claim records](claim-records/index.md) - Filled examples for high-impact claims.
+- [Accessibility evidence register](evidence/accessibility.md) - Classification for accessibility claims: automated, manual, user, or debt.
+- [Executable evidence coverage](evidence/executable-evidence.md) - Validator, fixture, CI, rendered-evidence, and review boundaries.
+- [Consumer migration evidence gate](gates/consumer-migration-evidence.md) - Blocking contract for a declared consumer migration.
+- [Consumer migration evidence](evidence/consumer-migration.md) - Claim boundaries for runtime and source-bound page evidence.
+
+## Admission Model
+
+Every non-layout design claim should follow this chain:
+
+```txt
+principle -> claim -> context -> warrant -> evidence family -> verification protocol -> boundary/debt
+```
+
+Evidence is not the gate. Evidence supports a claim only when the principle, gate, warrant, and boundary are explicit.
+
+High-impact claims use the [claim record template](claims.md#claim-record-template). Low-risk prose can stay as prose when it does not approve, block, redirect, or hand off implementation work.
+
+## Tree-Test Findability QA
+
+Findability QA checks whether a reader can choose the correct route for a task without already knowing the repository structure.
+
+Use this script for lightweight tree tests:
+
+| Scenario | Start | Expected primary route | PASS condition |
+| --- | --- | --- | --- |
+| Build a homepage from raw content. | [README](../README.md) | [Webpage Generation Workflow](../guides/webpage-generation-workflow.md) | The reader chooses the workflow before a recipe or catalog entry. |
+| Choose a layout for a screen with unknown constraints. | [README](../README.md) | [Layout Planning Guide](../GUIDE.md) | The reader starts with planning instead of a primitive. |
+| Find a primitive for a known spatial problem. | [README](../README.md) | [Layout Pattern Catalog](../CATALOG.md) | The reader reaches the generated catalog. |
+| Browse all spatial families. | [OKF index](../index.md) | [Pattern Categories](../patterns/index.md) | The reader reaches category-level browsing. |
+| Verify whether a claim has enough evidence. | [README](../README.md) | [Quality Gates](index.md) | The reader reaches gates before evidence references. |
+| Inspect validator coverage. | [Quality Gates](index.md) | [Executable Evidence Coverage](evidence/executable-evidence.md) | The reader can name what each validator proves and cannot prove. |
+| Name an observed motion effect. | [README](../README.md) | [Motion Vocabulary](../motion/vocabulary.md) | The first selected route is Motion and the term reference is reached within two hops. |
+| Review product-level interface craft. | [README](../README.md) | [Interface Craft Decisions](../design-engineering/interface-craft.md) | The first selected route is Design Engineering and shared quality gates remain visible. |
+| Compare an Apple interaction convention. | [README](../README.md) | [Apple Interaction](../platform-guides/apple-interaction.md) | The first selected route is Platform Guides and source/version limits are reached within two hops. |
+| Declare whether a consumer reference applies. | [README](../README.md) | [Consumer Reference](../consumer-reference/index.md) | The handoff reaches the shared contract without classifying it as a sixth domain. |
+| Prove a consumer migration preserves declared behavior. | [README](../README.md) | [Consumer Migration Readiness](../design-engineering/consumer-migration-readiness.md) | The reader reaches the Design Engineering method and its evidence gate within two hops. |
+| Find the authority route for uGUI, UI Toolkit, or NGUI. | [README](../README.md) | [Unity UI Systems](../game-ui/unity/ui-systems.md) | The first selected route is Game UI, and the system-specific source and version boundary is reached within three hops. |
+
+Record `PASS` only when the expected primary route is the first route selected. A link resolving successfully is not enough; the selected route must match the task intent.

package/quality/principles.md

@@ -0,0 +1,58 @@
+---
+type: Quality Guide
+title: Quality Principles
+description: Shared principles for the StyleGallery quality gate layer.
+---
+
+# Quality Principles
+
+These principles govern the `quality/` layer. They sit beside the layout pattern contract and do not change the scope of reusable pattern CSS.
+
+## Principles
+
+1. Principles before evidence
+   - A source, screenshot, scan, or token file becomes useful only when attached to a clear claim.
+   - Do not use evidence pages as a link dump or hidden rulebook.
+
+2. Layout remains spatial
+   - Layout gates own structure, flow, sizing, alignment, spacing mechanics, scrolling, ratio, containment, source order, and focus order.
+   - Brand, typography voice, color expression, shadow, animation, decoration, and product visual identity stay outside reusable pattern CSS.
+
+3. Accessibility precedes taste
+   - Accessibility and task completion outrank visual preference.
+   - Automated accessibility scans assist evaluation; they do not determine accessibility by themselves.
+
+4. Visual QA evidence precedes visual judgment
+   - Rendered captures, state screenshots, and visual diffs should exist before visual critique claims.
+   - Screenshot diffs show rendered change, not usability.
+
+5. Subjective review needs a warrant
+   - A subjective objection can block only when tied to a principle, task, brief, persona, accessibility risk, provenance risk, or missing evidence.
+   - Otherwise it is a review note or design debt, not a gate failure.
+
+6. Tokens are contract surfaces
+   - Design tokens can support consistency, portability, and source lineage.
+   - A token file does not prove visual quality.
+
+7. Debt stays visible
+   - Accepted design or accessibility debt must name the affected users, evidence gap, owner, and review trigger.
+   - Critical accessibility or task-completion failures are not ordinary debt.
+
+## Outcomes
+
+- `pass`: evidence satisfies the gate within its stated boundary.
+- `review_required`: evidence exists, but human judgment is required.
+- `blocked`: a principle, accessibility requirement, task requirement, provenance boundary, or evidence requirement is violated.
+- `informational`: useful reference, but not an admissible quality claim.
+
+## Guardrail Vocabulary
+
+- `accessibility precedence`: accessibility and task completion outrank taste.
+- `visual QA limits`: rendered evidence supports review but does not decide design quality alone.
+- `screenshot diff limits`: screenshot diffs show rendered change, not usability.
+- `automated accessibility scan limits`: automated scans assist evaluation, not determine accessibility.
+
+## IA Navigation
+
+Parent: [Quality Gates](index.md).
+Next: [Gate Contracts](gates/index.md) for claim-specific pass and block conditions.

package/recipes/article-page.md

@@ -0,0 +1,52 @@
+---
+type: Layout Recipe
+title: Article Page
+description: Compose readable prose with optional supporting aside content.
+screen_type: Article page
+primary_user_task: Read a long document while referencing supporting material.
+spatial_model: Constrained reading column with nearby supplemental content.
+---
+
+# Article Page
+
+## Recommended Pattern Stack
+
+- [content-limiter](../patterns/containment/content-limiter.md)
+- [sticky-aside](../patterns/split-sidebar/sticky-aside.md)
+- [stack](../patterns/stacking/stack.md)
+
+## DOM And Source Order
+
+Place the article before supplemental aside content when the article is the primary reading path. Use headings to expose document structure before adding layout classes.
+
+## Scroll Ownership
+
+The document owns scrolling. The aside may become sticky, but it should not introduce an independent scroll container unless the aside content is longer than the viewport and has a declared overflow behavior.
+
+## Accessibility Expectations
+
+- Focus expectation: Article links and controls follow the article's DOM order before moving to supplemental aside content unless the aside is the active task.
+- Scroll expectation: Sticky aside behavior must not cover headings, anchors, or focused links while the document scrolls.
+- Cognitive risk: Supplemental content can interrupt reading flow; keep references close to the article section they support.
+
+## Responsive Behavior
+
+At narrow widths, aside content should fall into document flow after the related article region. Keep references close to the content they support.
+
+## Constraints And Change Points
+
+Make the reading measure explicit through `max-inline-size`. Use section gaps for major article regions and stack gaps for local prose groups.
+
+## When Not To Use
+
+Do not use sticky aside behavior when supplemental content must be read in sequence as part of the main article.
+
+## Related Patterns
+
+- [sidebar](../patterns/split-sidebar/sidebar.md)
+- [box](../patterns/containment/box.md)
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.

package/recipes/command-surface.md

@@ -0,0 +1,55 @@
+---
+type: Layout Recipe
+title: Command Surface
+description: Compose a tool-heavy shell with stable command and content regions.
+screen_type: Command surface
+primary_user_task: Repeatedly execute commands while inspecting or editing content.
+spatial_model: Stable shell regions with wrapping or scrolling command rows.
+---
+
+# Command Surface
+
+## Recommended Pattern Stack
+
+- [scroll-body-shell](../patterns/viewport-shell/scroll-body-shell.md)
+- [split-nav](../patterns/in-line-grouping/split-nav.md)
+- [wrap-row](../patterns/in-line-grouping/wrap-row.md)
+
+## DOM And Source Order
+
+Place primary commands before secondary command groups when they operate on the same surface. Keep command labels and controlled regions connected by accessible names or headings.
+
+## Scroll Ownership
+
+The shell body owns content scrolling. Command rows should wrap when possible; use [reel](../patterns/in-line-grouping/reel.md) only when horizontal scanning is part of the interaction model.
+
+## Accessibility Checklist
+
+- Source order: Put primary commands before secondary commands and before the content region they affect when the command is the task entry point.
+- Focus expectation: Keyboard focus must reach every command, preserve visible focus, and return to the edited or inspected content after command execution when appropriate.
+- Scroll expectation: Keep fixed command regions outside the body scroll container; if command groups overflow horizontally, provide a named scroll model and keyboard path.
+- Semantic risk: Icon-only or compact commands need accessible names, state, and grouping before layout classes compress them.
+- Cognitive risk: Tool-heavy surfaces increase recognition and mode burden; keep command grouping stable and avoid moving commands between breakpoints without a documented overflow model.
+- Verification method: Pair `automated` accessible-name checks with `manual` keyboard traversal, focus-return, and mode-state review; reserve `debt` for commands that intentionally require later assistive-technology testing.
+
+## Responsive Behavior
+
+At narrow widths, command groups should wrap into stable rows or move into a declared overflow region. Do not let command text resize the shell.
+
+## Constraints And Change Points
+
+Set explicit gaps for command groups and explicit shell height when the body scrolls internally. Keep fixed command regions outside the body scroll container.
+
+## When Not To Use
+
+Do not use this recipe for a simple content page with one or two actions. A [cluster](../patterns/in-line-grouping/cluster.md) inside normal document flow is enough.
+
+## Related Patterns
+
+- [reel](../patterns/in-line-grouping/reel.md)
+- [panel-layout](../patterns/viewport-shell/panel-layout.md)
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.

package/recipes/dashboard.md

@@ -0,0 +1,56 @@
+---
+type: Layout Recipe
+title: Dashboard
+description: Compose repeated panels and action clusters on a page grid.
+screen_type: Dashboard
+primary_user_task: Scan and compare repeated status, metric, or workflow panels.
+spatial_model: Page grid containing repeated local grids and action groups.
+---
+
+# Dashboard
+
+## Recommended Pattern Stack
+
+- [page-grid](../patterns/grid-repetition/page-grid.md)
+- [card-grid](../patterns/grid-repetition/card-grid.md)
+- [cluster](../patterns/in-line-grouping/cluster.md)
+
+## DOM And Source Order
+
+Order panels by decision priority, not by visual symmetry. Headings and filters should precede the regions they control.
+
+## Scroll Ownership
+
+Prefer normal document scrolling. Introduce internal scroll containers only for panels whose independent scroll state is part of the task.
+
+## Accessibility Checklist
+
+- Source order: Order panels by the decision path a reader should follow; do not let grid placement make lower-priority panels read first.
+- Focus expectation: Filters, chart controls, and panel actions must follow the same priority order as their controlled regions.
+- Scroll expectation: If a panel scrolls internally, name the panel, keep its heading outside or at the start of that scroll region, and verify focus is not trapped inside it.
+- Semantic risk: Repeated metric cards can become anonymous groups; use headings, table/list semantics, or labelled regions before applying grid classes.
+- Cognitive risk: Dense dashboards increase comparison load; group metrics by task and avoid relying on position or color alone to explain status.
+- Verification method: Combine `automated` landmark/heading/contrast checks with `manual` keyboard, source-order, and cognitive walkthrough evidence; use `user` evidence for task-completion claims.
+
+## Responsive Behavior
+
+Let repeated panels reflow through grid constraints before adding viewport breakpoints. Action clusters should wrap before they overflow.
+
+## Constraints And Change Points
+
+Make page gutters, panel gaps, and minimum panel widths explicit. Avoid hiding a panel's overflow unless the panel has a declared fixed block size.
+
+## When Not To Use
+
+Do not use this recipe for a single focused workflow. A [form flow](form-flow.md) or [content-limiter](../patterns/containment/content-limiter.md) is usually clearer.
+
+## Related Patterns
+
+- [ram-grid](../patterns/grid-repetition/ram-grid.md)
+- [dense-grid](../patterns/grid-repetition/dense-grid.md)
+- [wrap-row](../patterns/in-line-grouping/wrap-row.md)
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.

package/recipes/form-flow.md

@@ -0,0 +1,55 @@
+---
+type: Layout Recipe
+title: Form Flow
+description: Compose sequential form content with constrained width and reachable actions.
+screen_type: Form flow
+primary_user_task: Complete a sequence of related inputs.
+spatial_model: Single primary column with grouped fields and action placement.
+---
+
+# Form Flow
+
+## Recommended Pattern Stack
+
+- [content-limiter](../patterns/containment/content-limiter.md)
+- [stack](../patterns/stacking/stack.md)
+- [cluster](../patterns/in-line-grouping/cluster.md)
+
+## DOM And Source Order
+
+Keep labels, descriptions, fields, and errors adjacent in DOM order. Group related fields under semantic headings before adding layout classes.
+
+## Scroll Ownership
+
+Prefer document scrolling. If actions must remain visible, use a shell or footer pattern only after confirming it does not obscure validation messages or focus targets.
+
+## Accessibility Checklist
+
+- Source order: Keep each label, description, input, hint, and error adjacent in DOM order, even when groups are visually split into columns.
+- Focus expectation: Keyboard focus must move through fields, validation messages, and actions in the same sequence a user completes the form.
+- Scroll expectation: Sticky or fixed actions must not cover focused fields, inline errors, or the first invalid field after submission.
+- Semantic risk: Group related controls with fieldset/legend or labelled sections before adding stack or cluster layout classes.
+- Cognitive risk: Long flows create memory burden; expose step context, error recovery, and required/optional state without depending on color alone.
+- Verification method: Use `automated` form-name/error association checks where possible, then `manual` keyboard and error-recovery review; use `user` evidence for completion-rate or comprehension claims.
+
+## Responsive Behavior
+
+Field groups should stack naturally. Action groups should wrap before they overflow and should preserve a clear primary action position.
+
+## Constraints And Change Points
+
+Use readable inline constraints for the form body. Keep field gaps, group gaps, and action gaps separate so density can change without changing structure.
+
+## When Not To Use
+
+Do not use this recipe for a data-dense editor where users compare many fields at once. A dashboard or panel layout may be more appropriate.
+
+## Related Patterns
+
+- [sticky-footer](../patterns/viewport-shell/sticky-footer.md)
+- [line-up](../patterns/stacking/line-up.md)
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.

package/recipes/homepage.md

@@ -0,0 +1,89 @@
+---
+type: Layout Recipe
+title: Homepage
+description: Compose raw content into a homepage or ordinary webpage before product-level visual styling.
+screen_type: Homepage
+primary_user_task: Understand the offer, find the right next path, and decide whether to act.
+spatial_model: First-viewport hook followed by stacked explanation, proof, comparison, conversion, and navigation sections.
+---
+
+# Homepage
+
+Use this recipe when raw content needs to become a homepage, landing page, campaign page, or general webpage and no narrower recipe has been chosen yet.
+
+## Recommended Pattern Stack
+
+- [cover](../patterns/viewport-shell/cover.md)
+- [content-limiter](../patterns/containment/content-limiter.md)
+- [stack](../patterns/stacking/stack.md)
+- [cluster](../patterns/in-line-grouping/cluster.md)
+- [ram-grid](../patterns/grid-repetition/ram-grid.md)
+- [frame](../patterns/media-fit/frame.md)
+
+## Content-To-Layout Matching
+
+Map content blocks to section jobs before selecting visual treatment.
+
+- Hook: use `cover` or a constrained first section when the opening message needs viewport-level framing.
+- Explain: use `content-limiter` and `stack` for readable copy and progressive disclosure.
+- Prove: use `ram-grid`, `card-grid`, or `columns` for testimonials, metrics, logos, examples, or repeated evidence.
+- Compare: use a grid or sidebar composition only when comparisons need alignment or nearby support.
+- Convert: use `cluster` or `wrap-row` for CTA groups that must wrap before overflow.
+- Navigate or retain: use footer, link clusters, or repeated navigation groups after the primary action path.
+
+Reject this recipe when the page is primarily a document, dashboard, form, command surface, or list-detail workflow.
+
+## DOM And Source Order
+
+Order sections by the visitor's decision path, not by visual symmetry. Put the primary heading, explanation, proof, and action in semantic order before layout classes. Repeated proof should be a list when each item has the same role.
+
+## Scroll Ownership
+
+Prefer normal document scrolling. Avoid nested scroll regions unless a section has an explicit independent task, such as a horizontally scrolling media reel with named keyboard and overflow behavior.
+
+## Accessibility Expectations
+
+- Focus expectation: Navigation, primary CTA, proof links, and conversion actions follow the visitor decision path declared in DOM order.
+- Scroll expectation: Any carousel, reel, sticky CTA, or first-viewport treatment must declare keyboard access and avoid hiding focused content.
+- Cognitive risk: Marketing hierarchy can overstate meaning visually; headings, section jobs, and CTA labels must make the same path understandable without the generated image.
+
+## Responsive Behavior
+
+Let sections collapse through intrinsic sizing, content limits, wrapping action rows, and repeat grids before adding viewport breakpoints. Keep the first viewport readable on narrow screens; do not require a generated hero image to carry essential text.
+
+## Constraints And Change Points
+
+Declare content measure, section gaps, page gutters, repeat-grid minimums, media ratios, and CTA wrapping thresholds. Treat brand color, typography, shadows, borders, and motion as product-level decisions outside this recipe.
+
+## GPT Image Reference
+
+Use the [Webpage Generation Workflow](../guides/webpage-generation-workflow.md) before generating the GPT Image reference. The prompt should describe the approved semantic order, section jobs, pattern stack, constraints, and harmony notes. After generation, extract hierarchy, spacing, media treatment, and CTA priority; keep decorative styling in the consuming product.
+
+Required preconditions before prompt:
+
+- Use case, audience, section jobs, semantic order, pattern stack, scroll owner, constraints, and harmony evaluation are approved.
+
+Image review extract-vs-ignore:
+
+- Extract section rhythm, hierarchy, approximate spacing, media treatment, and CTA priority.
+- Ignore decorative choices that belong to the consuming product or conflict with source order, accessibility, constraints, or content stress behavior.
+
+## Harmony Evaluation
+
+Use the [Harmony evaluation gate](../quality/gates/harmony-evaluation.md) before implementation. If hierarchy, rhythm, accessibility, or source order conflict with the visual reference, the layout contract wins and the image prompt should be regenerated.
+
+## When Not To Use
+
+Do not use this recipe to force marketing-page structure onto task-heavy apps, documentation, long articles, settings, or list-detail workflows.
+
+## Related Patterns
+
+- [page-grid](../patterns/grid-repetition/page-grid.md)
+- [card-grid](../patterns/grid-repetition/card-grid.md)
+- [sidebar](../patterns/split-sidebar/sidebar.md)
+- [sticky-footer](../patterns/viewport-shell/sticky-footer.md)
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.

package/recipes/index.md

@@ -0,0 +1,13 @@
+# Layout Recipes
+
+Recipes combine layout patterns into screen-level spatial models.
+
+Use the [primitive to recipe matrix](primitive-to-recipe-matrix.md) when you need pattern coverage, slot classification, lineage, and substitution risk across recipes.
+
+- [Homepage](homepage.md) - Content-led webpage composition with hero, proof, explanation, conversion, and navigation sections.
+- [SaaS settings](saas-settings.md) - Fixed navigation with a constrained settings flow.
+- [Dashboard](dashboard.md) - Repeated metric and panel regions on a page grid.
+- [Article page](article-page.md) - Readable prose with supporting aside content.
+- [List detail](list-detail.md) - Explorable list beside a detail region.
+- [Form flow](form-flow.md) - Sequential form content with reachable actions.
+- [Command surface](command-surface.md) - Tool-heavy shell with stable command regions.

package/recipes/list-detail.md

@@ -0,0 +1,55 @@
+---
+type: Layout Recipe
+title: List Detail
+description: Compose an explorable list beside its selected detail region.
+screen_type: List detail
+primary_user_task: Browse a collection and inspect one selected item.
+spatial_model: Peer list and detail regions with explicit scroll ownership.
+---
+
+# List Detail
+
+## Recommended Pattern Stack
+
+- [list-detail](../patterns/split-sidebar/list-detail.md)
+- [scroll-body-shell](../patterns/viewport-shell/scroll-body-shell.md)
+- [stack](../patterns/stacking/stack.md)
+
+## DOM And Source Order
+
+Place list controls before list results. Place detail content after the list in DOM order unless the detail is the primary task entry point.
+
+## Scroll Ownership
+
+Name whether the list, the detail region, or the page body owns scrolling. Avoid making both list and detail scroll independently unless the task requires side-by-side comparison.
+
+## Accessibility Checklist
+
+- Source order: Put list controls before list results, then the selected detail, unless the detail is the primary entry point for the task.
+- Focus expectation: Selecting a list item must either keep focus on the selected item with the detail announced by context, or move focus to the detail heading with a documented return path.
+- Scroll expectation: If list and detail scroll independently, name both regions and verify keyboard users can reach and leave each scroll container.
+- Semantic risk: The list, selected state, and detail region need roles, headings, or labels that expose their relationship before split-sidebar layout is applied.
+- Cognitive risk: Users can lose context when selection changes the detail region; preserve selected state, count/position, and clear return behavior.
+- Verification method: Use `automated` landmark/name checks, `manual` focus-return and scroll-container review, and `user` evidence for browse-and-compare task success claims.
+
+## Responsive Behavior
+
+At narrow widths, the list and detail regions should stack in a predictable order. Preserve focus return behavior when selecting an item changes the detail region.
+
+## Constraints And Change Points
+
+Set a minimum list width and a dominant detail width. Make shell height explicit when scroll ownership is internal to the viewport.
+
+## When Not To Use
+
+Do not use this recipe when the detail page is a full navigation destination. Use ordinary page navigation and a [content-limiter](../patterns/containment/content-limiter.md) instead.
+
+## Related Patterns
+
+- [supporting-pane](../patterns/split-sidebar/supporting-pane.md)
+- [fixed-sidenav-shell](../patterns/viewport-shell/fixed-sidenav-shell.md)
+
+## IA Navigation
+
+Parent: [Layout Recipes](index.md).
+Next: [Quality Gates](../quality/index.md) for claim checks, or [Layout Pattern Catalog](../CATALOG.md) when replacing a primitive.