stylegallery 0.1.3 → 0.1.6

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/recipes/homepage.md

@@ -37,8 +37,16 @@ Reject this recipe when the page is primarily a document, dashboard, form, comma
 
 Order sections by the visitor's decision path, not by visual symmetry. Put the primary heading, explanation, proof, and action in semantic order before layout classes. Repeated proof should be a list when each item has the same role.
 
+## Scroll Story Composition
+
+When a section explains a product through changing visual chapters, compose existing containment, stacking, overlay, and sticky responsibilities before proposing a new spatial pattern. Name the sticky containing block, stage height, document scroll track, offset, release boundary, and long-content fallback. Prevent clipping when copy is taller than the stage.
+
+Motion owns continuous progress and scene changes through the [Scroll-driven Story recipe](../motion/interaction-recipes.md#scroll-driven-story). The [Scroll Story Lab](../examples/scroll-story/README.md) demonstrates this composition with two products. Photography, device mockups, transforms, opacity, and timing remain in those consuming examples.
+
 ## Scroll Ownership
 
+A short full-page showcase can compose a viewport shell and [overlay-stack](../patterns/overlay-exception/overlay-stack.md) responsibilities with the [Full-viewport Scene Navigation contract](../motion/interaction-recipes.md#full-viewport-scene-navigation). Declare the document as fixed in scene mode, the chapter copy as the native overflow owner, and the document as the scroll owner in reading mode. The failure to prevent is a clipped or unreachable chapter when the viewport or text size changes. The [worked example](../examples/scene-navigation/README.md) uses a shrinkable stage between header and footer; it introduces no new reusable Layout pattern.
+
 Prefer normal document scrolling. Avoid nested scroll regions unless a section has an explicit independent task, such as a horizontally scrolling media reel with named keyboard and overflow behavior.
 
 ## Accessibility Expectations

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 });