stylegallery 0.1.4 → 0.1.7

package/design-terminology/comparison-workflow.md

@@ -0,0 +1,98 @@
+---
+type: Domain Guide
+title: Design Term Comparison Workflow
+description: Resolve source-specific terminology questions with a scoped relation, explicit uncertainty, and a reusable handoff.
+domain: design-terminology
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Design Term Comparison Workflow
+
+Primary role: terminology lookup, authoring, and handoff route.
+
+## Repository Boundary
+
+This workflow answers what two named sources mean and how those meanings relate. Internal naming still belongs to [Controlled Vocabulary](../guides/vocabulary.md). Implementation behavior belongs to its owning domain. Document retrieval does not execute a structured terminology query.
+
+## Reusable Method
+
+1. Capture the exact question, both labels, intended audience, and comparison scope.
+2. Identify each named source and [source kind](source-kinds.md). If either source is missing, report insufficient context.
+3. Check [Recorded Sources](source-vocabularies.md) and open the direct term locators in [Term Cases](conflict-cases.md).
+4. Record each label, concept, status, and version independently. Classify through [Concept Families](concept-families.md).
+5. Select a [relation type](relation-types.md), direction, and non-trivial boundary. A composed-of relationship is not automatically subtyping.
+6. Return the scoped result, term IDs, source recheck status, and a counterexample or missing observation.
+7. For a new record, update the source inventory and term/relation tables, then run their validator and fixtures.
+
+## Decision Table
+
+| Situation | Result to produce |
+| --- | --- |
+| Identical labels, distinct meanings in two named sources | `same_label_different_meaning`, both meanings and the confusion risk |
+| Shared region but source-specific features on both sides | `partial_overlap`, intersection and each side's difference |
+| One form stores or consumes another concept | `implementation_representation`, representation first and the loss/addition boundary |
+| Genuine set inclusion with a counterexample | `broader_than` or `narrower_than`, explicit direction |
+| Meaning overlaps across versions or systems | `near_equivalent`, declared symmetry and the divergence axis |
+| One source records a dated label replacement | `renamed_to`, same source and verifiable event |
+| The proposed comparison uses incompatible axes | `not_comparable`, the axis mismatch |
+| Source, scope, or meaning cannot be established | No relation recorded; say what evidence is missing |
+
+## Handoff Template
+
+```yaml
+question: # the consumer's actual terminology question
+term_ids: # exact identifiers from conflict-cases.md
+relation_types: # closed types actually relied on
+scope: # the recorded comparison scope
+answer: # locally written scoped conclusion
+boundary: # where substitution breaks
+sources_rechecked: # date and source locators, or unverified
+unknowns: # missing evidence, or none within the recorded scope
+consumer_reference: not_applicable
+consumer_reference_reason: This blank terminology template selects no consumer record.
+```
+
+## Worked Handoff
+
+Question: can a CSS custom property be called the same thing as an interchange token?
+
+Term identifiers: `css.custom-property`, `dtcg.token`. Relation type: `implementation_representation`, from the CSS representation to the token concept, in scope `token-to-css-output`. Answer: a custom property can consume a translated token value, but the runtime slot does not carry the full interchange record and can also store other values. Sources rechecked: the direct CSSWG and DTCG 2025.10 locators in [Term Cases](conflict-cases.md), 2026-09-08. Consumer reference: `not_applicable`, because this is a terminology explanation with no selected consumer record.
+
+This judgment does not prove any actual converter preserves aliases, types, or metadata.
+
+## Reader Verification Tasks
+
+| Task | Expected result | Failure signal |
+| --- | --- | --- |
+| Compare Figma and Carbon “Component” | Two source-specific records and `same_label_different_meaning` | One merged definition |
+| Compare variable, token, and custom property | `partial_overlap` plus representation-first mapping | Equivalence or reversed representation direction |
+| Compare the second DTCG draft with 2025.10 | Historical/current version scopes and no invented rename | Treating the draft as the current implementation contract |
+| Compare “style guide” and “design system” without organizations | Insufficient context; request the two sources | Universal history or deprecation claim |
+
+These are expected lookup outcomes. A maintainer records actual reader task results and participant identity separately before claiming findability evidence. Reader tasks are not a domain lifecycle prerequisite.
+
+## Opinionated Guidance
+
+Resolve ambiguity explicitly; a qualified answer is more useful than an unsupported winner. Retain historical records with their own scopes when a current reading changes.
+
+## Platform-Specific Guidance
+
+Direct source authority is limited to its named platform, system, tool, or specification. A platform terminology comparison does not establish a target's support for the named feature.
+
+## Unsupported Absolutes
+
+Do not infer equivalence from an absent relation, source popularity, or shared spelling. A passing record validator cannot determine whether a semantic judgment is persuasive.
+
+## Verification Contract
+
+Verify table consistency mechanically and meaning against both sources. Run the reader tasks for an actual findability claim. Re-review when either source revises its term or a reader encounters an unresolved ambiguity. The [domain lifecycle review](index.md#promotion-to-stable) follows the repository-owner policy separately from reader evidence.
+
+## Source, License, And Attribution
+
+Locally authored workflow relying on the term identifiers and relation types declared above. Named sources were rechecked through the direct locators in Term Cases on 2026-09-08. No upstream definitional prose is reproduced.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Cross-System Term Cases](conflict-cases.md).

package/design-terminology/conflict-cases.md

@@ -1,7 +1,7 @@
 ---
 type: Domain Guide
 title: Cross-System Term Cases
-description: Typed-relation term records and three representative cross-system scenarios with non-equivalence boundaries.
+description: Directly sourced terms and scoped relations for values, token resolution, interaction semantics, typography, components, and historical formats.
 domain: design-terminology
 lifecycle: experimental
 ---
@@ -12,81 +12,111 @@ 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.
+This page applies the [typed relation model](relation-types.md) 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.
+1. Name the sources in tension and the terms or concepts being compared.
 2. Record each side as a term record with source, kind, concept, status, and scope.
-3. Assign one relation type per pair per 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 | 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 |
+| 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-21 |
+| `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-21 |
+| `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-21 |
+| `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 |
+| `dtcg.alias` | Alias | [DTCG](https://www.designtokens.org/tr/2025.10/format/#alias-reference) (`specification`) | token-value-reference | current | Format Module 2025.10 | 2026-09-21 |
+| `fluent.alias-token` | Alias token | [Fluent 2](https://fluent2.microsoft.design/design-tokens#alias-tokens) (`design-system`) | semantic-design-value | current | dated Fluent token-layer guidance | 2026-09-21 |
+| `fluent.global-token` | Global token | [Fluent 2](https://fluent2.microsoft.design/design-tokens#global-tokens) (`design-system`) | context-independent-design-value | current | dated Fluent token-layer guidance | 2026-09-21 |
+| `carbon.color-token` | Token | [Carbon](https://carbondesignsystem.com/elements/color/overview/) (`design-system`) | theme-stable-color-role | current | Carbon color role and theme guidance | 2026-09-21 |
+| `dtcg.resolver-modifier` | Modifier | [DTCG Resolver](https://www.designtokens.org/tr/2025.10/resolver/#modifiers) (`specification`) | conditional-token-source-selection | current | Resolver Module 2025.10 | 2026-09-21 |
+| `html.popover` | Popover | [WHATWG HTML](https://html.spec.whatwg.org/multipage/popover.html) (`web-platform`) | temporary-presentation-mechanism | current | HTML popover attribute and APIs | 2026-09-21 |
+| `apple.popover` | Popover | [Apple HIG](https://developer.apple.com/design/human-interface-guidelines/popovers) (`platform-guideline`) | native-transient-presentation | current | dated HIG with per-platform considerations | 2026-09-21 |
+| `html.dialog` | Dialog | [WHATWG HTML](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element) (`web-platform`) | native-dialog-element | current | native HTML dialog without role override | 2026-09-21 |
+| `aria.dialog` | Dialog | [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/#dialog) (`specification`) | accessible-dialog-role | current | WAI-ARIA 1.2 dialog semantics | 2026-09-21 |
+| `apple.text-style` | Text style | [Apple HIG](https://developer.apple.com/design/human-interface-guidelines/typography) (`platform-guideline`) | native-typography-role-and-scaling | current | system text-style guidance and text-size adaptation | 2026-09-21 |
+| `fluent.type-ramp` | Type ramp | [Fluent 2](https://fluent2.microsoft.design/typography#type-ramp) (`design-system`) | platform-typography-role-collection | current | dated Fluent platform type guidance | 2026-09-21 |
+| `material3.typography` | Typography | [Material 3 Compose](https://developer.android.com/develop/ui/compose/designsystems/material3#typography) (`design-system`) | implemented-typography-role-collection | current | Compose implementation surface of Material 3 | 2026-09-21 |
+| `dtcg.typography` | Typography | [DTCG](https://www.designtokens.org/tr/2025.10/format/#typography) (`specification`) | composite-typography-record | current | Format Module 2025.10 | 2026-09-21 |
+| `css.font` | font | [CSSWG](https://www.w3.org/TR/css-fonts-4/#font-prop) (`web-platform`) | runtime-font-shorthand | current | CSS Fonts Level 4 font shorthand | 2026-09-21 |
+
+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 | 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 |
+| 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 |
+| `fluent.alias-token` | `dtcg.alias` | `partial_overlap` | semantic-layer-versus-reference | symmetric | Semantic values can use references; a DTCG reference need not carry a semantic role, while a flattened semantic export can lose its reference edge | 2026-09-21 |
+| `fluent.alias-token` | `carbon.color-token` | `partial_overlap` | role-oriented-color-values | symmetric | Both cover role-oriented color decisions; Fluent aliases also cover non-color values, while Carbon defines its own theme and layer roles without a one-to-one Fluent mapping | 2026-09-21 |
+| `fluent.global-token` | `dtcg.token` | `partial_overlap` | named-design-value-interchange | symmetric | Global values can be encoded as token records; Fluent's values are not intrinsically DTCG files, and DTCG records also express context-specific decisions beyond Fluent global values | 2026-09-21 |
+| `dtcg.resolver-modifier` | `dtcg.group` | `not_comparable` | organization-versus-resolution | symmetric | A modifier selects conditional token sources, while a group organizes records; neither grouping nor a group name supplies the resolver's input selection | 2026-09-21 |
+| `html.popover` | `apple.popover` | `partial_overlap` | temporary-content-presentation | symmetric | Temporary related content can fit both; HTML supplies a generic mechanism for varied semantics, while HIG adds native presentation and adaptation conventions that HTML does not supply | 2026-09-21 |
+| `html.dialog` | `aria.dialog` | `implementation_representation` | web-dialog-semantics | directional | The native HTML element can represent dialog semantics and adds lifecycle behavior; other markup can carry the ARIA role without acquiring that native behavior | 2026-09-21 |
+| `apple.text-style` | `dtcg.typography` | `partial_overlap` | typographic-attribute-exchange | symmetric | Static typography attributes overlap; native style scaling is outside the composite record, while DTCG records can describe styles outside Apple's system | 2026-09-21 |
+| `css.font` | `dtcg.typography` | `implementation_representation` | partial-typography-output | directional | The CSS shorthand can consume translated font attributes but omits letter spacing and source metadata, so additional output and provenance are required | 2026-09-21 |
+| `material3.typography` | `fluent.type-ramp` | `partial_overlap` | named-typography-roles | symmetric | Both organize typographic roles, but Compose exposes Material-specific slots while Fluent defines target-specific ramps; their role inventories and defaults are not interchangeable | 2026-09-21 |
 
-## Scenario A: Component vs Pattern
+## Scenario A: Component Versus Pattern
 
-Question: is a component a pattern; at what level do `primitive`, `component`, and `pattern` sit?
+Query phrasing: `component versus pattern terminology`, `difference between component and pattern across design systems`.
 
-Query phrasing covered: `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.
 
-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, Design Token, And CSS Custom Property
 
-## Scenario B: Variable vs Design Token vs CSS Custom Property
+Query phrasing: `figma variable design token custom property`.
 
-Question: are Figma's `variable`, DTCG's `token`, and CSS's `custom property` the same thing?
+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.
 
-Query phrasing covered: `figma variable design token custom property`. This is the same-label different-meaning case.
+## Scenario C: Historical And Current Token Formats
 
-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.
+Query phrasing: `historical design token format`, `DTCG second editors draft versus 2025.10`.
 
-## Scenario C: Style Guide vs Design System
+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.
 
-Question: is a `style guide` the same as a `design system`?
+## Scenario D: Style Guide Versus Design System
 
-Query phrasing covered: `style guide versus design system`.
+Query phrasing: `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.
+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).
+
+## Scenario E: Alias, Role, And Resolution
+
+Query phrasing: `Fluent alias DTCG reference`, `semantic token group theme resolver`.
+
+[Token Semantics And Resolution](token-semantics.md) compares semantic layering, reference edges, role-oriented color, group organization, and resolver selection. Record the selected context and translation losses; equal rendered values do not establish equivalent roles.
+
+## Scenario F: Dialog And Popover
+
+Query phrasing: `HTML popover Apple popover`, `dialog element ARIA dialog difference`.
+
+[Dialog And Popover Semantics](interaction-semantics.md) separates native vocabulary, web presentation mechanisms, accessibility roles, and the consumer's task. Carry the relation boundary into the implementation handoff instead of using a component name as a behavior specification.
+
+## Scenario G: Type Style, Type Ramp, And Font Output
+
+Query phrasing: `Dynamic Type typography token`, `Material Typography Fluent type ramp`, `CSS font DTCG typography`.
+
+[Typography Semantics](typography-semantics.md) distinguishes one style from a role collection and a runtime representation. Native scaling and missing output properties remain explicit translation work.
 
 ## Opinionated Guidance
 
@@ -108,13 +138,15 @@ When a case involves a platform guideline source, cite that platform's surface a
 
 ## 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.
+Run `node scripts/validate-design-terminology.mjs --json` and `node scripts/test-validate-design-terminology.mjs` after editing. The [fixture runner](../scripts/test-validate-design-terminology.mjs) checks rejection of invalid records and relations. Verify both direct source locators, the comparison scope, direction, and boundary against the [relation definitions](relation-types.md). 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
 
-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.
+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.
+
+Rechecked 2026-09-21: DTCG Format and Resolver 2025.10, Fluent tokens and typography, Carbon color overview/usage, WHATWG dialog/popover, WAI-ARIA 1.2 dialog, Apple HIG popovers/typography, Material 3 Compose typography, and CSS Fonts/Custom Properties. Apple bodies were inspected through official documentation JSON. Older record dates remain their original review bounds; this session did not recheck Figma, the historical DTCG draft, Carbon component/pattern meaning, or local Layout term meaning.
 
 ## IA Navigation
 
 Parent: [Design Terminology](index.md).
-Next: [StyleGallery Domains](../DOMAINS.md).
+Next: [Design Term Comparison Workflow](comparison-workflow.md).

package/design-terminology/index.md

@@ -18,22 +18,22 @@ Representative questions this domain answers: are Figma's variable, the DTCG des
 
 ## Promotion To Stable
 
-Promotion beyond `experimental` requires all of the following, each pass/fail checkable:
+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.
-- 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.
+
+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, 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:
+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?
@@ -47,6 +47,14 @@ The review result is recorded as: terms reviewed, relations reviewed, counts of
 
 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.
@@ -55,6 +63,12 @@ This domain is a working method template: consumers may fork it and re-record th
 - [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.
 
+## Source-Backed Deep Dives
+
+- [Token Semantics And Resolution](token-semantics.md). Compare semantic roles, references, groups, context resolution, and runtime values.
+- [Dialog And Popover Semantics](interaction-semantics.md). Separate platform names, HTML mechanisms, ARIA roles, and task behavior.
+- [Typography Roles, Styles, And Representations](typography-semantics.md). Compare native styles, role collections, composite records, and CSS output.
+
 ## 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).
@@ -62,4 +76,4 @@ This domain is a working method template: consumers may fork it and re-record th
 ## IA Navigation
 
 Parent: [StyleGallery](../index.md).
-Next: [Design Source Kinds](source-kinds.md).
+Next: [Design Term Comparison Workflow](comparison-workflow.md).

package/design-terminology/interaction-semantics.md

@@ -0,0 +1,87 @@
+---
+type: Domain Guide
+title: Dialog And Popover Semantics
+description: Separate native component names, HTML presentation behavior, ARIA semantics, and product interaction contracts.
+domain: design-terminology
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Dialog And Popover Semantics
+
+Primary role: interaction terminology comparison.
+
+## Repository Boundary
+
+This page owns the meaning comparison. [Native Interaction Contracts](../design-engineering/native-interaction-contracts.md) owns implementation decisions; [Platform Guides](../platform-guides/adaptation-workflow.md) owns native adaptation. Term identities and typed relations remain in [Term Cases](conflict-cases.md).
+
+## Reusable Method
+
+For a named surface, record four axes before assigning a component: source vocabulary, exposed semantics, presentation mechanism, and task behavior. Ask which one the speaker means. One product surface can involve all four without making them synonyms.
+
+### Direct Source Comparison
+
+| Source | What the cited term describes | Missing information for an implementation |
+| --- | --- | --- |
+| [Apple HIG popovers](https://developer.apple.com/design/human-interface-guidelines/popovers) | A platform-guided temporary presentation with platform-specific usage and adaptation conventions. | The target web role, keyboard behavior, and save policy. |
+| [HTML popover](https://html.spec.whatwg.org/multipage/popover.html) | An attribute/API mechanism that can be applied to elements with different semantics. | The task's semantic widget model. |
+| [HTML dialog](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element) | A native HTML element with its own presentation and lifecycle operations. | The task's name, focus destination, and application data decisions. |
+| [WAI-ARIA dialog](https://www.w3.org/TR/wai-aria-1.2/#dialog) | An accessibility role for a dialog, including an accessible-name requirement. | The code that makes interaction and presentation satisfy that role. |
+| [APG modal dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | An informative pattern for modal keyboard and focus behavior. | Evidence that the chosen implementation works in its actual runtime. |
+
+Read on 2026-09-21. Apple page content was inspected through its official documentation JSON as well as the indexed page. HTML is a Living Standard; WAI-ARIA 1.2 is a Recommendation. Source authority applies to each named surface, not to a universal cross-platform component.
+
+### Popover: Shared Region And Non-Shared Regions
+
+`html.popover` and `apple.popover` have `partial_overlap` in the recorded temporary-content scope. A temporary anchored information surface can fit both descriptions. HTML's mechanism also applies to semantically different surfaces without requiring the HIG's platform conventions. Apple's presentation includes native adaptation and usage decisions that the attribute does not supply.
+
+The overlap does not justify copying every native dismissal behavior into a web form. A reviewer still needs to know whether an outside interaction saves, requests close, discards, or is ignored. That decision belongs in the consumer's contract and must preserve the task's data policy.
+
+### Dialog: Representation Direction
+
+The recorded relation `html.dialog` → `aria.dialog` uses `implementation_representation`. The native element can represent the accessible dialog concept; the relation points from representation to semantic concept. Other markup can carry a dialog role, but adding the role does not manufacture native lifecycle behavior.
+
+The comparison is about ordinary dialog semantics, not every possible role override or misuse of the element. Modality is another axis: the implementation must make its declared background interaction and focus behavior true.
+
+### Worked Ambiguity: “Put It In A Modal Popover”
+
+Turn the phrase into an explicit task rather than selecting a library component by substring. Suppose an annotation editor must remain visible while its document is inspected. Decide whether inspecting means reading the visible background or interacting with it. If interaction is needed, a modal focus contract may conflict with the task.
+
+| Question | Recordable answer |
+| --- | --- |
+| What is the task? | Edit one annotation while retaining document context. |
+| What background interaction is allowed? | The consumer explicitly permits or suspends it. |
+| What semantics describe the editor? | A named form/surface/widget choice, independently justified. |
+| What displays it? | A selected native or web mechanism. |
+| What ends the task? | Save, cancel, navigation, and outside interaction each have defined effects. |
+| What comparison is being relied on? | Source-qualified term pair, relation type, scope, and recheck date. |
+
+This example is a proposal, not an observed platform product. A library's component name can be recorded as an implementation choice without becoming another universal term definition.
+
+## Opinionated Guidance
+
+Use task language in product copy and source-qualified language in engineering handoffs. If two engineers use the same word for different axes, preserve the distinction in the contract instead of forcing agreement on the label.
+
+## Platform-Specific Guidance
+
+Native compact-view adaptation, browser top-layer behavior, and accessibility role exposure require different evidence. Route an actual adaptation to [Adaptive Navigation](../platform-guides/adaptive-navigation.md). Do not infer host behavior from matching screenshots.
+
+## Unsupported Absolutes
+
+Popover does not universally mean nonmodal form, menu, tooltip, or dialog. Top-layer painting does not specify an accessibility role. A component named Modal does not prove that the background is inert or that focus returns correctly.
+
+## Verification Contract
+
+Recheck both meanings at their direct locators and explain the common and non-common regions. For implementation reliance, verify the exposed role, focus behavior, background interaction, and dismissal outcome separately. Source review cannot substitute for those observations.
+
+The scenarios are unexecuted. A relation-validator pass establishes record consistency only. Re-review when a platform convention, HTML behavior, ARIA role, or library wrapper changes the comparison.
+
+## Source, License, And Attribution
+
+Locally authored synthesis without copied examples or assets. Terminology reliance: `html.popover`, `apple.popover`, `html.dialog`, and `aria.dialog`; relation types: `partial_overlap` and `implementation_representation`. All named sources were rechecked 2026-09-21. Relations are author judgments, not independent semantic approval. `consumer_reference: not_applicable` because no consumer interaction record is selected.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Design Term Comparison Workflow](comparison-workflow.md).

package/design-terminology/relation-types.md

@@ -47,7 +47,9 @@ A relation record is invalid when any of the following holds:
 - 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.
+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
 
@@ -55,18 +57,22 @@ These rules are the human contract for v0.1; when the structured registry lands,
 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-08-18
+reviewed_on: 2026-09-08
 relations:
   - target: dtcg.token
     type: partial_overlap
+    scope: value-interchange
+    direction: symmetric
+    reviewed_on: 2026-09-08
     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.
+      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.
@@ -95,7 +101,7 @@ Every recorded relation names two term records, one type from the closed set, a
 
 ## Source, License, And Attribution
 
-This page is a locally authored model. Cited sources remain authoritative for their own definitions; no upstream prose is reproduced.
+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
 

package/design-terminology/source-vocabularies.md

@@ -31,10 +31,40 @@ This page inventories the named sources whose terms this domain records, with th
 | [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 |
+| [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 `reviewed_on` for this revision.
+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 the narrower source sets below. Locators in the term table point to the exact document or section, not a general vendor home page. The first set retains its 2026-09-08 review; later readings do not backdate or refresh unrelated terms.
+
+| 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.
+
+### Sources Rechecked On 2026-09-21
+
+| Named source | Source kind | Reviewed surface and version | Re-review trigger |
+| --- | --- | --- | --- |
+| DTCG | `specification` | [Format 2025.10](https://www.designtokens.org/tr/2025.10/format/); token, group, alias, and typography meanings | Format version or the selected comparison changes |
+| DTCG Resolver | `specification` | [Resolver 2025.10](https://www.designtokens.org/tr/2025.10/resolver/); modifiers and context selection | Resolver version or context-resolution contract changes |
+| Fluent 2 | `design-system` | [Design tokens](https://fluent2.microsoft.design/design-tokens) and [typography](https://fluent2.microsoft.design/typography); dated guidance | Token-layer or target-platform role meaning changes |
+| Carbon | `design-system` | [Color overview](https://carbondesignsystem.com/elements/color/overview/) and [usage](https://carbondesignsystem.com/elements/color/usage/); dated role/theme/layer guidance | Color role, theme, or contextual layer semantics change |
+| WHATWG HTML | `web-platform` | [Popover](https://html.spec.whatwg.org/multipage/popover.html) and [dialog](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element); Living Standard | Presentation or element semantics change |
+| WAI-ARIA | `specification` | [Dialog role in WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/#dialog) | Role version, meaning, or native representation changes |
+| Apple HIG | `platform-guideline` | [Popovers](https://developer.apple.com/design/human-interface-guidelines/popovers) and [typography](https://developer.apple.com/design/human-interface-guidelines/typography); dated platform guidance | Platform convention or text-style behavior changes |
+| Material 3 Compose | `design-system` | [Material 3 typography in Compose](https://developer.android.com/develop/ui/compose/designsystems/material3#typography); implementation surface of the system | Named style slots or system-to-implementation mapping changes |
+| CSSWG | `web-platform` | [Custom Properties Level 1](https://www.w3.org/TR/css-variables-1/) and [Fonts Level 4](https://www.w3.org/TR/css-fonts-4/#font-prop); runtime representations | Property or shorthand semantics change |
+
+For this set, `retrieved_on` and `reviewed_on` are 2026-09-21. Apple bodies were inspected through their official documentation JSON when the HTML reader returned a JavaScript shell. The previous Carbon `/guidelines/color/` locators were unavailable in the reader; the reviewed official pages use `/elements/color/`. No historical source record was silently relabeled current. DTCG modules remain Community Group reports, not W3C Recommendations. Source review here is by the author and does not satisfy independent semantic promotion.
 
 ## Freshness Policy
 
@@ -42,7 +72,7 @@ Every recorded source carries: `source_url`, `source_kind`, a version boundary (
 
 ## 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.
+- 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.