stylegallery 0.1.3 → 0.1.4

package/design-engineering/interface-craft.md

@@ -0,0 +1,107 @@
+---
+type: Domain Guide
+title: Interface Craft Decisions
+description: Repository-bounded method for purpose, implementation, review, and evidence decisions at the product layer.
+domain: design-engineering
+lifecycle: experimental
+source_repository: https://github.com/emilkowalski/skills
+source_path: skills/emil-design-eng/SKILL.md
+source_revision: 220e8607c90b17337d210125777b7b695f26c221
+---
+
+# Interface Craft Decisions
+
+Primary role: design-engineering decision guide.
+
+## Repository Boundary
+
+This page helps connect product intent, implementation detail, and verification. It does not create a second StyleGallery principle set, rank visual taste as objective quality, or override Layout, accessibility, source-order, and shared evidence contracts.
+
+## Reusable Method
+
+### Establish The Job
+
+Before tuning the interface, name:
+
+- the user task and state change;
+- why the behavior or treatment is necessary;
+- how frequently it appears;
+- which constraints and inputs it must survive;
+- the observable that will decide whether it works.
+
+If those answers are absent, implementation detail is premature.
+
+### Build A Verifiable Representation
+
+Use semantic structure and the owning domain's smallest robust contract first. Prototype the uncertain interaction or visual relationship at the lowest fidelity that exposes its failure modes. A prototype is evidence of one implementation state, not proof of general usability.
+
+### Review Observable Failures
+
+Inspect real content, empty states, long labels, constrained containers, repeated interaction, focus order, alternative input, relevant preferences, and target browsers/devices. When timing or continuity matters, review recordings slowly or frame by frame.
+
+### Record The Decision
+
+Use the shared high-impact claim shape:
+
+```text
+Principle:
+Claim:
+Context:
+Use case:
+Warrant:
+Evidence family:
+Verification protocol:
+Implementation handoff:
+Consumer reference: not_applicable
+Consumer reference reason: This blank craft-decision template declares no consumer-specific reference record.
+Boundary or limitation:
+Debt or escalation:
+Decision:
+```
+
+This makes the result reviewable without turning the practitioner's preference into authority.
+
+## Decision Questions
+
+| Question | Evidence that can help | What it cannot prove alone |
+| --- | --- | --- |
+| Does the detail serve the primary task? | Task model, prototype, user evidence | Universal preference |
+| Is the default understandable without instruction? | Task completion, terminology test, comparative prototype | Long-term adoption |
+| Does repetition make the behavior costly? | Frequency estimate, interaction timing, user evidence | One universal threshold |
+| Does the interface preserve continuity? | Rendered sequence, source/focus inspection | Human orientation for every user |
+| Does the implementation survive real constraints? | Content/container/input/browser matrix | Brand or aesthetic quality |
+| Is the final polish coherent with declared intent? | Named comparative criteria and representative review | Objective beauty |
+
+## Opinionated Guidance
+
+Small details can compound, strong defaults can lower adoption effort, and fresh-eye review can expose defects familiarity hides. These are practitioner heuristics. “Beautiful,” “delightful,” “premium,” “obvious,” and “feels right” require an operational definition and suitable human evidence when used as claims.
+
+## Platform-Specific Guidance
+
+CSS entry features, clipping techniques, Motion/Framer Motion, React effects, component-library variables, pointer capture, and browser-specific performance behavior belong in bounded implementation notes. Verify current official documentation and the actual product surface before recommending them.
+
+## Unsupported Absolutes
+
+- Beauty is not repository leverage or a sufficient acceptance criterion.
+- A fixed duration, easing, scale, velocity, or frequency threshold is not universal.
+- CSS does not categorically outperform JavaScript.
+- A property or API name does not prove hardware acceleration.
+- Product popularity does not prove a reusable implementation pattern.
+- A promotional or enthusiastic posture is not part of the review contract.
+
+## Verification Contract
+
+Every high-impact recommendation maps `principle -> claim -> context -> warrant -> evidence -> protocol -> boundary/debt`. Visual and interaction claims require rendered evidence; accessibility claims use the accessibility gate; human-quality claims need corresponding user or HCI evidence. A passing implementation keeps the owning domain's constraints visible in the handoff.
+
+## Source, License, And Attribution
+
+- Upstream inspiration: [emil-design-eng/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/emil-design-eng/SKILL.md)
+- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
+- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
+- Reuse form: independent method rewrite; upstream prose, tables, code, examples, distinctive ordering, and the quotation attributed to Paul Graham were not retained.
+- Evidence boundary: this practitioner source suggests review questions; it does not establish local quality, accessibility, performance, or adoption outcomes.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Platform Guides](../platform-guides/index.md).

package/design-terminology/concept-families.md

@@ -0,0 +1,78 @@
+---
+type: Domain Guide
+title: Design Concept Families
+description: Classification of design terms into foundation, interface-artifact, guidance, governance, consumption, and tooling-construct concept families.
+domain: design-terminology
+lifecycle: experimental
+---
+
+# Design Concept Families
+
+Primary role: design-term concept-family classification guide.
+
+## Repository Boundary
+
+This guide classifies design terms by the decision each term serves, as a property of the term's concept, independent of what kind of source uses it. A system's name for itself is not a concept family; see [Design Source Kinds](source-kinds.md). The families are review tools, not a universal ontology, and they never rename StyleGallery's own terms.
+
+## Reusable Method
+
+1. Capture the term inside its native source context with a named source.
+2. Identify the underlying concept, then assign one primary concept family.
+3. Record scope: whole system, one library, or a single artifact.
+4. Record audience and medium: designer-facing, engineer-facing, or tool-layer.
+5. Express relations to other terms only through the typed model in [Design Term Relations](relation-types.md).
+6. Cite the named source and document surface; never generalize from one source's usage.
+
+## Concept Families
+
+| Family | Question it answers | Typical terms |
+| --- | --- | --- |
+| `foundation` | What are the smallest reusable inputs? | token, design token, variable, primitive, core, base |
+| `interface-artifact` | What are the built interface units? | component, element, control, block, module, variant, state |
+| `guidance` | How is intent communicated? | principle, guideline, heuristic, standard, specification, recipe |
+| `governance` | How does the system change? | contribution, deprecation, versioning, adoption, migration, maturity |
+| `consumption` | Who uses which form? | package, library, kit, theme, plugin, preset |
+| `tooling-construct` | What does a tool's data model expose? | design-tool variable, mode, tool component, library file |
+
+`pattern` is recorded as `guidance` or `interface-artifact` depending on the cited source's own scope, never both at once.
+
+## Classification Cases
+
+| Case | Rule | Example |
+| --- | --- | --- |
+| Same term at different scope | Classify by the scope the source actually defines | `pattern` as workflow guidance in Carbon versus a spatial arrangement in a pattern library |
+| Same term for different audiences | Record audience as a separate axis before comparing | `token` in design tooling versus in generated CSS |
+| Era shift | Classify by current source usage; note the older meaning as history | `style guide` narrowed as `design system` broadened |
+| Tool layer versus system layer | A tool construct is `tooling-construct`, not the system's term for the same concept | A tool's variables versus a system's published token format |
+| Local override | A product may rename a family term locally; the family is shared, the authority is not | A product calling patterns `blocks` |
+
+## Opinionated Guidance
+
+- Classify the term as the named source uses it today, then compare through relations; never build one merged definition first.
+- Keep family and scope separate: `component` stays `interface-artifact` whether it names a button or a page region.
+- Prefer the narrowest scope the source supports; widen only with a second cited source.
+- Treat missing terms as gaps in that source's vocabulary, not omissions to fill by inference.
+
+## Platform-Specific Guidance
+
+Record the named source, its kind, and the review date for every classification. Route platform convention comparison to [Platform Guides](../platform-guides/index.md), motion terms to Motion, and StyleGallery's own term decisions to the [Controlled Vocabulary](../guides/vocabulary.md).
+
+## Unsupported Absolutes
+
+- One source's family structure is not a universal taxonomy.
+- A term's popularity does not establish its definition.
+- A tool vendor's feature name does not define the industry term.
+- Absence of a term in one source does not invalidate its use in another.
+
+## Verification Contract
+
+For every classified term, verify the named source still uses the term in the recorded family, scope, audience, and medium; re-check era-shifted terms against the current source; and confirm every cross-source claim carries a typed relation with a boundary.
+
+## Source, License, And Attribution
+
+This page is a locally authored, project-neutral proposed taxonomy. It cites named systems only as usage evidence and reproduces no upstream definitional prose.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Design Term Relations](relation-types.md).

package/design-terminology/conflict-cases.md

@@ -0,0 +1,120 @@
+---
+type: Domain Guide
+title: Cross-System Term Cases
+description: Typed-relation term records and three representative cross-system scenarios with non-equivalence boundaries.
+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 scope.
+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 | Source (kind) | Concept | Status | Scope | Reviewed on |
+| --- | --- | --- | --- | --- | --- |
+| `figma.variable` | Figma (`design-tool`) | named-design-value | current | file- or collection-bound | 2026-08-18 |
+| `figma.mode` | Figma (`design-tool`) | theme-context | current | variable collection | 2026-08-18 |
+| `figma.component` | Figma (`design-tool`) | tool-instance-model | current | file-bound | 2026-08-18 |
+| `component.code` | Codebases (`design-system`) | ui-building-block | current | codebase | 2026-08-18 |
+| `component.system` | Published system units (`design-system`) | published-ui-building-block | current | system-wide | 2026-08-18 |
+| `dtcg.token` | DTCG Format (`specification`) | interchange-record | current | format-bound | 2026-08-18 |
+| `css.custom-property` | CSS (`web-platform`) | runtime-value-slot | current | document/runtime | 2026-08-18 |
+| `polaris.token` | Polaris (`design-system`) | published-design-value | current | system-wide | 2026-08-18 |
+| `carbon.pattern` | Carbon (`design-system`) | workflow-guidance | current | system-wide | 2026-08-18 |
+| `polaris.pattern` | Polaris (`design-system`) | workflow-guidance | current | system-wide | 2026-08-18 |
+| `stylegallery.pattern` | StyleGallery (`pattern-library`) | spatial-primitive | current | repository | 2026-08-18 |
+| `primitive` (shared usage) | multiple systems | base-layer-input | current | per-system | 2026-08-18 |
+| `hig.material` | Apple HIG (`platform-guideline`) | visual-surface-treatment | current | OS platforms | 2026-08-18 |
+| `material.system` | Google (`design-system`) | system-collection-name | current | brand-wide | 2026-08-18 |
+| `styleguide` (historical) | industry history | visual-style-governance | historical | org-wide | 2026-08-18 |
+| `designsystem` (general) | industry usage | layered-system-collection | current | org-wide | 2026-08-18 |
+| `foundation` (layer label) | Material, Fluent, Carbon, Polaris (`design-system`) | base-layer-label | current | per-system | 2026-08-18 |
+| `variant` (`mode`/`state`/`theme`) | tool, code, tokens | theme-variant-context | current | per-surface | 2026-08-18 |
+
+## Recorded Relations
+
+| From | To | Type | Boundary |
+| --- | --- | --- | --- |
+| `figma.variable` | `dtcg.token` | `partial_overlap` | Exportable variables intersect the format; tool features such as modes exceed it, and not every variable is a portable token |
+| `figma.variable` | `css.custom-property` | `implementation_representation` | Variables can bind to custom properties in codegen; the binding is a representation path, not semantic identity |
+| `dtcg.token` | `css.custom-property` | `implementation_representation` | Custom properties are one serialization target for token values and also hold non-design values |
+| `polaris.token` | `dtcg.token` | `implementation_representation` | The format is one representation of Polaris's published values; the system, not the format, owns the values |
+| `figma.mode` | `variant` | `near_equivalent` | Modes, tool variants, component states, and token themes overlap as context switching but diverge in binding level |
+| `figma.component` | `component.code` | `same_label_different_meaning` | Tool instance model versus shipped code unit; swapping definitions breaks handoff |
+| `figma.component` | `component.system` | `same_label_different_meaning` | A tool construct versus a published system unit with API and support |
+| `carbon.pattern` | `stylegallery.pattern` | `partial_overlap` | Both are reusable solutions above atomic controls; Carbon patterns are workflow guidance, StyleGallery patterns are spatial primitives |
+| `carbon.pattern` | `polaris.pattern` | `near_equivalent` | Both name system-level workflow guidance with content and maturity differences |
+| `carbon.pattern` | `component.system` | `broader_than` | Within Carbon, patterns compose components into flows; the containment is system-scoped |
+| `primitive` | `foundation` | `near_equivalent` | Shared base-layer usage across systems with unstable extension: sometimes tokens, sometimes atoms |
+| `hig.material` | `material.system` | `same_label_different_meaning` | HIG names visual surface treatments; Material names a design system; the shared label is coincidence |
+| `styleguide` | `designsystem` | `partial_overlap` | Era- and org-scoped: a historical style guide governs visual style; a design system layers foundations, code, and governance; both labels coexist |
+| `foundation` (Material) | `foundation` | `near_equivalent` | Near-equivalent layer labels whose contents each system decides independently |
+
+## Scenario A: Component vs Pattern
+
+Question: is a component a pattern; at what level do `primitive`, `component`, and `pattern` sit?
+
+Query phrasing covered: `component versus pattern terminology`, `difference between component and pattern across design systems`.
+
+Answer shape: per system, not universal. In Carbon, `pattern` is `broader_than` its components within Carbon's scope; `carbon.pattern` and `stylegallery.pattern` share the reusable-solution region only as `partial_overlap`; `primitive` is `near_equivalent` to foundation terms with an unstable extension. A merged one-line definition would erase these boundaries.
+
+## Scenario B: Variable vs Design Token vs CSS Custom Property
+
+Question: are Figma's `variable`, DTCG's `token`, and CSS's `custom property` the same thing?
+
+Query phrasing covered: `figma variable design token custom property`. This is the same-label different-meaning case.
+
+Answer shape: no single equivalence holds. The three terms come from different source kinds (`design-tool`, `specification`, web platform mechanism) with different concepts: named-design-value, interchange-record, runtime-value-slot. `figma.variable` → `dtcg.token` is `partial_overlap`; `dtcg.token` → `css.custom-property` is `implementation_representation`. Substitution breaks in both directions: tool modes do not survive export, and custom properties carry non-design values.
+
+## Scenario C: Style Guide vs Design System
+
+Question: is a `style guide` the same as a `design system`?
+
+Query phrasing covered: `style guide versus design system`.
+
+Answer shape: no; `partial_overlap` scoped by era and organization. The historical `styleguide` record carries `historical_scope`: org-wide visual governance, dominant before layered systems with code and tokens; `introduced_in`/`deprecated_in` are not globally datable because adoption is per-organization, which is exactly why the relation is not `renamed_to`. Named-source evidence: the four recorded design systems each publish foundations-plus-components-plus-guidance, which no cited historical style guide scope covers.
+
+## 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
+
+For each relation, verify both cited sources still use the recorded terms and meanings, the typed relation and boundary still hold, `reviewed_on` is current for the claim, and every case names at least two sources in tension.
+
+## Source, License, And Attribution
+
+This page is a locally authored relation record with locally written summaries. Cited sources remain authoritative for their own definitions; no upstream definitional prose is reproduced.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [StyleGallery Domains](../DOMAINS.md).

package/design-terminology/index.md

@@ -0,0 +1,65 @@
+# 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
+
+Promotion beyond `experimental` requires all of the following, each pass/fail checkable:
+
+- 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.
+- At least three representative user tasks are verified: judging same-label different-meaning, judging a cross-system relation, and separating a historical term from a current one.
+- Representative findability queries return a target document or record.
+- Unresolved semantic disputes: zero.
+- Stale sources beyond their re-review trigger: zero.
+- Usage evidence from at least one real human or agent consumer exists.
+
+## 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, unrecorded terms, empty boundaries, contradiction pairs, malformed dates, and orphan terms. 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.
+
+## 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 Source Kinds](source-kinds.md).

package/design-terminology/relation-types.md

@@ -0,0 +1,103 @@
+---
+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.
+
+These rules are the human contract for v0.1; when the structured registry lands, they become validator rules unchanged.
+
+## Term Record Shape
+
+```yaml
+term_id: figma.variable
+label: Variable
+source: figma            # named source from source-vocabularies
+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-08-18
+relations:
+  - target: dtcg.token
+    type: partial_overlap
+    boundary: >
+      Some tool variables export as interchange tokens, but tool features
+      such as modes exceed the format, and not every variable is a
+      portable design token.
+```
+
+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. Cited sources remain authoritative for their own definitions; 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,79 @@
+---
+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://tr.designtokens.org/) | W3C Design Tokens Community Group | `specification` | `token`, `group`, `alias` data model | Specification draft version | current | 2026-08-18 |
+| [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 `reviewed_on` for this revision.
+
+## 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 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).