stylegallery 0.1.3 → 0.1.6

package/design-engineering/consumer-migration-readiness.md

@@ -0,0 +1,124 @@
+---
+type: Domain Guide
+title: Consumer Migration Readiness
+description: Evidence-bound method for deciding whether a consumer migration preserves its declared behavior.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Consumer Migration Readiness
+
+Use this method only when an existing consumer is being migrated and its behavior must remain demonstrably equivalent. It turns migration intent into a consumer-owned conformance record and executable page evidence without making StyleGallery the owner of product code or visual values.
+
+## Repository Boundary
+
+The consuming repository owns its conformance record, source paths, runtime scenarios, evidence artifacts, adoption mappings, deviations, debt, and approval decision. StyleGallery supplies an experimental method, closed schemas, and validators. It does not certify the consumer, define product defaults, or turn a local adoption into a shared standard.
+
+Ordinary implementation handoffs remain unchanged and may use `Consumer reference: not_applicable` with a sentence reason. Only a migration handoff that elects this method adds `Consumer migration conformance: declared` and one normalized repository-relative JSON record path.
+
+## Reusable Method
+
+1. Inventory the old and new consumer behavior before changing implementation.
+2. Create one consumer-local record using the [consumer conformance schema](../consumer-reference/schema/consumer-conformance-record.schema.json).
+3. Explicitly classify every migration dimension as `applicable` with runtime scenario IDs or `not_applicable` with a sentence reason.
+4. Map each adopted StyleGallery source anchor to a concrete local component, selector, or module plus its local decision, deviations, debt, and scenario IDs.
+5. Execute the named unit, integration, or browser command. A prose checklist, screenshot, or generated fixture alone is not runtime proof.
+6. For page work, create one source-bound evidence session, execute the browser matrix, finalize the manifest, and validate the completed session against the conformance record.
+7. Review the [consumer migration evidence gate](../quality/gates/consumer-migration-evidence.md). Block migration when required evidence is missing, stale, cross-session, source-drifted, or failed.
+
+## Migration Dimension Contract
+
+The record must classify exactly these thirteen dimensions:
+
+| Dimension | What the consumer must preserve or explicitly exclude |
+| --- | --- |
+| `behavior_inventory` | The complete named behavior surface being migrated. |
+| `route_parity` | Routes, entry points, and navigation outcomes. |
+| `field_parity` | Accepted fields, output fields, validation, and serialization. |
+| `action_parity` | User and programmatic actions plus observable outcomes. |
+| `state_transitions` | Allowed state changes, guards, and terminal states. |
+| `contract_precedence` | Which rule wins when old, new, and local contracts conflict. |
+| `direct_mutation` | Effects of direct state or model mutation. |
+| `indirect_mutation` | Effects reached through events, adapters, or dependent modules. |
+| `persistence_round_trip` | Save, reload, serialization, and restoration behavior. |
+| `reset_boundary` | What reset clears, preserves, and returns to defaults. |
+| `exact_time_boundary` | Inclusive or exclusive timing behavior at exact boundaries. |
+| `defaults_tri_state_mapping` | Mapping among absent, explicit default, and explicit non-default values. |
+| `atomic_batch_behavior` | All-or-nothing behavior, ordering, and rollback for grouped changes. |
+
+An `applicable` dimension references at least one declared runtime scenario. A `not_applicable` dimension includes a concrete sentence reason. Silence is never a classification.
+
+## Opinionated Guidance
+
+- Prefer the smallest scenario that proves an observable outcome over broad internal coverage.
+- Pin both the consumer revision and each adopted StyleGallery revision; a branch name or moving tag is insufficient.
+- Record local deviations honestly. Conformance means the declared boundary is internally consistent, not that every StyleGallery suggestion was copied.
+- Treat expired debt as a decision trigger. Do not rewrite evidence timestamps to make a stale review appear current.
+- Keep page evidence tied to the exact source inventory and browser run that produced it.
+
+## Platform-Specific Guidance
+
+Browser page evidence uses the required viewport set `320`, `375`, `768`, `1024`, and `1440` pixels plus the declared container, content, state, overlay, and page-scale cases. Platform-specific raster identity may supplement computed assertions, but it cannot replace semantic, focus, overflow, or contrast checks and cannot imply cross-platform pixel equivalence.
+
+## Unsupported Absolutes
+
+Passing this method does not prove complete accessibility, product correctness, usability, visual quality, independent adoption, cross-browser equivalence, or owner approval. Synthetic fixtures prove validator behavior only. A pinned revision proves source identity, not source authority or consumer suitability.
+
+## Verification Contract
+
+The minimum verification chain is:
+
+```txt
+consumer source inventory
+  -> conformance record with 13 explicit classifications
+  -> executable scenarios with zero exit and result artifacts
+  -> adoption mappings with pinned StyleGallery anchors
+  -> optional source-bound page-evidence manifest
+  -> consumer migration evidence gate decision
+```
+
+Validate a record without applicable page evidence directly:
+
+```sh
+node <stylegallery-root>/scripts/validate-consumer-conformance.mjs \
+  --root <consumer-root> \
+  --record <record.json> \
+  --json
+```
+
+Unit and integration scenarios declare a shell-free Node `argv` array beginning with `node`. The validator checks out the exact consumer revision in an isolated worktree, enables Node's permission model without child-process, worker, native-addon, or WASI grants, supplies only `PATH`, `CI=1`, deterministic locale flags, `STYLEGALLERY_RESULT_ARTIFACT`, and `STYLEGALLERY_RUNTIME_CONTEXT`, and requires the command to create that result artifact during the run. Commands may read and write only inside the isolated checkout, must be self-contained at the pinned revision, and cannot override the governed permission flags. The validator does not reuse the caller's `node_modules` or forward caller secrets.
+
+When `page_evidence.status` is `applicable`, use one artifact root for the complete lifecycle. Start the source-bound session before the browser run, write each runner result beneath that artifact root, finalize the session, and then validate the record against the completed artifacts:
+
+```sh
+node <stylegallery-root>/scripts/create-page-evidence-session.mjs \
+  --root <consumer-root> \
+  --record <record.json> \
+  --artifact-root <artifact-root> \
+  --json
+
+node <stylegallery-root>/scripts/finalize-page-evidence.mjs \
+  --root <consumer-root> \
+  --artifact-root <artifact-root> \
+  --runner-result <runner-result.json> \
+  --review-by <RFC3339-date-time> \
+  --json
+
+node <stylegallery-root>/scripts/validate-consumer-conformance.mjs \
+  --root <consumer-root> \
+  --record <record.json> \
+  --artifact-root <artifact-root> \
+  --json
+```
+
+`<record.json>` resolves from `<consumer-root>`, and each `<runner-result.json>` resolves from `<artifact-root>`. The completed manifest must match the consumer repository, revision, relevant source set, browser scenario set, run/session identities, and source digests. The StyleGallery checkout used for validation must contain every pinned StyleGallery revision; a shallow checkout that omits a historical pin fails closed. See [Consumer Migration Evidence](../quality/evidence/consumer-migration.md) for what each channel can and cannot support.
+
+## Source, License, And Attribution
+
+This is a StyleGallery-local method. It has no external source snapshot and intentionally declares `provenance_kind: local` rather than upstream repository metadata.
+
+## IA Navigation
+
+Parent: [Design Engineering](index.md).
+Next: [Consumer Migration Evidence Gate](../quality/gates/consumer-migration-evidence.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/interface-craft.md

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

package/design-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/concept-families.md

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