stylegallery 0.1.0

package/platform-guides/index.md

@@ -0,0 +1,26 @@
+# Platform Guides
+
+Platform Guides own bounded comparison with named platform conventions and their version, authority, adaptation, and freshness limits.
+
+## Scope Boundary
+
+In scope: comparative vocabulary, interaction questions, current official-source requirements, and locally verified adaptation notes.
+
+Out of scope: affiliation, brand imitation, unsupported platform equivalence, and authority over web standards, accessibility, or Layout contracts.
+
+## Available Guides
+
+- [Apple Interaction As A Comparative Reference](apple-interaction.md) turns selected interaction themes into questions for web adaptation without claiming platform equivalence.
+
+## Comparison, Not Imitation
+
+A platform guide names the platform, source authority, version or review date, web-adaptation boundary, and local verification protocol. Similar appearance or behavior does not establish affiliation or correctness.
+
+## Domain Contract
+
+See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and promotion rules.
+
+## IA Navigation
+
+Parent: [StyleGallery](../index.md).
+Next: [Apple Interaction As A Comparative Reference](apple-interaction.md).

package/quality/claim-records/index.md

@@ -0,0 +1,3 @@
+# Claim Records
+
+- [Sample claim records](samples.md)

package/quality/claim-records/samples.md

@@ -0,0 +1,92 @@
+---
+type: Quality Reference
+title: Sample Claim Records
+description: Filled structured quality claims for common review decisions.
+---
+
+# Sample Claim Records
+
+These examples show the minimum useful record shape. They are intentionally compact so high-impact claims remain reviewable without becoming heavy documentation work.
+
+## Claim Record 1 - Harmony Before Image Generation
+
+Principle: Accessibility precedence and principles before evidence.
+
+Claim: A homepage GPT Image reference should be generated only after the content-to-layout match and harmony evaluation approve semantic order, section jobs, pattern stack, scroll owner, and constraints.
+
+Context: Webpage generation can otherwise let a visual reference decide layout before source order and task flow are known.
+
+Use case: Homepage or ordinary webpage generation from raw content.
+
+Warrant: The image can help inspect hierarchy and spacing only after the layout contract names the content jobs and constraints it should express.
+
+Evidence family: `rationale`, `source`, `screenshot`.
+
+Verification protocol: Check that the layout brief names use case, section jobs, pattern stack, rejected alternatives, harmony notes, GPT Image reference prompt, and implementation handoff before image generation.
+
+Implementation handoff: Build semantic HTML and layout patterns first; copy only hierarchy, rhythm, media treatment, and CTA priority into product-level styling after the gate passes.
+Consumer reference: not_applicable
+Consumer reference reason: This sample contains no consumer-specific reference record.
+
+Boundary or limitation: The image cannot prove usability, accessibility, brand fit, or final implementation quality.
+
+Debt or escalation: If the visual reference conflicts with source order, focus order, accessibility, or content stress behavior, regenerate the prompt or record a blocked decision.
+
+Decision: pass when the harmony gate is complete before the image is generated.
+
+## Claim Record 2 - Screenshot Diff Limits
+
+Principle: Visual QA evidence precedes visual judgment.
+
+Claim: A stable screenshot diff supports a rendered-state claim, but it does not prove usability or accessibility.
+
+Context: Visual review often finds regressions, overflow, hidden text, and hierarchy shifts, but user-facing outcomes require stronger evidence.
+
+Use case: not applicable.
+
+Warrant: Screenshots show a bounded rendered state; usability and accessibility depend on task completion, semantics, keyboard flow, assistive technology, and user context.
+
+Evidence family: `screenshot`, `accessibility`, `user`.
+
+Verification protocol: Pair screenshots with the visual-evidence gate and route accessibility or usability claims to their dedicated evidence families.
+
+Implementation handoff: not applicable.
+Consumer reference: not_applicable
+Consumer reference reason: This screenshot-limits sample contains no consumer-specific reference record.
+
+Boundary or limitation: A screenshot can hide focus order, screen-reader output, dynamic states, and untested content stress.
+
+Debt or escalation: Escalate to accessibility or user evidence when the claim says readable, usable, accessible, clear, good, better, or harmonious for a person or task.
+
+Decision: review_required when screenshots are the only evidence for a human-outcome claim.
+
+## Claim Record 3 - Accessibility Scan Limits
+
+Principle: Accessibility is a boundary condition.
+
+Claim: An automated accessibility scan can support a scoped accessibility finding, but it cannot certify complete accessibility.
+
+Context: Automated checks miss keyboard behavior, assistive-technology behavior, cognitive load, language clarity, and some semantic defects.
+
+Use case: not applicable.
+
+Warrant: The scan is validator evidence for detectable rules; complete accessibility needs manual and contextual evidence.
+
+Evidence family: `validator`, `accessibility`, `user`.
+
+Verification protocol: Record the scan tool, ruleset, viewport or state, manual keyboard checks, and any required screen-reader, accessibility-tree, or cognitive review.
+
+Implementation handoff: not applicable.
+Consumer reference: not_applicable
+Consumer reference reason: This accessibility-limits sample contains no consumer-specific reference record.
+
+Boundary or limitation: The scan cannot prove accessibility for every user, device, browser, or assistive-technology pairing.
+
+Debt or escalation: Accessibility debt must name affected users, owner, review trigger, and the evidence gap before it can be accepted.
+
+Decision: blocked when a known accessibility failure is treated as a taste tradeoff or ordinary visual debt.
+
+## IA Navigation
+
+Parent: [Claim Records](index.md) in [Quality Gates](../index.md).
+Next: [Structured Quality Claims](../claims.md) for the template and high-impact scope rule.

package/quality/claim-records/stylegallery-multidomain-scope.md

@@ -0,0 +1,42 @@
+---
+type: Decision Record
+title: StyleGallery Multi-Domain Scope Decision
+description: Decision to supersede the layout-only repository identity with a governed multi-domain umbrella.
+---
+
+# StyleGallery Multi-Domain Scope Decision
+
+## Decision
+
+StyleGallery supersedes the repository-wide `layout-gallery` identity with five explicit domains: Layout, Motion, Design Engineering, Game UI, and Platform Guides. The prior layout-only rules remain authoritative inside Layout instead of being deleted or silently weakened.
+
+## Context
+
+The repository name and intended collection now exceed a single spatial corpus. Treating motion, interface craft, game-interface knowledge, engine-specific Game UI implementation, or platform comparison as Layout patterns would violate the existing pattern boundary, while leaving them ungoverned would bypass source-of-truth, ownership, lifecycle, and evidence rules.
+
+## Warrant
+
+Separate domains let each content family name what it owns, what it excludes, what evidence can support it, and who reviews it. Preserving existing Layout paths avoids a destructive migration and keeps the current generator isolated.
+
+## Consequences
+
+- Root navigation selects a domain before domain-local guidance.
+- `layout/index.md` is a facade; it does not replace README, the OKF index, planning guide, or catalog.
+- Motion and visual references cannot authorize decorative CSS in reusable Layout patterns.
+- `quality/**` remains shared evidence and gate infrastructure; Layout-specific gates stay explicitly named.
+- New externally inspired content starts experimental and requires immutable provenance plus an evidence boundary.
+
+## Rejected Alternatives
+
+- Keeping a layout-only root and hiding the new material under references would not make it a first-class StyleGallery category.
+- Moving all existing Layout paths under `layout/` would break stable links and generated ownership without adding user value.
+- Installing upstream agent skills would introduce agent authority, mutable acquisition, and document-contract conflicts instead of repository-native guidance.
+
+## Boundary Or Limitation
+
+This decision establishes information architecture and governance. It does not prove that any practitioner heuristic, platform behavior, accessibility outcome, or performance claim is correct for a product implementation.
+
+## IA Navigation
+
+Parent: [Claim Records](index.md) in [Quality Gates](../index.md).
+Next: [StyleGallery Domains](../../DOMAINS.md) for the active domain manifest.

package/quality/claims.md

@@ -0,0 +1,77 @@
+---
+type: Quality Reference
+title: Structured Quality Claims
+description: Claim-record template and scope rules for high-impact design judgments.
+---
+
+# Structured Quality Claims
+
+Use a claim record when a design judgment would otherwise rest on taste, authority, or an unlabeled artifact.
+
+The record makes the review chain inspectable:
+
+```txt
+principle -> claim -> context -> warrant -> evidence family -> verification protocol -> boundary/debt
+```
+
+## High-Impact Claim
+
+A high-impact claim is any statement that can block, approve, or redirect layout, accessibility, implementation, or design-review work.
+
+Treat the following as high-impact terms when they decide work rather than describe prose:
+
+- `good`, `better`, or `best`;
+- `harmonious` or `harmony`;
+- `appropriate`, `proper`, or `fit`;
+- `usable`, `accessible`, `readable`, `credible`, or `clear`;
+- claims that a screenshot, source, generated image, validator, or public design system proves quality.
+
+## When A Claim Record Is Required
+
+Create a claim record when:
+
+- a quality gate accepts, rejects, blocks, or defers a claim;
+- a harmony evaluation decides whether a GPT Image reference can guide implementation;
+- a screenshot, validator, accessibility scan, source, or rationale artifact is used as evidence;
+- a high-impact term changes the pattern stack, source order, accessibility requirement, implementation handoff, or accepted debt;
+- a claim names user perception, usability, accessibility, or visual quality.
+
+## Low-Risk Prose
+
+Do not require a claim record for:
+
+- navigation text, index summaries, or cross-reference copy;
+- examples that do not approve or block work;
+- local descriptions of fields already governed by a linked gate;
+- editorial wording that does not create implementation guidance.
+
+Low-risk prose can still link to a gate or claim record when the reader needs the review boundary.
+
+## Claim Record Template
+
+```txt
+Principle:
+Claim:
+Context:
+Use case:
+Warrant:
+Evidence family:
+Verification protocol:
+Implementation handoff:
+Consumer reference: not_applicable
+Consumer reference reason: This blank claim template declares no consumer-specific reference record.
+Boundary or limitation:
+Debt or escalation:
+Decision:
+```
+
+`Use case` and `Implementation handoff` are required for harmony claims. For other claim types, write `not applicable` rather than deleting the fields.
+
+## Review Rule
+
+A record is complete only when the evidence family names what the artifact can support and the boundary says what it cannot prove. Evidence without a warrant remains a blocking condition.
+
+## IA Navigation
+
+Parent: [Quality Gates](index.md).
+Next: [Sample Claim Records](claim-records/samples.md) for compact examples of completed quality decisions.

package/quality/evidence/accessibility.md

@@ -0,0 +1,58 @@
+---
+type: Evidence Reference
+title: Accessibility Evidence
+description: Accessibility evidence sources and limits.
+---
+
+# Accessibility Evidence
+
+Accessibility evidence combines standards, automated checks, manual review, and user-context judgment.
+
+## Claim Classification Register
+
+Every accessibility claim must name one verification method before it is used in a quality record.
+
+| Verification method | Supports | Does not support | Required record |
+| --- | --- | --- | --- |
+| automated | Rule-scoped checks such as axe, ACT, contrast math, lint rules, or validator output. | Keyboard logic, screen-reader comprehension, task success, or cognitive load beyond the tested rule. | Tool name, rule set, scope, date, and unresolved findings. |
+| manual | Expert review of DOM/source order, focus order, keyboard behavior, screen-reader flow, motion comfort, language clarity, or cognitive load. | Representative user comprehension or population-level accessibility. | Reviewer, scenario, viewport/device if relevant, observed pass/fail, and debt. |
+| user | Participant evidence for task completion, comprehension, perceived effort, or assistive-technology fit. | General compliance outside the tested audience and scenario. | Audience, task, method, sample limits, outcome, and follow-up trigger. |
+| debt | A known gap accepted for a bounded reason. | A positive accessibility claim. | Affected users, risk, owner, review trigger, and expiry condition. |
+
+## Quality Claim Linkage
+
+Quality claims that mention accessibility must link directly to one register row and one evidence artifact. If the claim depends on multiple facts, split it: for example, contrast may be `automated`, while keyboard order and cognitive load require `manual` or `user` evidence.
+
+## Evidence Types
+
+- WCAG-oriented checks;
+- ACT-rule checks;
+- automated scan output;
+- keyboard and focus review;
+- contrast review;
+- accessibility-tree or screen-reader review;
+- cognitive accessibility review.
+
+## Can Support
+
+- no issue was detected by a tested rule set;
+- a specific WCAG or ACT-related condition was checked;
+- a manual review found or did not find a stated barrier;
+- an accessibility debt item has affected users and a review trigger.
+
+## Cannot Prove
+
+- complete accessibility;
+- universal task completion;
+- cognitive accessibility for every user;
+- assistive technology behavior that was not tested.
+- accessibility from a screenshot, visual diff, generated image, or GPT Image reference.
+
+## Required Phrase
+
+Automated accessibility scans assist evaluation, not determine accessibility.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/consumer-migration.md

@@ -0,0 +1,42 @@
+---
+type: Evidence Reference
+title: Consumer Migration Evidence
+description: Evidence channels and claim boundaries for consumer migration readiness.
+---
+
+# Consumer Migration Evidence
+
+Consumer migration evidence is a linked chain, not a single screenshot or successful validator invocation.
+
+## Evidence Channels
+
+| Channel | Supports | Does not support by itself |
+| --- | --- | --- |
+| Conformance schema and validator | The record is closed, all thirteen dimensions are explicit, paths are safe, and references are internally consistent. | The behavior inventory is complete or the product is correct. |
+| Unit and integration scenarios | Named observable behavior passed at the pinned source digest and zero exit. | Browser layout, visual quality, or untested behavior. |
+| Browser matrix | Named viewport, container, content, state, overlay, page-scale, focus, overflow, contrast, and semantic assertions passed in the executed browser. | Complete accessibility, usability, or cross-browser equivalence. |
+| Page-evidence session | Artifacts came from one source-bound session and match the finalized manifest hashes and identities. | Independent provenance, design approval, or truth outside the declared run. |
+| Adoption mapping | A pinned StyleGallery anchor was interpreted as a named local decision for a concrete consumer target. | Universal adoption or permission to import product styling into Layout. |
+| Freshness audit | Evidence is within its declared advisory or blocking review window. | Continued correctness after source or environment changes. |
+| Human review | A named reviewer evaluated the inventory, exclusions, deviations, debt, and claim boundary. | Facts outside the recorded review method and scope. |
+
+## Page Evidence Matrix
+
+When page evidence applies, execute widths `320`, `375`, `768`, `1024`, and `1440` pixels. Cover tight, medium, roomy, and full-width containers; empty, short, long, and unbroken content; applicable interactive states and overlays; and declared page-scale changes. Assert logical focus, absence of unusable overflow, sufficient computed contrast, and semantic landmarks in the live page.
+
+Raster capture is review material. Deterministic computed and semantic assertions are the blocking evidence. Platform-specific screenshots remain nonblocking unless a separately approved platform baseline contract says otherwise.
+
+## Source And Session Binding
+
+Create the page session before capture and finalize only from a clean, unchanged source inventory. A completed manifest must preserve the consumer repository and revision, exact relevant-source paths and digests, intended browser scenario IDs, run ID, session ID, runner exit, artifact paths, byte counts, dimensions where relevant, and SHA-256 hashes. Reject cross-revision, cross-run, cross-session, missing, extra, changed, symlinked, escaped, or replayed artifacts.
+
+For unit and integration evidence, the stored result must be structurally equivalent JSON to the result created by the declared Node `argv` in an isolated checkout of the pinned consumer revision. The governed Node permission boundary denies descendant processes, workers, native addons, and WASI; an `argv` cannot weaken those denials. Whitespace and object-key order may differ; parsed values may not. A prewritten receipt, a zero-exit no-op, current-worktree dependencies, and caller CI identity variables are not runtime proof.
+
+## Claim Boundary
+
+A passing record supports: “the named migration scenarios and evidence agree with this declared contract at these pinned revisions.” It cannot support: “the product is fully accessible,” “all behavior is preserved,” “the design is correct,” “StyleGallery certifies this consumer,” or “this local decision is a shared standard.”
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Consumer Migration Readiness](../../design-engineering/consumer-migration-readiness.md).

package/quality/evidence/design-rationale.md

@@ -0,0 +1,34 @@
+---
+type: Evidence Reference
+title: Design Rationale Evidence
+description: Rationale structures for design-side quality decisions.
+---
+
+# Design Rationale Evidence
+
+Design rationale records why a quality claim is admissible.
+
+## Evidence Structures
+
+- issue, position, and argument;
+- question, option, and criterion;
+- claim, ground, and warrant;
+- goal, strategy, context, assumption, and evidence.
+
+## Can Support
+
+- a design decision considered alternatives;
+- a claim has a warrant;
+- a limitation or counterclaim is visible;
+- design debt is intentional rather than accidental.
+
+## Cannot Prove
+
+- the selected option is empirically best;
+- a user-facing outcome without user or task evidence;
+- accessibility, usability, or visual quality by itself.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/executable-evidence.md

@@ -0,0 +1,79 @@
+---
+type: Evidence Reference
+title: Executable Evidence Coverage
+description: Claim-to-evidence map for validators, tests, rendered QA, review, and source citations.
+---
+
+# Executable Evidence Coverage
+
+Executable evidence identifies which claims are machine-enforced, which are only inspected, and which need rendered or human evidence before they can be stated strongly.
+
+## Evidence Families
+
+- Validator: repository scripts that inspect files and fail with a non-zero exit code.
+- Advisory warning: a validator result that reports preferred wording or labels in `warnings` while leaving `ok: true` and the exit code at zero.
+- Fixture test: positive or negative examples that prove a validator rejects or accepts the intended shape.
+- CI command: a workflow command that runs on pull requests or pushes.
+- Rendered evidence: screenshots, viewport captures, browser QA, or visual diffs.
+- Human review: expert, heuristic, accessibility, or task review that records a claim boundary.
+- Source citation: external or local references used only inside a stated claim boundary.
+
+## Validator Coverage Map
+
+| Claim | Validator or test | CI command | Positive evidence | Negative evidence | Evidence boundary |
+| --- | --- | --- | --- | --- | --- |
+| OKF files have required structural metadata and valid root index or log shapes. | `scripts/validate-okf.mjs` and `scripts/test-validate-okf.mjs` | `node scripts/validate-okf.mjs --json`; `node scripts/test-validate-okf.mjs --json` | `success_path` fixture returns `ok: true`. | Missing frontmatter, missing type, concept frontmatter on `index.md`, and malformed log date fixtures must fail. | Proves repository structure, not conceptual quality or source truth. |
+| Pattern documents carry the required spatial contract sections and restricted CSS/HTML shape. | `scripts/validate-patterns.mjs` and `scripts/test-validate-patterns.mjs` | `node scripts/validate-patterns.mjs --min-count 46 --json`; `node scripts/test-validate-patterns.mjs --json` | Generated patterns satisfy required fields, sections, CSS ordering, selector, and count rules. | Missing metadata, unsorted CSS, forbidden decorative properties, ID selectors, missing code blocks, missing HTML hooks, and missing contract sections must fail. Preferred accessibility detail labels emit warnings without blocking equivalent prose. | Proves the written pattern contract and static examples, not rendered layout quality. |
+| Webpage-generation workflow references remain present across guides, recipes, and gates. | `scripts/validate-webpage-workflow.mjs` and `scripts/test-validate-webpage-workflow.mjs` | `node scripts/validate-webpage-workflow.mjs --json`; `node scripts/test-validate-webpage-workflow.mjs --json` | The success fixture includes the required workflow references and contract snippets. | Missing route structure, required template fields, link targets, safety boundaries, or route order must fail. Preferred link labels and GUIDE wording emit warnings. | Proves required structure and safety boundaries are present, not that a generated webpage is visually harmonious. |
+| Consumer migration readiness remains discoverable and keeps migration-only handoff semantics. | `scripts/validate-ia.mjs`, `scripts/test-validate-ia.mjs`, `scripts/validate-webpage-workflow.mjs`, and `scripts/test-validate-webpage-workflow.mjs` | Run both validators and fixture harnesses. | Root, domain, consumer-reference, quality gate, evidence, workflow, and taxonomy routes reach the method within two hops; ordinary templates retain reasoned non-applicability while migration guidance declares a separate field. | Missing method routes, missing thirteen-dimension wording, missing migration-only boundary, or replacing the ordinary handoff declaration must fail. | Proves documentation structure and declared handoff semantics, not a consumer migration result. |
+| A consumer-owned migration record links thirteen explicit classifications, executable scenarios, adoption mappings, and applicable source-bound page evidence. | `scripts/validate-consumer-conformance.mjs`, `scripts/test-validate-consumer-conformance.mjs`, page-evidence lifecycle scripts, and their fixture harnesses. | Run the conformance and page-evidence contract suites; execute the browser matrix separately when page evidence applies. | Closed schemas, pinned revisions, safe paths, zero-exit scenario records, adoption mappings, and one finalized matching page session pass. | Missing dimensions, unknown scenarios, unsafe paths, source drift, failed runner, cross-run/session/revision reuse, missing/extra/tampered artifacts, and mismatched source or scenario sets fail with named findings. | Supports agreement at pinned revisions only; it does not certify accessibility, product correctness, usability, adoption, or approval. |
+| Consumer browser semantics hold across the declared viewport, container, content, state, overlay, and Chromium page-scale matrix. | `tests/consumer-conformance.spec.mjs`, `scripts/test-consumer-conformance-sentinel.mjs`, and `scripts/run-consumer-page-evidence-ci.mjs` | The blocking `consumer-conformance` job runs 147 generated browser scenarios and all eight semantic/filesystem negative controls. The nonblocking `consumer-page-evidence` job creates a source-bound synthetic consumer session, verifies that its receipt uses the synthetic Git repository, branch, and revision instead of the parent Actions identity, captures one selected raster with `PAGE_EVIDENCE_*`, finalizes and validates it, then uploads only the completed packet. | Widths 320, 375, 768, 1024, and 1440; tight, medium, roomy, and full containers; empty, long-label, long-paragraph, CJK, and unbroken content; state, overlay, and Chromium page-scale probes exercise focus, overflow, contrast-ratio math, semantics, and runtime errors. | Overflow, clipped focus, low contrast, focus leakage, console-error mutations, or a leaked parent Actions identity fail on their named assertion; symlinked, pre-existing, and cleanup-redirected page-evidence paths fail without outside writes, deletion, or overwritten bytes. | The blocking job proves deterministic browser contracts in the pinned Chromium environment. The optional validated packet supports review but does not prove usability, accessibility, product suitability, or cross-browser behavior. |
+| Explicit evidence deadlines are audited weekly without inventing a repository-wide maximum age. | `scripts/audit-evidence-freshness.mjs`, `scripts/test-audit-evidence-freshness.mjs`, and `scripts/validate-governance.mjs` | `.github/workflows/evidence-freshness.yml` runs Monday at 05:00 UTC and by manual dispatch in advisory mode, emits annotations, and uploads the JSON report for 14 days. | Fresh, expiring, expired, review-due, and no-explicit-expiry records retain their declared semantics. | Malformed records and auditor failures remain blocking even though due-date findings are advisory. | The audit reports only explicit `expires_at` and `review_by` values; it does not infer a TTL, establish evidence quality, or revoke a claim automatically. |
+| Markdown links resolve inside the repository. | `scripts/validate-links.mjs` | `node scripts/validate-links.mjs --json` | All checked Markdown links resolve to local files or are intentionally external or anchors. | A local link that escapes the repository or points at a missing file must fail. | Proves link targets exist, not that the target content supports a claim. |
+| Catalog and generated pattern indexes match the pattern data source. | `scripts/validate-catalog.mjs` | `node scripts/validate-catalog.mjs --json` | `CATALOG.md`, category indexes, and expected pattern files match `scripts/pattern-data.mjs`. | Missing, unexpected, or unlisted pattern files must fail. | Proves catalog consistency, not pattern usefulness. |
+| Governance, lifecycle, generated-file, ownership, and stale-content policy remain discoverable and CI-enforced. | `scripts/validate-governance.mjs` and `scripts/test-validate-governance.mjs` | `node scripts/validate-governance.mjs --json`; `node scripts/test-validate-governance.mjs --json` | `GOVERNANCE.md`, `.github/CODEOWNERS`, generated warnings, generated metadata, root link targets, lifecycle states, `scheduled_stale_audit` metadata, and CI wiring are present. | Missing governance file, generated warning, generated metadata, CODEOWNERS coverage, or stale policy fixtures must fail. Preferred governance prose and link labels emit warnings. | Proves governance policy is present and linked, not that CODEOWNERS users have verified repository write access. |
+| Domain topology, metadata, provenance, scope boundaries, and root routes remain enforced. | `scripts/validate-domains.mjs` and `scripts/test-validate-domains.mjs` | `node scripts/validate-domains.mjs --json`; `node scripts/test-validate-domains.mjs` | Five governed domains and their declared leaves are reachable and attributed. | Domain metadata, immutable provenance, scope boundaries, and root-route fixtures must fail. | A full SHA proves content identity syntax, not publisher authenticity, source ownership, or local quality. |
+| Consumer-reference handoffs, schema/runtime parity, repository-local record paths, lifecycle separation, ownership truth, and dependency direction remain enforced. | `scripts/validate-consumer-reference.mjs` and `scripts/test-validate-consumer-reference.mjs` | `node scripts/validate-consumer-reference.mjs --json`; `node scripts/test-validate-consumer-reference.mjs --json` | Declared and reasoned-not-applicable fixtures exit zero, every shipped schema rule has accepted/rejected parity coverage, all repository handoffs declare applicability, fixtures remain related, and ownership discloses placeholder single-account review. | Unknown top-level or nested properties, invalid schema fields, missing handoff or reason, stable with ended support, boolean independence, unresolved/absolute/scheme/network/parent/item-or-record-symlink/non-JSON paths, scaffold success, sixth-domain classification, literal or supported computed reverse imports, and repository handoff omissions must fail with named finding codes and non-zero child exit. | Proves receiver-contract consistency, bounded static dependency detection, and path containment, not general JavaScript data-flow safety, visual quality, independent adoption, verified owner permissions, or consumer implementation conformance. |
+| Promotion governance remains a closed JSON-only, invariant-scoped, deferred example contract. | `scripts/validate-promotion-rfc.mjs` and `scripts/test-validate-promotion-rfc.mjs` | `node scripts/validate-promotion-rfc.mjs --json`; `node scripts/test-validate-promotion-rfc.mjs --json` | The manifest-declared policy and two canonical examples pass with deferred decisions, zero attestations, exact support commitment, and no promotion claim. | Manifest-declared invalid fixtures plus forged, unregistered, duplicate, path, extension, support, evidence, canonical-drift, and lifecycle mutations exit non-zero with named findings. | Synthetic validation does not authenticate adoption, organizations, owners, support capacity, provenance, or a promotion decision; the current canonical inventory supplies no real independent consumers. |
+| Portable token source and generated CSS agree through the pinned restricted adapter. | `scripts/build-reference-artifacts.mjs`, `scripts/validate-reference-artifacts.mjs`, and `scripts/test-reference-adapters.mjs` | Build with `--fail-on-warning`, validate the generated manifest, then run the adapter fixture harness. | Dimension, color, duration, tested border values, and whole-token curly aliases emit nonzero CSS declarations with matching counts and hashes; output references remain CSS variable references. | `$extends`, JSON Pointer, resolver/modifier/theme documents, unknown reserved fields, non-string descriptions, adapter-unsafe path segments, untested type/unit, partial/dangling/cyclic/type-mismatched aliases, missing output, zero count, warning, scaffold/unknown manifest fields, missing/duplicate declaration, object sentinel, unresolved or forged value, and count drift must fail with named findings and non-zero child exit. | Proves the pinned adapter preserves this tested subset and that committed artifacts independently rebuild from their canonical source, not that tokens are product defaults, portable beyond the tested adapters, visually suitable, or adopted by a consumer. |
+| The proposed Chromium sentinel preserves canonical card-grid geometry and truth-derived calibration evidence. | `tests/consumer-reference-sentinels.spec.mjs`, `scripts/test-consumer-reference-sentinel.mjs`, `scripts/validate-baseline-manifest.mjs`, and strict raw calibration harnesses. | Run the ordinary sentinel and semantic negatives in the digest-pinned nonblocking Chromium job; validate manifest/raw evidence in the contract job. | Computed visibility/cardinality/grid/gap/geometry/overflow checks precede a locator screenshot; raw DOM and AX bytes are recorded and hash-checked across runs; completion and zero diff derive only from a zero child exit, the exact passing Playwright identity, verified raw hashes, and post-assertion comparison proof. | Hidden layout, long-content overflow, fake/malformed Playwright, missing or nonzero exit, absent comparison/artifact, tampered hash, duplicate/unknown metadata, malformed recursive records, and incomplete run sets must fail without writing a completed aggregate. | Local DOM/AX/rendered evidence does not prove semantic DOM/AX conformance, product suitability, accessibility, or owner approval. 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. Both Chromium jobs are nonblocking and CI never updates snapshots. |
+| Governed-local button states retain source-bound visual, DOM, and accessibility-tree evidence across both example profiles. | `scripts/create-component-state-session.mjs`, `scripts/finalize-component-state-evidence.mjs`, `scripts/validate-component-state.mjs`, and the component-state source, contract, artifact, generator, and sentinel harnesses. | `npm run test:component-state`; `npm run validate:component-state`; run the digest-pinned component-state browser capture and `npm run test:component-state:runtime-negative`. | Editorial and terminal each declare the five compound scenarios `action-disabled-busy`, `action-focused`, `action-loading-busy`, `disclosure-expanded-loading`, and `toggle-focused-pressed`; their environment-scoped approved PNG hashes and dimensions are canonical pre-capture inputs; the generated state, keyboard, and evidence matrices match their records; one clean capture session binds the browser artifacts to the governed source inventory. | Missing or altered source bindings, missing executable source manifests, invalid state/profile records, scenario drift, coordinated PNG/manifest/sidecar substitution, unapproved environment-specific raster identity, malformed or replayed runtime artifacts, hash/count mismatch, insufficient focus clearance, and sentinel mutations must exit non-zero with named findings. | Proves the declared examples and captured channels agree for an explicitly approved browser environment. Legacy source-less receipts are intentionally rejected by the capture receipt, `session_link`, and `completed_session` schemas and by executable finalization and validation. Environment-scoped PNG identity does not imply cross-platform pixel equivalence. It does not prove product suitability, independent adoption, full accessibility, cross-browser behavior, or owner approval; synthetic negative fixtures are not authenticated provenance. |
+
+## Validator Severity Contract
+
+- `failures` contains structural, schema, safety-boundary, link-target, ordering, or generated-drift violations. Any failure sets `ok: false` and exits non-zero.
+- `warnings` contains preferred natural-language wording, link labels, or scannability guidance. Warnings leave `ok: true` and exit zero.
+- A fixture that moves a check from blocking to advisory must prove both sides: an equivalent paraphrase produces a warning, while the corresponding missing structure or machine-readable field still fails.
+
+## Claim Boundaries
+
+- Validator evidence can support "the repository enforces this structural rule."
+- Fixture evidence can support "the validator rejects this known-bad shape."
+- CI evidence can support "this command runs in the workflow."
+- Rendered evidence can support "this viewport or state was captured for review."
+- Human review can support "a reviewer evaluated this claim under a named method."
+- Source citation can support "this claim has an admissible reference boundary."
+
+## Rendered Evidence Backlog
+
+| Rendered claim | Required evidence |
+| --- | --- |
+| A pattern produces the intended layout behavior across breakpoints. | Browser screenshot matrix for narrow, medium, and wide viewports, plus the relevant state if the pattern has interaction or overflow. |
+| A generated webpage is harmonious. | Browser screenshots of the page, a completed harmony evaluation gate, and a human review note. |
+| A visual change is stable. | Before and after screenshots or a visual diff for the named viewport and state. |
+| Accessibility is acceptable. | Automated checks, keyboard/focus review, and manual accessibility review scoped to the claim. |
+
+## Rejection Rules
+
+Reject a claim when:
+
+- it says or implies that visual quality is proven by validator output;
+- it treats screenshot evidence as proof of usability, accessibility, or task completion;
+- it treats source citations as proof of local rendered behavior;
+- it claims CI coverage for a script that is not run by `.github/workflows/validate.yml`;
+- it omits the negative fixture or failure mode for an enforced validator rule.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/families.md

@@ -0,0 +1,56 @@
+---
+type: Evidence Reference
+title: Evidence Family Glossary
+description: Normalized evidence families for structured quality claims.
+---
+
+# Evidence Family Glossary
+
+Use these evidence-family names in claim records. A claim can cite more than one family when the warrant needs multiple kinds of support.
+
+## `validator`
+
+Executable checks, fixtures, schema validation, link checks, and CI output.
+
+- Can support: file shape, required fields, link integrity, route order, repeatable mechanical constraints.
+- Cannot prove: usability, accessibility, visual quality, brand fit, or user comprehension.
+
+## `screenshot`
+
+Screenshots, visual diffs, viewport captures, state captures, and rendered DOM artifacts.
+
+- Can support: what rendered at a specific viewport, state, density, or interaction point.
+- Cannot prove: task success, accessibility, user preference, or complete responsive behavior by itself.
+
+## `accessibility`
+
+Automated scans, keyboard checks, contrast checks, semantic review, screen-reader or accessibility-tree review, reduced-motion checks, and cognitive accessibility review.
+
+- Can support: named accessibility risks, pass/fail observations, and review scope.
+- Cannot prove: complete accessibility for every user or every assistive-technology pairing.
+
+## `user`
+
+Participant evidence, task review, persona review, cognitive walkthrough, heuristic evaluation, or validated perception instruments.
+
+- Can support: task success, perceived clarity, user comprehension, or human-judgment claims inside the observed population and method.
+- Cannot prove: universal preference, brand quality, or outcomes outside the tested task.
+
+## `source`
+
+Academic, standards, official tooling, methodology, vendor, practice, or public design-system references.
+
+- Can support: vocabulary, methods, constraints, standards, and implementation examples.
+- Cannot prove: local quality unless connected to repository context, rendered evidence, and a warrant.
+
+## `rationale`
+
+ADR-style or Toulmin-style records, options considered, criteria, counterclaims, limitations, debt, owner, and review trigger.
+
+- Can support: why a decision is admissible, what alternatives were rejected, and what boundary controls the claim.
+- Cannot prove: the selected option is empirically best without `user` or other outcome evidence.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Executable evidence](executable-evidence.md) for validator, fixture, CI, rendered, review, and citation boundaries.

package/quality/evidence/hci-evaluation.md

@@ -0,0 +1,36 @@
+---
+type: Evidence Reference
+title: HCI Evaluation Evidence
+description: Usability, walkthrough, heuristic, and perception evidence boundaries.
+---
+
+# HCI Evaluation Evidence
+
+HCI evidence helps separate task success, perceived usability, aesthetics, and cognitive load.
+
+## Evidence Types
+
+- heuristic evaluation;
+- cognitive walkthrough;
+- persona or task review;
+- first-impression or perceived-aesthetics evidence;
+- user testing or validated instruments when required.
+
+## Can Support
+
+- a task path has been reviewed;
+- a usability heuristic has an observed issue or pass condition;
+- a design claim needs human review rather than static validation;
+- empirical evidence is required before making a strong user-perception claim.
+
+## Cannot Prove
+
+- universal user preference;
+- aesthetic quality from a single expert opinion;
+- task success without a task scenario;
+- user perception without user or validated-instrument evidence.
+
+## IA Navigation
+
+Parent: [Evidence References](index.md).
+Next: [Quality Gates](../index.md) to decide whether the evidence supports a claim.

package/quality/evidence/index.md

@@ -0,0 +1,16 @@
+# Evidence References
+
+Evidence references describe what sources and artifacts can support. They do not decide quality by themselves.
+
+## References
+
+- [Sources](sources.md) - Source admissibility and source families.
+- [Evidence family glossary](families.md) - Normalized `validator`, `screenshot`, `accessibility`, `user`, `source`, and `rationale` families for claim records.
+- [Executable evidence](executable-evidence.md) - Validator, fixture, CI, rendered, review, and citation boundaries.
+- [Consumer migration evidence](consumer-migration.md) - Runtime, page-session, adoption, freshness, and human-review boundaries for migration readiness.
+- [Visual QA](visual-qa.md) - Rendered evidence references and limits.
+- [Accessibility](accessibility.md) - Accessibility evidence references and limits.
+- [HCI evaluation](hci-evaluation.md) - Heuristic, walkthrough, and user-evidence references.
+- [Design rationale](design-rationale.md) - Rationale and argument-structure references.
+- [Tokens](tokens.md) - Design token evidence and limits.
+- [Search, metadata, and polyhierarchy](search-metadata-polyhierarchy.md) - Retrieval benchmark, metadata dictionary, and search adoption decision.