stylegallery 0.1.4 → 0.1.6

package/design-engineering/component-contract.md

@@ -0,0 +1,98 @@
+---
+type: Domain Guide
+title: Component Contract
+description: Define product component semantics, states, events, asynchronous ownership, and verification before visual treatment.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Component Contract
+
+Primary role: product component implementation handoff.
+
+## Repository Boundary
+
+This contract describes consumer-owned behavior. It does not create a shared component library, new Layout primitive, or default visual values. Existing profile records have their own closed schema; this planning template cannot substitute for their evidence records.
+
+## Reusable Method
+
+Start with semantic HTML or the platform's native control. Name the public inputs, emitted events, internal state, and owner of persisted data. Then describe each transition and its observable outcome. Use the [Worked Examples](worked-examples.md) to check common failure paths.
+
+## Contract Template
+
+| Field | Required answer |
+| --- | --- |
+| Task | The user action and the outcome the component supports |
+| Semantics | Element/control, accessible name, description, value, relationships |
+| Inputs | Data and callbacks, required/optional values, identity and revision |
+| Outputs | Events, payload meaning, when they are emitted, who commits the result |
+| State | Initial, active, selected, disabled, pending, empty, error, completed as applicable |
+| State ownership | Controlled inputs versus internal temporary state; reconciliation rule |
+| Input and focus | Keyboard, pointer, touch, focus entry/return and unavailable actions |
+| Async ownership | Request identity, duplicate action policy, stale result handling, cancellation |
+| Content | Empty, long, localized, unbroken and unavailable data |
+| Spatial composition | Layout source, parent constraints, scroll owner and overflow behavior |
+| Presentation | Product-owned values, density, visual hierarchy and optional motion brief |
+| Lifecycle | Creation, navigation, rerender, removal, event/listener cleanup |
+| Evidence | Expected behavior, actual result, runtime, source revision and artifacts |
+| Handoff | `consumer_reference` record or `not_applicable` with a reason |
+
+## Worked Contract: Save Action
+
+Task: persist the current editable document. The form owns the draft; the save operation owns a submitted snapshot; the server owns the persisted result. A success for snapshot A must not mark newer draft B as saved.
+
+| Current state | Event | Next state | Required effect |
+| --- | --- | --- | --- |
+| Clean | Edit | Dirty | Keep entered values; mark unsaved changes |
+| Dirty | Submit valid draft A | Saving A | Capture A and a request identity; acknowledge pending |
+| Saving A | Submit again | Saving A | Apply the declared duplicate policy; this example ignores the duplicate |
+| Saving A | Edit to B | Saving A with dirty B | Preserve B and distinguish it from submitted A |
+| Saving A | Matching success | Clean if draft still A; otherwise dirty B | Record persisted A without discarding B |
+| Saving A | Matching failure | Dirty current draft with error | Keep values and offer retry |
+| Any | Stale response | Unchanged | Ignore responses outside the active operation |
+| Any | Unmount/navigation | Disposed | Stop UI updates; cancellation does not imply the server rolled back |
+
+Implementation sketch, independent of framework:
+
+```text
+on submit:
+  if a request is active: return
+  validate the current draft
+  copy the draft into submittedSnapshot
+  create requestIdentity
+  start persistence(requestIdentity, submittedSnapshot)
+on result(identity, result):
+  if disposed or identity is not active: return
+  clear the active request
+  if successful: set persistedSnapshot to submittedSnapshot
+  else: expose a recoverable error
+  derive dirty state by comparing current draft with persistedSnapshot
+```
+
+A real application also defines revision conflicts, server normalization, and retry semantics. The sketch is not a distributed consistency protocol. Its handoff is `consumer_reference: not_applicable` because this fictional example selects no consumer profile or conformance record.
+
+## Opinionated Guidance
+
+Use state names that expose meaningful differences. Two booleans can accidentally permit “saved and failed”; a state transition table helps reveal impossible combinations. Do not merge input validity, request state, and persisted revision into one visual status.
+
+## Platform-Specific Guidance
+
+For web forms, preserve native label and form relationships. Validate custom semantics against the applicable [accessibility evidence gate](../quality/gates/accessibility-evidence.md). Framework scheduling, request abort behavior, and server idempotency require separate implementation evidence.
+
+## Unsupported Absolutes
+
+A state table does not prove accessibility, successful persistence, race freedom, or device coverage. Cancelling a client request does not prove its remote side effects stopped.
+
+## Verification Contract
+
+Resolve responses out of order, edit during saving, fail then retry, activate repeatedly, and remove the component before completion. Inspect both persisted and displayed values. Include keyboard-only operation, long content, and constrained parents. Record actual outcomes; the table above is an unexecuted reference contract. Review when a public input, event, or state meaning changes.
+
+## Source, License, And Attribution
+
+Locally authored contract and pseudocode; no framework or upstream implementation is copied. Shared quality gates own evidence admissibility.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Design Engineering Worked Examples](worked-examples.md).

package/design-engineering/decision-tree.md

@@ -0,0 +1,69 @@
+---
+type: Domain Guide
+title: Design Engineering Decision Tree
+description: Route product craft work from the uncertain decision to a contract, example, and appropriate evidence.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Design Engineering Decision Tree
+
+Primary role: product implementation planning route.
+
+## Repository Boundary
+
+This route turns a product request into a bounded implementation decision. It owns neither shared quality policy nor a default design system. Use the existing Layout corpus for geometry and Motion for temporal behavior.
+
+## Reusable Method
+
+1. Write the user's action and the expected result in one sentence.
+2. Identify what is uncertain: content, structure, state, identity, platform behavior, or perception.
+3. Select the route below and produce its named artifact.
+4. Implement the smallest slice containing the risky state, including failure and recovery.
+5. Verify the observable and record the remaining limitation using [Interface Craft Decisions](interface-craft.md).
+
+## Task Routes
+
+| Uncertain decision | Primary route | Artifact to produce |
+| --- | --- | --- |
+| What should this screen contain? | [Webpage Generation Workflow](../guides/webpage-generation-workflow.md) | Content inventory and task model |
+| What owns size, flow, and scroll? | [Layout Planning Guide](../GUIDE.md) | Layout brief and pattern composition |
+| What happens after activation or failure? | [Component Contract](component-contract.md) | State, event, focus, and asynchronous ownership tables |
+| How should a form, search, or destructive action recover? | [Worked Examples](worked-examples.md) | Scenario-specific acceptance cases |
+| Does a product detail serve the task? | [Interface Craft Decisions](interface-craft.md) | Claim with an observable and evidence boundary |
+| How do distinct identities use one Layout contract? | [Reference Profiles](reference-profiles/index.md) | Explicit profile selection and value ownership |
+| Will an existing consumer survive migration? | [Consumer Migration Readiness](consumer-migration-readiness.md) | Thirteen-dimension consumer-owned conformance record |
+| What should move and why? | [Motion Decision Tree](../motion/decision-tree.md) | Motion brief with interruption policy |
+| Is a platform convention transferable? | [Platform Adaptation Workflow](../platform-guides/adaptation-workflow.md) | Native fact, web mapping, fallback, and runtime matrix |
+
+## Worked Intake
+
+Request: “Make saving settings feel responsive.” The risky decision is whether acknowledgement means persistence. Begin with a component contract: clean, dirty, saving, saved, and failed. A saving label acknowledges submission; the saved state waits for the persistence response. Preserve unsaved edits when requests fail. Only then evaluate a completion treatment through Motion. This order exposes duplicate writes and lost edits before visual review.
+
+An acceptance statement can be: “A failed save leaves the entered values available for retry.” “Feels responsive” remains a human perception hypothesis until measured in the relevant task.
+
+## Opinionated Guidance
+
+Prototype the uncertain state rather than an entire polished screen. A good first slice includes the initiating action, its failure, and a recovery path. Add complexity when it resolves an observed limitation.
+
+## Platform-Specific Guidance
+
+Distinguish browser, OS, assistive technology, framework, and component library versions in evidence. A library's state name is an implementation detail, not the user's task definition.
+
+## Unsupported Absolutes
+
+No selected framework, profile, token set, or prototype proves product quality. Component completion does not demonstrate migration readiness for an entire consumer.
+
+## Verification Contract
+
+The route succeeds when a reviewer can find the decision owner, artifact, failure case, and evidence needed without guessing. Verify one ordinary, one exceptional, and one interrupted task. Revisit when a route sends the reader to the wrong domain or cannot produce a testable acceptance statement.
+
+## Source, License, And Attribution
+
+Locally authored routing and settings example. Linked repository documents remain authoritative for their own contracts.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Component Contract](component-contract.md).

package/design-engineering/index.md

@@ -8,6 +8,16 @@ In scope: purpose, frequency, interaction detail, implementation review, prototy
 
 Out of scope: a second universal principle set, unsupported claims of beauty or adoption, and overrides of semantic, accessibility, Layout, or shared quality contracts.
 
+## Start Here
+
+| Task | Route |
+| --- | --- |
+| Route the uncertain product decision. | [Design Engineering Decision Tree](decision-tree.md) |
+| Specify semantics, state, requests, and focus. | [Component Contract](component-contract.md) |
+| Apply settings, search, and destructive-action contracts. | [Design Engineering Worked Examples](worked-examples.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.
+
 ## Documents
 
 - [Interface Craft Decisions](interface-craft.md) connects product purpose, implementation detail, and verification without treating taste as proof.
@@ -20,9 +30,9 @@ This domain proposes product-layer questions. [Quality Gates](../quality/index.m
 
 ## Domain Contract
 
-See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and promotion rules.
+See [StyleGallery Domains](../DOMAINS.md) for lifecycle, provenance, page membership, and staleness rules.
 
 ## IA Navigation
 
 Parent: [StyleGallery](../index.md).
-Next: [Consumer Migration Readiness](consumer-migration-readiness.md).
+Next: [Design Engineering Decision Tree](decision-tree.md).

package/design-engineering/worked-examples.md

@@ -0,0 +1,127 @@
+---
+type: Domain Guide
+title: Design Engineering Worked Examples
+description: Apply component contracts to settings, asynchronous search, and destructive list actions with explicit recovery cases.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Design Engineering Worked Examples
+
+Primary role: product interaction recipe collection.
+
+## Repository Boundary
+
+These fictional examples connect decisions to expected behavior. They are neither shipped components nor captured product evidence. Values and presentation belong to the consumer; the referenced Layout recipes retain their spatial boundaries.
+
+The separate [Interaction Lab](../examples/domain-interactions/README.md) implements the save and search contracts as a local web prototype. Its [browser observations](../examples/domain-interactions/verification.md) apply to that exact example and source snapshot; they do not prove a consumer backend or the destructive-action recipe below.
+
+## Reusable Method
+
+Choose a matching user task, adapt its state ownership through the [Component Contract](component-contract.md), and execute the listed failure cases in the consuming application. The decision is incomplete until expected and actual results are recorded separately.
+
+## Settings With Explicit Save
+
+Task: edit preferences, inspect changes, and save intentionally. Compose the [SaaS Settings recipe](../recipes/saas-settings.md); let its selected patterns own page structure and scrolling. The form owns the editable draft, the operation owns the submitted snapshot, and persistence determines success.
+
+Keep field errors beside their inputs and provide a route to the first relevant error. On network failure, retain all entered values. A successful save of an older snapshot must leave subsequent edits dirty. If leaving the screen can lose changes, define discard/cancel/save behavior and what happens if saving fails.
+
+| Test | Expected behavior |
+| --- | --- |
+| Submit missing required input | Expose the error and retain other values |
+| Submit, edit again, then receive success | Confirm the submitted snapshot; preserve later edits |
+| Fail and retry | Keep the draft; issue the retry under the declared request policy |
+| Cancel navigation with dirty data | Stay on the form with the same draft and a usable focus target |
+
+Evidence still needed: keyboard/error announcement, persistence responses, and source-bound runtime capture. A prototype cannot prove real data was saved.
+
+## Search With Detail Selection
+
+Task: search a collection and inspect an item without losing the search context. Compose [List Detail](../recipes/list-detail.md). Separate query text, submitted query, active request, results, and selected item identity. Displayed detail must name the selected item even when the result set refreshes.
+
+Keep typing responsive; a request for an older query cannot replace a newer result. Distinguish “no results” from loading and failure. On a tight surface, preserve selection and query when navigating between list and detail. If the selected item disappears, choose a documented empty detail or next-item policy instead of silently showing stale data.
+
+| Test | Expected behavior |
+| --- | --- |
+| Submit A, then B; resolve B before A | Results remain for B after A arrives |
+| Receive zero results | Show the submitted query and a recovery action |
+| Resize with detail selected | Preserve selection and query; keep focus on a logical available target |
+| Remove the selected item remotely | Explain its unavailability or choose the documented next target |
+
+Evidence still needed: out-of-order response trace, selection identity, tight/wide rendered states, and input coverage. Motion is optional; use [Reorder and Filter](../motion/interaction-recipes.md#reorder-and-filter) only when it communicates stable identity.
+
+## Destructive Action In A List
+
+Task: remove a selected item with understandable consequences. Separate the initiating control, decision surface, pending operation, and final list update. Choose confirmation or undo from actual reversibility and product requirements. Do not offer undo when the backend cannot restore the item.
+
+Name the affected item and scope. During pending deletion, prevent unintended duplicate operations according to the contract. Failure preserves the item and a recovery path. On success, return focus to an appropriate neighboring item or list heading if the invoker was removed. A dialog's visual exit must not leave a blocker behind.
+
+| Test | Expected behavior |
+| --- | --- |
+| Cancel confirmation | No deletion; return to the invoker |
+| Fail the operation | Explain failure and preserve the item |
+| Succeed while filters change | Remove by stable identity, not old row position |
+| Remove the final item | Present an empty state and a logical focus destination |
+
+Evidence still needed: actual operation result, focus trace, dialog semantics, and recovery behavior. Use [Modal Transition](../motion/interaction-recipes.md#modal-transition) only for optional presentation.
+
+## Implementation Handoff
+
+```yaml
+example: # settings-save, search-detail, or destructive-list-action
+consumer_reference: not_applicable
+consumer_reference_reason: These fictional examples select no consumer-owned profile or evidence record.
+layout_source: # the selected recipe and the consumer's pinned revision
+state_owner: # component, screen, and persistence responsibilities
+acceptance_cases: # adapted rows above
+observed_results: not_run
+remaining_evidence: # actual runtime, input, device, and user evidence
+```
+
+## Product Story And Media Handoff
+
+Start with an observation sheet for a product homepage: section job, reading order, scene boundaries, changing objects, media crop, and source-confidence level. Record an unknown rendering mechanism as unknown; cinematic appearance alone does not establish video, Canvas, WebGL, or a library.
+
+| Decision | Product-owned record | Verification |
+| --- | --- | --- |
+| Typography and rhythm | Heading measure, copy length, spacing, contrast and image ratio | Real copy, text growth, narrow windows |
+| Scene composition | Subject identity, crop and focal point, transparent layers, background transitions | First/middle/last and transition frames |
+| Media export | Dimensions, frame order, codec/format, alpha, poster, source/license | Decode readiness and failed asset |
+| Runtime budget | Download bytes, decoded-memory estimate, cache and concurrency limits | Slow requests, repeated reversal, idle work |
+| Static equivalent | Every essential message in semantic HTML, explicit reading mode | No script, reduced motion, keyboard access |
+
+Use the [Motion scene contract](../motion/interaction-recipes.md#scene-composition-contract) and compare the [Flow and headphones examples](../examples/scroll-story/README.md). Their shared controller demonstrates content substitution; both are related local examples and establish no independent adopter evidence. Their different typography, colors, and assets remain product choices.
+
+Complete one representative scene before producing an entire video or image sequence. Review its composition and transition framing, then export at the target dimensions. A polished poster does not validate the intervening frames. This section is locally authored practice guidance, not adapted external visual expression.
+
+### Persistent Subject And Page Navigation
+
+The Flow story keeps one device shell mounted while its screen content and pose change with progress. The [Scene Navigation example](../examples/scene-navigation/README.md) carries that same identity principle into a page whose chapter selection changes while document position stays fixed. Background, text, device pose, and screen layers share one state owner. These are local product treatments, not profile values or reusable Layout CSS.
+
+For this page type, add an input map and URL/history contract to the visual handoff. Specify which surface owns wheel/swipe, which copy regions retain native scrolling, how a focused outgoing action is recovered, and how the user reaches ordinary reading. Review intermediate frames as well as the endpoints; semantic availability must not depend on a visual completion callback.
+
+## Opinionated Guidance
+
+Preserve the user's work across recoverable failures. Status text should explain the real operation; motion and color alone are insufficient descriptions of what happened.
+
+## Platform-Specific Guidance
+
+Native navigation, browser history, component libraries, and platform controls differ. Record the exact implementation of cancellation and focus return rather than copying a screenshot's apparent behavior.
+
+## Unsupported Absolutes
+
+Confirmation is not always safer than undo. Optimistic updates are not always appropriate. A worked example does not certify a consumer migration or establish universal usability.
+
+## Verification Contract
+
+Execute all adapted acceptance rows plus long text, empty content, relevant constraints and preferences, and every claimed input method. For a migration use the larger [Migration Readiness](consumer-migration-readiness.md) contract. Review these examples when an observed failure lacks an owner or recovery action.
+
+## Source, License, And Attribution
+
+Locally authored scenarios and expected-result tables. Repository links provide spatial and evidence contracts, not proof that these scenarios have run.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Interface Craft Decisions](interface-craft.md).

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 tool values, runtime representations, components, patterns, and historical formats.
 domain: design-terminology
 lifecycle: experimental
 ---
@@ -18,75 +18,64 @@ This page applies the typed relation model to recorded term records and conflict
 
 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.
+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-08 |
+| `dtcg.group` | Group | [DTCG](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/#groups) (`specification`) | token-organization | current | Format Module 2025.10 | 2026-09-08 |
+| `dtcg.token.draft2` | Token | [DTCG](https://www.designtokens.org/tr/second-editors-draft/format/#design-token) (`specification`) | interchange-record | historical | Second Editors' Draft, 2022-06-14 | 2026-09-08 |
+| `css.custom-property` | Custom property | [CSSWG](https://www.w3.org/TR/css-variables-1/#defining-variables) (`web-platform`) | runtime-value-slot | current | CSS Custom Properties Level 1 | 2026-09-08 |
+| `carbon.component` | Component | [Carbon](https://carbondesignsystem.com/all-about-carbon/what-is-carbon/) (`design-system`) | published-ui-building-block | current | Carbon design and implementation resources | 2026-09-08 |
+| `carbon.pattern` | Pattern | [Carbon](https://carbondesignsystem.com/patterns/overview/) (`design-system`) | workflow-guidance | current | Carbon patterns catalog | 2026-09-08 |
+| `stylegallery.pattern` | Pattern | [StyleGallery](../layout/index.md) (`pattern-library`) | spatial-primitive | current | repository Layout corpus | 2026-09-08 |
+
+The external locators and local Layout contract were rechecked on the dates shown. Current status is bounded by the named source/version, not a promise about every later release. Concept labels are local classification summaries.
 
 ## Recorded Relations
 
-| From | To | Type | 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 |
 
-## 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).
 
 ## Opinionated Guidance
 
@@ -108,13 +97,13 @@ 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 its fixtures after editing. Verify both direct source locators, the comparison scope, direction, and boundary. The validator checks record shape and graph invariants; semantic accuracy still requires source review. Re-review when a named source changes the cited meaning.
 
 ## Source, License, And Attribution
 
-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.
 
 ## IA Navigation
 
 Parent: [Design Terminology](index.md).
-Next: [StyleGallery Domains](../DOMAINS.md).
+Next: [Design Term Comparison Workflow](comparison-workflow.md).