stylegallery 0.1.0

package/AGENTS.md

@@ -0,0 +1,156 @@
+---
+type: Agent Instructions
+title: StyleGallery agent instructions
+description: Rules coding agents must follow when editing this governed multi-domain gallery.
+---
+
+# Agent Instructions
+
+This repository is StyleGallery: a governed gallery with Layout, Motion, Design Engineering, Game UI, and Platform Guides domains. Read [StyleGallery Domains](DOMAINS.md) before adding a domain, changing a domain boundary, or adapting an external source.
+
+Before editing generated artifacts, validators, lifecycle state, or ownership policy, read [Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md).
+
+## Core Rules
+
+- Classify every change by domain before editing.
+- Keep domain-local guidance inside its owning path and preserve shared evidence boundaries.
+- Do not use one domain to bypass another domain's constraints.
+- Treat `consumer-reference/` as shared non-domain schema, provenance, routing, and evidence infrastructure; it owns no profile values, visual defaults, component implementation, or product CSS.
+- Keep dependency direction consumer/profile -> Layout. Do not import consumer-reference records, profile data, tokens, or decorative values into `layout/**`, `patterns/**`, `scripts/pattern-data.mjs`, or `CATALOG.md`.
+- Include the consumer-reference handoff field in implementation handoffs. Use one normalized repository-relative JSON record or `not_applicable` with a sentence reason.
+- Treat `patterns/**`, `recipes/**`, `GUIDE.md`, and `CATALOG.md` as the Layout corpus at their existing paths.
+- Treat the Layout domain as a layout pattern library, not a visual design system.
+- Start with semantic HTML before adding layout classes.
+- Keep DOM order, reading order, and focus order logical.
+- Keep each pattern focused on one primary spatial problem.
+- Allow secondary spatial behavior only when it is required for composition.
+- Use the smallest robust set of CSS declarations, not the fewest fragile declarations.
+- Prefer plain HTML and CSS as the source of truth.
+- Make constraints explicit: widths, heights, gaps, breakpoints, scroll containers, and fixed or sticky anchors should be easy to find.
+- Make scroll responsibility obvious in both class names and CSS.
+- Keep decorative styling out of reusable pattern CSS.
+
+The remaining pattern, CSS, naming, token, checklist, and verification rules apply to the Layout domain. Non-Layout domain documents may discuss product-layer behavior, but they do not authorize decorative or motion properties in reusable Layout pattern CSS.
+
+## Pattern Boundary Gate
+
+Before adding a new pattern or changing reusable pattern CSS, check [Layout Decision Tree](guides/decision-tree.md) and [Layout Brief Template](guides/layout-brief.md).
+
+- Decide whether the work is a new pattern, a recipe composition, or product styling outside this repository.
+- Name the layout owner, scroll owner, core layout declarations, excluded demo/product styling, and likely breaking content case.
+- For scroll or responsive changes, include the failure case the pattern prevents, such as a missing shrink constraint or a viewport breakpoint used for component-local behavior.
+- Add a new pattern only when existing patterns or recipes do not already cover the spatial responsibility.
+
+## CSS Authoring
+
+- Use layout properties only unless a non-layout property is required to explain layout behavior.
+- Prefer low-specificity, single-class selectors.
+- Do not use ID selectors for styling or layout naming.
+- Avoid deep combinators, selector chaining, element-qualified classes, and nesting unless the pattern explicitly demonstrates that tradeoff.
+- Use cascade layers when the CSS surface grows beyond isolated snippets.
+- Keep CSS declarations in alphabetical order inside each rule.
+- Prefer intrinsic sizing and content/container-driven adaptation.
+- Use viewport breakpoints only for viewport-level patterns.
+- Prefer container queries for component-local responsiveness.
+- Prefer logical properties for spacing and sizing unless physical direction is required.
+- Use state hooks or `data-*` attributes for variants instead of escalating selector specificity.
+
+## CSS Scope
+
+Allowed by default:
+
+- `align-*`
+- `aspect-ratio`
+- `block-size`
+- `box-sizing`
+- `container-*`
+- `display`
+- `flex-*`
+- `gap`
+- `grid-*`
+- `height`
+- `inline-size`
+- `inset`
+- `justify-*`
+- `margin`
+- `margin-block`
+- `margin-inline`
+- `max-*`
+- `min-*`
+- `overflow`
+- `padding`
+- `padding-block`
+- `padding-inline`
+- `place-*`
+- `position`
+- `width`
+- `z-index`
+
+Avoid in reusable pattern CSS unless there is a layout-specific reason:
+
+- `animation`
+- `background`
+- `border`
+- `border-radius`
+- `box-shadow`
+- `color`
+- `filter`
+- `font-*`
+- `opacity`
+- `text-*`
+- `transition`
+- `transform`
+
+## Class Naming
+
+- Class names must describe layout responsibility, not visual appearance.
+- Class names should make relationships obvious: root-child, parent-child, area-element, and fixed-scroll relationships.
+- Prefer pattern-scoped names for related nodes.
+- Avoid vague names like `container`, `wrapper`, `box`, `top`, `content`, and `bottom` unless the surrounding pattern name makes their responsibility unambiguous.
+- Avoid DOM-depth names that mirror every nested node; name stable roles instead.
+- Do not use IDs for layout naming. Use IDs only for JavaScript hooks or document-level targets when needed.
+
+Example:
+
+```html
+<div class="fixed_header_layout">
+    <header class="fixed_header_layout_header"></header>
+    <main class="fixed_header_layout_scroll_area"></main>
+</div>
+```
+
+## Value And Token Policy
+
+- Tokenize reusable design intent, not every layout number.
+- Use tokens for stable shared values such as content width, gutters, stack gaps, section gaps, and density steps.
+- Keep browser/context mechanics in raw CSS: `auto`, percentages, intrinsic sizing, viewport units, and container-query units.
+- Put tokens behind logical CSS, for example `padding-block: var(--space-4)`.
+- Use breakpoint names for layout states, not device names.
+
+## Pattern Checklist
+
+Before finishing a pattern change, check:
+
+- Does the pattern optimize one primary spatial problem?
+- Can the DOM structure be understood without the CSS?
+- Are semantic HTML elements used before layout classes?
+- Are class names semantically clear and relationship-aware?
+- Is every CSS declaration necessary for robust behavior?
+- Are declarations alphabetized?
+- Is selector specificity low and intentional?
+- Is scroll ownership explicit?
+- Are constraints and change points easy to find?
+- Did decorative styling stay out of the reusable pattern?
+
+## Verification Checklist
+
+Verify the smallest relevant matrix for the change:
+
+- Viewports: `320px`, `375px`, `768px`, `1024px`, `1440px`
+- Containers: tight, medium, roomy, and `100%` parent
+- Content: empty, short, long label, long paragraph, unbroken string
+- Direction: `ltr` and `rtl`
+- Writing mode: default, plus vertical writing mode if the pattern claims support
+- Interaction: default, hover, focus, active, expanded, scroll top/middle/bottom when relevant
+
+If there is no runnable gallery surface yet, inspect the snippets directly and report that manual browser verification is not available.

package/CATALOG.md

@@ -0,0 +1,69 @@
+---
+type: Catalog
+title: Layout Pattern Catalog
+description: Generated index of layout-gallery patterns.
+---
+
+# Layout Pattern Catalog
+
+Primary role: pattern lookup.
+
+<!-- Generated from `scripts/generate-patterns.mjs` and `scripts/pattern-data.mjs`. Do not hand-edit generated catalog or pattern docs; edit the source files and regenerate. -->
+
+Generated from `scripts/generate-patterns.mjs` and `scripts/pattern-data.mjs`.
+
+## Planning Layer
+
+- [Layout Planning Guide](GUIDE.md) - Pre-design entry point for choosing and composing patterns.
+- [Decision Tree](guides/decision-tree.md) - Question-driven route from screen constraints to pattern categories.
+- [Layout Brief](guides/layout-brief.md) - Questions to answer before selecting a pattern stack.
+- [Layout Recipes](recipes/index.md) - Screen-level compositions built from reusable patterns.
+
+## Patterns
+
+- [stack](patterns/stacking/stack.md) - Stacking: Create consistent vertical rhythm between direct children.
+- [box](patterns/containment/box.md) - Containment: Wrap content with predictable internal spacing.
+- [center](patterns/centering/center.md) - Centering: Center a block while respecting a maximum measure.
+- [cluster](patterns/in-line-grouping/cluster.md) - In-line grouping: Keep related items together while allowing wrapping.
+- [content-limiter](patterns/containment/content-limiter.md) - Containment: Keep prose width readable inside fluid containers.
+- [super-center](patterns/centering/super-center.md) - Centering: Center one region along both axes.
+- [icon-frame](patterns/media-fit/icon-frame.md) - Media / Fit: Keep an icon aligned inside a fixed square slot.
+- [frame](patterns/media-fit/frame.md) - Media / Fit: Preserve media aspect ratio in a responsive slot.
+- [cover](patterns/viewport-shell/cover.md) - Viewport / Shell: Keep a central region balanced between optional header and footer.
+- [sidebar](patterns/split-sidebar/sidebar.md) - Split / Sidebar: Let a narrow sidebar and wider content wrap when space is tight.
+- [switcher](patterns/split-sidebar/switcher.md) - Split / Sidebar: Switch equal regions from row to stack without a viewport breakpoint.
+- [media-object](patterns/split-sidebar/media-object.md) - Split / Sidebar: Align media and descriptive content as a stable pair.
+- [split-nav](patterns/in-line-grouping/split-nav.md) - In-line grouping: Separate primary and secondary nav actions in one row.
+- [holy-grail](patterns/viewport-shell/holy-grail.md) - Viewport / Shell: Place header, footer, sidebars, and main content in a resilient shell.
+- [sticky-footer](patterns/viewport-shell/sticky-footer.md) - Viewport / Shell: Keep footer at the bottom when content is short.
+- [sticky-header](patterns/viewport-shell/sticky-header.md) - Viewport / Shell: Keep a header visible above a scrolling content region.
+- [scroll-body-shell](patterns/viewport-shell/scroll-body-shell.md) - Viewport / Shell: Keep shell regions fixed while only the body scrolls.
+- [fixed-sidenav-shell](patterns/viewport-shell/fixed-sidenav-shell.md) - Viewport / Shell: Keep side navigation stable while main content scrolls.
+- [sticky-aside](patterns/split-sidebar/sticky-aside.md) - Split / Sidebar: Keep related aside content visible during long reads.
+- [ram-grid](patterns/grid-repetition/ram-grid.md) - Grid / Repetition: Repeat items into as many useful columns as space allows.
+- [card-grid](patterns/grid-repetition/card-grid.md) - Grid / Repetition: Align repeating cards in rows and columns.
+- [twelve-span-grid](patterns/grid-repetition/twelve-span-grid.md) - Grid / Repetition: Provide a twelve-column placement scaffold.
+- [page-grid](patterns/grid-repetition/page-grid.md) - Grid / Repetition: Align page content to margins, gutters, and a central track.
+- [grid-wrapper](patterns/grid-repetition/grid-wrapper.md) - Grid / Repetition: Center grid tracks while allowing full-width breakout tracks.
+- [columns](patterns/grid-repetition/columns.md) - Grid / Repetition: Flow long content into balanced text columns.
+- [deconstructed-pancake](patterns/in-line-grouping/deconstructed-pancake.md) - In-line grouping: Let equal cards stretch in a row and stack naturally when narrow.
+- [line-up](patterns/stacking/line-up.md) - Stacking: Keep card footer actions aligned at the bottom.
+- [clamped-card](patterns/containment/clamped-card.md) - Containment: Constrain a card to a readable fluid width.
+- [fluid-styles](patterns/containment/fluid-styles.md) - Containment: Let a region fill available width without exceeding a readable max.
+- [split-screen](patterns/split-sidebar/split-screen.md) - Split / Sidebar: Split a viewport or region into two balanced panes.
+- [list-detail](patterns/split-sidebar/list-detail.md) - Split / Sidebar: Place an explorable list beside its detail region.
+- [supporting-pane](patterns/split-sidebar/supporting-pane.md) - Split / Sidebar: Keep supplemental information beside a primary task.
+- [feed](patterns/stacking/feed.md) - Stacking: Stack repeated content items with stable rhythm.
+- [breadcrumb](patterns/in-line-grouping/breadcrumb.md) - In-line grouping: Lay out hierarchy links compactly with wrapping.
+- [pagination](patterns/in-line-grouping/pagination.md) - In-line grouping: Lay out page controls as a bounded wrapping row.
+- [badge-list](patterns/in-line-grouping/badge-list.md) - In-line grouping: Align item labels with trailing counts.
+- [step-nav](patterns/stacking/step-nav.md) - Stacking: Present sequential steps with consistent vertical rhythm.
+- [tab-strip](patterns/in-line-grouping/tab-strip.md) - In-line grouping: Keep peer tabs in one stable row that can wrap.
+- [reel](patterns/in-line-grouping/reel.md) - In-line grouping: Let a row scroll horizontally instead of wrapping.
+- [imposter](patterns/overlay-exception/imposter.md) - Overlay / Exception: Place an overlay region over a parent without changing document order.
+- [panel-layout](patterns/viewport-shell/panel-layout.md) - Viewport / Shell: Create predictable main and utility panels.
+- [overlay-stack](patterns/overlay-exception/overlay-stack.md) - Overlay / Exception: Stack several regions into the same grid cell.
+- [wrap-row](patterns/in-line-grouping/wrap-row.md) - In-line grouping: Wrap controls into rows with stable gaps.
+- [dense-grid](patterns/grid-repetition/dense-grid.md) - Grid / Repetition: Fill a compact grid with repeated small items.
+- [masonry-approx](patterns/grid-repetition/masonry-approx.md) - Grid / Repetition: Approximate staggered content with columns when exact row alignment is not needed.
+- [main-with-rail](patterns/split-sidebar/main-with-rail.md) - Split / Sidebar: Keep primary content dominant with a narrow secondary rail.

package/DOMAINS.md

@@ -0,0 +1,65 @@
+---
+type: Domain Manifest
+title: StyleGallery Domains
+description: Canonical domain ownership, scope, lifecycle, page membership, and provenance policy.
+---
+
+# StyleGallery Domains
+
+Primary role: domain manifest.
+
+This manifest is the source of truth for top-level StyleGallery domains. A domain owns a coherent decision surface; a category is a domain-local browse placement and must not be used as a synonym for domain.
+
+## Domain Contract
+
+| Domain | Hub | Lifecycle | Owns | Does not own | Review owner |
+| --- | --- | --- | --- | --- | --- |
+| Layout | [Layout](layout/index.md) | `stable` and `generated` | Spatial patterns, recipes, planning, constraints, and scroll ownership. | Product motion, visual treatment, or platform imitation. | Pattern-data owner |
+| Motion | [Motion](motion/index.md) | `experimental` | Motion naming, review procedure, and bounded practice guidance. | Universal prescriptions or reusable Layout CSS. | Motion domain owner |
+| Design Engineering | [Design Engineering](design-engineering/index.md) | `experimental` | Product-layer craft questions and evidence-bearing decisions. | A second shared principle system or taste as proof. | Design Engineering domain owner |
+| Game UI | [Game UI](game-ui/index.md) | `experimental` | Game-interface classification, hierarchy, reference records, and implementation guides nested by engine. | Reusable Layout CSS or claims that one engine structure is universal. | Game UI domain owner |
+| Platform Guides | [Platform Guides](platform-guides/index.md) | `experimental` | Comparative references for a named platform and version context. | Affiliation, brand imitation, or authority over web standards. | Platform Guides domain owner |
+
+## Page Manifest
+
+| Domain | Manual hub | Governed leaves |
+| --- | --- | --- |
+| Layout | `layout/index.md` | Existing `GUIDE.md`, Layout-specific `guides/*.md`, and `recipes/*.md`; generated `patterns/**/*.md` and `CATALOG.md` remain at current paths. Shared `quality/**/*.md` infrastructure governs every domain without becoming a Layout leaf. |
+| Motion | `motion/index.md` | `motion/vocabulary.md`, `motion/review-workflow.md`, `motion/practice-reference.md` |
+| Design Engineering | `design-engineering/index.md` | `design-engineering/interface-craft.md`, `design-engineering/consumer-migration-readiness.md`, `design-engineering/reference-profiles/index.md`, `design-engineering/reference-profiles/governed-local/index.md`, `design-engineering/reference-profiles/external-adaptation/index.md` |
+| Game UI | `game-ui/index.md` | `game-ui/classification.md`, `game-ui/screen-hierarchy.md`, `game-ui/reference-record.md`, `game-ui/unity/architecture.md`, `game-ui/unity/ui-systems.md`, `game-ui/unity/cli-loop.md`, `game-ui/unity/repository-map.md`, `game-ui/unity/org-wiki.md` |
+| Platform Guides | `platform-guides/index.md` | `platform-guides/apple-interaction.md` |
+
+## Shared Non-Domain Infrastructure
+
+[Consumer Reference](consumer-reference/index.md) is shared schema, provenance, routing, and evidence infrastructure outside the five-domain contract. It owns no profile implementation or visual values and cannot add a sixth domain row. Consumer or profile records may depend on Layout; Layout and its generated corpus cannot import those records.
+
+## External Adaptation Contract
+
+The initial five domain leaves are independent method rewrites inspired by [emilkowalski/skills](https://github.com/emilkowalski/skills) at snapshot `220e8607c90b17337d210125777b7b695f26c221`. Other adapted leaves record their own repositories and revisions in page metadata.
+
+- Each externally adapted leaf records `source_repository`, exact `source_path`, and the full `source_revision`. Locally authored synthesis leaves state that boundary in their attribution section and omit upstream metadata.
+- A full SHA identifies source content; it does not prove publisher authenticity or local quality.
+- The local pages do not retain upstream prose, tables, code samples, distinctive examples, or distinctive sequence.
+- Apple/WWDC-derived expression and quotations attributed to other authors, including the Paul Graham quotation noted during review, are excluded.
+- If recognizable upstream expression is added later, preserve the full upstream MIT notice and record the copied material separately before merge.
+- Tracked repository documents must not depend on `.omo/`; stable upstream blob links and tracked repository contracts carry contributor-facing provenance.
+
+`design-engineering/consumer-migration-readiness.md` is the separately declared StyleGallery-local leaf. It uses `provenance_kind: local`, carries no external source fields, and remains experimental. Its presence does not change the external-adaptation inventory or make its consumer-local method universal policy.
+
+## Promotion And Staleness
+
+External adaptations begin `experimental`. Promotion to `stable` requires a demonstrated reader or review task, evidence that the document improves that task, a named review owner, and no unresolved provenance or platform-version debt. Remove or revise a page when its source revision changes materially, a platform claim becomes stale, a local quality gate contradicts it, or a reader test shows the route is misleading.
+
+### Consumer Reference Promotion
+
+Consumer-reference promotion does not add a domain. The StyleGallery-local `>=2` independent-consumer gateway applies only to consumer-local → shared-experimental invariant eligibility. Editorial and terminal are related examples in one fixture set, so neither counts as an independent consumer. Shared stable has no numeric adoption threshold.
+
+Normative correctness may waive adoption count only; regression evidence, invariant scope, owner and support capacity, compatibility, migration, deprecation, rollback, and provenance duties remain required. A failed stable contract is restricted, maintained, rolled back, or deprecated with migration, never silently relabeled experimental. Promotion records are JSON-only; the committed examples are synthetic, `example_only`, deferred, and contain zero adopter attestations.
+
+Consumer-reference maturity is governed independently from artifact mode. Stable records cannot have ended support, and related repository fixtures are not independent adoption evidence.
+
+## IA Navigation
+
+Parent: [StyleGallery](index.md).
+Next: [Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md) for ownership and validator policy.

package/GOVERNANCE.md

@@ -0,0 +1,222 @@
+---
+type: Governance Reference
+title: Governance, Lifecycle, And Docs-As-Code
+description: Source-of-truth, generated artifact, domain, lifecycle, ownership, and stale-content policy for StyleGallery.
+scheduled_stale_audit: deferred
+scheduled_evidence_audit: active_advisory
+---
+
+# Governance, Lifecycle, And Docs-As-Code
+
+Primary role: governance reference.
+
+Use this file before editing repository documentation. It names which file is authoritative, which files are generated, which validators must run, and which review owner should check the change.
+
+## Source Of Truth Matrix
+
+| Doc family | Source of truth | Generator | Generated artifacts | Lifecycle state | Stale trigger | Validator | Review owner |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Root repository guide | `README.md` | Manual | None | `stable` | Source-of-truth route changes, broken root links, or ownership changes. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs`, `scripts/validate-governance.mjs` | Repository governance owner |
+| OKF bundle map | `index.md` | Manual | None | `stable` | New root entry, moved concept, broken root links, or ownership changes. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs`, `scripts/validate-governance.mjs` | Repository governance owner |
+| Agent editing rules | `AGENTS.md` | Manual | None | `stable` | Rule changes, generated-artifact policy changes, or ownership changes. | `scripts/validate-links.mjs`, `scripts/validate-governance.mjs` | Repository governance owner |
+| Planning guides | `GUIDE.md`, `guides/*.md` | Manual | None | `stable` | Workflow changes, route changes, source-lineage changes, or broken guide links. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs` | Planning-doc owner |
+| Layout recipes | `recipes/*.md` | Manual | None | `stable` | Pattern-stack changes, route changes, or broken recipe links. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs` | Recipe owner |
+| Quality gates and evidence | `quality/**/*.md` | Manual | None | `stable` | Claim-boundary changes, evidence-family changes, or broken quality links. | `scripts/validate-okf.mjs`, `scripts/validate-links.mjs`, `scripts/validate-ia.mjs` | Quality owner |
+| Consumer reference contract | `consumer-reference/contract.md`, `consumer-reference/schema/item.schema.json` | Manual | None | `stable` contract with related fixtures | Handoff shape, path boundary, lifecycle, ownership, or dependency-direction changes. | `scripts/validate-consumer-reference.mjs`, `scripts/test-validate-consumer-reference.mjs` | Repository governance owner with Validation owner |
+| Agent-native knowledge interface | `consumer-reference/agent-native/registry.json`, `consumer-reference/agent-native/schema/*.json`, `scripts/agent-native/*.mjs`, `scripts/sg.mjs`, `scripts/sg-mcp.mjs` | Manual, with protocol projections derived from one operation registry | CLI JSON, read-only MCP tools/resources, A2A Task projections, and AG-UI event projections | `experimental` interface over governed records | Identity grammar, canonical hashing, registry records, operation metadata, capability/effect semantics, receipt/conformance rules, protocol mapping, retrieval, or learning-promotion rules change. | `npm run test:agent-native`, syntax checks in `.github/workflows/validate.yml` | Repository governance owner with Validation owner |
+| Portable token source | `consumer-reference/fixtures/token-portability/valid-reference.json`, `consumer-reference/schema/portable-tokens.schema.json` | `scripts/build-reference-artifacts.mjs` with Style Dictionary `5.5.0` | `consumer-reference/generated/tokens.css`, `consumer-reference/generated/manifest.json` | `stable` restricted adapter contract, `generated` output | Allowed token shape, adapter/version pin, source token count, warning, declaration, or content hash changes. | `scripts/validate-reference-artifacts.mjs`, `scripts/test-reference-adapters.mjs` | Repository governance owner with Validation owner |
+| Governed local reference profiles | `design-engineering/reference-profiles/governed-local/editorial/profile.json`, `design-engineering/reference-profiles/governed-local/editorial/tokens.dtcg.json`, `design-engineering/reference-profiles/governed-local/editorial/local-foundations.json`, `design-engineering/reference-profiles/governed-local/terminal/profile.json`, `design-engineering/reference-profiles/governed-local/terminal/tokens.dtcg.json`, `design-engineering/reference-profiles/governed-local/terminal/local-foundations.json` | Manual | None | `experimental`, `example_only`, non-default related fixtures | Layout revision, identity values, UA/reset assumptions, explicit selection, or fixture relationship changes. | `scripts/validate-consumer-reference.mjs`, `scripts/test-validate-consumer-reference.mjs` | Design Engineering owner with Validation owner |
+| Component-state evidence matrices | Each profile's declared `components/*.component.json`, `states/*.states.json`, `fixtures/*.fixture.json`, and `evidence/*.evidence.json` records | `scripts/generate-consumer-reference-evidence.mjs` | `design-engineering/reference-profiles/governed-local/editorial/generated/state-matrix.md`, `design-engineering/reference-profiles/governed-local/editorial/generated/keyboard-matrix.md`, `design-engineering/reference-profiles/governed-local/editorial/generated/evidence-coverage.md`, `design-engineering/reference-profiles/governed-local/terminal/generated/state-matrix.md`, `design-engineering/reference-profiles/governed-local/terminal/generated/keyboard-matrix.md`, `design-engineering/reference-profiles/governed-local/terminal/generated/evidence-coverage.md` | `generated` output from `experimental` canonical records | Declared record paths, capture-session identity, scenario/mode/channel counts, claim boundary, generated escaping, or generator output changes. | `scripts/validate-component-state.mjs`, `scripts/test-validate-component-state.mjs`, `scripts/test-validate-component-state-artifacts.mjs`, `scripts/test-generate-consumer-reference-evidence.mjs` | Design Engineering owner with Validation owner |
+| Consumer migration conformance | `consumer-reference/schema/consumer-conformance-record.schema.json`, `design-engineering/consumer-migration-readiness.md` | Manual | Consumer-owned conformance records | `experimental` method | Method, dimension, scenario, mapping, or ownership changes. | `scripts/validate-consumer-conformance.mjs`, `scripts/test-validate-consumer-conformance.mjs` | Design Engineering owner with Validation owner |
+| Consumer page-evidence lifecycle | `consumer-reference/schema/page-evidence-session.schema.json`, `consumer-reference/schema/page-evidence-manifest.schema.json` | Browser/session tooling | Consumer-owned session, runner, manifest, and raster artifacts | `experimental` evidence protocol | Source, revision, session, run, scenario, review deadline, or artifact integrity changes. | `scripts/test-validate-page-evidence.mjs`, deterministic Chromium consumer-conformance job | Validation owner with consumer owner |
+| Explicit evidence freshness schedule | Evidence records that declare `expires_at` or `review_by` | `.github/workflows/evidence-freshness.yml` | Advisory JSON audit artifact | `stable` narrow schedule | Explicit deadline, auditor, schedule, or inventory changes. | `scripts/audit-evidence-freshness.mjs`, `scripts/test-audit-evidence-freshness.mjs` | Validation owner |
+| Deterministic consumer browser conformance | `tests/consumer-conformance.spec.mjs`, `tests/fixtures/consumer-conformance-scenarios.mjs`, `tests/helpers/render-consumer-conformance.mjs` | Playwright `1.61.0` in the digest-pinned `linux/amd64` image | Optional page-evidence raster artifact | `experimental` contract with blocking semantic gate and nonblocking raster capture | Viewport, container, content, state, overlay, page-scale, focus, overflow, contrast, semantics, or runtime-error changes. | Playwright matrix and `scripts/test-consumer-conformance-sentinel.mjs` | Validation owner with Design Engineering owner |
+| Shared promotion policy | `consumer-reference/policies/shared-experimental.json`, `consumer-reference/schema/promotion-rfc.schema.json` | Manual | None; promotion fixtures are synthetic examples | `stable` policy with `example_only`, deferred fixtures | Gateway scope, independence basis, evidence, ownership, support, compatibility, migration, deprecation, rollback, provenance, or decision changes. | `scripts/validate-promotion-rfc.mjs`, `scripts/test-validate-promotion-rfc.mjs` | Repository governance owner with actual consumer, support, migration, rollback, and Validation owners |
+| Proposed Chromium sentinel | `tests/helpers/render-consumer-reference.mjs`, `consumer-reference/schema/{baseline-manifest,calibration-record}.schema.json`, `consumer-reference/baselines/*.json` | Playwright `1.61.0` in the digest-pinned `linux/amd64` image | `tests/snapshots/consumer-reference-card-grid.png`, raw GitHub Actions calibration artifact | `experimental`, nonblocking while owner approval is pending | Renderer source, exact image/platform/tool pin, baseline bytes, computed layout contract, or calibration metadata changes. | `scripts/validate-baseline-manifest.mjs`, `scripts/test-validate-baseline-manifest.mjs`, `scripts/test-summarize-sentinel-calibration.mjs`, Playwright | Repository governance owner with Validation owner |
+| Domain manifest and scope decision | `DOMAINS.md`, `quality/claim-records/stylegallery-multidomain-scope.md` | Manual | None | `stable` | Domain membership, repository-scope, or provenance-policy changes. | `scripts/validate-domains.mjs`, `scripts/validate-governance.mjs` | Repository governance owner |
+| Layout domain hub | `layout/index.md` | Manual | None | `stable` | Layout route or ownership changes. | `scripts/validate-domains.mjs`, `scripts/validate-ia.mjs` | Pattern-data owner |
+| Motion domain guidance | `motion/*.md` | Manual | None | `experimental` | Upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Motion domain owner |
+| Design Engineering domain guidance | `design-engineering/*.md` | Manual | None | `experimental` | Upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Design Engineering domain owner |
+| Game UI domain guidance | `game-ui/**/*.md` | Manual | None | `experimental` | Classification, hierarchy, engine implementation, evidence boundary, or route changes. | `scripts/validate-domains.mjs` | Game UI domain owner |
+| Platform Guides domain guidance | `platform-guides/*.md` | Manual | None | `experimental` | Platform version, upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Platform Guides domain owner |
+| Pattern data and examples | `scripts/pattern-data.mjs` | Manual data source | `patterns/**/*.md`, `patterns/**/index.md`, `patterns/index.md`, `CATALOG.md` | `generated` output from `stable` source | Source-lineage URL changes, generated drift, category changes, or pattern count changes. | `scripts/validate-patterns.mjs`, `scripts/validate-catalog.mjs`, `scripts/validate-governance.mjs` | Pattern-data owner |
+| Pattern generator | `scripts/generate-patterns.mjs` | Manual code source | `patterns/**/*.md`, `patterns/**/index.md`, `patterns/index.md`, `CATALOG.md` | `stable` generator, `generated` output | Generated structure changes, generated-warning changes, or generated metadata changes. | `node -c scripts/generate-patterns.mjs`, generated drift check, `scripts/validate-governance.mjs` | Pattern-data owner |
+| Validation scripts | `scripts/validate-*.mjs`, `scripts/test-validate-*.mjs` | Manual code source | CI validation output | `stable` | Validator scope changes, fixture changes, or CI parity changes. | `node -c`, matching fixture tests, `.github/workflows/validate.yml` | Validation owner |
+| CI workflows | `.github/workflows/validate.yml`, `.github/workflows/evidence-freshness.yml` | Manual | GitHub Actions runs and audit artifacts | `stable` | Validation step, explicit-deadline schedule, generated drift policy, or owner changes. | GitHub Actions, `scripts/validate-governance.mjs` | Repository governance owner |
+
+## Generated Artifact Policy
+
+Generated files are not source of truth. Do not hand-edit generated artifacts to change pattern content or catalog structure.
+
+- Edit `scripts/pattern-data.mjs` when changing pattern names, categories, source lineage, sample HTML, CSS declarations, responsiveness, or scroll ownership.
+- Edit `scripts/generate-patterns.mjs` when changing generated document structure, generated warnings, accessibility contract text, IA navigation text, or catalog layout.
+- Regenerate with `node scripts/generate-patterns.mjs`.
+- Verify with `git diff --exit-code -- CATALOG.md patterns` after generation.
+- Generated artifacts must contain a generated warning that points contributors back to `scripts/generate-patterns.mjs` and `scripts/pattern-data.mjs`.
+
+Current generated artifacts:
+
+- `CATALOG.md`
+- `patterns/index.md`
+- `patterns/**/index.md`
+- `patterns/**/*.md`
+- `consumer-reference/generated/tokens.css`
+- `consumer-reference/generated/manifest.json`
+- `design-engineering/reference-profiles/governed-local/editorial/generated/state-matrix.md`
+- `design-engineering/reference-profiles/governed-local/editorial/generated/keyboard-matrix.md`
+- `design-engineering/reference-profiles/governed-local/editorial/generated/evidence-coverage.md`
+- `design-engineering/reference-profiles/governed-local/terminal/generated/state-matrix.md`
+- `design-engineering/reference-profiles/governed-local/terminal/generated/keyboard-matrix.md`
+- `design-engineering/reference-profiles/governed-local/terminal/generated/evidence-coverage.md`
+- `tests/snapshots/consumer-reference-card-grid.png` (proposed; update only by an explicit local baseline proposal, never in CI)
+
+Portable token artifacts are regenerated only from the restricted fixture through the pinned adapter. Run `npm run build`; never broaden the allowed token subset to accommodate an adapter false-success, and revert the adapter with both generated files if the pin regresses.
+
+Component-state evidence matrices are regenerated only from the records declared by each `profile.json`. Run `node scripts/generate-consumer-reference-evidence.mjs --json`; never hand-edit any of the six matrices or substitute undeclared record paths.
+
+Browser state evidence begins with `scripts/create-component-state-session.mjs`. Its closed receipt binds a random nonce and session ID to the checked-out revision, branch, attempt, exact runtime pins, viewport, intended profile/scenario/channel set, and a deterministic digest of the relevant capture sources before capture. Receipt creation rejects dirty relevant sources. DOM and AX artifacts embed the receipt digest and session identity; browser-authored visual sidecars bind the same session, scenario, capture time, source digest, PNG bytes, dimensions, and hash. Finalization accepts exactly 30 channel passes over the closed 40-file runtime set. Validation uses the receipt and completed manifest interval, not a wall-clock maximum age, so an unchanged downloaded session remains verifiable later.
+
+## Lifecycle States
+
+Use these states in reviews and governance notes. Do not invent new lifecycle language when one of these states fits.
+
+| State | Meaning | Change rule |
+| --- | --- | --- |
+| `draft` | Useful but still being shaped. | May change in structure or wording; review owner checks source-of-truth fit. |
+| `stable` | Canonical guidance or contract. | Requires validator coverage or a named evidence boundary before behavior changes. |
+| `deprecated` | Kept for history or migration. | Must name the replacement and removal trigger. |
+| `experimental` | Accepted exploration that should not be treated as canonical. | Must name the review trigger that promotes, revises, or removes it. |
+| `generated` | Produced from generator/data source. | Change the source file, regenerate, and run generated drift checks. |
+
+Default lifecycle:
+
+- Root docs, guides, recipes, quality docs, validators, and CI are `stable` unless a page explicitly says otherwise.
+- `DOMAINS.md`, the scope decision, and `layout/index.md` are `stable`; domain leaves under `motion/`, `design-engineering/`, `game-ui/`, and `platform-guides/` begin `experimental`.
+- Generated pattern docs, generated pattern indexes, and `CATALOG.md` are `generated`.
+- Draft research artifacts under `.omo/` are `draft` or `experimental` and are not contributor-facing source of truth.
+
+## Review Ownership
+
+The CODEOWNERS file is a review proposal for high-impact areas. It should stay conservative until repository maintainers replace `@changeroa` with a verified team.
+
+Consumer-reference ownership records the current truth as `owner.enforcement: "placeholder"` and `review_independence: "single_account"`. Multiple logical review roles assigned to this account do not create independent review.
+
+| Area | Review owner | Review focus |
+| --- | --- | --- |
+| `GOVERNANCE.md`, `README.md`, `index.md`, `AGENTS.md` | Repository governance owner | Source-of-truth routing, lifecycle, stale-content policy, contributor path. |
+| `scripts/pattern-data.mjs`, `scripts/generate-patterns.mjs`, `patterns/**`, `CATALOG.md` | Pattern-data owner | Generated drift, source lineage, pattern contract, generated warning coverage. |
+| `guides/**`, `GUIDE.md`, `recipes/**` | Planning-doc owner | Planning flow, task routes, recipe composition boundaries. |
+| `quality/**` | Quality owner | Claim boundaries, executable evidence, review gates. |
+| `consumer-reference/**` | Repository governance owner with Validation owner | Required handoff, repository-local record safety, lifecycle separation, ownership truth, and reverse-dependency guard. |
+| `consumer-reference/schema/{consumer-conformance-record,page-evidence-session,page-evidence-manifest}.schema.json`, `scripts/*consumer-conformance*.mjs`, `scripts/*page-evidence*.mjs` | Validation owner with Design Engineering owner | Closed migration dimensions, source/revision/session/run binding, artifact containment, executable scenario coverage, and consumer-owned adoption mapping. |
+| `consumer-reference/policies/**`, `consumer-reference/fixtures/promotion/**`, `consumer-reference/schema/promotion-rfc.schema.json`, `scripts/*promotion-rfc.mjs` | Repository governance owner with actual consumer, support, migration, rollback, and Validation owners | Invariant-only scope, independence truth, claim-scoped evidence, compatibility, support capacity, lifecycle duties, and zero promotion/adoption overclaim. |
+| `consumer-reference/adapters/**`, `consumer-reference/generated/**`, `scripts/*reference-artifacts.mjs`, `scripts/test-reference-adapters.mjs` | Repository governance owner with Validation owner | Restricted token ingress, exact adapter pin, warning handling, token/declaration counts, hashes, preserved aliases, and generated drift. |
+| `DOMAINS.md`, `layout/**` | Repository governance owner with Pattern-data owner | Domain routing and preservation of the stable Layout path contract. |
+| `motion/**` | Motion domain owner | Motion terminology, review procedure, practice classification, and evidence boundaries. |
+| `design-engineering/**` | Design Engineering domain owner | Separation of product heuristics from shared quality gates. |
+| `design-engineering/reference-profiles/**` | Design Engineering owner with Validation owner | Profile-local identity and values, pinned Layout provenance, explicit non-default selection, and related-fixture truth. |
+| `tests/**`, `playwright.config.mjs`, `consumer-reference/baselines/**`, `scripts/*baseline*.mjs`, `scripts/*sentinel*.mjs`, `scripts/*renderer-purity.mjs` | Repository governance owner with Validation owner | Pure rendering, computed semantics before screenshots, immutable browser pins, required consumer-conformance semantics, optional raster capture, calibration cardinality, and pending owner approval. |
+| `game-ui/**` | Game UI domain owner | Player-task classification, hierarchy responsibility, reference records, engine-specific subtrees, and cross-engine boundaries. |
+| `platform-guides/**` | Platform Guides domain owner | Platform/source/version limits, comparison boundaries, and stale review. |
+| `scripts/validate-*.mjs`, `scripts/test-validate-*.mjs`, `.github/workflows/validate.yml`, `.github/workflows/evidence-freshness.yml` | Validation owner | Validator scope, negative fixtures, blocking/advisory boundaries, CI parity. |
+
+## Shared Promotion Governance
+
+The StyleGallery-local `>=2` independent-consumer gateway applies only to consumer-local → shared-experimental invariant eligibility. It is neither a universal rule nor a stable threshold. Shared stable has no numeric adoption threshold; it requires claim-scoped evidence, active owner and support capacity, compatibility review, known-issue and exception visibility, migration and deprecation readiness, rollback triggers, resolved provenance debt, and an explicit scope decision.
+
+Normative accessibility, security, standards, or correctness fixes may waive adoption count only. They never waive regression proof, scope control, owner acceptance, support capacity, compatibility, migration, deprecation, or rollback. Palette, typography, imagery, motion character, and component skin remain consumer-local even when repeated.
+
+The committed RFC fixtures are synthetic `example_only` proposals with `decision: "deferred"`; they contain zero durable adopter attestations and record no promotion. Editorial and terminal remain related fixtures in one set and never count as independent consumers. Current review truth remains `review_independence: "single_account"`; booleans and multiple role labels do not create independent review.
+
+If evidence fails, restrict, maintain, or roll back the candidate. A consumed stable contract may be deprecated only with a named migration; it must never be silently relabeled shared-experimental. The canonical JSON policy and RFC records own these decisions; no YAML promotion record is valid.
+
+## Staleness Control
+
+Decision: run a weekly advisory audit only for evidence records that already declare `expires_at` or `review_by`.
+
+The independent `.github/workflows/evidence-freshness.yml` schedule runs Monday at 05:00 UTC and also supports manual dispatch. It currently inventories the committed Chromium calibration record; consumer-owned page-evidence manifests enter the same audit by passing their explicit record path to `scripts/audit-evidence-freshness.mjs`.
+
+No repository-wide maximum age or inferred time-to-live applies. Evidence without an explicit deadline remains outside this schedule. An expired `expires_at` or due `review_by` emits an advisory annotation and a JSON report without failing solely because the date passed. Malformed records and auditor failures remain blocking even though due-date findings are advisory.
+
+Audit trigger:
+
+- Run `node scripts/validate-links.mjs --json` and `node scripts/validate-governance.mjs --json` when external source lineage, generated policy, root navigation, or validation ownership changes.
+- Run `node scripts/validate-domains.mjs --json` and `node scripts/test-validate-domains.mjs` when domain membership, scope boundaries, source paths, source revisions, platform context, or promotion state changes.
+- Run `node scripts/test-audit-evidence-freshness.mjs --json` when `expires_at`, `review_by`, record inventory, advisory classification, or the scheduled workflow changes.
+
+## Required Verification
+
+For governance changes, run:
+
+```sh
+node scripts/validate-governance.mjs --json
+node scripts/test-validate-governance.mjs --json
+node scripts/validate-links.mjs --json
+node scripts/validate-domains.mjs --json
+node scripts/test-validate-domains.mjs
+node scripts/validate-consumer-reference.mjs --json
+node scripts/test-validate-consumer-reference.mjs --json
+node scripts/test-validate-consumer-conformance.mjs --case valid-runtime-proof --json
+node scripts/test-validate-consumer-conformance.mjs --json
+node scripts/test-validate-page-evidence.mjs --json
+node scripts/test-audit-evidence-freshness.mjs --json
+```
+
+For generated pattern or catalog changes, also run:
+
+```sh
+node scripts/generate-patterns.mjs
+git diff --exit-code -- CATALOG.md patterns
+node scripts/validate-patterns.mjs --min-count 46 --json
+node scripts/validate-catalog.mjs --json
+```
+
+For portable token source, adapter, or generated artifact changes, run:
+
+```sh
+npm ci --ignore-scripts --no-audit --no-fund
+node scripts/build-reference-artifacts.mjs --adapter style-dictionary --fail-on-warning --json
+node scripts/validate-reference-artifacts.mjs --manifest consumer-reference/generated/manifest.json --json
+node scripts/test-reference-adapters.mjs --json
+git diff --exit-code -- consumer-reference/generated
+```
+
+For the proposed Chromium sentinel, also run:
+
+```sh
+npm run test:sentinel
+node scripts/test-consumer-reference-sentinel.mjs
+node scripts/validate-baseline-manifest.mjs --json
+node scripts/test-validate-baseline-manifest.mjs --json
+node scripts/test-summarize-sentinel-calibration.mjs
+node scripts/validate-renderer-purity.mjs --json
+node scripts/test-renderer-purity.mjs
+```
+
+For capture-session-bound component-state evidence, also run:
+
+```sh
+STATE_EVIDENCE_ROOT=".tmp/consumer-reference-state"
+mkdir -p "$STATE_EVIDENCE_ROOT"
+node scripts/create-component-state-session.mjs --output "$STATE_EVIDENCE_ROOT/capture-session.json" --json
+STATE_SESSION_RECEIPT="$STATE_EVIDENCE_ROOT/capture-session.json" \
+  STATE_ARTIFACT_DIR="$STATE_EVIDENCE_ROOT/runtime" \
+  npm run test:component-state:runtime -- --reporter=line
+node scripts/finalize-component-state-evidence.mjs --artifact-root "$STATE_EVIDENCE_ROOT" --json
+node scripts/validate-component-state.mjs \
+  --artifact-root "$STATE_EVIDENCE_ROOT" \
+  --runtime-manifest "$STATE_EVIDENCE_ROOT/runtime-manifest.json" \
+  --json
+npm run test:component-state:runtime-negative
+```
+
+For shared promotion governance, also run:
+
+```sh
+node scripts/validate-promotion-rfc.mjs --json
+node scripts/test-validate-promotion-rfc.mjs --json
+```
+
+Do not pass `--update-snapshots` in CI. Calibration runs exactly 20 times on the manifest's digest-pinned `linux/amd64` container and uploads raw Playwright JSON, strict exit records, PNG, DOM, AX, metadata, and post-assertion comparison evidence. Failed or incomplete calibration still uploads its truthful raw evidence without writing a completed aggregate. It remains nonblocking until the named owner explicitly approves the baseline.
+
+Completed-CI repository, workflow, run ID and attempt, SHA, and artifact-name fields are workflow-recorded, self-asserted metadata, not an external attestation. The self-asserted repository field names the canonical upstream changeroa/StyleGallery; the self-asserted execution_repository field names the actual GitHub Actions repository and is limited to changeroa/StyleGallery or ark-jo/StyleGallery. The committed calibration's external_verification object records an independently checked GitHub Actions run and artifact API identity; artifact.api_digest is distinct from committed_ci.raw_evidence_sha256. Future CI aggregates remain awaiting_external_verification until their uploaded artifact API identity is independently checked. Linux/amd64 repeatability is externally verified only for committed run 29260372260; it does not establish baseline-owner approval or product suitability. Baseline-owner approval remains unclaimed until the named owner explicitly approves it. Synthetic fixtures validate rejection and acceptance behavior only; they are not authenticated provenance.

package/GUIDE.md

@@ -0,0 +1,59 @@
+---
+type: Planning Guide
+title: Layout Planning Guide
+description: Pre-design entry point for choosing and composing StyleGallery Layout patterns.
+---
+
+# Layout Planning Guide
+
+Primary role: planning workflow.
+
+Use this guide before a layout problem appears. It helps you classify a screen, name its spatial responsibilities, and choose a small stack of layout patterns before writing application CSS.
+
+The StyleGallery Layout domain has two modes:
+
+- **After a problem appears:** find a named pattern in `CATALOG.md` and port its HTML/CSS contract.
+- **Before a problem appears:** start with the screen type, answer the layout brief, then compose patterns from `recipes/`.
+- **When content needs to become a webpage:** use the [Webpage generation workflow](guides/webpage-generation-workflow.md) to classify the use case, make the content-to-layout match, run harmony evaluation, create the GPT Image reference, and record the implementation handoff before writing product CSS.
+
+## Planning Flow
+
+1. Identify the primary user task.
+2. Name the primary content and supporting content.
+3. If the request is an ordinary webpage or homepage, classify the use case before choosing a recipe.
+4. Decide what owns scrolling.
+5. Decide whether the problem is viewport-level or component-local.
+6. Choose a screen recipe.
+7. Replace any recipe pattern that does not match the real content constraints.
+8. Run a harmony evaluation against the chosen use case, content hierarchy, pattern stack, and accessibility constraints.
+9. If visual direction is needed, create a GPT Image reference from the approved layout brief and keep the image outside reusable pattern CSS.
+10. Record an implementation handoff: pattern stack, semantic order, constraints, image-reference observations, accepted debt, and verification plan.
+    - Consumer reference: `not_applicable`.
+    - Consumer reference reason: This generic planning workflow declares no consumer-specific reference record.
+11. Verify the result against long, empty, narrow, and wide content.
+
+## Entry Points
+
+- [Decision tree](guides/decision-tree.md): start here when you do not know the pattern name.
+- [Layout brief](guides/layout-brief.md): answer these questions before selecting a pattern stack.
+- [Webpage generation workflow](guides/webpage-generation-workflow.md): start here when content needs to become a homepage or ordinary webpage.
+- [Documentation mode taxonomy](guides/documentation-mode-taxonomy.md): use this when adding, moving, or reviewing documentation.
+- [Controlled vocabulary](guides/vocabulary.md): use this when terms affect routing, metadata, search, claim records, or review decisions.
+- [Recipe index](recipes/index.md): screen-type compositions built from reusable patterns.
+- [Pattern catalog](CATALOG.md): individual layout primitives and their contracts.
+
+## How To Choose A Recipe
+
+Choose the recipe that matches the screen's spatial model, not the product category.
+
+- A settings page and documentation app may both use a fixed side navigation.
+- A dashboard and gallery may both use repeated grid regions.
+- A support inbox and file browser may both use list-detail layout.
+- A command surface and toolbar-heavy editor may both need wrapping or scrolling action rows.
+- A landing page, product homepage, personal site, and campaign page may all start from the [Homepage](recipes/homepage.md) recipe, then diverge by section jobs and visual direction.
+
+Recipes are starting points. If a recipe has one pattern that does not fit, replace that pattern rather than copying the recipe blindly.
+
+## What Not To Put Here
+
+The planning layer does not define brand, typography, color, border, shadow, or animation. Those belong to the consuming product. This repository only records layout responsibility, semantic structure, constraints, scroll ownership, and composition.