stylegallery 0.1.0

package/quality/evidence/pattern-contract-audit.md

@@ -0,0 +1,96 @@
+---
+type: Quality Evidence
+title: Pattern Contract Audit
+description: Maps pattern document metadata, validator checks, and human review responsibilities.
+---
+
+# Pattern Contract Audit
+
+This audit connects the generated pattern anatomy to the decisions a reviewer or implementer must make. The source of truth remains `scripts/pattern-data.mjs`; `scripts/generate-patterns.mjs` emits the pattern pages; `scripts/validate-patterns.mjs` enforces the mechanical contract.
+
+## Required Field Rationale
+
+| Field | Responsibility | Why It Exists |
+| --- | --- | --- |
+| `name` | selection, validation | Gives each pattern a stable identity for indexes, generated headings, and class-parity checks. |
+| `category` | selection, governance | Groups patterns by spatial family so the catalog can expose comparable options and reviewers can sample by family. |
+| `primary_spatial_problem` | selection, implementation | States the one layout problem the pattern optimizes, preventing a reusable pattern from absorbing product styling or unrelated behavior. |
+| `secondary_spatial_problems` | selection, governance | Records intentional composition pressure without letting secondary behavior become the primary contract. |
+| `layout_axis` | implementation, validation | Identifies whether the pattern acts on block, inline, or both axes, which shapes CSS review and failure analysis. |
+| `content_shape` | implementation, validation | Describes the content assumptions behind the snippet so adopters can test empty, short, long, and mixed content deliberately. |
+| `responsiveness` | implementation, validation | Names the adaptation model; the validator gives `reflow` patterns an extra mechanic check for wrap, query, or intrinsic guards. |
+| `constraints` | implementation, validation | Makes widths, heights, gaps, scroll containers, anchors, and other change points explicit instead of implicit in the code block. |
+| `scroll_ownership` | implementation, governance | Separates ordinary document flow from patterns that own a named scroll container, a key accessibility and QA responsibility. |
+| `source_lineage` | governance | Points reviewers to the pattern's conceptual lineage so borrowed ideas can be checked for faithful translation, not just attribution. |
+
+## Validator-Enforced Responsibilities
+
+Validator-enforced checks in `scripts/validate-patterns.mjs` cover the contract pieces that can be read mechanically:
+
+- Frontmatter must include every required field in the table above.
+- Every pattern must include the required anatomy sections: use case, HTML, CSS, core properties, breakage properties, constraints, scroll ownership, accessibility/source order, browser fallback, composition, and anti-patterns.
+- HTML and CSS fenced blocks must exist, and CSS class hooks must match HTML class hooks in both directions.
+- CSS declarations must be alphabetical inside each rule.
+- ID selectors and forbidden decorative properties are rejected in reusable pattern CSS.
+- `reflow` responsiveness requires an inspectable reflow mechanic such as a container query, media query, intrinsic repeat, wrap, or narrow guard.
+- Pattern count must satisfy the minimum threshold passed to the validator.
+
+## Human-Review-Only Risks
+
+Human-review-only risks remain outside the validator because they require judgment, domain fit, or source interpretation:
+
+- Whether the `primary_spatial_problem` is narrow enough to keep the pattern reusable.
+- Whether `secondary_spatial_problems` are genuine composition constraints or disguised feature creep.
+- Whether semantic HTML, DOM order, reading order, and focus order remain logical for the sampled use case.
+- Whether `constraints` describe the actual change points a downstream implementer must preserve.
+- Whether `scroll_ownership` is clear enough for keyboard, screen-reader, and nested-scroll QA.
+- Whether source lineage is meaningful: a URL should explain the pattern's origin or adjacent precedent, not act as a decorative citation.
+- Whether browser fallback notes are realistic for the properties the snippet actually uses.
+
+The split is intentional: validator-enforced rules prevent structural drift; Human-review-only rules protect interpretation quality.
+
+## Structural CSS Boundary
+
+Allowed structural CSS is the CSS that explains layout mechanics and can be tied to a spatial responsibility. Source-backed examples include `patterns/stacking/stack.md` using `display` and `gap`, `patterns/grid-repetition/ram-grid.md` using `grid-template-columns`, `patterns/viewport-shell/scroll-body-shell.md` using `overflow`, and `patterns/overlay-exception/imposter.md` using `position`, `inset`, `place-items`, and `z-index`.
+
+Forbidden decorative CSS remains out of reusable pattern snippets unless a layout-specific reason is documented. The forbidden side includes `color`, `background`, `border`, `border-radius`, `box-shadow`, `filter`, `font-*`, `opacity`, `text-*`, `animation`, `transition`, and `transform`. These properties can belong in a product theme or demonstration wrapper; they should not be smuggled into the reusable layout contract.
+
+The practical boundary is: keep CSS that changes geometry, flow, intrinsic sizing, scroll containment, or anchoring; reject CSS whose main effect is visual treatment.
+
+## Representative Pattern Audit
+
+| Category | Representative Source | Section Quality | Review-Only Risk |
+| --- | --- | --- | --- |
+| Stacking | `patterns/stacking/stack.md` | Anatomy is compact and the breakage note correctly names `display` and `gap`. | Check that future variants do not turn vertical rhythm into spacing tokens or typography guidance. |
+| Containment | `patterns/containment/content-limiter.md` | Constraints are visible through `max-inline-size`, `margin-inline`, and `padding-inline`. | Review whether prose width examples stay about readable measure, not editorial page styling. |
+| Media / Fit | `patterns/media-fit/frame.md` | Core properties identify both the frame and child media responsibilities. | Confirm media semantics remain real content and not placeholder-only examples. |
+| Viewport / Shell | `patterns/viewport-shell/scroll-body-shell.md` | Scroll ownership is explicit in both metadata and child class naming. | Test nested scroll behavior manually when a downstream shell adds focusable regions. |
+| Grid / Repetition | `patterns/grid-repetition/ram-grid.md` | The intrinsic repeat mechanic is clear and minimal. | Verify long labels and narrow containers remain readable, since count alone does not prove usable cards. |
+| Overlay / Exception | `patterns/overlay-exception/imposter.md` | The anchor/overlay relationship is legible and source order remains stable. | Review modal semantics and focus behavior in product use; placement alone does not make a complete dialog. |
+
+## External Lineage Review
+
+The current lineage set is meaningful at the concept level:
+
+- Every Layout lineage is appropriate for stack, overlay, and media-like primitives because those references explain spatial constraints and composition.
+- MDN lineage is appropriate for property-led shell behavior such as overflow mechanics.
+- GOV.UK layout lineage is appropriate for containment and readable-width decisions because it is a production design-system precedent.
+- web.dev one-line layout lineage is appropriate for intrinsic grid repetition.
+
+Lineage review should reject links that only resemble a pattern name. A useful lineage link must explain the layout mechanic, the governance principle, or the implementation risk carried by the generated snippet.
+
+## Contract Summary
+
+The contract is strong when each field and section has a job:
+
+- selection: choose the right spatial primitive before writing product CSS.
+- implementation: preserve the smallest robust HTML/CSS anatomy.
+- validation: catch drift that can be detected mechanically.
+- governance: surface risks that require reviewer judgment.
+
+The validator should stay mechanical. Reviewers should own semantic fit, lineage quality, fallback realism, and whether examples still teach structure instead of style.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/search-metadata-polyhierarchy.md

@@ -0,0 +1,86 @@
+---
+type: Evidence Reference
+title: Search, Metadata, And Polyhierarchy
+description: Evidence for pattern retrieval, metadata vocabulary, and search adoption decisions.
+---
+
+# Search, Metadata, And Polyhierarchy
+
+This record measures whether the generated index graph and pattern frontmatter solve discovery tasks before adding a search engine or faceted UI.
+
+Source of truth:
+
+- `scripts/pattern-data.mjs` stores the pattern table.
+- `scripts/generate-patterns.mjs` renders pattern frontmatter, `CATALOG.md`, and category indexes.
+- `scripts/validate-catalog.mjs --json` guards generated index consistency.
+
+Generated catalog remains canonical. Search, if added later, is a derived access path and must not replace `CATALOG.md`, `patterns/index.md`, or `patterns/*/index.md` as the canonical catalog.
+
+## Metadata Dictionary
+
+| Field | Definition | Allowed values in current corpus | Retrieval use | Drift rule |
+| --- | --- | --- | --- | --- |
+| `type` | OKF document kind for each generated pattern page. | `Layout Pattern` | Exclude non-pattern pages from pattern retrieval. | Single fixed value for generated patterns. |
+| `name` | Stable slug and file identity. | 46 unique slugs. | Exact lookup and duplicate detection. | Must match generated file slug. |
+| `title` | Display title for the pattern page. | Same 46 slugs as `name`. | Human scan label. | Must match `name` unless a deliberate display-title policy is introduced. |
+| `category` | Canonical navigation group rendered into `patterns/index.md` and category indexes. | `Centering`, `Containment`, `Grid / Repetition`, `In-line grouping`, `Media / Fit`, `Overlay / Exception`, `Split / Sidebar`, `Stacking`, `Viewport / Shell` | Primary browse path and catalog grouping. | Do not introduce near-synonyms such as `Inline grouping` or `Grid repetition`. |
+| `description` | Short problem statement mirrored from `primary_spatial_problem`. | One sentence per pattern. | Text scan inside `CATALOG.md`. | Keep aligned with `primary_spatial_problem`. |
+| `primary_spatial_problem` | The one spatial problem the pattern optimizes. | One sentence per pattern. | Task-to-pattern matching. | Split the pattern if this becomes multiple primary problems. |
+| `secondary_spatial_problems` | Incidental spatial behavior that helps composition. | `none` | Future polyhierarchy hook. | `none` means no secondary facet is claimed. |
+| `layout_axis` | Dominant spatial axis. Allowed values: layout_axis: `block`, `inline`, `both`. | `block` (11), `inline` (24), `both` (11) | Filters layout direction before choosing a category. | Use these axis terms only; avoid `horizontal`, `vertical`, and `2D` aliases. |
+| `content_shape` | Dominant content structure expected by the pattern. | `mixed` (46) | Future distinction between prose, media, controls, and repeated items. | Current vocabulary is underdeveloped; do not facet on it yet. |
+| `responsiveness` | How the pattern adapts. Allowed values: responsiveness: `breakpointed`, `fixed`, `fluid`, `reflow`, `scroll`, `wrap`. | `fluid` (26), `wrap` (9), `reflow` (6), `fixed` (3), `breakpointed` (1), `scroll` (1) | Distinguishes intrinsic, wrapping, breakpoint, and scrolling behavior. | Keep `reflow` and `wrap` distinct: `wrap` changes row/line packing; `reflow` changes layout structure. |
+| `constraints` | Human-readable statement of constraints and change points. | `Uses only local class hooks and explicit layout constraints.` | Confirms whether constraints are documented. | Improve wording only when generated from the source table. |
+| `scroll_ownership` | Declares whether the pattern owns an internal scroll container. | `No internal scroll container.` (43), `Pattern owns the named scroll container.` (3) | Finds shells and rows where scroll responsibility is explicit. | Do not introduce synonyms such as `page scroll`, `local scroll`, or `internal scrolling` as facet values. |
+| `source_lineage` | Source family or canonical reference URL. | MDN, Every Layout, web.dev, Carbon, GOV.UK, Material, and related source URLs. | Supports source-backed evaluation and lineage audits. | Keep URL strings exact; group families in derived reports only. |
+
+## Polyhierarchy Classification
+
+The corpus already has a lightweight polyhierarchy:
+
+| Relationship | Status | Reason |
+| --- | --- | --- |
+| Pattern -> `category` | Canonical browse hierarchy | Category drives generated indexes and should stay single-valued. |
+| Pattern -> `layout_axis` | Intended retrieval facet | Axis cuts across categories without changing canonical placement. |
+| Pattern -> `responsiveness` | Intended retrieval facet | Adaptation behavior is orthogonal to category. |
+| Pattern -> `scroll_ownership` | Intended retrieval facet | Scroll responsibility cuts across shell, inline, and sidebar patterns. |
+| Pattern -> `source_lineage` | Intended evidence facet | Source family supports traceability, not navigation ownership. |
+| Pattern -> `content_shape` | Drift risk | Current value is `mixed` for all patterns, so it should not be exposed as a facet yet. |
+| Pattern -> `secondary_spatial_problems` | Drift risk | Current value is `none` for all patterns, so it is a placeholder rather than a usable hierarchy. |
+
+Facet value drift is a failure when two names represent one concept. Current high-risk examples to reject are `inline` vs `horizontal`, `block` vs `vertical`, `wrap` vs `wrapping`, and `Pattern owns the named scroll container.` vs `internal scroll`.
+
+## Retrieval Benchmark
+
+| Task | Current index-only result | Metadata-assisted result | Measurement | Decision |
+| --- | --- | --- | --- | --- |
+| find a reflow-aware pattern with scroll ownership guidance | `CATALOG.md` cannot express the conjunction; category indexes require manual opening of candidate files. | No exact pattern has both `responsiveness: reflow` and `Pattern owns the named scroll container.`. Closest scroll-ownership matches are `scroll-body-shell`, `fixed-sidenav-shell`, and `reel`; reflow candidates are `list-detail`, `main-with-rail`, `media-object`, `split-screen`, `supporting-pane`, and `panel-layout`. | PASS as a measured answer: the metadata exposes that this is a no-exact-match query instead of hiding it behind search. | Add retrieval evidence; do not add search yet. |
+| Find a shell pattern where the body owns scrolling. | `CATALOG.md` contains `scroll-body-shell`, but the scroll ownership claim is only visible after opening the page. | `category: Viewport / Shell` plus `scroll_ownership: Pattern owns the named scroll container.` returns `scroll-body-shell` and `fixed-sidenav-shell`. | PASS. | Metadata dictionary is enough. |
+| Find a pattern that wraps inline controls. | `patterns/in-line-grouping/index.md` lists likely candidates, but responsiveness is not visible in the index. | `category: In-line grouping` plus `responsiveness: wrap` returns `breadcrumb`, `cluster`, `deconstructed-pancake`, `pagination`, `split-nav`, `tab-strip`, and `wrap-row`. | PASS. | A generated facet report may help later; search is not required. |
+| Find source-backed grid repetition patterns. | `CATALOG.md` groups grid patterns but does not expose lineage. | `category: Grid / Repetition` plus `source_lineage` groups Carbon, MDN, GOV.UK, Material, and web.dev-backed patterns. | PASS. | Keep source lineage as metadata, not primary navigation. |
+
+Benchmark conclusion: current indexes answer name/category browsing; metadata answers cross-cutting retrieval. The observed weakness is lack of a published dictionary and benchmark, not lack of full-text search.
+
+## Search Decision Record
+
+Decision: do not add Pagefind or DocSearch yet.
+
+Rationale:
+
+- The measured failures are metadata-publication gaps, not search-engine gaps.
+- A search box could hide category, axis, responsiveness, and scroll-ownership vocabulary drift instead of fixing it.
+- The generated catalog and category indexes already provide the canonical graph; search should remain derived if introduced.
+
+Revisit search only when a benchmark task fails after metadata is public and the failure cannot be solved by a generated facet report or clearer index text.
+
+Search adoption guardrails:
+
+- Keep `CATALOG.md` as the canonical pattern list.
+- Generate search data from pattern frontmatter rather than hand-maintaining a second index.
+- Validate facet vocabulary before indexing so drift cannot become search UI state.
+- Treat Pagefind or DocSearch results as navigation aids, not source-of-truth records.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/sources.md

@@ -0,0 +1,43 @@
+---
+type: Evidence Reference
+title: Source Admissibility
+description: Source families and boundaries for quality gate evidence.
+---
+
+# Source Admissibility
+
+Sources are admissible only inside a claim boundary.
+
+## Source Families
+
+- Academic and standards sources can support conceptual claims.
+- Official standards and methodology documents can support accessibility, evaluation, and process claims.
+- Official tool docs can support operational procedures.
+- Vendor or practice docs can support implementation examples, not prove human design quality.
+- Public design-system docs can support vocabulary and comparison, not brand imitation or affiliation.
+- Practitioner skill repositories can suggest terminology, procedures, and review questions; they cannot establish normative local policy without independent evidence and governance adoption.
+
+## Required Source Boundary
+
+For every cited source, record:
+
+- what the source can support;
+- what the source cannot prove;
+- whether it is academic, standards, official tooling, or practice reference;
+- whether the claim needs local rendered evidence or user evidence.
+
+## Rejection Rules
+
+Reject source use when:
+
+- a blog post is used as proof of human design quality;
+- a public design system is treated as permission to imitate a brand;
+- a tool doc is used to prove accessibility or usability outcomes;
+- a source is cited without a claim, warrant, or boundary.
+- mutable branch names or abbreviated revisions are used as the only provenance for adapted external guidance;
+- third-party or platform-derived expression is assumed to be covered by a practitioner's repository license.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/tokens.md

@@ -0,0 +1,33 @@
+---
+type: Evidence Reference
+title: Token Evidence
+description: Design token contract surfaces and boundaries.
+---
+
+# Token Evidence
+
+Tokens are contract surfaces for reusable design decisions.
+
+## Can Support
+
+- a value has a stable name and source lineage;
+- related surfaces share a consistent value;
+- a design decision can travel across tools or codebases;
+- token categories and aliases are inspectable.
+
+## Cannot Prove
+
+- visual quality;
+- accessibility;
+- brand fit;
+- motion comfort;
+- task success.
+
+## Boundary
+
+Use tokens for shared design intent. Keep browser and layout mechanics such as `auto`, percentages, intrinsic sizing, and container-query units in CSS when they are layout behavior rather than design intent.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/visual-qa.md

@@ -0,0 +1,41 @@
+---
+type: Evidence Reference
+title: Visual QA Evidence
+description: Rendered evidence sources and limits.
+---
+
+# Visual QA Evidence
+
+Visual QA evidence helps inspect rendered output.
+
+## Evidence Types
+
+- screenshot baselines;
+- visual diffs;
+- responsive viewport captures;
+- state captures for hover, focus, active, disabled, error, expanded, and loading states;
+- reduced-motion captures when motion behavior is claimed.
+
+## Can Support
+
+- a rendered state changed;
+- a rendered state stayed stable against a baseline;
+- a viewport or state has evidence available for review;
+- visual review can proceed from concrete artifacts.
+
+## Cannot Prove
+
+- usability;
+- accessibility;
+- brand fit;
+- aesthetic quality;
+- task completion.
+
+## Required Phrase
+
+Screenshot diffs show rendered change, not usability.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/gates/accessibility-evidence.md

@@ -0,0 +1,60 @@
+---
+type: Quality Gate
+title: Accessibility Evidence Gate
+description: Accessibility evidence requirements and overclaim boundaries.
+---
+
+# Accessibility Evidence Gate
+
+Accessibility precedes taste.
+
+## Scope
+
+Use this gate when a claim affects access, comprehension, keyboard use, screen-reader flow, contrast, motion comfort, error recovery, or cognitive load.
+
+## Accepted Evidence
+
+- WCAG-oriented checks where applicable;
+- ACT-rule, axe, Storybook, or equivalent automated findings;
+- keyboard and focus-path checks;
+- contrast and non-color-only meaning checks;
+- screen-reader or accessibility-tree review when the claim depends on semantics;
+- cognitive accessibility review for language, memory burden, predictability, and help.
+
+## Verification Method Register
+
+Classify every accessibility claim before approval:
+
+- `automated`: rule-scoped machine checks such as axe, ACT, contrast math, lint output, or validator output.
+- `manual`: expert review of DOM order, focus order, keyboard behavior, screen-reader flow, language clarity, motion comfort, or cognitive load.
+- `user`: participant evidence for task completion, comprehension, assistive-technology fit, or perceived effort.
+- `debt`: a known accessibility gap with affected users, owner, review trigger, and expiry condition.
+
+The claim record must include the verification method, the evidence artifact, the boundary, and any accepted debt. A rendered screenshot, visual diff, generated image, or GPT Image reference can be supporting context only; it is not an accessibility verification method.
+
+## Required Boundary Language
+
+- Automated accessibility scans assist evaluation, not determine accessibility.
+- Passing an automated scan means no issue was found by that tested rule set.
+- Manual judgment is required for claims involving task completion, cognitive load, clarity, assistive technology behavior, or user comprehension.
+- Visual evidence cannot prove accessibility unless it is paired with the relevant automated, manual, user, or debt record.
+
+## Blocking Conditions
+
+Block an accessibility claim when:
+
+- focus is invisible or illogical;
+- essential meaning depends on color alone;
+- required alternatives for media are missing;
+- motion lacks a reduced-motion path when motion safety is declared;
+- a known accessibility failure is treated as a taste tradeoff;
+- accessibility debt lacks affected users and a review trigger.
+
+## Boundary
+
+Accessibility evidence may require expert or user review. Do not turn a scan result into a complete accessibility certification.
+
+## IA Navigation
+
+Parent: [Gate Contracts](index.md).
+Next: [Evidence References](../evidence/index.md) when a gate needs admissible support.

package/quality/gates/consumer-migration-evidence.md

@@ -0,0 +1,53 @@
+---
+type: Quality Gate
+title: Consumer Migration Evidence Gate
+description: Blocking contract for consumer-owned migration conformance and page evidence.
+---
+
+# Consumer Migration Evidence Gate
+
+Use this gate only for a declared consumer migration. Ordinary implementation handoffs keep the existing consumer-reference applicability contract and do not need a migration record.
+
+## Required Contract
+
+Record:
+
+```txt
+Consumer migration conformance: declared
+Consumer migration conformance record: path/to/consumer-conformance.json
+Consumer revision:
+Relevant source inventory:
+Thirteen migration-dimension classifications:
+Runtime scenario results:
+Adoption mappings:
+Page evidence: applicable | not_applicable
+Deviations:
+Debt and review dates:
+Claim boundary:
+Decision: pass | block
+```
+
+The record path is normalized, repository-relative JSON inside the consuming repository. The record follows the [consumer conformance schema](../../consumer-reference/schema/consumer-conformance-record.schema.json) and the [receiver contract](../../consumer-reference/contract.md).
+
+## Blocking Conditions
+
+Block when any of the following is true:
+
+- any of the thirteen migration dimensions is absent rather than explicitly `applicable` or `not_applicable`;
+- an applicable dimension has no declared runtime scenario, or a scenario has a nonzero exit, missing result artifact, mismatched run/session identity, or stale source digest;
+- an adoption mapping lacks a pinned StyleGallery revision and anchor, concrete local target, local decision, scenario link, or declared deviations and debt;
+- page evidence is applicable but its source inventory, revision, browser scenario catalog, repository, run, session, artifact hashes, or finalized manifest does not match the conformance record;
+- a source changes between session creation and finalization, an artifact escapes the evidence root, a symlink or unmanifested artifact is accepted, or evidence is reused across sessions;
+- expired blocking evidence or malformed freshness metadata is presented as current;
+- the handoff implies that passing validator or browser checks proves complete accessibility, product correctness, usability, or approval.
+
+## Evidence Decision
+
+Pass means only that the declared migration contract and its named evidence agree at the pinned consumer and StyleGallery revisions. It does not mean the migration is universally correct or that omitted behavior is safe. Reviewers still decide whether the inventory and `not_applicable` reasons are credible.
+
+Use [Consumer Migration Evidence](../evidence/consumer-migration.md) to interpret runtime, browser, freshness, and review channels. Use [Executable Evidence](../evidence/executable-evidence.md) for the repository-wide distinction between structural enforcement and human judgment.
+
+## IA Navigation
+
+Parent: [Gate Contracts](index.md).
+Next: [Consumer Migration Evidence](../evidence/consumer-migration.md).

package/quality/gates/design-claim.md

@@ -0,0 +1,56 @@
+---
+type: Quality Gate
+title: Design Claim Gate
+description: Contract for admitting non-layout design claims.
+---
+
+# Design Claim Gate
+
+The design claim gate prevents evidence from becoming unsupported authority.
+
+## Required Contract
+
+Every non-layout design claim should state:
+
+```txt
+Principle:
+Claim:
+Context:
+Warrant:
+Evidence family:
+Verification protocol:
+Boundary or limitation:
+Debt or escalation:
+Decision:
+```
+
+## Evidence Families
+
+Use the normalized [evidence family glossary](../evidence/families.md):
+
+- `validator`: file shape, headings, frontmatter, source lineage, token structure, fixture output, and CI checks.
+- `screenshot`: screenshots, visual diffs, state captures, viewport captures, and rendered DOM artifacts.
+- `accessibility`: WCAG/ACT checks, keyboard checks, contrast checks, assistive-technology/manual review, and cognitive accessibility review.
+- `user`: heuristic evaluation, cognitive walkthrough, persona or task review, user testing, validated visual-aesthetics instruments, and participant evidence.
+- `source`: academic, standards, official tooling, methodology, vendor, practice, and public design-system references inside a stated boundary.
+- `rationale`: Toulmin/ADR-style records, options considered, criteria, counterclaims, limitations, debt, owner, and review trigger.
+
+## Blocking Conditions
+
+Block a design claim when:
+
+- it has evidence but no warrant;
+- it treats a screenshot diff as proof of usability;
+- it treats an automated accessibility scan as proof of accessibility;
+- it cites public design systems as proof of universal quality;
+- it conflicts with accessibility or task completion;
+- it requires changes inside generated layout pattern surfaces.
+
+## Boundary
+
+This gate admits claims. It does not prescribe a product brand, palette, illustration style, typeface, animation system, or component library.
+
+## IA Navigation
+
+Parent: [Gate Contracts](index.md).
+Next: [Evidence References](../evidence/index.md) when a gate needs admissible support.

package/quality/gates/harmony-evaluation.md

@@ -0,0 +1,78 @@
+---
+type: Quality Gate
+title: Harmony Evaluation Gate
+description: Contract for judging webpage content-to-layout fit, visual-reference use, and implementation handoff.
+---
+
+# Harmony Evaluation Gate
+
+Use this gate before a generated image or visual reference becomes implementation guidance for a homepage or ordinary webpage.
+
+## Required Contract
+
+Record:
+
+```txt
+Use case:
+Primary task:
+Audience:
+Content-to-layout match:
+Overall harmony:
+Claim record route:
+GPT Image reference:
+Implementation handoff:
+Consumer reference: not_applicable
+Consumer reference reason: This blank harmony-gate template declares no consumer-specific reference record.
+Rejected alternatives:
+Final implementation proof:
+Evidence family:
+Verification protocol:
+Boundary or limitation:
+Decision:
+```
+
+Do not generate a GPT Image reference before harmony evaluation approves the semantic order, section jobs, pattern stack, scroll owner, and constraints.
+Source order, accessibility, brand correctness, and usability cannot be inferred from the image.
+Final implementation proof: screenshot or visual-diff evidence, accessibility evidence, and viewport/content stress evidence from the built page.
+
+## Evidence Families
+
+Use the normalized [evidence family glossary](../evidence/families.md):
+
+- `validator`: layout brief fields, recipe choice, pattern stack, semantic skeleton, linkable workflow docs, and validator output.
+- `screenshot`: generated GPT Image reference, screenshots, state captures, viewport captures, and visual diffs.
+- `accessibility`: keyboard order, focus visibility, contrast, reduced-motion, semantic landmarks, assistive-technology review, and cognitive accessibility review.
+- `user`: content hierarchy review, cognitive walkthrough, visitor decision-path review, design critique, participant testing, or validated measurement.
+- `source`: external methodology or standards used to frame the harmony claim.
+- `rationale`: claim record, rejected alternatives, limitations, accepted debt, owner, and review trigger.
+
+## Blocking Conditions
+
+Block the harmony claim when:
+
+- the use case is unnamed;
+- the page uses a fashionable layout that does not match the content jobs;
+- the GPT Image reference is generated before semantic order, section jobs, and pattern stack are approved;
+- the GPT Image reference is generated before scroll owner and constraints are approved;
+- rejected alternatives are missing when a fashionable or image-led pattern was considered;
+- a generated image is treated as proof of usability, accessibility, or brand fit;
+- visual novelty weakens source order, focus order, task completion, or content stress behavior;
+- decorative styling is moved into reusable pattern CSS;
+- the implementation handoff omits constraints, scroll ownership, accepted debt, or verification.
+
+## Accessibility Boundary
+
+Generated images, screenshots, visual diffs, and GPT Image references cannot prove accessibility. They can show rendered state, hierarchy, or visual intent, but accessibility claims must link to the accessibility evidence register and name an `automated`, `manual`, `user`, or `debt` verification method.
+
+## Boundary
+
+This gate decides whether a webpage composition is coherent enough to guide implementation. It does not define the consuming product's brand, typography, color, illustration style, animation system, or component library.
+
+Use a [structured claim record](../claims.md) when the harmony decision approves, blocks, or redirects implementation. Harmony records must include the use case and implementation handoff because they decide what the implementer may safely carry from a visual reference into product-level styling.
+
+If the work is an existing-consumer migration that declares conformance, route the separate migration evidence decision through the [Consumer Migration Evidence Gate](consumer-migration-evidence.md). Harmony cannot substitute for runtime parity or source-bound page evidence.
+
+## IA Navigation
+
+Parent: [Gate Contracts](index.md).
+Next: [Evidence References](../evidence/index.md) when a gate needs admissible support.

package/quality/gates/index.md

@@ -0,0 +1,13 @@
+# Gate Contracts
+
+Gate contracts define what kind of evidence can support a claim.
+
+## Gates
+
+- [Layout gate](layout.md) - Mechanical layout contract and stress evidence.
+- [Design claim gate](design-claim.md) - Required shape for non-layout design claims.
+- [Visual evidence gate](visual-evidence.md) - Rendered evidence and visual QA boundaries.
+- [Accessibility evidence gate](accessibility-evidence.md) - Accessibility evidence and review boundaries.
+- [Rationale gate](rationale.md) - Decision rationale, alternatives, warrants, and debt.
+- [Harmony evaluation gate](harmony-evaluation.md) - Contract for judging content-to-layout fit, overall harmony, GPT Image references, and implementation handoff.
+- [Consumer migration evidence gate](consumer-migration-evidence.md) - Blocking contract for consumer-owned migration conformance, runtime proof, and source-bound page evidence.

package/quality/gates/layout.md

@@ -0,0 +1,52 @@
+---
+type: Quality Gate
+title: Layout Gate
+description: Mechanical quality gate for StyleGallery Layout spatial pattern claims.
+---
+
+# Layout Gate
+
+The layout gate is the existing pattern contract made explicit as a quality gate.
+
+## Scope
+
+Layout owns:
+
+- semantic structure where it affects layout;
+- source order and focus order;
+- flow, sizing, alignment, spacing mechanics, scrolling, ratio, and containment;
+- explicit constraints and change points;
+- viewport, container, content, direction, writing-mode, and interaction stress.
+
+Layout does not own brand, typography voice, color expression, shadow, animation, decoration, or product visual identity.
+
+## Evidence
+
+Accepted layout evidence includes:
+
+- pattern frontmatter and required sections;
+- HTML and CSS snippets;
+- required core properties and break-if-removed notes;
+- constraints and scroll ownership;
+- accessibility and source-order notes;
+- validator output from `scripts/validate-patterns.mjs`;
+- manual stress checks from the repository verification matrix.
+
+## Blocking Conditions
+
+Block a layout claim when:
+
+- the pattern solves more than one primary spatial problem without being marked as a composite;
+- required contract sections are missing;
+- reusable CSS includes decorative properties without a layout-specific reason;
+- source order, focus order, or scroll ownership is unclear;
+- reflow claims are unsupported by the CSS mechanism.
+
+## Boundary
+
+Visual polish is not a layout pass/fail condition. If a concern is about color, typography voice, surface treatment, motion, or brand fit, route it to the design claim gate.
+
+## IA Navigation
+
+Parent: [Gate Contracts](index.md).
+Next: [Evidence References](../evidence/index.md) when a gate needs admissible support.