stylegallery 0.1.0

package/guides/documentation-mode-taxonomy.md

@@ -0,0 +1,157 @@
+---
+type: Documentation Guide
+title: Documentation Mode Taxonomy
+description: Primary documentation modes, hybrid decisions, and task routing for StyleGallery.
+---
+
+# Documentation Mode Taxonomy
+
+Use this guide when adding, moving, or reviewing documentation. Each page should have one primary documentation mode so readers know whether to learn, follow steps, look up a contract, understand a rationale, or apply a policy gate.
+
+## Modes
+
+| Mode | Reader posture | Page should contain |
+| --- | --- | --- |
+| Tutorial | Learn by completing a first small task. | Ordered path, concrete starting state, completion marker. |
+| How-to | Follow steps to finish a known task. | Action sequence, decision points, expected handoff. |
+| Reference | Look up stable facts or contracts. | Names, fields, sections, generated indexes, boundaries. |
+| Explanation | Understand principles and rationale. | Why the repo works this way, scope, tradeoffs. |
+| Policy/procedure | Decide whether work is admissible. | Required contract, evidence, blocking conditions, boundary. |
+
+Do not use `mixed` as a mode. If a page has more than one reading posture, keep one primary mode and record the secondary mode plus the reason.
+
+## Page-Mode Matrix
+
+| Page or family | Primary mode | Secondary mode | Routing note |
+| --- | --- | --- | --- |
+| `README.md` | Explanation | How-to | Start here for repository purpose and top-level route selection. |
+| `GUIDE.md` | How-to | Explanation | Start here before the layout problem is obvious. |
+| `CATALOG.md` | Reference | None | Use when the pattern name or spatial problem is already known. |
+| `DOMAINS.md` | Reference | Policy/procedure | Use for top-level domain scope, membership, lifecycle, ownership, and provenance. |
+| `GOVERNANCE.md` | Reference | Policy/procedure | Look up source-of-truth, lifecycle, generated artifact, and review-owner rules. |
+| `AGENTS.md` | Policy/procedure | Reference | Use when editing the repository as an agent. |
+| `index.md` | Reference | None | OKF bundle index and link map. |
+| `log.md` | Reference | None | Chronological update record. |
+| `layout/index.md` | Reference | How-to | Enter the existing Layout planning, pattern, recipe, and quality routes without moving them. |
+| `motion/index.md` | Reference | Explanation | Enter Motion terminology, review, and practice references. |
+| `motion/*.md` | Reference or How-to | Explanation | Apply experimental motion terminology and review guidance inside its evidence boundary. |
+| `design-engineering/index.md` | Reference | Explanation | Enter Design Engineering product-level decision guidance. |
+| `design-engineering/*.md` | Explanation | How-to | Apply experimental practitioner methods without treating taste as proof. |
+| `design-engineering/consumer-migration-readiness.md` | How-to | Policy/procedure | Build a consumer-owned migration evidence chain without claiming universal authority. |
+| `platform-guides/index.md` | Reference | Explanation | Enter bounded comparative platform references. |
+| `platform-guides/*.md` | Explanation | Reference | Compare a named platform with explicit source, version, adaptation, and evidence limits. |
+| `guides/decision-tree.md` | How-to | Reference | Route from constraints to pattern families and recipes. |
+| `guides/layout-brief.md` | How-to | Reference | Fill before selecting a pattern stack. |
+| `guides/vocabulary.md` | Reference | Policy/procedure | Look up canonical terms, aliases, deprecated terms, and scannability rules. |
+| `guides/webpage-generation-workflow.md` | How-to | Policy/procedure | Convert raw content into a webpage handoff while preserving gate order. |
+| `guides/documentation-mode-taxonomy.md` | Reference | Policy/procedure | Audit documentation modes and routing. |
+| `recipes/index.md` | Reference | How-to | Look up screen-level recipes. |
+| `recipes/primitive-to-recipe-matrix.md` | Reference | How-to | Compare recipe primitive slots, substitution risks, and structural responsibilities. |
+| `recipes/homepage.md` | How-to | Reference | Compose a homepage or ordinary webpage from raw content. |
+| `recipes/article-page.md` | How-to | Reference | Compose readable prose with supporting aside content. |
+| `recipes/command-surface.md` | How-to | Reference | Compose a command-heavy shell. |
+| `recipes/dashboard.md` | How-to | Reference | Compose repeated panels and action clusters. |
+| `recipes/form-flow.md` | How-to | Reference | Compose a sequential form path. |
+| `recipes/list-detail.md` | How-to | Reference | Compose explorable list and detail regions. |
+| `recipes/saas-settings.md` | How-to | Reference | Compose fixed navigation with settings content. |
+| `patterns/index.md` | Reference | None | Pattern category index. |
+| `patterns/*/index.md` | Reference | None | Category-level pattern index. |
+| `patterns/centering/*.md` | Reference | None | Stable centering pattern contracts. |
+| `patterns/containment/*.md` | Reference | None | Stable containment pattern contracts. |
+| `patterns/grid-repetition/*.md` | Reference | None | Stable grid and repetition pattern contracts. |
+| `patterns/in-line-grouping/*.md` | Reference | None | Stable in-line grouping pattern contracts. |
+| `patterns/media-fit/*.md` | Reference | None | Stable media fitting pattern contracts. |
+| `patterns/overlay-exception/*.md` | Reference | None | Stable overlay and exception pattern contracts. |
+| `patterns/split-sidebar/*.md` | Reference | None | Stable split and sidebar pattern contracts. |
+| `patterns/stacking/*.md` | Reference | None | Stable stacking pattern contracts. |
+| `patterns/viewport-shell/*.md` | Reference | None | Stable viewport and shell pattern contracts. |
+| `quality/index.md` | Explanation | Policy/procedure | Understand the quality layer and route to gates. |
+| `quality/principles.md` | Explanation | Policy/procedure | Understand shared quality principles before using gates. |
+| `quality/claims.md` | Reference | Policy/procedure | Look up structured claim-record requirements and scope rules. |
+| `quality/claim-records/index.md` | Reference | None | Look up claim-record examples. |
+| `quality/claim-records/samples.md` | Reference | Explanation | Inspect compact examples of high-impact quality claim records. |
+| `quality/gates/index.md` | Reference | Policy/procedure | Look up available gate contracts. |
+| `quality/gates/accessibility-evidence.md` | Policy/procedure | Reference | Decide whether accessibility evidence supports a claim. |
+| `quality/gates/design-claim.md` | Policy/procedure | Reference | Decide whether a non-layout design claim is admissible. |
+| `quality/gates/harmony-evaluation.md` | Policy/procedure | Reference | Decide whether a webpage composition can guide implementation. |
+| `quality/gates/consumer-migration-evidence.md` | Policy/procedure | Reference | Decide whether declared consumer migration evidence is sufficient. |
+| `quality/gates/layout.md` | Policy/procedure | Reference | Decide whether a layout claim satisfies the pattern contract. |
+| `quality/gates/rationale.md` | Policy/procedure | Reference | Decide whether a rationale exposes options, warrant, and debt. |
+| `quality/gates/visual-evidence.md` | Policy/procedure | Reference | Decide whether rendered evidence supports a visual claim. |
+| `quality/evidence/index.md` | Reference | None | Look up evidence reference families. |
+| `quality/evidence/accessibility.md` | Reference | Explanation | Understand accessibility evidence boundaries. |
+| `quality/evidence/consumer-migration.md` | Reference | Explanation | Understand runtime, browser, session, adoption, freshness, and review boundaries for a migration. |
+| `quality/evidence/design-rationale.md` | Reference | Explanation | Understand design-rationale evidence boundaries. |
+| `quality/evidence/executable-evidence.md` | Reference | Policy/procedure | Map validators, tests, rendered QA, review, and source citations to claim boundaries. |
+| `quality/evidence/families.md` | Reference | Explanation | Look up normalized evidence-family names and boundaries. |
+| `quality/evidence/hci-evaluation.md` | Reference | Explanation | Understand HCI evidence boundaries. |
+| `quality/evidence/pattern-contract-audit.md` | Reference | Explanation | Map generated pattern contracts to validator and human-review responsibilities. |
+| `quality/evidence/search-metadata-polyhierarchy.md` | Reference | Explanation | Document retrieval metadata, facet drift, and search-adoption evidence. |
+| `quality/evidence/sources.md` | Reference | Policy/procedure | Look up source admissibility boundaries. |
+| `quality/evidence/tokens.md` | Reference | Explanation | Understand token evidence boundaries. |
+| `quality/evidence/visual-qa.md` | Reference | Explanation | Understand visual QA evidence boundaries. |
+
+The wildcard rows are intentional. Generated pattern pages share one stable reference contract, and generated category indexes share one stable reference posture.
+
+## Hybrid Decisions
+
+| Page or family | Decision | Reason |
+| --- | --- | --- |
+| `README.md` | Keep and label | The page primarily explains repository purpose, but it must also route readers to the correct next document. |
+| `GUIDE.md` | Keep and label | The page is a how-to entry point, but it needs explanation to separate before-problem and after-problem use. |
+| `DOMAINS.md` | Keep and label | The manifest is a domain reference whose scope, lifecycle, and provenance rules also govern edits. |
+| `GOVERNANCE.md` | Keep and label | The page is a governance reference whose rules also operate as edit procedure. |
+| `AGENTS.md` | Keep as policy/procedure | The page governs agent edits and doubles as a reference for recurring repository rules. |
+| `guides/decision-tree.md` | Keep and label | The page is navigational how-to; reference links are necessary outputs, not a competing mode. |
+| `guides/layout-brief.md` | Keep and label | The page is a fill-in how-to whose prompts also act as a stable brief reference. |
+| `guides/vocabulary.md` | Keep and label | The page is a term reference with policy rules for canonical and deprecated language. |
+| `guides/webpage-generation-workflow.md` | Keep and label | The page is a how-to workflow with policy checkpoints around harmony, image reference, and handoff order. |
+| `guides/documentation-mode-taxonomy.md` | Keep and label | The page is a reference matrix with policy rules for avoiding unlabeled mixed modes. |
+| `recipes/index.md` | Keep and label | The page is a recipe lookup index, with enough how-to routing to choose the next recipe. |
+| `recipes/primitive-to-recipe-matrix.md` | Keep and label | The page is a reference matrix that supports how-to substitution decisions. |
+| `recipes/*.md` | Intentional hybrid | Recipes teach composition steps while preserving reusable reference contracts for pattern stacks, constraints, and scroll ownership. |
+| `quality/index.md` | Keep and label | The page explains why the quality layer exists and routes readers into policy/procedure gates. |
+| `quality/principles.md` | Keep and label | The page explains shared principles that later become gate policy. |
+| `quality/claims.md` | Keep and label | The page is a claim-record reference with procedure for when a record is required. |
+| `quality/claim-records/samples.md` | Keep and label | The page is a reference example set that explains why each claim shape is acceptable. |
+| `quality/gates/index.md` | Keep and label | The page is a gate lookup index, with policy/procedure routing to the correct contract. |
+| `quality/gates/*.md` | Keep as policy/procedure | Gate pages must remain checkable procedures with required contracts, evidence families, blocking conditions, and boundaries. |
+| `quality/evidence/*.md` | Keep as reference | Evidence pages define what a source or artifact can support; they do not decide pass/fail by themselves. |
+
+## Task Routing
+
+| User task | Read first | Then read |
+| --- | --- | --- |
+| Understand what the repository is for. | `README.md` | `DOMAINS.md` |
+| Choose the owning StyleGallery domain. | `DOMAINS.md` | The selected domain `index.md` |
+| Name or review product motion. | `motion/index.md` | The matching Motion reference or workflow |
+| Review a product-level craft decision. | `design-engineering/index.md` | `design-engineering/interface-craft.md`, then the relevant quality gate |
+| Prove an existing consumer migration. | `design-engineering/consumer-migration-readiness.md` | `quality/gates/consumer-migration-evidence.md`, then the consumer-owned conformance record |
+| Compare an Apple interaction convention. | `platform-guides/index.md` | `platform-guides/apple-interaction.md` and current official sources |
+| Choose a layout when the pattern name is unknown. | `GUIDE.md` | `guides/decision-tree.md` |
+| Turn raw content into a homepage or webpage. | `guides/webpage-generation-workflow.md` | `recipes/homepage.md`, `quality/gates/harmony-evaluation.md` |
+| Look up a known layout primitive. | `CATALOG.md` | The relevant `patterns/*/*.md` page |
+| Compose a screen from reusable patterns. | `recipes/index.md` | The matching recipe page and linked pattern contracts |
+| Review whether a quality claim is admissible. | `quality/index.md` | The relevant `quality/gates/*.md` and `quality/evidence/*.md` pages |
+| Edit repository docs or patterns as an agent. | `AGENTS.md` | This taxonomy and the changed page family |
+
+## First-Run Tutorial Outline
+
+The webpage-generation path needs a tutorial only when a reader has raw content and has not yet produced a layout handoff before. Keep the full workflow in `guides/webpage-generation-workflow.md`; add a separate tutorial only if repeated users need a smaller first success path.
+
+Suggested tutorial outline:
+
+1. Start with one short homepage brief and supplied content blocks.
+2. Name the use case and primary task.
+3. Map content blocks to section jobs.
+4. Choose `recipes/homepage.md` or reject it with one reason.
+5. Run the harmony gate checklist.
+6. Produce the implementation handoff.
+
+Completion marker:
+
+```txt
+First-run complete when the reader has a use case, section-job map, selected recipe, harmony-gate decision, and implementation handoff.
+```
+
+Do not treat generated imagery, screenshots, or decorative choices as the tutorial completion marker. The first success is a handoff that can be implemented without weakening semantic order, scroll ownership, or quality-gate boundaries.

package/guides/layout-brief.md

@@ -0,0 +1,220 @@
+---
+type: Planning Guide
+title: Layout Brief Template
+description: Questions to answer before selecting a layout pattern stack.
+---
+
+# Layout Brief Template
+
+Use this template before choosing patterns. The answer should describe spatial responsibility, not visual style.
+
+## Screen
+
+- What is the screen type?
+- What is the primary user task?
+- What is the primary content?
+- What is the supporting content?
+
+## Source Order
+
+- Does DOM order match reading order?
+- Does visual order match focus order?
+- Which landmarks, headings, lists, links, buttons, or form controls are required before layout classes?
+
+## Scroll Ownership
+
+- What owns scrolling?
+- Is there one scroll container or more than one?
+- Which regions stay fixed, sticky, or static?
+- Where is height determined?
+
+## Constraints
+
+- What are the minimum and maximum inline sizes?
+- Which gaps are stable across the screen?
+- Which regions may shrink, wrap, or overflow?
+- Which values are product tokens, and which are browser mechanics?
+
+## Responsiveness
+
+- Is this a viewport-level problem or a component-local problem?
+- Can the layout adapt through intrinsic sizing before adding breakpoints?
+- Should container queries be used instead of viewport breakpoints?
+- What changes at narrow, medium, and roomy container sizes?
+
+## Content Stress
+
+- What happens when content is empty?
+- What happens with long labels?
+- What happens with long paragraphs?
+- What happens with an unbroken string?
+- Does the layout survive `ltr` and `rtl` direction?
+
+## Webpage Generation Intake
+
+Use these fields when raw content must become a homepage or ordinary webpage before a pattern stack is obvious.
+
+Content-to-layout match:
+
+- What type of webpage is being made: homepage, campaign page, product page, article, documentation, portfolio, or support page?
+- Which content blocks are mandatory, optional, repeated, or disposable?
+- Which section job does each block serve: hook, explain, prove, compare, convert, navigate, or retain?
+- Which layout recipe is the closest spatial model, and which recipes were rejected?
+
+Harmony evaluation:
+
+- Does the section order match the visitor's decision path?
+- Does the visual weight match content priority before decoration is considered?
+- Do repeated regions share a rhythm without hiding unique content jobs?
+- Do accessibility, source order, and task completion override visual novelty where they conflict?
+
+GPT Image reference:
+
+- Required preconditions before prompt: use case, content blocks, section jobs, selected recipe, approved pattern stack, constraints, and harmony notes.
+- What image prompt will be generated from the approved content hierarchy and pattern stack?
+- Which details must the image clarify: hero composition, section rhythm, hierarchy, spacing, media treatment, or CTA priority?
+- Image review extract-vs-ignore: implementable hierarchy, spacing, media treatment, and CTA priority go into the handoff; decorative styling and proof-like claims stay out of reusable pattern CSS.
+- Which generated-image details are decorative and must not be copied into reusable pattern CSS?
+- Accepted image debt: record unclear areas that need another image, a written decision, or product-owner follow-up.
+- Which unclear generated-image details need a written decision, another reference, or explicit exclusion before implementation?
+
+Implementation handoff:
+
+- Which semantic HTML skeleton, layout patterns, constraints, and scroll owners are approved?
+- Which image-reference observations become product-level visual styling outside the pattern library?
+- Which viewport, content-stress, accessibility, and visual-evidence checks must pass before shipping?
+- Consumer reference: `not_applicable`.
+- Consumer reference reason: This blank planning template declares no consumer-specific reference record.
+- Consumer migration conformance: omit for ordinary work; for an elected migration method, use `declared` plus one normalized consumer-local JSON record path.
+
+## Minimum Required Fields By Use Case
+
+Use the smallest field set that can keep source order, scroll ownership, and constraints from being overridden by visual taste or generated imagery.
+
+Homepage:
+
+- Content blocks, section jobs, closest recipe, pattern stack, scroll owner, constraints, harmony evaluation, GPT Image reference, implementation handoff.
+
+Dashboard:
+
+- Repeated panel inventory, scan or comparison task, closest recipe, pattern stack, scroll owner, constraints, harmony evaluation, GPT Image reference, implementation handoff.
+
+Article:
+
+- Reading path, supplemental content, closest recipe, pattern stack, scroll owner, constraints, harmony evaluation, GPT Image reference, implementation handoff.
+
+Form:
+
+- Input groups, validation and action placement, closest recipe, pattern stack, scroll owner, constraints, harmony evaluation, GPT Image reference, implementation handoff.
+
+Command surface:
+
+- Command regions, controlled content regions, closest recipe, pattern stack, scroll owner, constraints, harmony evaluation, GPT Image reference, implementation handoff.
+
+## Rejected Alternatives
+
+Record alternatives at the point they are rejected so the implementation handoff does not reopen them accidentally.
+
+```txt
+Rejected pattern or recipe:
+Reason rejected:
+Which requirement it weakened:
+Replacement:
+Accepted tradeoff:
+```
+
+## Candidate Pattern Stack
+
+Record the initial pattern stack and why each pattern is responsible for a specific spatial problem.
+
+```txt
+Screen type:
+Primary task:
+Primary content:
+Supporting content:
+Scroll owner:
+Pattern boundary:
+Pattern stack:
+Layout owner:
+Core layout declarations:
+Demo or product styling excluded:
+Constraints:
+Change points:
+Likely breaking content case:
+Patterns rejected:
+Webpage use case:
+Section jobs:
+Harmony notes:
+GPT Image reference prompt:
+Implementation handoff:
+Consumer reference: not_applicable
+Consumer reference reason: This blank layout brief declares no consumer-specific reference record.
+```
+
+Short examples:
+
+- New pattern: `Pattern boundary: repeated layout failure`, `Layout owner: tab_strip owns inline overflow`, `Demo or product styling excluded: active tab color`.
+- Recipe composition: `Pattern boundary: recipe composition`, `Pattern stack: fixed-sidenav-shell, content-limiter, stack`, `Patterns rejected: new settings-page pattern`.
+- Product styling: `Pattern boundary: product styling`, `Core layout declarations: card-grid placement only`, `Demo or product styling excluded: shadows, radius, color accents`.
+
+Minimal code example:
+
+```html
+<section class="settings_shell" aria-label="Settings">
+    <nav class="settings_shell_nav" aria-label="Settings sections"></nav>
+    <main class="settings_shell_scroll_area"></main>
+</section>
+```
+
+```css
+.settings_shell {
+    block-size: 100dvb;
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+}
+
+.settings_shell_scroll_area {
+    min-block-size: 0;
+    overflow: auto;
+}
+```
+
+In this example, `settings_shell` owns viewport sizing and columns, `settings_shell_scroll_area` owns scrolling, and visual treatment such as active nav color, borders, shadows, and typography stays outside the reusable layout CSS.
+
+Failure example:
+
+```css
+/* Avoid: overflow is named, but the grid child may refuse to shrink. */
+.settings_shell_scroll_area {
+    overflow: auto;
+}
+```
+
+```css
+/* Prefer: the scroll owner can shrink inside the shell track. */
+.settings_shell_scroll_area {
+    min-block-size: 0;
+    overflow: auto;
+}
+```
+
+Styling boundary example:
+
+```css
+/* Avoid in reusable pattern CSS: layout and product styling are mixed. */
+.settings_shell_scroll_area {
+    background: var(--panel-background);
+    border-radius: var(--radius-lg);
+    box-shadow: var(--shadow-lg);
+    min-block-size: 0;
+    overflow: auto;
+}
+```
+
+```css
+/* Prefer in reusable pattern CSS: only the scroll responsibility remains. */
+.settings_shell_scroll_area {
+    min-block-size: 0;
+    overflow: auto;
+}
+```

package/guides/vocabulary.md

@@ -0,0 +1,148 @@
+---
+type: Planning Guide
+title: Controlled Vocabulary
+description: Canonical terminology, aliases, deprecated terms, and scannability rules for StyleGallery.
+---
+
+# Controlled Vocabulary
+
+Use this page when a term affects routing, metadata, search, claim records, workflow handoff, or review decisions. Prefer the canonical term in headings, frontmatter, validator output, and route labels. Use aliases only when explaining reader-facing alternatives.
+
+Primary role: vocabulary and scannability contract.
+
+## Canonical Terms
+
+- Canonical: `domain`
+  - Concept: top-level knowledge ownership
+  - Definition: A governed StyleGallery decision surface with a named scope, exclusions, lifecycle, source-of-truth, validator, and review owner.
+  - Use for: Layout, Motion, Design Engineering, Game UI, Platform Guides, root routing, and `domain` frontmatter on governed leaves.
+- Canonical: `category`
+  - Concept: domain-local browse placement
+  - Definition: A canonical grouping inside one domain; it cannot change the owning domain or its evidence boundary.
+  - Use for: Layout pattern families and future domain-local indexes after a governed need is established.
+- Canonical: `pattern`
+  - Concept: reusable spatial primitive
+  - Definition: A minimal HTML/CSS layout contract that solves one primary spatial problem.
+  - Use for: Individual files under `patterns/`, generated catalog entries, pattern stacks, and primitive references.
+- Canonical: `recipe`
+  - Concept: screen composition
+  - Definition: A screen-level composition that maps a common use case to a pattern stack.
+  - Use for: Files under `recipes/`, planning flow, and primitive-to-recipe dependency records.
+- Canonical: `gate`
+  - Concept: quality decision contract
+  - Definition: A named quality contract that decides whether a claim is admissible and which evidence can support it.
+  - Use for: Files under `quality/gates/` and review decisions.
+- Canonical: `claim`
+  - Concept: review assertion
+  - Definition: A statement about layout, design, accessibility, evidence, rationale, or harmony that needs a warrant and boundary.
+  - Use for: Quality records, design rationale, and implementation handoff.
+- Canonical: `evidence family`
+  - Concept: evidence class
+  - Definition: A class of support for a claim, such as mechanical, rendered, accessibility, interpretive, empirical, source, or debt evidence.
+  - Use for: Gate records and evidence index entries.
+- Canonical: `scroll ownership`
+  - Concept: scroll responsibility
+  - Definition: The named element or region that owns scrolling, fixed behavior, sticky behavior, and height determination.
+  - Use for: Pattern frontmatter, layout briefs, recipes, and handoffs.
+- Canonical: `harmony`
+  - Concept: content layout fit
+  - Definition: The fit between content hierarchy, spatial rhythm, visual weight, constraints, accessibility precedence, and pattern boundaries.
+  - Use for: Webpage generation workflow and the harmony evaluation gate.
+- Canonical: `debt`
+  - Concept: accepted unresolved risk
+  - Definition: A known limitation that is accepted with a boundary, owner, and verification or follow-up path.
+  - Use for: Evidence records, implementation handoff, and quality-gate decisions.
+- Canonical: `consumer reference`
+  - Concept: optional consumer record handoff
+  - Definition: A required handoff field that either declares one repository-local JSON record or gives a sentence reason for non-applicability.
+  - Use for: Consumer-owned visual or component guidance without moving values into Layout.
+- Canonical: `maturity`
+  - Concept: consumer reference lifecycle
+  - Definition: The lifecycle state of a consumer reference item: experimental, stable, or deprecated.
+  - Use for: Lifecycle and support decisions; never as a synonym for artifact mode.
+- Canonical: `artifact mode`
+  - Concept: consumer reference storage role
+  - Definition: How a consumer reference artifact is held, independently of its maturity.
+  - Use for: Schema-only, consumer-local, governed-local, or external-consumer records.
+- Canonical: `warrant`
+  - Concept: claim reasoning
+  - Definition: The reason an evidence family can support a claim in a specific context.
+  - Use for: Quality gates and design rationale.
+- Canonical: `boundary`
+  - Concept: claim limitation
+  - Definition: The explicit limit of what a page, pattern, gate, source, image, test, or screenshot proves.
+  - Use for: Gate records, evidence pages, and implementation handoff.
+
+## Aliases
+
+- Alias: `area` -> `domain`
+  - Use only in reader-facing explanation; policy and metadata use `domain`.
+- Alias: `section` -> `category`
+  - Use only for document structure or explanatory prose, not canonical placement metadata.
+- Alias: `primitive` -> `pattern`
+  - Use `primitive` only when contrasting individual patterns with recipes.
+- Alias: `layout primitive` -> `pattern`
+  - Use in explanatory prose only; canonical records should use `pattern`.
+- Alias: `screen recipe` -> `recipe`
+  - Use when a reader might confuse recipes with CSS snippets.
+- Alias: `quality gate` -> `gate`
+  - Use in navigation labels; canonical records may use `gate`.
+- Alias: `visual reference` -> `GPT Image reference`
+  - Use `GPT Image reference` when the generated-image workflow is specifically involved.
+
+## Deprecated Terms
+
+- Deprecated: `component` -> `pattern`
+  - Reason: In Layout, component implies visual or framework ownership; Layout owns spatial pattern contracts.
+- Deprecated: `template` -> `recipe`
+  - Reason: Template implies copy-paste completeness; recipes are starting compositions.
+- Deprecated: `proof` -> `evidence`
+  - Reason: Proof overstates what screenshots, tests, generated images, or sources can establish unless the gate names the boundary.
+- Deprecated: `style guide` -> `controlled vocabulary`
+  - Reason: The vocabulary stabilizes decision language; it does not define brand voice.
+- Deprecated: `library` -> `domain`
+  - Reason: Library does not name ownership, exclusions, lifecycle, or review responsibility.
+
+## Local-Only Terms
+
+- Local-only: `OKF`
+  - Meaning: The repository's knowledge-bundle structure.
+  - Boundary: Use only for bundle maps, indexes, and repository organization.
+- Local-only: `pattern stack`
+  - Meaning: The ordered set of patterns selected for a screen or section.
+  - Boundary: Do not use it as a synonym for final product styling.
+- Local-only: `section job`
+  - Meaning: A content block's role in a webpage decision path, such as hook, explain, prove, compare, convert, navigate, or retain.
+  - Boundary: Use in webpage generation, not in every pattern file.
+- Local-only: `consumer component`
+  - Meaning: A component owned by an opted-in consuming product or Design Engineering reference.
+  - Boundary: Never use it to rename a Layout pattern or move component authority into shared infrastructure.
+
+## Scannability Checklist
+
+- Use headings for decision boundaries, not decorative grouping.
+- Keep lists short enough to scan; split a long list by task or concept when it carries more than one decision.
+- Put the canonical term first, then aliases or boundaries.
+- Prefer descriptive link text that names the destination decision, not generic text such as "here" or "more."
+- Keep each paragraph to one idea when it explains policy or routing.
+- Use tables only when comparison across columns is the reader's task; use lists for simple sequences.
+- Put boundaries near the claim they limit so a reader does not have to infer them from another page.
+
+## Vale Proposal
+
+Prose linting should wait until the vocabulary is stable.
+
+When the terms above stop changing, add Vale as a proposal first:
+
+- Add accepted terms to a Vale vocabulary `accept.txt`.
+- Add deprecated terms to `reject.txt` only after each replacement is documented here.
+- Start with report-only checks for `Vale.Terms` and `Vale.Avoid`.
+- Promote lint failures only after README, GUIDE, recipes, gates, and pattern frontmatter are aligned.
+
+## Source Notes
+
+- [Google paragraph structure guidance](https://developers.google.com/style/paragraph-structure) supports short, single-idea paragraphs for scannability.
+- [Google cross-reference guidance](https://developers.google.com/style/cross-references) supports descriptive link text.
+- [Microsoft scannable content guidance](https://learn.microsoft.com/en-us/style-guide/scannable-content/) supports headings, lists, sidebars, and tables as scan aids.
+- [Microsoft headings guidance](https://learn.microsoft.com/en-us/style-guide/scannable-content/headings) treats headings as structure and scan entry points.
+- [Vale vocabulary guidance](https://vale.sh/docs/keys/vocab) distinguishes accepted and rejected vocabulary terms.