stylegallery 0.1.3 → 0.1.4

package/motion/vocabulary.md

@@ -0,0 +1,82 @@
+---
+type: Domain Guide
+title: Motion Vocabulary
+description: Evidence-bounded method and reference for naming observable interface motion.
+domain: motion
+lifecycle: experimental
+source_repository: https://github.com/emilkowalski/skills
+source_path: skills/animation-vocabulary/SKILL.md
+source_revision: 220e8607c90b17337d210125777b7b695f26c221
+---
+
+# Motion Vocabulary
+
+Primary role: motion terminology reference.
+
+## Repository Boundary
+
+This page helps a reader name observed motion. It does not prescribe implementation, authorize motion in reusable Layout CSS, or make a product-quality judgment.
+
+The terms are implementation-neutral. A framework, operating-system behavior, or branded example may illustrate a term only when clearly labeled and separately verified.
+
+## Reusable Method
+
+1. Record what changes: presence, position, scale, shape, state, scroll relationship, or feedback.
+2. Record what coordinates the change: time, sequence, input, velocity, or viewport progress.
+3. Compare the observation with the closest term families below.
+4. Return one exact term only when the observed cues distinguish it.
+5. When multiple terms remain plausible, return ordered candidates and state the missing observation.
+6. When nothing matches, return `unknown`; do not invent a canonical winner.
+
+## Term Families
+
+| Term | Observed cues | Distinguish from | Implementation-neutral meaning | Evidence boundary |
+| --- | --- | --- | --- | --- |
+| Fade | Visibility changes without a necessary spatial path. | Reveal | A gradual visibility change. | Does not imply opacity is the implementation. |
+| Slide | The element follows a directional path into, out of, or within a region. | Shared-element transition | A positional transition without necessarily preserving identity across views. | Direction and clipping must be observed. |
+| Scale transition | Apparent size changes around an origin. | Morph | Size changes while the element's basic identity remains stable. | Does not establish the correct origin or amount. |
+| Reveal | A boundary progressively exposes content. | Fade | Visibility is controlled by an advancing edge, mask, or equivalent boundary. | The masking mechanism may be unknown. |
+| Stagger | Similar elements begin related changes at distinct offsets. | Orchestration | A repeated sequence pattern, usually across peers. | The offset value is product-specific. |
+| Orchestration | Several motion events form one coordinated sequence. | Stagger | Coordination may include different elements, jobs, and timings. | Intent must be documented, not inferred from timing alone. |
+| Crossfade | One state loses visibility while another gains it in the same region. | Morph | Identity is exchanged rather than geometrically transformed. | Overlap and source order need inspection. |
+| Shared-element transition | A recognizable element appears to retain identity between states or views. | Layout animation | Continuity connects a source representation with a destination representation. | Identity continuity is a perception claim requiring rendered evidence. |
+| Layout animation | A spatial change is visually interpolated instead of appearing instantly. | Shared-element transition | Position or size changes within the layout state of an element. | Does not endorse animating layout-triggering CSS properties. |
+| Scroll-driven motion | Progress corresponds to scroll progress. | Scroll reveal | The scroll position continuously controls progress rather than merely triggering entry. | Browser and input behavior require local testing. |
+| Parallax | Layers appear to travel at different rates during a shared movement. | Ordinary scroll | Relative speed creates a depth cue. | Depth, comfort, and reduced-motion outcomes are not guaranteed. |
+| Spring motion | Response is modeled as a target-seeking dynamic system rather than a fixed timeline. | Bounce | A spring may settle without visible overshoot. | Parameters and perceived duration remain implementation-specific. |
+| Bounce | Motion overshoots or reverses before settling. | Spring motion | Visible overshoot is the defining cue, regardless of implementation. | Playfulness and appropriateness are product judgments. |
+| Interruptible motion | New input redirects a change from its current presented state. | Restarted animation | Continuity is maintained when the target changes mid-flight. | Requires interaction evidence, not source inspection alone. |
+| Rubber-band response | Movement continues beyond a boundary with increasing resistance, then returns. | Bounce | Resistance is tied to boundary overshoot and direct manipulation. | Platform examples are not a universal physics contract. |
+| Jank | Motion visibly misses expected visual continuity. | Intentional stepped motion | The discontinuity is unintended and associated with delivery or computation limits. | Frame or performance evidence is needed to attribute cause. |
+
+## Opinionated Guidance
+
+The family ordering favors what a reader can observe before implementation details. It is useful for retrieval, but it is not a complete ontology. Add a term only after a reader task demonstrates that existing terms and aliases cannot express the distinction.
+
+## Platform-Specific Guidance
+
+Names tied to iOS, macOS, a browser API, Motion, Framer Motion, React, or a component library are examples or implementation facets. Keep the cross-platform term primary and label the platform context separately.
+
+## Unsupported Absolutes
+
+- Do not call this vocabulary authoritative outside StyleGallery.
+- Do not force the nearest term when the observation is incomplete.
+- Do not attach universal FPS, GPU, duration, easing, or reduced-motion rules to a definition.
+- Do not infer implementation technology from rendered appearance alone.
+
+## Verification Contract
+
+A vocabulary lookup should exercise exact, ambiguous, and unknown cases. Pass requires one justified term, an ordered candidate set with a stated distinction, or `unknown`; invented winners fail. A new term also requires a findability task showing the current route cannot reach an adequate term within two hops.
+
+## Source, License, And Attribution
+
+- Upstream inspiration: [animation-vocabulary/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/animation-vocabulary/SKILL.md)
+- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
+- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
+- Reuse form: independent method rewrite; upstream prose, tables, code, examples, and distinctive ordering were not retained.
+- Evidence boundary: the upstream artifact records practitioner terminology; it does not prove local performance, accessibility, usability, or quality.
+
+## IA Navigation
+
+Parent: [Motion](index.md).
+Next: [Motion Review Workflow](review-workflow.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylegallery",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A governed gallery of portable interface knowledge with deterministic CLIs and read-only MCP servers.",
   "type": "module",
   "homepage": "https://github.com/changeroa/StyleGallery#readme",
@@ -47,11 +47,27 @@
     "consumer-reference/agent-native/v2/schema/material-record.schema.json",
     "consumer-reference/contract.md",
     "consumer-reference/index.md",
+    "design-engineering/consumer-migration-readiness.md",
     "design-engineering/index.md",
+    "design-engineering/interface-craft.md",
     "design-engineering/reference-profiles/governed-local/editorial/profile.json",
     "design-engineering/reference-profiles/governed-local/index.md",
     "design-engineering/reference-profiles/index.md",
+    "design-terminology/concept-families.md",
+    "design-terminology/conflict-cases.md",
+    "design-terminology/index.md",
+    "design-terminology/relation-types.md",
+    "design-terminology/source-kinds.md",
+    "design-terminology/source-vocabularies.md",
+    "game-ui/classification.md",
     "game-ui/index.md",
+    "game-ui/reference-record.md",
+    "game-ui/screen-hierarchy.md",
+    "game-ui/unity/architecture.md",
+    "game-ui/unity/cli-loop.md",
+    "game-ui/unity/org-wiki.md",
+    "game-ui/unity/repository-map.md",
+    "game-ui/unity/ui-systems.md",
     "guides/decision-tree.md",
     "guides/documentation-mode-taxonomy.md",
     "guides/layout-brief.md",
@@ -61,6 +77,9 @@
     "layout/index.md",
     "log.md",
     "motion/index.md",
+    "motion/practice-reference.md",
+    "motion/review-workflow.md",
+    "motion/vocabulary.md",
     "patterns/centering/center.md",
     "patterns/centering/index.md",
     "patterns/centering/super-center.md",
@@ -117,7 +136,9 @@
     "patterns/viewport-shell/scroll-body-shell.md",
     "patterns/viewport-shell/sticky-footer.md",
     "patterns/viewport-shell/sticky-header.md",
+    "platform-guides/apple-interaction.md",
     "platform-guides/index.md",
+    "quality/claim-records/design-terminology-domain-scope.md",
     "quality/claim-records/index.md",
     "quality/claim-records/samples.md",
     "quality/claim-records/stylegallery-multidomain-scope.md",

package/platform-guides/apple-interaction.md

@@ -0,0 +1,89 @@
+---
+type: Domain Guide
+title: Apple Interaction As A Comparative Reference
+description: Bounded comparison of Apple interaction themes with explicit web-adaptation and provenance limits.
+domain: platform-guides
+lifecycle: experimental
+source_repository: https://github.com/emilkowalski/skills
+source_path: skills/apple-design/SKILL.md
+source_revision: 220e8607c90b17337d210125777b7b695f26c221
+platform: Apple platforms
+platform_version: verify-current
+reviewed_on: 2026-07-11
+---
+
+# Apple Interaction As A Comparative Reference
+
+Primary role: platform comparison guide.
+
+## Repository Boundary
+
+This page uses selected Apple-platform interaction themes as comparative questions. It does not reproduce Apple guidance, establish affiliation, prescribe imitation, or treat a native implementation value as valid for the web.
+
+Current official Apple documentation is required for Apple-specific claims. Current web standards and browser documentation are required for web adaptation. Local rendered, device, accessibility, and performance evidence is required for product conclusions.
+
+## Reusable Method
+
+For each proposed comparison:
+
+1. Name the user task, platform, OS/API version, input method, and state transition.
+2. Describe the observable behavior without branded terminology.
+3. Identify the platform convention and its current official source.
+4. Separate the reusable interaction question from native implementation details.
+5. Define the web adaptation, including unavailable or materially different capabilities.
+6. Verify the adapted behavior on its real surface and record what remains unproven.
+
+## Comparative Questions
+
+| Theme | Question to investigate | Required evidence | Boundary |
+| --- | --- | --- | --- |
+| Response | Does feedback begin close enough to input to preserve cause and effect? | Interaction recording and input-state trace | No universal latency value is implied. |
+| Direct manipulation | Does the presented state follow, cancel, and resume from user input coherently? | Repeated drag/reversal test on target input modes | One-to-one tracking is not always required. |
+| Interruption | Can new input redirect a transition without jumping or locking control? | Mid-transition retarget and reversal evidence | Springs are one option, not a requirement. |
+| Velocity continuity | Does release-to-settle behavior avoid an observable seam? | Gesture and presented-state recording | Native velocity APIs and web libraries differ. |
+| Spatial consistency | Can the reader understand where content came from and where it returns? | Before/intermediate/after render plus source/focus order | Visual path cannot override semantic order. |
+| Recoverability | Can a user cancel, reverse, undo, or safely recover where the task requires it? | Task and error-path evidence | Confirmation is not universally preferable to undo. |
+| Wayfinding | Can the interface answer location, available destinations, contents, and exit? | Navigation task evidence | Familiar platform placement may not transfer across products. |
+| Soft boundaries | Would progressive resistance communicate a limit better than a hard stop? | Comparative prototype and input/device evidence | The resistance curve is not standardized across platforms. |
+| Multimodal feedback | Do visual, audio, and haptic cues share a clear cause and useful purpose? | Device timing and accessibility evidence | Web haptics/audio are not native equivalents and may be unavailable. |
+| Adaptive presentation | Does the interface remain usable across text size, contrast, transparency, motion preference, input, and viewport changes? | Relevant preference and constraint matrix | A platform feature name does not prove web accessibility. |
+
+## Opinionated Guidance
+
+Momentum-aware settling, source-anchored transitions, progressive boundary resistance, and carefully coordinated feedback can be useful hypotheses for directly manipulated interfaces. Translucent materials, system typography, haptics, and visual delight are product and platform choices outside reusable Layout pattern CSS.
+
+## Platform-Specific Guidance
+
+- iOS/macOS gesture physics, native spring APIs, Dynamic Type, system materials, haptics, and SwiftUI/UIKit behavior must be labeled as Apple-specific.
+- Any value described as shipped by Apple requires a direct, current official source and version.
+- A web mapping must identify browser support, input differences, accessibility behavior, and fallback semantics.
+- `backdrop-filter`, the Vibration API, web media queries, and JavaScript animation libraries are not equivalents merely because they can approximate one visible effect.
+
+## Unsupported Absolutes
+
+- Do not call an upstream formula or parameter an exact Apple implementation without a primary official source.
+- Do not require direct manipulation to track one-to-one in every context.
+- Do not require audio and haptic events on one exact frame as a universal web contract.
+- Do not claim translucent chrome is generally superior to opaque structure.
+- Do not adopt a single spring configuration as a safe default across tasks.
+- Do not import a named set of Apple principles as StyleGallery's shared principles.
+- Do not infer native behavior, platform affiliation, or accessibility from visual similarity.
+
+## Verification Contract
+
+Record the official platform source and version, the web-standard or browser source for adaptation, the exact target devices and input modes, relevant user preferences, and the observed pass/fail behavior. Use a real interactive prototype for interaction claims. State explicitly when native behavior cannot be reproduced or verified on the web.
+
+Review this page when Apple changes the cited convention, the web platform changes the adaptation surface, the source revision changes, or local testing contradicts the guidance. `platform_version: verify-current` prevents this experimental page from masquerading as a version-pinned platform contract.
+
+## Source, License, And Attribution
+
+- Upstream inspiration: [apple-design/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/apple-design/SKILL.md)
+- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
+- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
+- Reuse form: independent method rewrite; upstream prose, tables, code, exact-value sequences, Apple/WWDC-derived expression, and quotations were not retained.
+- Evidence boundary: the upstream artifact is a practitioner interpretation and provenance record, not an official Apple or web-platform source.
+
+## IA Navigation
+
+Parent: [Platform Guides](index.md).
+Next: [Layout](../layout/index.md).

package/quality/claim-records/design-terminology-domain-scope.md

@@ -0,0 +1,57 @@
+---
+type: Decision Record
+title: Design Terminology Domain Scope Decision
+description: Decision to add Design Terminology as the sixth StyleGallery domain, with four placement alternatives compared and the domain's independent decision surface defined.
+---
+
+# Design Terminology Domain Scope Decision
+
+## Decision
+
+StyleGallery adds Design Terminology as a sixth explicit domain. The domain's independent decision surface, in one sentence:
+
+> Design Terminology binds design terms to their named sources, classifies them by source kind and concept family, and judges typed semantic relations and conflicts between terms from different sources.
+
+Concretely, this domain and only this domain decides: which named source a term belongs to, what kind of source that is, which concept family the term serves, and which typed relation with which boundary holds between two terms. The five existing domains keep their boundaries unchanged.
+
+The domain does not own: StyleGallery's internal canonical naming (the [Controlled Vocabulary](../../guides/vocabulary.md) keeps it), actual UI behavior or implementation methods, accessibility rules, platform-specific interaction adaptation (Platform Guides keeps it), and any universal prescription about which term is generally better.
+
+## Alternatives Compared
+
+| Candidate | Strength | Weakness | Disposition |
+| --- | --- | --- | --- |
+| Extend `guides/vocabulary.md` | Close to existing terminology stewardship | Mixes StyleGallery's internal canonical word set with external systems' term meanings on one authoritative page; the vocabulary would then compete with external definitions it is supposed to route around | Rejected: internal canonical control and external comparative meaning are different decisions with different evidence and freshness rules |
+| `platform-guides/terminology/` | Reuses an existing comparative domain | Tools (Figma), specifications (DTCG Format), and pattern libraries are not platforms; hosting them under Platform Guides would erase the source-kind axis this domain depends on | Rejected: source kind, not platform comparison, is the primary axis |
+| Shared non-domain `terminology/` | Easy to reference across domains | No named owner, lifecycle, validator, or review authority; consumer-reference already carries the no-second-authority rule for shared infrastructure | Rejected: ungoverned placement reproduces the silent-collision problem the content exists to solve |
+| New sixth domain `design-terminology/` | Owns an independent lifecycle, review owner, validator coverage, and experimental-to-stable promotion path | Widest infrastructure blast radius: manifest, validators, schemas, sealed material cardinality, and package inventory all change | Adopted, with the conditions below |
+
+Adoption conditions: content starts `experimental`; a machine-readable term/concept/source/relation registry is a promotion prerequisite; every external meaning claim carries an official source and review date; typed relations replace plain term-pair tables.
+
+## Naming
+
+Terminology, not topology: topology suggests a formal relation graph or ontology that this domain does not yet provide; v0.1 compares definitions, usage scope, and conflicts. Terminology, not vocabulary: the [Controlled Vocabulary](../../guides/vocabulary.md) owns StyleGallery's canonical internal word set; this domain compares the meanings and relations of terms used by external named sources.
+
+## Context
+
+Named design systems, platform guidelines, specifications, and design tools define overlapping terms differently, and handoffs between them fail on silent term collisions. Recording these definitions inside Layout would violate the pattern boundary; the controlled vocabulary page is for internal canonical terms; Platform Guides compares interaction conventions rather than terminology.
+
+## Warrant
+
+A separate domain lets terminology comparison name its own evidence boundary: cited official sources, dated structural readings, typed relations with boundaries, and working translations that never override repository policy.
+
+## Consequences
+
+- `design-terminology/**` begins `experimental` with a named review owner and validator coverage.
+- The domain manifest, root routes, quality scope, vocabulary domain list, and governance rows record six domains; Consumer Reference remains shared infrastructure and still cannot add a domain row.
+- Record consistency is machine-enforced from v0.1 by `scripts/validate-design-terminology.mjs` (closed relation types, recorded terms on both sides, non-trivial boundaries, contradiction pairs, date and status shape, no orphan terms). Human semantic review is required at stable promotion only, per the repository promotion rules; it is not a merge gate for `experimental` content.
+- Domain identity and cardinality are currently sealed in multiple surfaces (closed schema enums, identity sets, discover cardinality, package inventory, snapshot tests) requiring synchronized manual edits when a domain is added. This is recorded technical debt, not tamper evidence alone: one author changing all copies in one commit weakens duplication as independent evidence while keeping drift risk. Revisit triggers: a seventh domain id is added, manual-change sites exceed twelve, a cardinality drift incident occurs, or registry generation changes. Target structure when triggered: one canonical domain registry generating enums, lists, and package inventory, with an independently reviewed sealed digest as the tamper check. Named review owner for this debt: the Design Terminology domain owner until a governance owner is designated.
+- Term relations recorded by the domain are working judgments, not repository policy for other domains.
+
+## Boundary Or Limitation
+
+This decision establishes ownership and governance only. It does not verify that any cited external vocabulary is current beyond each record's review date, does not make any external definition authoritative for product implementation, and does not claim the typed relation model is complete beyond the recorded cases.
+
+## IA Navigation
+
+Parent: [Claim Records](index.md) in [Quality Gates](../index.md).
+Next: [StyleGallery Domains](../../DOMAINS.md) for the active domain manifest.

package/quality/evidence/executable-evidence.md

@@ -32,7 +32,7 @@ Executable evidence identifies which claims are machine-enforced, which are only
 | Markdown links resolve inside the repository. | `scripts/validate-links.mjs` | `node scripts/validate-links.mjs --json` | All checked Markdown links resolve to local files or are intentionally external or anchors. | A local link that escapes the repository or points at a missing file must fail. | Proves link targets exist, not that the target content supports a claim. |
 | Catalog and generated pattern indexes match the pattern data source. | `scripts/validate-catalog.mjs` | `node scripts/validate-catalog.mjs --json` | `CATALOG.md`, category indexes, and expected pattern files match `scripts/pattern-data.mjs`. | Missing, unexpected, or unlisted pattern files must fail. | Proves catalog consistency, not pattern usefulness. |
 | Governance, lifecycle, generated-file, ownership, and stale-content policy remain discoverable and CI-enforced. | `scripts/validate-governance.mjs` and `scripts/test-validate-governance.mjs` | `node scripts/validate-governance.mjs --json`; `node scripts/test-validate-governance.mjs --json` | `GOVERNANCE.md`, `.github/CODEOWNERS`, generated warnings, generated metadata, root link targets, lifecycle states, `scheduled_stale_audit` metadata, and CI wiring are present. | Missing governance file, generated warning, generated metadata, CODEOWNERS coverage, or stale policy fixtures must fail. Preferred governance prose and link labels emit warnings. | Proves governance policy is present and linked, not that CODEOWNERS users have verified repository write access. |
-| Domain topology, metadata, provenance, scope boundaries, and root routes remain enforced. | `scripts/validate-domains.mjs` and `scripts/test-validate-domains.mjs` | `node scripts/validate-domains.mjs --json`; `node scripts/test-validate-domains.mjs` | Five governed domains and their declared leaves are reachable and attributed. | Domain metadata, immutable provenance, scope boundaries, and root-route fixtures must fail. | A full SHA proves content identity syntax, not publisher authenticity, source ownership, or local quality. |
+| Domain topology, metadata, provenance, scope boundaries, and root routes remain enforced. | `scripts/validate-domains.mjs` and `scripts/test-validate-domains.mjs` | `node scripts/validate-domains.mjs --json`; `node scripts/test-validate-domains.mjs` | Six governed domains and their declared leaves are reachable and attributed. | Domain metadata, immutable provenance, scope boundaries, and root-route fixtures must fail. | A full SHA proves content identity syntax, not publisher authenticity, source ownership, or local quality. |
 | Consumer-reference handoffs, schema/runtime parity, repository-local record paths, lifecycle separation, ownership truth, and dependency direction remain enforced. | `scripts/validate-consumer-reference.mjs` and `scripts/test-validate-consumer-reference.mjs` | `node scripts/validate-consumer-reference.mjs --json`; `node scripts/test-validate-consumer-reference.mjs --json` | Declared and reasoned-not-applicable fixtures exit zero, every shipped schema rule has accepted/rejected parity coverage, all repository handoffs declare applicability, fixtures remain related, and ownership discloses placeholder single-account review. | Unknown top-level or nested properties, invalid schema fields, missing handoff or reason, stable with ended support, boolean independence, unresolved/absolute/scheme/network/parent/item-or-record-symlink/non-JSON paths, scaffold success, sixth-domain classification, literal or supported computed reverse imports, and repository handoff omissions must fail with named finding codes and non-zero child exit. | Proves receiver-contract consistency, bounded static dependency detection, and path containment, not general JavaScript data-flow safety, visual quality, independent adoption, verified owner permissions, or consumer implementation conformance. |
 | Promotion governance remains a closed JSON-only, invariant-scoped, deferred example contract. | `scripts/validate-promotion-rfc.mjs` and `scripts/test-validate-promotion-rfc.mjs` | `node scripts/validate-promotion-rfc.mjs --json`; `node scripts/test-validate-promotion-rfc.mjs --json` | The manifest-declared policy and two canonical examples pass with deferred decisions, zero attestations, exact support commitment, and no promotion claim. | Manifest-declared invalid fixtures plus forged, unregistered, duplicate, path, extension, support, evidence, canonical-drift, and lifecycle mutations exit non-zero with named findings. | Synthetic validation does not authenticate adoption, organizations, owners, support capacity, provenance, or a promotion decision; the current canonical inventory supplies no real independent consumers. |
 | Portable token source and generated CSS agree through the pinned restricted adapter. | `scripts/build-reference-artifacts.mjs`, `scripts/validate-reference-artifacts.mjs`, and `scripts/test-reference-adapters.mjs` | Build with `--fail-on-warning`, validate the generated manifest, then run the adapter fixture harness. | Dimension, color, duration, tested border values, and whole-token curly aliases emit nonzero CSS declarations with matching counts and hashes; output references remain CSS variable references. | `$extends`, JSON Pointer, resolver/modifier/theme documents, unknown reserved fields, non-string descriptions, adapter-unsafe path segments, untested type/unit, partial/dangling/cyclic/type-mismatched aliases, missing output, zero count, warning, scaffold/unknown manifest fields, missing/duplicate declaration, object sentinel, unresolved or forged value, and count drift must fail with named findings and non-zero child exit. | Proves the pinned adapter preserves this tested subset and that committed artifacts independently rebuild from their canonical source, not that tokens are product defaults, portable beyond the tested adapters, visually suitable, or adopted by a consumer. |

package/quality/index.md

@@ -1,6 +1,6 @@
 # Quality Gates
 
-`quality/` is shared StyleGallery infrastructure for deciding whether Layout, Motion, Design Engineering, Game UI, and Platform Guides claims are admissible.
+`quality/` is shared StyleGallery infrastructure for deciding whether Layout, Motion, Design Engineering, Game UI, Platform Guides, and Design Terminology claims are admissible.
 
 This shared layer does not make the repository a visual design system. Layout pattern files still own spatial structure only; domain guidance cannot bypass these gates. Quality gates explain how claims are framed, what evidence can support them, and when review or debt is required.
 
@@ -48,7 +48,7 @@ Use this script for lightweight tree tests:
 | Name an observed motion effect. | [README](../README.md) | [Motion Vocabulary](../motion/vocabulary.md) | The first selected route is Motion and the term reference is reached within two hops. |
 | Review product-level interface craft. | [README](../README.md) | [Interface Craft Decisions](../design-engineering/interface-craft.md) | The first selected route is Design Engineering and shared quality gates remain visible. |
 | Compare an Apple interaction convention. | [README](../README.md) | [Apple Interaction](../platform-guides/apple-interaction.md) | The first selected route is Platform Guides and source/version limits are reached within two hops. |
-| Declare whether a consumer reference applies. | [README](../README.md) | [Consumer Reference](../consumer-reference/index.md) | The handoff reaches the shared contract without classifying it as a sixth domain. |
+| Declare whether a consumer reference applies. | [README](../README.md) | [Consumer Reference](../consumer-reference/index.md) | The handoff reaches the shared contract without classifying it as a seventh domain. |
 | Prove a consumer migration preserves declared behavior. | [README](../README.md) | [Consumer Migration Readiness](../design-engineering/consumer-migration-readiness.md) | The reader reaches the Design Engineering method and its evidence gate within two hops. |
 | Find the authority route for uGUI, UI Toolkit, or NGUI. | [README](../README.md) | [Unity UI Systems](../game-ui/unity/ui-systems.md) | The first selected route is Game UI, and the system-specific source and version boundary is reached within three hops. |
 

package/scripts/agent-native/v2/material-admission.mjs

@@ -17,7 +17,7 @@ const MANIFEST_REF = "sg:manifest/material-admission-v2";
 const MATERIAL_REF_PATTERN = /^sg:material\/path-sha256-[a-f0-9]{64}$/;
 const MATERIAL_VERSION_PATTERN = /^sg:material\/path-sha256-[a-f0-9]{64}@sha256:[a-f0-9]{64}$/;
 const HASH_PATTERN = /^[a-f0-9]{64}$/;
-const DOMAINS = new Set(["layout", "motion", "design-engineering", "game-ui", "platform-guides", "shared"]);
+const DOMAINS = new Set(["layout", "motion", "design-engineering", "game-ui", "platform-guides", "design-terminology", "shared"]);
 const LIFECYCLES = new Set(["draft", "stable", "deprecated", "experimental", "generated"]);
 const RECORD_KEYS = new Set(["schema_version", "record_kind", "stable_ref", "version_id", "repository_path", "media_type", "source_sha256", "byte_length", "lifecycle", "domain"]);
 const MANIFEST_KEYS = new Set(["schema_version", "record_kind", "stable_ref", "version_id", "admission_policy_ref", "admission_policy_version_id", "materials"]);

package/scripts/agent-native/v2/material-identity.mjs

@@ -6,7 +6,7 @@ export const MATERIAL_STABLE_REF_KINDS = Object.freeze(["domain", "page", "patte
 const KIND_SET = new Set(MATERIAL_STABLE_REF_KINDS);
 const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PATH_ID = /^path-sha256-[a-f0-9]{64}$/;
-const DOMAIN_IDS = new Set(["layout", "motion", "design-engineering", "game-ui", "platform-guides"]);
+const DOMAIN_IDS = new Set(["layout", "motion", "design-engineering", "game-ui", "platform-guides", "design-terminology"]);
 const MATERIAL_ID = PATH_ID;
 
 export class MaterialIdentityError extends TypeError {
@@ -56,7 +56,7 @@ export function materialIdentityForRecord(record) {
   if (typeof repositoryPath !== "string") fail("material_record_identity_invalid", "record has no bound source path");
   let kind = "page";
   let id = `path-sha256-${sha256(Buffer.from(repositoryPath, "utf8"))}`;
-  const domainMatch = /^(layout|motion|design-engineering|game-ui|platform-guides)\/index\.md$/.exec(repositoryPath);
+  const domainMatch = /^(layout|motion|design-engineering|game-ui|platform-guides|design-terminology)\/index\.md$/.exec(repositoryPath);
   if (domainMatch) { kind = "domain"; id = domainMatch[1]; }
   else if (/^patterns\/[^/]+\/[^/]+\.md$/.test(repositoryPath)) kind = "pattern";
   return deepFreeze({

package/scripts/agent-native/v2/material-mcp-adapter.mjs

@@ -16,7 +16,7 @@ const manifestPath = path.join(repositoryRoot, "consumer-reference", "agent-nati
 const exposedNames = new Set(["material-context", "material-discover", "material-get", "material-search"]);
 const descriptions = Object.freeze({
   "material-context": "Build a deterministic, provenance-bound material context within a token budget.",
-  "material-discover": "Discover the five governed StyleGallery domain entries.",
+  "material-discover": "Discover the six governed StyleGallery domain entries.",
   "material-get": "Read bounded UTF-8 bytes for one canonical v2 material StableRef.",
   "material-search": "Search admitted material deterministically, optionally returning only repository-relative paths.",
 });

package/scripts/agent-native/v2/material-queries.mjs

@@ -310,11 +310,36 @@ function titleOf(text) {
   return /^#{1,6}\s+(.+?)\s*$/m.exec(text)?.[1] ?? "";
 }
 function fieldMembership(fieldTokens, queryTokens) {
-  const members = new Set(fieldTokens);
   let count = 0;
-  for (const token of queryTokens) if (members.has(token)) count += 1;
+  for (const token of queryTokens) if (fieldTokens.has(token)) count += 1;
   return count;
 }
+function queryTokenMembership(value, queryTokenSet) {
+  const matches = new Set();
+  for (const token of tokenizeMaterialText(value)) {
+    if (queryTokenSet.has(token)) matches.add(token);
+  }
+  return matches;
+}
+function rarityWeightsFor(documents, queryTokens) {
+  return queryTokens.map((token) => {
+    const documentFrequency = documents.reduce((count, document) => count + Number(
+      document.titleTokens.has(token) || document.pathTokens.has(token) || document.bodyTokens.has(token),
+    ), 0);
+    return {
+      document_frequency: documentFrequency,
+      multiplier: Math.ceil(documents.length / Math.max(1, documentFrequency)),
+      token,
+    };
+  });
+}
+function weightedFieldMembership(fieldTokens, rarityByToken, fieldWeight) {
+  let score = 0;
+  for (const [token, multiplier] of rarityByToken) {
+    if (fieldTokens.has(token)) score += multiplier * fieldWeight;
+  }
+  return score;
+}
 function sourceIdentity(record) {
   return { stable_ref: record.stable_ref, version_id: record.version_id, source_sha256: record.source_sha256, byte_length: record.byte_length };
 }
@@ -325,7 +350,7 @@ export function materialDiscover({ repositoryRoot, fileSystem = fs }) {
     .filter(({ identity }) => identity.kind === "domain")
     .map(({ record, identity }) => ({ identity, source: sourceIdentity(record), lifecycle: record.lifecycle }))
     .sort((left, right) => compare(left.identity.stable_ref, right.identity.stable_ref));
-  if (domains.length !== 5) fail("material_domain_set_invalid", "material manifest does not contain the five governed domains");
+  if (domains.length !== 6) fail("material_domain_set_invalid", "material manifest does not contain the six governed domains");
   return deepFreeze({ schema_version: "2.0", manifest_version_id: manifest.version_id, domains });
 }
 
@@ -334,20 +359,19 @@ export function materialSearch({ repositoryRoot, input, fileSystem = fs, sourceR
   const state = snapshot ? requireSnapshot(snapshot) : loadMetadata(repositoryRoot, fileSystem);
   const { root, manifest } = state;
   const beforeInventory = snapshot ? state.inventory : trackedInventory(repositoryRoot, gitRunner);
-  const ranked = [];
+  const queryTokenSet = new Set(normalized.scoringTokens);
+  const documents = [];
   for (const record of manifest.materials) {
     const bytes = readRecord({ repositoryRoot, root, record, fileSystem, sourceReader, gitRunner, inventory: beforeInventory });
     let body;
     try { body = utf8Fatal.decode(bytes); } catch { fail("material_source_utf8_invalid", "material source is not valid UTF-8"); }
     const title = titleOf(body);
-    const titleCount = fieldMembership(tokenizeMaterialText(title), normalized.scoringTokens);
-    const pathCount = fieldMembership(tokenizeMaterialText(record.repository_path), normalized.scoringTokens);
-    const bodyCount = fieldMembership(tokenizeMaterialText(body), normalized.scoringTokens);
-    const score = titleCount * MATERIAL_SEARCH_WEIGHTS.title + pathCount * MATERIAL_SEARCH_WEIGHTS.path + bodyCount * MATERIAL_SEARCH_WEIGHTS.body;
-    if (score === 0) continue;
-    ranked.push({
-      repositoryPath: record.repository_path,
-      result: { identity: materialIdentityForRecord(record), source: sourceIdentity(record), title, score, match_counts: { title: titleCount, path: pathCount, body: bodyCount } },
+    documents.push({
+      bodyTokens: queryTokenMembership(body, queryTokenSet),
+      pathTokens: queryTokenMembership(record.repository_path, queryTokenSet),
+      record,
+      title,
+      titleTokens: queryTokenMembership(title, queryTokenSet),
     });
   }
   const afterInventory = trackedInventory(repositoryRoot, gitRunner);
@@ -355,6 +379,28 @@ export function materialSearch({ repositoryRoot, input, fileSystem = fs, sourceR
     assertTracked(record, afterInventory);
     if (canonicalize(beforeInventory.get(record.repository_path)) !== canonicalize(afterInventory.get(record.repository_path))) fail("material_source_race", "material source tracking changed during read");
   }
+  const rarityWeights = rarityWeightsFor(documents, normalized.scoringTokens);
+  const rarityByToken = new Map(rarityWeights.map(({ token, multiplier }) => [token, multiplier]));
+  const ranked = [];
+  for (const document of documents) {
+    const titleCount = fieldMembership(document.titleTokens, normalized.scoringTokens);
+    const pathCount = fieldMembership(document.pathTokens, normalized.scoringTokens);
+    const bodyCount = fieldMembership(document.bodyTokens, normalized.scoringTokens);
+    const score = weightedFieldMembership(document.titleTokens, rarityByToken, MATERIAL_SEARCH_WEIGHTS.title)
+      + weightedFieldMembership(document.pathTokens, rarityByToken, MATERIAL_SEARCH_WEIGHTS.path)
+      + weightedFieldMembership(document.bodyTokens, rarityByToken, MATERIAL_SEARCH_WEIGHTS.body);
+    if (score === 0) continue;
+    ranked.push({
+      repositoryPath: document.record.repository_path,
+      result: {
+        identity: materialIdentityForRecord(document.record),
+        source: sourceIdentity(document.record),
+        title: document.title,
+        score,
+        match_counts: { title: titleCount, path: pathCount, body: bodyCount },
+      },
+    });
+  }
   ranked.sort((left, right) => right.result.score - left.result.score || compare(left.result.identity.stable_ref, right.result.identity.stable_ref));
   const selected = ranked.slice(0, normalized.limit);
   const envelope = {
@@ -362,6 +408,8 @@ export function materialSearch({ repositoryRoot, input, fileSystem = fs, sourceR
     normalization: "Unicode NFKC; ECMAScript locale-independent lowercase; Letter/Number-led Unicode words retaining attached Marks; unique query-token field membership",
     query: normalized.query.normalize("NFKC").toLowerCase(), tokens: normalized.tokens,
     scoring_tokens: normalized.scoringTokens, weights: MATERIAL_SEARCH_WEIGHTS,
+    rarity_weighting: "ceil(material_count / max(1, token_document_frequency))",
+    rarity_weights: rarityWeights,
   };
   if (normalized.pathsOnly) return deepFreeze({ ...envelope, paths_only: true, paths: selected.map(({ repositoryPath }) => repositoryPath), total_matches: ranked.length });
   return deepFreeze({ ...envelope, results: selected.map(({ result }) => result), total_matches: ranked.length });