stylegallery 0.1.6 → 0.1.7

package/design-engineering/state-management/state-brief.md

@@ -0,0 +1,83 @@
+---
+type: Domain Guide
+title: State Management Brief
+description: Record authority, transitions, effects, lifetime, and acceptance cases before implementation.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# State Management Brief
+
+## Repository Boundary
+
+This is a consumer planning template within Design Engineering. It supplements the [Component Contract](../component-contract.md); it is not a profile schema or evidence record.
+
+## Reusable Method
+
+For each independently owned value, complete one inventory row. Avoid a single status enum that conflates validation, request progress, persisted revision, and selection.
+
+| Field | Required answer |
+| --- | --- |
+| User task | Action and observable result |
+| Authoritative source | Server, route, form, component, or session owner |
+| State shape | Valid values, initial value, identity and revision |
+| Derived values | Inputs, equality, and cache invalidation if any |
+| Writes | Accepted intents, payloads, rejection and normalization |
+| Transitions | Event + guard → next state + effect |
+| Lifetime | Creation, identity switch, navigation, disposal and cleanup |
+| Async policy | Request identity, duplicates, stale results, uncertainty |
+| Persistence | Stored fields, scope, version, expiry, restoration conflicts |
+| Recovery | Retry, discard, reconciliation and focus destination |
+| Composition | Selected patterns and any rejected alternatives |
+| Evidence | Failure trace, expected result, runtime, actual result |
+
+### Worked Brief: Editing A Display Name
+
+| Value | Owner | Lifetime | Write rule |
+| --- | --- | --- | --- |
+| Acknowledged name and revision | Server; cache holds observation | Account session | Matching authoritative response |
+| Draft name | Settings form | Until discard, accepted save, or guarded departure | User edit |
+| Dirty | Derived | Same as form | Compare draft to acknowledged baseline |
+| Submitted name and request ID | Save operation | One attempt | Capture before starting effect |
+| Pending destination | Router guard | Confirmation decision | Latest attempted destination |
+
+Invariant: acknowledging A never marks later draft B saved. Failure trace: edit A → submit → edit B → acknowledge A. Expected result: A is the baseline; B remains visible and dirty. Rejected alternative: binding fields directly to the cache loses a reliable Cancel target.
+
+### Implementation Handoff
+
+```yaml
+domain: design-engineering
+state_patterns: [draft-and-baseline, submitted-snapshot, unsaved-navigation]
+state_owner: settings form and save operation
+persistence_owner: consumer backend
+consumer_reference: not_applicable
+consumer_reference_reason: This blank planning example selects no consumer profile or conformance record.
+observed_results: not_run
+remaining_evidence: consumer runtime, request traces, keyboard and focus recovery
+```
+
+## Opinionated Guidance
+
+An unresolved owner is an implementation question, not a reason to introduce more booleans. Write product choices such as discard policy explicitly; do not hide them inside effects.
+
+## Platform-Specific Guidance
+
+Include router, cache, framework, and persistence adapter versions only in the consumer handoff where they affect behavior. Check IME input and native form submission for editable fields.
+
+## Unsupported Absolutes
+
+Completing this template does not establish executed evidence or backend persistence. A request token alone cannot resolve concurrent server edits.
+
+## Verification Contract
+
+A second reader should identify every write owner and execute the failure trace without inventing policy. Record normal, failed, interrupted, and identity-changing cases before implementation.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](index.md).
+Next: [Continue the state management route](verification.md).

package/design-engineering/state-management/verification.md

@@ -0,0 +1,65 @@
+---
+type: Domain Guide
+title: State Management Verification Matrix
+description: Test event ordering, failure recovery, navigation, and identity boundaries separately from UI presentation.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# State Management Verification Matrix
+
+## Repository Boundary
+
+This matrix verifies consumer behavior under Design Engineering. Shared [quality gates](../../quality/index.md) own evidence admissibility. Passing a local model does not promote a domain or certify a consumer.
+
+## Reusable Method
+
+Start with the selected pattern's invariant. Use controlled promises or an injected transport to choose completion order. Assert both displayed state and effect count or persistence payload; a screenshot alone cannot show which snapshot was saved.
+
+| Dimension | Required stress when applicable | Observable |
+| --- | --- | --- |
+| Ordering | Start A/B; resolve B/A; stale error after new success | Current result, status, and error remain correlated |
+| Mutation | Edit during save; normalized result; version conflict | Draft, baseline, submitted payload, revision |
+| Duplication | Keyboard + pointer + another caller | Declared count and outcome sharing |
+| Failure | Definitive rejection versus unknown write outcome | Draft retained; reconciliation before unsafe retry |
+| Lifetime | Dispose; A → B → A; logout | No old-generation updates or scope leakage |
+| Navigation | Back, Forward, reload, deep link, canceled departure | URL, visible controls, draft, and selection agree |
+| Persistence | Corrupt version, wrong scope, unavailable storage, delayed restore | Valid defaults and preserved newer edits |
+| Accessibility | Pending, error, empty, removed invoker | Announcements and logical focus recovery |
+| Composition | Filter while deleting; edit during save-and-leave | Combined invariants survive interleaving |
+
+### Executable Local Coverage
+
+From a repository checkout, `npm run test:state-management` extracts and executes the standalone `js` block from each of the 12 pattern pages in an isolated Node process. The examples assert model outcomes for ownership, projections, selection, drafts, save snapshots, navigation decisions, stale completions, duplicate effects, optimistic recovery, URL parsing, identity generations, and restore validation.
+
+The four recipes declare integration acceptance sequences; they are not runnable browser fixtures. Existing [Interaction Lab](../../examples/domain-interactions/README.md) is a separate prototype with its own evidence scope. New recipe acceptance remains unexecuted until adapted to a consumer.
+
+### Evidence Record
+
+Record source revision, runtime, selected pattern/recipe, initial state, event sequence, submitted payload/effect count, expected state, actual state, and remaining limitations. Label unrun cases `not_run`; separate a model assertion from a browser observation and a server acknowledgement.
+
+## Opinionated Guidance
+
+Use deterministic event ordering instead of sleeps. Test the stale failure path as well as stale success, and inspect cleanup/finally paths that can accidentally clear a newer pending operation.
+
+## Platform-Specific Guidance
+
+Run browser navigation, focus, assistive-technology announcements, and storage failure checks in the actual target environment. Node URL and reducer examples cannot certify those integrations.
+
+## Unsupported Absolutes
+
+A green model suite does not prove race freedom under every interleaving, real persistence, or accessibility. Synthetic transports do not establish server idempotency.
+
+## Verification Contract
+
+For every consumer claim, identify a matching executed case or explicitly list missing evidence. Revisit the matrix when a real failure is not representable by its dimensions.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](index.md).
+Next: [Continue the state management route](recipes/index.md).

package/design-engineering/text-input-and-internationalization.md

@@ -0,0 +1,91 @@
+---
+type: Domain Guide
+title: Text Input And Internationalization
+description: Design composition-aware editing, explicit text units, bidirectional content, and locale-bound presentation without corrupting user input.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Text Input And Internationalization
+
+Primary role: multilingual text interaction and verification guide.
+
+## Repository Boundary
+
+This guide owns text editing and product-data decisions. Layout owns spatial constraints; a translation or input method does not authorize copying product typography into reusable Layout CSS. Browser text measurement is not proof that an editor preserves user intent.
+
+## Reusable Method
+
+Declare three contracts before implementing formatting: what the user can edit, what the application stores, and what it displays. Name the unit of any limit or selection offset. Then inventory composition, paste, autofill, correction, undo, direction, and locale changes. An event sequence from one Latin keyboard is a narrow sample.
+
+### Source Findings
+
+| Source | Bounded finding | Design consequence |
+| --- | --- | --- |
+| [UI Events](https://www.w3.org/TR/uievents/#events-compositionevents) | Composition has its own event lifecycle; `isComposing` identifies events within a composition session. | Do not treat every intermediate edit as a committed command. |
+| [Input Events Level 2](https://www.w3.org/TR/input-events-2/) | Input types describe edit intentions. The draft distinguishes cancelability during IME composition. | Inspect actual events; a universal keydown filter cannot govern every edit path. |
+| [Unicode Text Segmentation, UAX #29](https://www.unicode.org/reports/tr29/) | Grapheme clusters approximate user-perceived characters; boundaries are distinct from code points and words. | State whether a limit counts bytes, code units, code points, or grapheme clusters. |
+| [ECMA-402 Segmenter](https://tc39.es/ecma402/#segmenter-objects) | `Intl.Segmenter` exposes locale-sensitive segmentation at named granularities. | Name locale and granularity when using segmentation in a UI. |
+| [W3C bidirectional markup guidance](https://www.w3.org/International/questions/qa-html-dir) | HTML direction metadata and isolation help mixed-direction content retain its intended ordering. | Treat document direction and inserted user text separately. |
+| [Accessible Authentication explanation](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html) | WCAG 2.2's AA criterion limits required cognitive-function tests, with specified alternatives and assistance. | Do not casually remove paste or password-manager assistance from an authentication flow. |
+
+Sources were inspected 2026-09-21. UI/Input Events and ECMA-402 publication states must be read as labeled; a draft API description is not a claim that every target implements it identically. UAX #29 has versioned rules, so record the Unicode/runtime boundary for a reproducible segmentation claim.
+
+### Worked Scenario: Korean Search With Suggestions
+
+The user enters a Korean name, navigates candidates, commits composition, and then submits a search. Product state distinguishes the editable text, composition status, selected suggestion identity, and submitted query.
+
+Local policy: preserve the browser's in-progress composition. Do not move focus, replace the input node, run destructive formatting, or submit the form merely because a command key arrived during composition. Commit-driven search is a product choice; live preview during composition needs a separate decision and stale-result policy.
+
+| Event or condition | Proposed responsibility | Failure it prevents |
+| --- | --- | --- |
+| Composition starts | Keep the editing node and draft stable. | Rerendering discards the input method's active composition. |
+| Intermediate input | Retain the edit without treating a candidate as the submitted query. | A provisional syllable becomes an unintended request or selection. |
+| Candidate confirmation | Let the input method complete its edit before interpreting a separate application command. | Enter both confirms composition and submits unexpectedly. |
+| Suggestions return out of order | Match them to current query intent. | An old response replaces suggestions for the current text. |
+| User presses Escape | Resolve input-method, popup, and outer-surface ownership deliberately. | One key cancels composition, closes the popup, and closes the editor. |
+
+The exact native event order is a target observation, not prescribed here. Test the real IME in each supported browser/OS; synthetic composition events do not recreate the operating system's input method. Use [latest request wins](state-management/patterns/latest-request-wins.md) for replaceable reads.
+
+### Text Units And Limits
+
+For a visible “characters remaining” count, decide what users should perceive as one unit, then compare that policy with the backend limit. A grapheme count cannot guarantee that a byte-limited service accepts the value. Show the relevant limit rather than truncating silently after submission.
+
+Use a corpus containing Hangul composition, a base letter plus combining mark, emoji sequences, an empty value, pasted line breaks, and a long unbroken identifier. Verify counters, truncation, deletion, selection restoration, and round trips. A correct count with corrupted cursor placement is still an editing failure.
+
+Formatting belongs at a declared boundary. If a field needs grouping separators, preserve an editable representation and caret policy. A localized display string is not automatically a canonical stored number or date. Decide how incomplete input, ambiguous separators, and locale changes are resolved before adding automatic reformatting.
+
+### Direction And Mixed Content
+
+Set the document's language and base direction intentionally. Isolate inserted names, identifiers, and other independently directed text where needed; test punctuation and adjacent controls as well as the text itself. CSS alignment alone cannot establish the semantic direction of user data.
+
+Product tests should include an RTL name beside an LTR identifier, paired punctuation, numerals, and a trailing action. Preserve logical reading order while the Layout owner chooses logical spacing and containment.
+
+## Opinionated Guidance
+
+Preserve raw editing intent until a clear commit boundary. Prefer a reversible validation message over eager rewriting that the user cannot undo. Store stable identity separately from the localized label of a suggestion.
+
+## Platform-Specific Guidance
+
+Keyboard layouts, IMEs, dictation, autofill, and virtual keyboards can take different event paths. Record OS, browser, input method, locale, and assistive technology instead of a generic “mobile tested.” For typography and scaling, use [Preferences And Accessibility](../platform-guides/preferences-and-accessibility.md).
+
+## Unsupported Absolutes
+
+One code point is not necessarily one perceived character. A keypress is not the only way to edit text. A segmentation API is not a locale-aware parser. Programmatically dispatched events are not evidence that a native IME works.
+
+## Verification Contract
+
+The proposed cases cover real composition, candidate selection, paste, undo/redo, replacement selection, autofill, server rejection, mixed direction, and locale change with an unfinished draft. Bind observed input and submitted data to the same scenario; independently inspect the accepted backend value where that claim matters.
+
+Record both intended and observed event/selection outcomes, without storing private user input in diagnostic artifacts. The examples above are test data proposals; no IME, browser, or backend execution is claimed. Re-review after editor, formatter, runtime, or locale-policy changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis of the linked primary sources, inspected 2026-09-21. No upstream examples are reproduced. `consumer_reference: not_applicable` because no consumer editor record is selected.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Loading And Feedback](loading-and-feedback.md).

package/design-engineering/worked-examples.md

@@ -21,6 +21,8 @@ The separate [Interaction Lab](../examples/domain-interactions/README.md) implem
 
 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.
 
+The [State Management recipes](state-management/recipes/index.md) expand these tasks into explicit pattern stacks and substitution rules, including a multi-step form. These existing scenarios remain at their original anchors.
+
 ## 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.

package/design-terminology/conflict-cases.md

@@ -1,7 +1,7 @@
 ---
 type: Domain Guide
 title: Cross-System Term Cases
-description: Directly sourced terms and scoped relations for tool values, runtime representations, components, patterns, and historical formats.
+description: Directly sourced terms and scoped relations for values, token resolution, interaction semantics, typography, components, and historical formats.
 domain: design-terminology
 lifecycle: experimental
 ---
@@ -12,11 +12,11 @@ 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 explicit scope and declare its direction.
 4. Write the non-equivalence boundary: where substitution breaks.
@@ -30,13 +30,27 @@ This page applies the typed relation model to recorded term records and conflict
 | `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` | 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-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.
 
@@ -52,6 +66,15 @@ The external locators and local Layout contract were rechecked on the dates show
 | `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 Versus Pattern
 
@@ -77,6 +100,24 @@ Query phrasing: `style guide versus design system`.
 
 Result: insufficient context until an organization and dated source are named on both sides. “Industry history” cannot stand in for a specific historical style guide. Do not create a universal rename or deprecation event; request the two sources and then use the [Comparison Workflow](comparison-workflow.md).
 
+## 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
 
 - Resolve a conflict only after naming every source involved; silent resolution creates the next conflict.
@@ -97,12 +138,14 @@ When a case involves a platform guideline source, cite that platform's surface a
 
 ## Verification Contract
 
-Run `node scripts/validate-design-terminology.mjs --json` and its fixtures after editing. Verify both direct source locators, the comparison scope, direction, and boundary. The validator checks record shape and graph invariants; semantic accuracy still requires source review. Re-review when a named source changes the cited meaning.
+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
 
 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).

package/design-terminology/index.md

@@ -63,6 +63,12 @@ These workflows and worked cases are usable experimental guidance. Expected-resu
 - [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).

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/source-vocabularies.md

@@ -38,7 +38,7 @@ All entries cite official first-party URLs (`authority: official`); `retrieved_o
 
 ## Direct Sources For Current Term Records
 
-The [Term Cases](conflict-cases.md) use this narrower source set, rechecked 2026-09-08. Locators in the term table point to the exact document or section, not a general vendor home page.
+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 |
 | --- | --- | --- | --- |
@@ -50,6 +50,22 @@ The [Term Cases](conflict-cases.md) use this narrower source set, rechecked 2026
 
 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
 
 Every recorded source carries: `source_url`, `source_kind`, a version boundary (specification version, product version, OS cycle, or dated reviewed page set), `status` in `current` / `deprecated` / `historical` / `unknown`, `reviewed_on`, and `retrieved_on`. Living sites without publishable versions record the reviewed page set and a re-review trigger. Terms with era history additionally record `introduced_in`, `deprecated_in`, `renamed_to`, and `historical_scope` in [Cross-System Term Cases](conflict-cases.md).

package/design-terminology/token-semantics.md

@@ -0,0 +1,90 @@
+---
+type: Domain Guide
+title: Token Semantics And Resolution
+description: Compare semantic roles, references, groups, resolver contexts, and runtime values without treating their names as interchangeable.
+domain: design-terminology
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-09-21
+---
+
+# Token Semantics And Resolution
+
+Primary role: source-specific token terminology comparison.
+
+## Repository Boundary
+
+This page compares vocabulary and the decisions obscured by ambiguous token names. It imports no token values, themes, or compiler behavior. [Consumer Reference](../consumer-reference/index.md) owns interchange/evidence infrastructure; consumer profiles own their values and implementation. Layout's token boundary remains unchanged.
+
+Canonical term and relation records live in [Cross-System Term Cases](conflict-cases.md). This guide explains their use; it does not establish a second term registry.
+
+## Reusable Method
+
+When a handoff says “alias,” “semantic,” or “theme,” identify whether it refers to design intent, a reference edge, organization, context selection, or a runtime representation. Record the named source before choosing an equivalence relation. Inspect the exported structure separately from the visual result.
+
+### Sources And Distinctions
+
+| Source | Source-backed distinction | Question for a handoff |
+| --- | --- | --- |
+| [Fluent 2 tokens](https://fluent2.microsoft.design/design-tokens) | Global tokens hold context-independent values; alias tokens add semantic meaning. | Does “alias” name a semantic layer in this system? |
+| [DTCG Format 2025.10](https://www.designtokens.org/tr/2025.10/format/) | A token value may reference another token; groups organize records. | Does “alias” name a reference relationship in an interchange document? |
+| [Carbon color overview](https://carbondesignsystem.com/elements/color/overview/) | Color tokens preserve roles across themes while assigned values can change. | Is the role stable across every theme being compared? |
+| [Carbon color usage](https://carbondesignsystem.com/elements/color/usage/) | Contextual color tokens depend on the layer where they are used. | Is the surrounding layer part of value resolution? |
+| [DTCG Resolver 2025.10](https://www.designtokens.org/tr/2025.10/resolver/) | Modifiers conditionally select sources through contexts; ordered resolution determines the resulting token set. | Where are the selected contexts and conflict order recorded? |
+| [CSS Custom Properties Level 1](https://www.w3.org/TR/css-variables-1/) | Custom properties participate in CSS runtime value substitution and the cascade. | Which original semantics and metadata remain after translation? |
+
+All six source surfaces were inspected on 2026-09-21. DTCG 2025.10 modules are Community Group reports, not W3C Recommendations. The Fluent and Carbon pages are dated system documentation, not guarantees about every package release.
+
+### Alias Is Not One Decision
+
+The recorded `fluent.alias-token` / `dtcg.alias` relation is `partial_overlap`. A semantic token may use a reference, but a reference edge does not itself prove a semantic role. A reference between two raw values illustrates the non-semantic region; a consumer's exported semantic value may be flattened and no longer retain its reference edge.
+
+The `fluent.alias-token` / `carbon.color-token` relation is also scoped overlap. Both can express role-oriented color decisions, but their vocabularies and non-color coverage differ. This is not permission to rename one system's tokens after another's or assert that their role sets are identical.
+
+### Grouping Is Not Context Selection
+
+The recorded `dtcg.resolver-modifier` / `dtcg.group` relation is `not_comparable` for organization-versus-resolution. Ask where a context is selected, where sources are ordered, and where a group is merely a path. A directory or group named `dark` does not independently explain how a consumer chooses dark appearance.
+
+This distinction also prevents confusing a token system's theme with a user's complete preference state. A selected theme does not determine text scaling, reduced motion, or every platform accessibility preference; those adaptation decisions belong to [Platform Guides](../platform-guides/preferences-and-accessibility.md).
+
+### Worked Handoff: Same Color, Different Meaning
+
+Two consumer roles happen to resolve to the same displayed color in one theme. Preserve the roles separately when their purposes differ. Equality of an output value is evidence of that output only; it does not justify merging source concepts.
+
+| Handoff field | Proposed content | Why it matters |
+| --- | --- | --- |
+| Source term | Source-qualified identifier and locator | Keeps a role name attached to its own vocabulary. |
+| Comparison scope | The particular translation being considered | Prevents a local mapping from becoming universal equivalence. |
+| Context | Theme, layer, or resolver inputs actually selected | Makes value resolution reproducible. |
+| Output representation | Target format and adapter version | Separates serialization from semantic intent. |
+| Retained/lost information | Role, reference edges, metadata, and unsupported structures | Exposes lossy translation. |
+| Verification | Structural check plus rendered state evidence if appearance is claimed | Avoids treating a valid file as a usable component. |
+
+The fields are a local analysis aid. They do not expand this repository's closed token adapter or admit arbitrary DTCG features into existing schemas.
+
+## Opinionated Guidance
+
+Prefer source-qualified names in cross-system discussions. Before merging tokens, compare responsibilities across contexts, not just matching values in a screenshot. Keep compiler inputs explicit enough that another consumer can explain how an output was obtained.
+
+## Platform-Specific Guidance
+
+An exported custom property, native resource, or tool variable can consume translated design information without preserving the full source contract. The concrete adapter owns unit conversion, missing features, and runtime context. Comparative vocabulary cannot certify that adapter.
+
+## Unsupported Absolutes
+
+A reference is not proof of semantic intent. A group is not automatically a theme selector. The same value is not the same role. A valid DTCG document is not a declaration that StyleGallery supports every feature in that document.
+
+## Verification Contract
+
+Recheck both source locators for each relied-on relation and record the scope and direction. Probe a matching value with different roles, a changed theme, a contextual layer change, and a flattened export. Inspect the actual adapter if making a round-trip or runtime claim.
+
+These are proposed checks. Only source readings and Markdown record consistency are claimed here; no token pipeline or product rendering was executed. Re-review when a vocabulary, module version, or adapter contract changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis; no source token values or upstream expression are copied. Terminology reliance: `fluent.alias-token`, `fluent.global-token`, `carbon.color-token`, `dtcg.alias`, `dtcg.token`, `dtcg.group`, `dtcg.resolver-modifier`, and `css.custom-property`. Relations used: `partial_overlap`, `implementation_representation`, and `not_comparable`. Named sources were rechecked 2026-09-21; local relations remain author judgments, not independent semantic approval. `consumer_reference: not_applicable` because no consumer profile or adapter record is selected.
+
+## IA Navigation
+
+Parent: [Design Terminology](index.md).
+Next: [Typography Semantics](typography-semantics.md).