stylegallery 0.1.3 → 0.1.6

package/design-terminology/conflict-cases.md

@@ -0,0 +1,109 @@
+---
+type: Domain Guide
+title: Cross-System Term Cases
+description: Directly sourced terms and scoped relations for tool values, runtime representations, components, patterns, and historical formats.
+domain: design-terminology
+lifecycle: experimental
+---
+
+# Cross-System Term Cases
+
+Primary role: applied cross-system term relation record.
+
+## Repository Boundary
+
+This page applies the typed relation model to recorded term records and conflict scenarios. It does not rename StyleGallery's own terms, and its relations are working judgments with boundaries, not claims that one source's definition is correct. V0.1 records these as Markdown; the structured registry is a promotion prerequisite.
+
+## Reusable Method
+
+1. Name the sources in tension and the shared term.
+2. Record each side as a term record with source, kind, concept, status, and scope.
+3. Assign one relation type per pair per explicit scope and declare its direction.
+4. Write the non-equivalence boundary: where substitution breaks.
+5. Stamp `reviewed_on`; re-verify when any involved source revises its term.
+
+## Term Records
+
+| Term | Label | Source (kind) | Concept | Status | Scope | Reviewed on |
+| --- | --- | --- | --- | --- | --- | --- |
+| `figma.variable` | Variable | [Figma](https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes) (`design-tool`) | named-design-value | current | variable collection; dated help page | 2026-09-08 |
+| `figma.mode` | Mode | [Figma](https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes) (`design-tool`) | value-context | current | values selected within a collection | 2026-09-08 |
+| `figma.collection` | Collection | [Figma](https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes) (`design-tool`) | variable-organization | current | collection containing variables and modes | 2026-09-08 |
+| `figma.component` | Component | [Figma](https://help.figma.com/hc/en-us/articles/360038662654-Guide-to-components-in-Figma) (`design-tool`) | tool-instance-model | current | reusable design object and its instances | 2026-09-08 |
+| `dtcg.token` | Token | [DTCG](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/#design-token) (`specification`) | interchange-record | current | Format Module 2025.10 | 2026-09-08 |
+| `dtcg.group` | Group | [DTCG](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/#groups) (`specification`) | token-organization | current | Format Module 2025.10 | 2026-09-08 |
+| `dtcg.token.draft2` | Token | [DTCG](https://www.designtokens.org/tr/second-editors-draft/format/#design-token) (`specification`) | interchange-record | historical | Second Editors' Draft, 2022-06-14 | 2026-09-08 |
+| `css.custom-property` | Custom property | [CSSWG](https://www.w3.org/TR/css-variables-1/#defining-variables) (`web-platform`) | runtime-value-slot | current | CSS Custom Properties Level 1 | 2026-09-08 |
+| `carbon.component` | Component | [Carbon](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) (`design-system`) | published-ui-building-block | current | Carbon design and implementation resources | 2026-09-08 |
+| `carbon.pattern` | Pattern | [Carbon](https://carbondesignsystem.com/patterns/overview/) (`design-system`) | workflow-guidance | current | Carbon patterns catalog | 2026-09-08 |
+| `stylegallery.pattern` | Pattern | [StyleGallery](../layout/index.md) (`pattern-library`) | spatial-primitive | current | repository Layout corpus | 2026-09-08 |
+
+The external locators and local Layout contract were rechecked on the dates shown. Current status is bounded by the named source/version, not a promise about every later release. Concept labels are local classification summaries.
+
+## Recorded Relations
+
+| From | To | Type | Scope | Direction | Boundary | Reviewed on |
+| --- | --- | --- | --- | --- | --- | --- |
+| `figma.variable` | `dtcg.token` | `partial_overlap` | value-interchange | symmetric | Exportable design values overlap; Figma prototype values need not be tokens, while the format has composite structures not supplied by one scalar variable | 2026-09-08 |
+| `css.custom-property` | `dtcg.token` | `implementation_representation` | token-to-css-output | directional | A custom property can consume a translated token value; it also holds non-design values and does not preserve the entire token record | 2026-09-08 |
+| `figma.collection` | `dtcg.group` | `partial_overlap` | value-organization | symmetric | Both organize named values; a Figma collection includes modes, while a format group can nest groups and carry format-specific metadata | 2026-09-08 |
+| `figma.mode` | `dtcg.group` | `not_comparable` | context-versus-containment | symmetric | A mode selects value context; a group organizes token records. Containment alone does not choose the active context | 2026-09-08 |
+| `figma.component` | `carbon.component` | `same_label_different_meaning` | handoff-artifact-identity | symmetric | A reusable tool object and a system-published UI unit share a label; a design instance is not by itself the system's implementation contract | 2026-09-08 |
+| `carbon.pattern` | `stylegallery.pattern` | `partial_overlap` | reusable-interface-guidance | symmetric | Both describe reusable interface arrangements; Carbon includes task sequences and flows, while StyleGallery Layout covers spatial constraints without those interaction contracts | 2026-09-08 |
+| `carbon.component` | `carbon.pattern` | `not_comparable` | catalog-unit-subtyping | symmetric | Composition is not set containment: a workflow can use components without being a broader class whose instances include component instances | 2026-09-08 |
+| `dtcg.token.draft2` | `dtcg.token` | `near_equivalent` | versioned-token-concept | symmetric | The named-value interchange concept overlaps; the 2022 draft and 2025.10 format have different conformance details, so historical files need version-specific validation | 2026-09-08 |
+
+## Scenario A: Component Versus Pattern
+
+Query phrasing: `component versus pattern terminology`, `difference between component and pattern across design systems`.
+
+Distinguish Figma's design object from Carbon's published component before comparing either with a pattern. `figma.component` and `carbon.component` use `same_label_different_meaning`. Within Carbon, components participate in patterns; composition does not establish the set-theoretic `broader_than` relation. Carbon and StyleGallery patterns have `partial_overlap` within reusable interface guidance, with different behavioral boundaries.
+
+## Scenario B: Variable, Design Token, And CSS Custom Property
+
+Query phrasing: `figma variable design token custom property`.
+
+These are different labels from three source kinds. Their relation is not the same-label case. `figma.variable` and `dtcg.token` have `partial_overlap`; `css.custom-property` → `dtcg.token` is `implementation_representation`, with the representation first. A tool-to-code binding requires a consumer-owned translation; it does not establish equivalence or guarantee a lossless round trip.
+
+## Scenario C: Historical And Current Token Formats
+
+Query phrasing: `historical design token format`, `DTCG second editors draft versus 2025.10`.
+
+The retained 2022 source describes a historical draft. The versioned 2025.10 source describes an intended-for-implementation format. Both remain records; a common label does not make their file contracts identical. The relation is `near_equivalent` for the concept, not `renamed_to`: the label did not change. Neither Community Group report is a W3C Recommendation.
+
+## Scenario D: Style Guide Versus Design System
+
+Query phrasing: `style guide versus design system`.
+
+Result: insufficient context until an organization and dated source are named on both sides. “Industry history” cannot stand in for a specific historical style guide. Do not create a universal rename or deprecation event; request the two sources and then use the [Comparison Workflow](comparison-workflow.md).
+
+## Opinionated Guidance
+
+- Resolve a conflict only after naming every source involved; silent resolution creates the next conflict.
+- Prefer surface-prefixed translations over merged definitions when handing off.
+- StyleGallery's own [Controlled Vocabulary](../guides/vocabulary.md) stays authoritative inside this repository.
+- Add a case only with at least two named, cited sources in genuine tension.
+
+## Platform-Specific Guidance
+
+When a case involves a platform guideline source, cite that platform's surface and route deeper convention comparison to [Platform Guides](../platform-guides/index.md); engine terms route to Game UI; motion terms to Motion.
+
+## Unsupported Absolutes
+
+- A working relation is not a standard.
+- One source's revision does not obligate others to follow.
+- A recorded case does not close the conflict outside its boundary.
+- Tool feature names do not settle system-layer definitions.
+
+## Verification Contract
+
+Run `node scripts/validate-design-terminology.mjs --json` and its fixtures after editing. Verify both direct source locators, the comparison scope, direction, and boundary. The validator checks record shape and graph invariants; semantic accuracy still requires source review. Re-review when a named source changes the cited meaning.
+
+## Source, License, And Attribution
+
+Locally authored summaries and judgments, with direct source links per term. Rechecked 2026-09-08: Figma variables/components, DTCG 2025.10 and second draft, CSS Custom Properties Level 1, Carbon system/pattern pages, and the local Layout hub. No source prose or code samples are copied. This is an author source review, not independent semantic approval.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Design Term Comparison Workflow](comparison-workflow.md).

package/design-terminology/index.md

@@ -0,0 +1,73 @@
+# Design Terminology
+
+Design Terminology owns the decision surface that binds design terms to their named sources, classifies them by source kind and concept family, and judges typed semantic relations and conflicts between them.
+
+## Scope Boundary
+
+In scope: source-kind classification for named vocabulary sources, concept-family classification for design terms, a typed relation model between terms from different sources, source-bounded vocabulary inventories with freshness fields, and cross-system conflict cases.
+
+Out of scope: StyleGallery's own canonical naming, actual UI behavior or implementation methods, accessibility rules, platform-specific interaction adaptation, universal prescriptions about which term is generally better, and authority over any external vocabulary.
+
+This domain decides: which source a term belongs to, what kind of source that is, which concept family the term serves, and what typed relation holds between two terms with its boundary. It does not decide what StyleGallery calls things internally, whether an implementation is correct, or which external definition wins.
+
+## Evidence And Research Boundary
+
+V0.1 is a Markdown-only browsing and verification stage. Term records and typed relations are authored and reviewed as Markdown tables in [Cross-System Term Cases](conflict-cases.md); a machine-readable term, concept, source, and relation registry is a prerequisite for promotion beyond `experimental`. Material v2 currently exposes these pages through document search only; it does not answer structured crosswalk queries.
+
+Representative questions this domain answers: are Figma's variable, the DTCG design token, and the CSS custom property the same thing; is a component a pattern; is a style guide the same as a design system; which of two clashing labels came from which source.
+
+## Promotion To Stable
+
+Domain lifecycle decisions follow the [repository-owner policy](../DOMAINS.md#lifecycle-and-staleness). The following source, ownership, and machine-contract checks inform a proposed transition beyond `experimental`:
+
+- A named review owner, secondary reviewer, freshness owner, and dispute resolver are recorded.
+- A machine-readable registry with schema exists for terms, concepts, sources, and relations; until then `scripts/validate-design-terminology.mjs` enforces record consistency on the Markdown tables.
+- A relation invariant validator derived from the forbidden error states in [Design Term Relations](relation-types.md) passes.
+- Every term carries a direct source locator.
+- Every relation names both sources and a non-trivial boundary.
+- Representative findability queries return a target document or record.
+- Unresolved semantic disputes: zero.
+- Stale sources beyond their re-review trigger: zero.
+
+Reader tasks, user studies, adoption counts, and attestations are neither required nor sufficient for a domain lifecycle change. Reader-task observations may support a separately scoped findability claim.
+
+## Content Review Contract
+
+Record consistency is enforced mechanically from v0.1 by `scripts/validate-design-terminology.mjs`, which parses the term and relation tables and rejects unknown types, duplicate or unrecorded terms, missing source locators, empty boundaries/scopes, conflicting directions, containment cycles, impossible calendar dates, invalid temporal relations, label mismatches, and orphan terms. Source meaning and authority remain review judgments. Human semantic review is a **stable-promotion gate only**, not a merge gate for `experimental` content; it covers every term and relation (not a sample) against this checklist:
+
+- Is the source kind correct for each cited source?
+- Does each term description match what its source actually supports?
+- Is each relation type appropriate for its pair?
+- Is each relation boundary sufficient?
+- Are both terms compared at the same abstraction level?
+- Is official-source authority overstated anywhere?
+- Is each historical/current status correct?
+
+The review result is recorded as: terms reviewed, relations reviewed, counts of accepted, revised, and unresolved items, reviewer name, and review date. Author self-audit alone does not satisfy promotion.
+
+This domain is a working method template: consumers may fork it and re-record their own sources, terms, and relations. Forked records are consumer-owned and never feed values back into StyleGallery.
+
+## Start Here
+
+| Task | Route |
+| --- | --- |
+| Resolve a source-specific question and produce a scoped handoff. | [Design Term Comparison Workflow](comparison-workflow.md) |
+
+These workflows and worked cases are usable experimental guidance. Expected-result tables are test designs; actual product, engine, and reader evidence must be recorded separately. Review on a failed task, a source change, or a changed ownership contract.
+
+## Available Guides
+
+- [Design Source Kinds](source-kinds.md) classifies what kind of thing a vocabulary source is before its terms are read.
+- [Design Source Vocabularies](source-vocabularies.md) inventories named sources with kind, version boundary, status, and review date.
+- [Design Concept Families](concept-families.md) classifies design terms by the decision each term serves.
+- [Design Term Relations](relation-types.md) defines the typed relation model and the term record shape.
+- [Cross-System Term Cases](conflict-cases.md) applies typed relations to recorded term records and conflict scenarios.
+
+## Domain Contract
+
+[Vocabulary](../guides/vocabulary.md) owns StyleGallery's canonical internal word set; Design Terminology compares the meanings and relations of terms used by external named sources. Platform Guides compares platform interaction conventions, not terminology; Motion owns motion terminology. Naming rationale: topology suggests a relation graph this domain does not yet provide; terminology is the accurate name for comparing definitions, usage scope, and conflicts. Scope decision: [Design Terminology Domain Scope Decision](../quality/claim-records/design-terminology-domain-scope.md).
+
+## IA Navigation
+
+Parent: [StyleGallery](../index.md).
+Next: [Design Term Comparison Workflow](comparison-workflow.md).

package/design-terminology/relation-types.md

@@ -0,0 +1,109 @@
+---
+type: Domain Guide
+title: Design Term Relations
+description: Typed semantic relation model between design terms from different named sources, and the term record shape.
+domain: design-terminology
+lifecycle: experimental
+---
+
+# Design Term Relations
+
+Primary role: typed term relation model.
+
+## Repository Boundary
+
+This guide defines the closed set of typed relations used to judge how two design terms relate, and the shape of a term record. It does not decide which external definition is correct, and its types never rename StyleGallery's own terms. Relations are judgments recorded with evidence, not standards.
+
+## Reusable Method
+
+1. Record both terms with their sources, kinds, and concepts.
+2. Choose exactly one relation type from the closed set below.
+3. Write the boundary statement: the specific scope in which the relation holds and where it breaks.
+4. Stamp `reviewed_on`; a relation without a date is unverified.
+5. Re-verify the relation whenever either source revises the term.
+
+## Relation Types
+
+| Relation type | Meaning | Invariants | Required boundary statement |
+| --- | --- | --- | --- |
+| `equivalent_within_scope` | The two terms denote the same concept inside one named scope | Symmetric; a named scope must exist and be recorded | The scope, and what changes outside it |
+| `near_equivalent` | Mostly overlapping meaning with known divergences | Symmetry must be declared per record; the axis creating the divergence must be named | The divergences and their axis |
+| `partial_overlap` | Some instances satisfy both terms; others satisfy only one | Symmetric; both the common region and each non-common region must be recorded | Which instances fall on each side |
+| `broader_than` | The first term's extension properly contains the second's | Directional; the reverse side must hold `narrower_than` when recorded from the other term; a counterexample direction must exist | The contained region and a counterexample direction |
+| `narrower_than` | Inverse of `broader_than` | Directional; must be the inverse of the paired `broader_than` record | Same as above, inverted |
+| `implementation_representation` | One term is a way the other is serialized, stored, or consumed | Directional and fixed: the from-term is the representation, the to-term is the semantic concept; the direction must not flip between records of the same pair | The representation direction and what is lost or added |
+| `renamed_to` | A source replaced one label with another | Intra-source temporal: both terms must belong to one named source, with a dated or versioned rename event | The rename event and both statuses |
+| `deprecated_in_favor_of` | A source withdrew one term in favor of another | Requires a deprecation basis and a replacement source of record | The withdrawal scope and migration note |
+| `same_label_different_meaning` | Identical labels, distinct concepts | Requires evidence that label is identical while concept or scope differs | Both meanings and the confusion risk |
+| `not_comparable` | No meaningful relation holds at the cited scopes | Symmetric; the comparison axis that fails must be named | Why comparison fails |
+
+### Forbidden Error States
+
+A relation record is invalid when any of the following holds:
+
+- The same term pair records `broader_than` and `narrower_than` simultaneously in one direction (these are inverse views, not two facts).
+- The same pair and scope records `equivalent_within_scope` and `not_comparable` (or any other contradiction) at once.
+- `renamed_to` lacks a time or version basis for the rename event.
+- Either term lacks an official, named source.
+- The boundary field is empty or restates the type without adding scope.
+
+The Markdown validator enforces unique source-qualified term IDs, direct source locators, actual calendar dates, explicit scope and direction, identical labels for `same_label_different_meaning`, temporal status/event requirements, inverse consistency, and acyclic containment within each scope. It ignores fenced examples and HTML comments. Locators must be HTTPS or existing repository documents; the validator does not authenticate source ownership or evaluate semantic truth.
+
+The term table has seven columns: identifier, label, source/kind with direct locator, concept, status, scope, and reviewed date. The relation table has seven: from, to, type, scope, direction, boundary, and reviewed date. Scope is a non-empty kebab-case comparison identifier. One directed pair has one relation per scope; a separately recorded inverse must agree. Symmetric types use `symmetric`; representation, containment, and temporal relations use `directional`; `near_equivalent` declares either explicitly. Self-relations are invalid. Boundaries must contain a substantive sentence; a length check can reject blanks but cannot establish semantic adequacy.
+
+## Term Record Shape
+
+```yaml
+term_id: figma.variable
+label: Variable
+source: figma            # named source from source-vocabularies
+source_url: https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes
+source_kind: design-tool # from source-kinds
+concept: named-design-value
+status: current          # current | deprecated | historical | unknown
+scope: file-or-collection-bound
+reviewed_on: 2026-09-08
+relations:
+  - target: dtcg.token
+    type: partial_overlap
+    scope: value-interchange
+    direction: symmetric
+    reviewed_on: 2026-09-08
+    boundary: >
+      Exportable design values overlap; prototype values need not be
+      tokens, and one scalar variable does not provide every composite
+      structure in the 2025.10 format.
+```
+
+In v0.1 this shape is authored as the Markdown tables in [Cross-System Term Cases](conflict-cases.md). A machine-readable registry holding terms, concepts, sources, and relations is a prerequisite for promoting this domain beyond `experimental`; until then Material v2 answers document search only, not structured crosswalk queries.
+
+## Opinionated Guidance
+
+- One relation type per pair, per scope; two relations for the same pair require two named scopes.
+- `partial_overlap` with a stated boundary beats an unqualified equivalence.
+- A relation between different source kinds must say what the kind difference contributes.
+- Reject a recorded relation whose boundary restates the type without adding scope.
+
+## Platform-Specific Guidance
+
+Relations involving a platform guideline source cite that platform's surface; deeper convention comparison routes to [Platform Guides](../platform-guides/index.md).
+
+## Unsupported Absolutes
+
+- A relation is not a standard and binds no source.
+- Popularity does not decide `broader_than`.
+- Tool-layer feature names do not settle system-layer relations.
+- Absence of a relation between two terms is not evidence of equivalence.
+
+## Verification Contract
+
+Every recorded relation names two term records, one type from the closed set, a non-trivial boundary, and a review date; verify both sources still use the terms as recorded before promotion.
+
+## Source, License, And Attribution
+
+This page is a locally authored model. The illustrative `figma.variable` and `dtcg.token` relation uses `partial_overlap`; its named sources were rechecked on 2026-09-08 as recorded in [Term Cases](conflict-cases.md). No upstream prose is reproduced.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Cross-System Term Cases](conflict-cases.md).

package/design-terminology/source-kinds.md

@@ -0,0 +1,77 @@
+---
+type: Domain Guide
+title: Design Source Kinds
+description: Classification of vocabulary sources into design system, platform guideline, specification, design tool, pattern library, and brand style guide kinds.
+domain: design-terminology
+lifecycle: experimental
+---
+
+# Design Source Kinds
+
+Primary role: vocabulary source-kind classification guide.
+
+## Repository Boundary
+
+This guide classifies what kind of thing a vocabulary source is before any of its terms are read or compared. Source kind is a property of the source, not of a term; a term inherits its source's kind for reading rules only. The kinds are review tools for comparing sources, not a ranking of authority.
+
+## Reusable Method
+
+1. Identify the named source and its official link.
+2. Assign one primary source kind.
+3. Record what the kind implies for reading its terms: audience, stability, and versioning behavior.
+4. Record the version boundary: specification version, product version, OS release cycle, or a dated review set for living sites.
+5. Re-classify when a source restructures, such as a design tool publishing a system layer.
+6. Never compare terms across kinds as though the kinds were identical.
+
+## Source Kinds
+
+| Source kind | What it is | How to read its terms | Examples |
+| --- | --- | --- | --- |
+| `design-system` | A maintained, layered collection of foundations, components, and guidance, usually with code | Terms name layers of one system's current release; expect drift across releases | Material 3, Fluent 2, Carbon, Polaris |
+| `platform-guideline` | A platform owner's rules for software on that platform | Terms are scoped to the platform's release cycle and certification context | Apple Human Interface Guidelines |
+| `specification` | A versioned interchange or conformance document | Terms are defined exactly for the version; meaning changes require a new version | W3C Design Tokens Format |
+| `design-tool` | A product whose data model exposes tool constructs | Terms name tool features, not industry definitions; product versions rename freely | Figma variables, modes, components |
+| `web-platform` | A browser or platform runtime mechanism | Terms name runtime behavior standardized across vendors, not one system's vocabulary | CSS custom properties |
+| `pattern-library` | A curated collection of reusable solutions, with or without a full system | Terms name the collection's own units; scope is the collection, not an organization | StyleGallery Layout patterns |
+| `brand-style-guide` | An organization's visual and voice governance document | Terms govern expression, not interface structure; often narrower than a design system | Historical print-lineage style guides |
+
+## Classification Cases
+
+| Case | Rule | Example |
+| --- | --- | --- |
+| Platform guideline mistaken for a design system | A platform guideline binds a platform release; a design system versions itself | HIG is a platform guideline even though it looks system-like |
+| Specification mistaken for a system | A specification defines an interchange shape; it ships no components or guidance | DTCG Format defines the token data model, not a token set |
+| Tool feature mistaken for an industry term | A tool construct is evidence of the tool's model, not a universal definition | Figma `variables` is a feature name |
+| Pattern library inside a system | A library can be part of a system; classify by what is being cited | Citing Carbon patterns cites the system's library layer |
+| Brand guide that grew into a system | Classify by what the cited source governs today, and record the history | An org guide that now ships tokens and code |
+
+## Opinionated Guidance
+
+- Record source kind before recording any term from that source.
+- Treat kind and authority as separate: an official source of any kind is authoritative only for itself.
+- Prefer the narrowest kind that fits the cited surface.
+- Date every kind assignment; sources restructure.
+
+## Platform-Specific Guidance
+
+Platform guideline sources are recorded here only for terminology. Bounded comparison of their interaction conventions belongs to [Platform Guides](../platform-guides/index.md); engine vocabulary belongs to Game UI.
+
+## Unsupported Absolutes
+
+- Source kind does not imply quality or maturity.
+- One system's layer structure is not a template for other kinds.
+- A tool's market share does not convert its feature names into industry terms.
+- A specification's precision does not extend to systems that consume it.
+
+## Verification Contract
+
+For every recorded source, verify the official link resolves, the source kind still fits the cited surface, the version boundary is stated, and the review date is current enough for the claim being made.
+
+## Source, License, And Attribution
+
+This page is a locally authored, project-neutral classification. Named sources are cited only as examples of their kind; no upstream definitional prose is reproduced.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Design Source Vocabularies](source-vocabularies.md).

package/design-terminology/source-vocabularies.md

@@ -0,0 +1,93 @@
+---
+type: Domain Guide
+title: Design Source Vocabularies
+description: Freshness-bounded inventory of named vocabulary sources with source kind, vocabulary surface, version boundary, and review status.
+domain: design-terminology
+lifecycle: experimental
+---
+
+# Design Source Vocabularies
+
+Primary role: named vocabulary source inventory.
+
+## Repository Boundary
+
+This page inventories the named sources whose terms this domain records, with the fields needed to re-verify each reading later. It records which surfaces each source publishes, not what any surface should contain. It does not adjudicate a universal definition of `design system` or rank sources.
+
+## Reusable Method
+
+1. Name the source and its owner.
+2. Assign the source kind using [Design Source Kinds](source-kinds.md).
+3. Record the published vocabulary surfaces as verbatim layer names.
+4. Record the version boundary and status, and stamp `reviewed_on` and `retrieved_on`.
+5. Re-verify before any promotion beyond `experimental`, and record what changed.
+
+## Recorded Sources
+
+| Source | Owner | Source kind | Vocabulary surface | Version boundary | Status | Reviewed on |
+| --- | --- | --- | --- | --- | --- | --- |
+| [Material 3](https://m3.material.io/foundations) | Google | `design-system` | `foundations`, `components`, `styles`, `design tokens` | Living site; reviewed page set below | current | 2026-08-18 |
+| [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/) | Apple | `platform-guideline` | `components`, `materials`, `layout`, patterns | OS release cycle; reviewed page set | current | 2026-08-18 |
+| [Fluent 2](https://fluent2.microsoft.design/) | Microsoft | `design-system` | `foundations`, `components`, `patterns`, tokens | Living site; reviewed page set | current | 2026-08-18 |
+| [Carbon](https://carbondesignsystem.com/) | IBM | `design-system` | `foundations` including tokens, `components`, `patterns` | Living site; reviewed page set | current | 2026-08-18 |
+| [Polaris](https://polaris.shopify.com/) | Shopify | `design-system` | `foundations` including design tokens, `components`, `patterns`, `icons` | Living site; package versions for code | current | 2026-08-18 |
+| [Design Tokens Format](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) | Design Tokens Community Group | `specification` | `token`, `group`, `alias` data model | Format Module 2025.10; Community Group report, not a W3C Recommendation | current | 2026-09-08 |
+| [Figma](https://help.figma.com/hc/en-us) | Figma | `design-tool` | `variables`, `modes`, `components` as tool constructs | Product and help-center version | current | 2026-08-18 |
+
+All entries cite official first-party URLs (`authority: official`); `retrieved_on` equals the corresponding `reviewed_on`. Entries retaining 2026-08-18 are prior bounded readings, not rechecked claims for the current session.
+
+## Direct Sources For Current Term Records
+
+The [Term Cases](conflict-cases.md) use this narrower source set, rechecked 2026-09-08. Locators in the term table point to the exact document or section, not a general vendor home page.
+
+| Named source | Source kind | Reviewed surface and version | Re-review trigger |
+| --- | --- | --- | --- |
+| Figma | `design-tool` | [Variables, collections, modes](https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes) and [components](https://help.figma.com/hc/en-us/articles/360038662654-Guide-to-components-in-Figma); dated help pages | Tool data model or cited help meaning changes |
+| DTCG | `specification` | [2025.10 Format](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/) and [Second Editors' Draft, 2022-06-14](https://www.designtokens.org/tr/second-editors-draft/format/) | A comparison changes version; retain the historical scope |
+| CSSWG | `web-platform` | [CSS Custom Properties Level 1](https://www.w3.org/TR/css-variables-1/#defining-variables) | The cited runtime-value definition changes |
+| Carbon | `design-system` | [What is Carbon](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) and [patterns overview](https://carbondesignsystem.com/patterns/overview/) | Component or pattern scope changes |
+| StyleGallery | `pattern-library` | Local [Layout hub](../layout/index.md) and its repository contract | Layout ownership or pattern contract changes |
+
+The DTCG 2022 reading is historical evidence of a draft, not an implementation recommendation. A direct locator and a recorded reading establish provenance for the local summary; independent semantic approval remains separate.
+
+## Freshness Policy
+
+Every recorded source carries: `source_url`, `source_kind`, a version boundary (specification version, product version, OS cycle, or dated reviewed page set), `status` in `current` / `deprecated` / `historical` / `unknown`, `reviewed_on`, and `retrieved_on`. Living sites without publishable versions record the reviewed page set and a re-review trigger. Terms with era history additionally record `introduced_in`, `deprecated_in`, `renamed_to`, and `historical_scope` in [Cross-System Term Cases](conflict-cases.md).
+
+## Reading The Inventory
+
+- Four of the seven broad browse sources are design systems; HIG is a platform guideline, DTCG is a specification, Figma is a tool. Horizontal comparison is valid only within a kind, or through typed relations with boundaries.
+- `foundations` labels are near-equivalent as layer names, but each system decides what the layer contains.
+- The DTCG row records an interchange format, not a published token set.
+- Dates above are the reading bound; any later restructure is new evidence, not a back-fill.
+
+## Opinionated Guidance
+
+- Cite surfaces verbatim; do not translate one source's layer names into another's inside a record.
+- Add a source only when its vocabulary surface is public, named, and officially linkable.
+- Record doc-surface and code-package vocabulary separately when they diverge.
+- Treat a renamed surface as new evidence with a new review date.
+
+## Platform-Specific Guidance
+
+Platform-owned sources appear here only for terminology records; interaction-convention comparison routes to [Platform Guides](../platform-guides/index.md).
+
+## Unsupported Absolutes
+
+- A source's layer count is not a maturity measure.
+- Absence of a surface does not mean the source lacks that capability.
+- This inventory does not verify any link resolves today beyond its recorded review date.
+- Inclusion here is not an endorsement for product adoption.
+
+## Verification Contract
+
+Before promotion or material edit, re-verify each cited surface still exists and still publishes the recorded layer names; update `status` and `reviewed_on`; confirm no entry quotes upstream definitional text.
+
+## Source, License, And Attribution
+
+This page is locally authored. Every cited source remains the authority on its own vocabulary; links are usage evidence, and no upstream prose, tables, or code samples are reproduced.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Design Concept Families](concept-families.md).

package/game-ui/classification.md

@@ -0,0 +1,82 @@
+---
+type: Domain Guide
+title: Game UI Classification
+description: Engine-neutral method for classifying game interfaces by player task, presentation, input, state, and motion.
+domain: game-ui
+lifecycle: experimental
+---
+
+# Game UI Classification
+
+Primary role: game-interface classification guide.
+
+## Repository Boundary
+
+This guide proposes a local, project-neutral taxonomy for classifying observable game-interface behavior without assuming a specific engine or art direction. Its player-task classes and classification axes are review tools, not a universal ontology. It does not turn a visual genre into a functional category or authorize decorative properties in reusable Layout patterns.
+
+## Reusable Method
+
+1. Capture the rendered screen or interaction in context.
+2. Assign one primary player-task class.
+3. Add secondary classes only when the same surface genuinely composes responsibilities.
+4. Record visual language, input, state, motion, and implementation as separate axes.
+5. Attach evidence for default, exceptional, and transitional states.
+6. State what is observed, inferred, and still unverified.
+
+## Player-Task Classes
+
+| Primary class | Player question | Typical examples |
+| --- | --- | --- |
+| `hud` | What is happening during play right now? | Health, ammo, objective, marker, cooldown |
+| `navigation` | Where can I go next? | Main menu, pause menu, chapter or mode selection |
+| `dialog` | What decision or interruption needs attention? | Confirmation, reconnect, privacy, system notice |
+| `inventory` | What do I own, equip, compare, or improve? | Loadout, stash, equipment, crafting, upgrade |
+| `progression` | What did I unlock or how am I advancing? | Results, level up, rewards, rank change |
+| `commerce` | What can I acquire and at what cost? | Shop, offer, product detail, currency shortage |
+| `tutorial` | What action should I learn or perform? | Coach mark, forced step, contextual hint |
+| `narrative` | What story or authored event is being presented? | Dialogue, boss intro, cinematic overlay |
+| `system-status` | Is the application ready and connected? | Splash, loading, sign-in, reconnect, patch status |
+| `input-surface` | How do I directly control the game? | Virtual stick, action button, key binding |
+
+## Classification Axes
+
+| Axis | Example values | Evidence requirement |
+| --- | --- | --- |
+| World relationship | `diegetic`, `spatial`, `overlay`, `full-screen` | Capture placement relative to play space |
+| Material character | `flat-graphic`, `framed`, `skeuomorphic`, `translucent`, `textural` | Capture repeated surface treatment |
+| Genre signal | `tactical`, `industrial`, `fantasy-ornamental`, `arcade`, `horror`, `casual` | Show repeated shape, type, icon, and material cues |
+| Information density | `sparse`, `standard`, `dense` | Count simultaneous choices and information groups |
+| Emphasis model | `typographic`, `icon-led`, `character-led`, `item-led`, `effect-led` | Identify first and second attention targets |
+| Input | pointer, keyboard, gamepad, touch, gaze, mixed | Exercise every declared input mode |
+| Motion role | affordance, activation, state change, transition, value change, reward, guidance, ambient | Record trigger, properties, timing, and interruption |
+
+## Opinionated Guidance
+
+- Organize the gallery first by player task, then filter by presentation and implementation axes.
+- Use two or three visual tags supported by repeated evidence.
+- Classify independent player-task regions separately when a screen composes them.
+- Do not infer style or behavior from project, prefab, widget, scene, or class names alone.
+
+## Platform-Specific Guidance
+
+Record engine, UI framework, render space, scaling policy, navigation system, text system, and motion system as implementation evidence. Route detailed engine hierarchy and API guidance to the matching engine-specific Game UI guide.
+
+## Unsupported Absolutes
+
+- A genre label does not establish a visual style.
+- A screenshot does not prove responsive behavior, focus behavior, or motion interruption.
+- A production project's folder structure is not a universal architecture.
+- Similar appearance does not prove equivalent accessibility, performance, or interaction behavior.
+
+## Verification Contract
+
+Verify narrow and wide surfaces, every declared input mode, long localized text, empty and loading states, disabled and error states, repeated open and close, rapid selection changes, and interrupted motion where relevant.
+
+## Source, License, And Attribution
+
+This page is a locally authored, project-neutral proposed taxonomy. It reproduces no game assets, project-specific hierarchy, or upstream implementation samples.
+
+## IA Navigation
+
+Parent: [Game UI](index.md).
+Next: [Game UI Screen Hierarchy](screen-hierarchy.md).

package/game-ui/decision-tree.md

@@ -0,0 +1,81 @@
+---
+type: Domain Guide
+title: Game UI Decision Tree
+description: Select player-task recipes, ownership boundaries, and engine routes from the screen's purpose.
+domain: game-ui
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Game UI Decision Tree
+
+Primary role: game screen planning route.
+
+## Repository Boundary
+
+This route selects game-interface responsibilities independently of engine and art direction. The [Classification](classification.md) remains the local taxonomy; the [Screen Hierarchy](screen-hierarchy.md) defines ownership roles.
+
+## Reusable Method
+
+1. Write the player's question while the interface is visible.
+2. Choose one primary task class from the table below.
+3. Decide whether play continues and which input actions must be blocked.
+4. Assign lifetime, focus, sorting, and state ownership.
+5. Adapt a [Screen Recipe](screen-recipes.md), then run the [Verification Workflow](verification-workflow.md).
+
+## Player Task Route
+
+| Player question | Primary class | Recipe |
+| --- | --- | --- |
+| What is happening during play? | `hud` | [Play status and input](screen-recipes.md#play-status-and-input) |
+| How do I perform an action? | `input-surface` | [Play status and input](screen-recipes.md#play-status-and-input) |
+| Where can I go, pause, or leave? | `navigation` | [Pause and navigation](screen-recipes.md#pause-and-navigation) |
+| What decision requires attention? | `dialog` | [Blocking decisions and connection](screen-recipes.md#blocking-decisions-and-connection) |
+| Is the game ready or connected? | `system-status` | [Blocking decisions and connection](screen-recipes.md#blocking-decisions-and-connection) |
+| What can I equip or compare? | `inventory` | [Inventory and comparison](screen-recipes.md#inventory-and-comparison) |
+| What have I earned or unlocked? | `progression` | [Results and progression](screen-recipes.md#results-and-progression) |
+| What can I obtain, and at what cost? | `commerce` | [Offers and acquisition](screen-recipes.md#offers-and-acquisition) |
+| What should I learn next? | `tutorial` | [Teaching and narrative](screen-recipes.md#teaching-and-narrative) |
+| What story is being presented? | `narrative` | [Teaching and narrative](screen-recipes.md#teaching-and-narrative) |
+
+If a screen contains several tasks, classify regions independently. A purchase confirmation inside an inventory screen is a dialog owned by a commerce operation; it is not another inventory slot.
+
+## Ownership Decisions
+
+| Decision | Record before implementing |
+| --- | --- |
+| Lifetime | Application, session, scene, screen, entity, or one operation |
+| Play relationship | Continues, pauses locally, or requests a networked pause; identify authority |
+| Input | Active action map, focus owner, pointer/gamepad coexistence, cancellation |
+| Ordering | Screen, HUD, world-linked, modal, or transient host; name competing hosts |
+| Data | Authoritative state versus preview, selection, pending operation and stale data |
+| Exit | What is restored, destroyed, retained, or reconciled |
+
+## Worked Selection
+
+A loadout screen shows owned equipment, character attributes, and a purchase button for an unavailable slot. Inventory is primary; comparison is a supporting region. The purchase flow is commerce and any confirmation is a modal decision. Closing the modal returns to the same slot. Losing connection updates operation status without clearing the loadout selection. A server response after the screen closes belongs to the operation owner, not a destroyed view.
+
+## Opinionated Guidance
+
+Separate the player's task from visual genre. Assign one cancellation owner for each active layer so the same Back/Cancel input does not dismiss a dialog and its parent screen together.
+
+## Platform-Specific Guidance
+
+For Unity, select the [UI System](unity/ui-systems.md), map [Architecture](unity/architecture.md), then use the [CLI Loop](unity/cli-loop.md) for the declared stack. Other engines retain these role contracts but require their own verified API mapping; no cross-engine runtime equivalence is claimed.
+
+## Unsupported Absolutes
+
+A pause menu does not imply multiplayer simulation can pause. Hierarchy order does not prove input blocking, focus, or sorting. A taxonomy label does not establish rendered behavior.
+
+## Verification Contract
+
+Check one ordinary screen, one overlay composition, and one unexpected interruption such as disconnection or scene teardown. Every active layer needs a named lifetime, input, sorting, and exit owner. Revisit the route if a real player task cannot be classified without forcing unrelated responsibilities together.
+
+## Source, License, And Attribution
+
+Locally authored route and fictional loadout case. It imports no game assets, third-party hierarchy, or engine code.
+
+## IA Navigation
+
+Parent: [Game UI](index.md).
+Next: [Game UI Screen Recipes](screen-recipes.md).