@topogram/cli 0.3.48 → 0.3.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.48",
+  "version": "0.3.49",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/generator/context/slice.js

@@ -194,6 +194,7 @@ function projectionSlice(graph, projectionId) {
     verification_targets: recommendedVerificationTargets(graph, [projectionId, ...capabilities, ...entities, ...shapes, ...components], {
       rationale: "Projection slices affect generated contract and runtime surfaces, so verification should follow the projection closure."
     }),
+    ui_agent_packet: uiAgentPacketForProjection(graph, projection),
     write_scope: buildDefaultWriteScope(),
     review_boundary: projection.reviewBoundary || {
       automation_class: "review_required",
@@ -286,6 +287,7 @@ function componentSlice(graph, componentId) {
     verification_targets: recommendedVerificationTargets(graph, verificationScope, {
       rationale: "Component changes affect every related projection — verification should follow the component contract closure."
     }),
+    ui_agent_packet: uiAgentPacketForComponent(graph, component, projections),
     write_scope: buildDefaultWriteScope(),
     review_boundary: {
       automation_class: "review_required",
@@ -331,6 +333,135 @@ function componentDependencyKind(dependency) {
   return prefix || null;
 }
 
+function uiAgentPacketForProjection(graph, projection) {
+  if (!String(projection.platform || "").startsWith("ui_")) {
+    return null;
+  }
+  const sharedProjection = projection.platform === "ui_shared"
+    ? projection
+    : sharedUiProjectionFor(graph, projection);
+  const ownerProjection = sharedProjection || projection;
+  return {
+    type: "ui_agent_packet",
+    version: 1,
+    ownership: {
+      componentPlacement: "ui_shared",
+      designIntent: "ui_shared",
+      concreteSurfaceOwns: ["routes", "surface_hints"]
+    },
+    sharedProjection: sharedProjection
+      ? {
+          id: sharedProjection.id,
+          name: sharedProjection.name || sharedProjection.id
+        }
+      : null,
+    screens: (ownerProjection.uiScreens || []).map((screen) => ({
+      id: screen.id,
+      kind: screen.kind,
+      title: screen.title || screen.id
+    })),
+    routes: (projection.uiRoutes || []).map((route) => ({
+      screenId: route.screenId,
+      path: route.path
+    })),
+    components: (ownerProjection.uiComponents || []).map((usage) => componentUsagePacket(usage)),
+    design: designIntentPacket(ownerProjection),
+    requiredGates: uiRequiredGates(projection.id)
+  };
+}
+
+function uiAgentPacketForComponent(graph, component, projectionIds) {
+  const projectionSet = new Set(projectionIds);
+  const sourceUsages = [];
+  for (const projection of graph.byKind.projection || []) {
+    for (const usage of projection.uiComponents || []) {
+      if (usage.component?.id !== component.id) continue;
+      sourceUsages.push({
+        projection: {
+          id: projection.id,
+          platform: projection.platform,
+          ownership: projection.platform === "ui_shared" ? "owner" : "concrete"
+        },
+        usage: componentUsagePacket(usage),
+        design: designIntentPacket(projection)
+      });
+      projectionSet.add(projection.id);
+    }
+  }
+
+  return {
+    type: "ui_agent_packet",
+    version: 1,
+    ownership: {
+      componentContract: "component",
+      componentPlacement: "ui_shared",
+      concreteSurfacesInherit: true
+    },
+    component: {
+      id: component.id,
+      name: component.name || component.id,
+      category: component.category || null,
+      patterns: component.componentContract?.patterns || [],
+      regions: component.componentContract?.regions || [],
+      behaviors: component.componentContract?.behaviors || []
+    },
+    sourceUsages,
+    inheritedBy: [...projectionSet]
+      .filter((projectionId) => !sourceUsages.some((entry) => entry.projection.id === projectionId))
+      .sort(),
+    requiredGates: uiRequiredGates(null, component.id)
+  };
+}
+
+function sharedUiProjectionFor(graph, projection) {
+  for (const reference of projection.realizes || []) {
+    const candidate = (graph.byKind.projection || []).find((entry) => entry.id === reference.id);
+    if (candidate?.platform === "ui_shared") {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function componentUsagePacket(usage) {
+  return {
+    screenId: usage.screenId || null,
+    region: usage.region || null,
+    componentId: usage.component?.id || null,
+    dataBindings: (usage.dataBindings || []).map((binding) => ({
+      prop: binding.prop || null,
+      source: binding.source?.id || binding.source || null
+    })),
+    eventBindings: (usage.eventBindings || []).map((binding) => ({
+      event: binding.event || null,
+      action: binding.action || null,
+      target: binding.target?.id || binding.target || null
+    }))
+  };
+}
+
+function designIntentPacket(projection) {
+  return (projection.uiDesign || []).map((entry) => ({
+    key: entry.key,
+    role: entry.role,
+    value: entry.value
+  }));
+}
+
+function uiRequiredGates(projectionId = null, componentId = null) {
+  return [
+    { command: "topogram check", reason: "Validate shared UI ownership, taxonomy, references, and topology." },
+    {
+      command: `topogram component check${projectionId ? ` --projection ${projectionId}` : ""}${componentId ? ` --component ${componentId}` : ""}`,
+      reason: "Validate component placement, props, events, regions, and patterns."
+    },
+    {
+      command: `topogram component behavior${projectionId ? ` --projection ${projectionId}` : ""}${componentId ? ` --component ${componentId}` : ""}`,
+      reason: "Inspect behavior realizations and partial bindings before code changes."
+    }
+  ];
+}
+
 function journeySlice(graph, journeyId) {
   const journey = getJourneyDoc(graph, journeyId);
   const capabilities = [...(journey.relatedCapabilities || [])].sort();

package/src/generator/registry.js

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../ui/taxonomy.js";
 
 /**
  * @typedef {Object} GeneratorManifest
@@ -23,6 +24,8 @@ import { createRequire } from "node:module";
  * @property {boolean} [planned]
  */
 
+const RENDERED_COMPONENT_PATTERNS = [...UI_GENERATOR_RENDERED_COMPONENT_PATTERNS];
+
 /** @type {GeneratorManifest[]} */
 export const GENERATOR_MANIFESTS = [
   {
@@ -76,7 +79,7 @@ export const GENERATOR_MANIFESTS = [
     stack: { runtime: "node", framework: "sveltekit", language: "typescript" },
     capabilities: { routes: true, components: true, coverage: true },
     componentSupport: {
-      patterns: ["summary_stats", "board_view", "calendar_view", "resource_table", "data_grid_view"],
+      patterns: RENDERED_COMPONENT_PATTERNS,
       behaviors: ["selection", "sorting", "filtering", "search", "pagination", "bulk_action", "optimistic_update"],
       unsupported: "warning"
     },
@@ -94,7 +97,7 @@ export const GENERATOR_MANIFESTS = [
     stack: { runtime: "browser", framework: "react", language: "typescript" },
     capabilities: { routes: true, components: true, coverage: true },
     componentSupport: {
-      patterns: ["summary_stats", "board_view", "calendar_view", "resource_table", "data_grid_view"],
+      patterns: RENDERED_COMPONENT_PATTERNS,
       behaviors: ["selection", "sorting", "filtering", "search", "pagination", "bulk_action", "optimistic_update"],
       unsupported: "warning"
     },

package/src/generator/surfaces/shared.js

@@ -38,7 +38,8 @@ export function uiProjectionCandidates(graph) {
       (projection.uiAppShell || []).length > 0 ||
       (projection.uiNavigation || []).length > 0 ||
       (projection.uiScreenRegions || []).length > 0 ||
-      (projection.uiComponents || []).length > 0
+      (projection.uiComponents || []).length > 0 ||
+      (projection.uiDesign || []).length > 0
   );
 }
 

package/src/generator/surfaces/web/react-components.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../../../ui/taxonomy.js";
+
 /**
  * @typedef {{ id?: string, name?: string }} ComponentReference
  * @typedef {{ component?: ComponentReference, region?: string, pattern?: string }} ComponentUsage
@@ -71,13 +73,7 @@ export function reactComponentUsageSupport(usage, componentContracts) {
   const pattern = usagePattern(usage, componentContracts);
   return {
     pattern,
-    supported: [
-      "summary_stats",
-      "board_view",
-      "calendar_view",
-      "resource_table",
-      "data_grid_view"
-    ].includes(pattern || "")
+    supported: UI_GENERATOR_RENDERED_COMPONENT_PATTERNS.has(pattern || "")
   };
 }
 

package/src/generator/surfaces/web/sveltekit-components.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../../../ui/taxonomy.js";
+
 /**
  * @typedef {{ id?: string, name?: string }} ComponentReference
  * @typedef {{ component?: ComponentReference, region?: string, pattern?: string }} ComponentUsage
@@ -62,13 +64,7 @@ export function svelteKitComponentUsageSupport(usage, componentContracts) {
   const pattern = usagePattern(usage, componentContracts);
   return {
     pattern,
-    supported: [
-      "summary_stats",
-      "board_view",
-      "calendar_view",
-      "resource_table",
-      "data_grid_view"
-    ].includes(pattern || "")
+    supported: UI_GENERATOR_RENDERED_COMPONENT_PATTERNS.has(pattern || "")
   };
 }
 

package/src/import/core/runner.js

@@ -2,6 +2,9 @@ import { IMPORT_TRACKS } from "./contracts.js";
 import { dedupeCandidateRecords, ensureTrailingNewline, idHintify, makeCandidateRecord } from "./shared.js";
 import { createImportContext } from "./context.js";
 import { getEnrichersForTrack, getExtractorsForTrack } from "./registry.js";
+import {
+  collectionPatternFromPresentations
+} from "../../ui/taxonomy.js";
 
 function parseImportTracks(fromValue) {
   if (!fromValue) {
@@ -95,25 +98,6 @@ function selectDetectionsForTrack(track, detections) {
   return detections;
 }
 
-function collectionPatternFromPresentations(presentations) {
-  if (presentations.includes("data_grid")) return "data_grid_view";
-  if (presentations.includes("table")) return "resource_table";
-  if (presentations.includes("cards")) return "resource_cards";
-  if (presentations.includes("board")) return "board_view";
-  if (presentations.includes("calendar")) return "calendar_view";
-  if (presentations.includes("gallery")) return "resource_cards";
-  return "search_results";
-}
-
-function presentationFromPattern(pattern) {
-  if (pattern === "data_grid_view") return "data_grid";
-  if (pattern === "resource_table") return "table";
-  if (pattern === "resource_cards") return "cards";
-  if (pattern === "board_view") return "board";
-  if (pattern === "calendar_view") return "calendar";
-  return "list";
-}
-
 function importedApiCapabilityIds(allCandidates) {
   return [...(allCandidates?.api?.capabilities || [])]
     .map((capability) => capability.id_hint)
@@ -181,6 +165,17 @@ function deriveUiComponentCandidates(candidates) {
       pattern,
       data_prop: "rows",
       data_source: loadCapability,
+      inferred_props: [{ name: "rows", type: "array", required: true, source: loadCapability }],
+      inferred_events: [],
+      inferred_region: "results",
+      inferred_pattern: pattern,
+      evidence: screen.provenance || [],
+      missing_decisions: [
+        "confirm component reuse boundary",
+        "confirm prop names and data source",
+        "confirm events and behavior",
+        "confirm supported regions and patterns"
+      ],
       notes: [
         "Imported component candidates are review-only.",
         "Confirm props, behavior, events, and reuse before adoption."
@@ -294,8 +289,11 @@ function reportMarkdown(track, candidates) {
     );
   }
   if (track === "ui") {
+    const componentLines = (candidates.components || []).map((component) =>
+      `- \`${component.id_hint}\` confidence ${component.confidence || "unknown"} pattern \`${component.pattern || component.inferred_pattern || "unknown"}\` region \`${component.region || component.inferred_region || "unknown"}\` evidence ${(component.evidence || component.provenance || []).length} missing decisions ${(component.missing_decisions || []).length}`
+    );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Components: ${candidates.components.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
+      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Components: ${candidates.components.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Component Candidates\n\n${componentLines.length ? componentLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topogram/candidates/app/ui/drafts/components/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram component check <path>\`, and \`topogram component behavior <path>\`.\n`
     );
   }
   if (track === "verification") {
@@ -327,7 +325,15 @@ function componentCandidateFileName(component) {
 }
 
 function renderComponentCandidate(component) {
+  const evidenceCount = (component.evidence || component.provenance || []).length;
+  const missingDecisions = component.missing_decisions || [
+    "confirm component reuse boundary",
+    "confirm prop names and data source",
+    "confirm events and behavior"
+  ];
   return `component ${component.id_hint} {
+  # Import metadata: confidence ${component.confidence || "unknown"}; evidence ${evidenceCount}; inferred pattern ${component.pattern || component.inferred_pattern || "search_results"}; inferred region ${component.region || component.inferred_region || "results"}.
+  # Missing decisions: ${missingDecisions.join("; ")}.
   name "${component.label || component.id_hint}"
   description "Candidate reusable component inferred from imported UI evidence. Review props, behavior, events, and reuse before adoption."
   category collection
@@ -353,6 +359,26 @@ function uiComponentLinesForCandidates(componentCandidates, allCandidates) {
     });
 }
 
+function enrichUiComponentDataSources(uiCandidates, allCandidates) {
+  if (!uiCandidates || !Array.isArray(uiCandidates.components)) {
+    return uiCandidates;
+  }
+  return {
+    ...uiCandidates,
+    components: uiCandidates.components.map((component) => {
+      const dataSource = inferredDataSourceForComponent(component, allCandidates);
+      const dataProp = component.data_prop || "rows";
+      return {
+        ...component,
+        data_source: component.data_source || dataSource,
+        inferred_props: (component.inferred_props || []).map((prop) =>
+          prop.name === dataProp ? { ...prop, source: prop.source || dataSource } : prop
+        )
+      };
+    })
+  };
+}
+
 function draftUiProjectionFiles(context, candidates, allCandidates = {}) {
   const ui = candidates || { screens: [], routes: [], actions: [], stacks: [] };
   const screens = [...(ui.screens || [])].sort((a, b) => String(a.route_path || "").localeCompare(String(b.route_path || "")) || a.id_hint.localeCompare(b.id_hint));
@@ -477,6 +503,20 @@ ${capabilityHints.length > 0 ? capabilityHints.map((hint) => `    ${hint}`).join
     shell ${shell}
 ${presentations.includes("search") ? "    global_search true\n" : ""}${presentations.includes("multi_window") ? "    windowing multi_window\n" : ""}  }
 
+  ui_design {
+    density comfortable
+    tone operational
+    radius_scale medium
+    color_role primary accent
+    color_role danger critical
+    typography_role body readable
+    typography_role heading prominent
+    action_role primary prominent
+    action_role destructive danger
+    accessibility contrast aa
+    accessibility focus visible
+  }
+
   ui_screens {
 ${uiScreensBlock}
   }
@@ -616,6 +656,9 @@ export function runImportApp(inputPath, options = {}) {
   }
 
   if (candidates.ui) {
+    candidates.ui = enrichUiComponentDataSources(candidates.ui, candidates);
+    files["candidates/app/ui/candidates.json"] = `${JSON.stringify(candidates.ui, null, 2)}\n`;
+    files["candidates/app/ui/report.md"] = reportMarkdown("ui", candidates.ui);
     Object.assign(files, draftUiProjectionFiles(context, candidates.ui, candidates));
   }
 

package/src/realization/ui/build-ui-shared-realization.js

@@ -1,5 +1,6 @@
 import { getProjection, uiProjectionCandidates } from "../../generator/surfaces/shared.js";
 import { buildComponentBehaviorRealizations } from "../../component-behavior.js";
+import { defaultPatternForScreen } from "../../ui/taxonomy.js";
 
 function toBooleanFlag(value, fallback = false) {
   if (value === "true") return true;
@@ -47,21 +48,6 @@ function ownershipFieldByCapability(graph) {
   return output;
 }
 
-function deriveDefaultPattern(screen, collectionEntries) {
-  if (screen.kind === "detail") return "detail_panel";
-  if (screen.kind === "form") return "edit_form";
-  if (screen.kind === "board") return "board_view";
-  if (screen.kind === "calendar") return "calendar_view";
-  if (screen.kind === "dashboard" || screen.kind === "analytics" || screen.kind === "report") return "summary_stats";
-  if (screen.kind === "feed" || screen.kind === "inbox") return "activity_feed";
-  const view = collectionEntries.find((entry) => entry.operation === "view")?.value;
-  if (view === "data_grid") return "data_grid_view";
-  if (view === "table") return "resource_table";
-  if (view === "cards" || view === "gallery") return "resource_cards";
-  if (screen.kind === "list") return "resource_table";
-  return null;
-}
-
 function componentById(graph, componentId) {
   return (graph.byKind.component || []).find((component) => component.id === componentId) || null;
 }
@@ -88,6 +74,50 @@ function regionContractFor(regionEntries, regionName) {
   return (regionEntries || []).find((entry) => entry.region === regionName) || null;
 }
 
+function buildDesignIntentContract(projection) {
+  const design = {
+    density: "comfortable",
+    tone: "operational",
+    radiusScale: "medium",
+    colorRoles: {},
+    typographyRoles: {},
+    actionRoles: {},
+    accessibility: {}
+  };
+
+  for (const entry of projection.uiDesign || []) {
+    if (entry.key === "density" && entry.role) {
+      design.density = entry.role;
+      continue;
+    }
+    if (entry.key === "tone" && entry.role) {
+      design.tone = entry.role;
+      continue;
+    }
+    if (entry.key === "radius_scale" && entry.role) {
+      design.radiusScale = entry.role;
+      continue;
+    }
+    if (entry.key === "color_role" && entry.role && entry.value) {
+      design.colorRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "typography_role" && entry.role && entry.value) {
+      design.typographyRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "action_role" && entry.role && entry.value) {
+      design.actionRoles[entry.role] = entry.value;
+      continue;
+    }
+    if (entry.key === "accessibility" && entry.role && entry.value) {
+      design.accessibility[entry.role] = entry.value;
+    }
+  }
+
+  return design;
+}
+
 export function buildComponentUsageContract(graph, entry, options = {}) {
   const componentId = entry.component?.id || null;
   const contract = componentId ? componentContractFor(graph, componentId) : null;
@@ -184,7 +214,7 @@ function buildUiScreenContract(graph, projection, screen, ownershipFields) {
   );
   const visibilityEntries = (projection.uiVisibility || []).filter((entry) => screenActionIds.has(entry.capability?.id));
   const patterns = new Set(regionEntries.map((entry) => entry.pattern).filter(Boolean));
-  const derivedDefaultPattern = deriveDefaultPattern(screen, collectionEntries);
+  const derivedDefaultPattern = defaultPatternForScreen(screen, collectionEntries);
   if (derivedDefaultPattern) {
     patterns.add(derivedDefaultPattern);
   }
@@ -286,6 +316,7 @@ export function buildUiSharedRealization(graph, options = {}) {
       realizes: projection.realizes,
       outputs: projection.outputs,
       components: buildComponentContractMap(graph, componentUsages),
+      design: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens
@@ -305,6 +336,7 @@ export function buildUiSharedRealization(graph, options = {}) {
       realizes: projection.realizes,
       outputs: projection.outputs,
       components: buildComponentContractMap(graph, componentUsages),
+      design: buildDesignIntentContract(projection),
       appShell: buildAppShellContract(projection),
       navigation: buildNavigationContract(projection, screens),
       screens

package/src/realization/ui/build-web-realization.js

@@ -1,8 +1,6 @@
 import { buildApiRealization } from "../api/index.js";
 import { generatorDefaultsMap, getProjection, sharedUiProjectionForWeb } from "../../generator/surfaces/shared.js";
 import {
-  buildComponentContractMap,
-  buildComponentUsageContract,
   buildUiSharedRealization
 } from "./build-ui-shared-realization.js";
 
@@ -38,6 +36,7 @@ export function buildWebRealization(graph, options = {}) {
         realizes: [],
         outputs: [],
         components: {},
+        design: null,
         screens: []
       };
   const concreteContract = buildUiSharedRealization(graph, { projectionId: projection.id });
@@ -70,30 +69,15 @@ export function buildWebRealization(graph, options = {}) {
     screenMap.set(screen.id, {
       ...existing,
       ...screen,
-      components: [...(existing.components || []), ...(screen.components || [])],
+      components: [...(existing.components || [])],
       regions: mergeByKey(existing.regions || [], screen.regions || [], (entry) => entry.region),
       patterns: [...new Set([...(existing.patterns || []), ...(screen.patterns || [])])]
     });
   }
-  for (const entry of projection.uiComponents || []) {
-    if (!screenMap.has(entry.screenId)) {
-      continue;
-    }
-    const screen = screenMap.get(entry.screenId);
-    if ((screen.components || []).some((usage) => componentUsageFingerprint(usage) === componentUsageFingerprintFromEntry(entry))) {
-      continue;
-    }
-    screen.components = [...(screen.components || []), buildComponentUsageContract(graph, entry, {
-      region: (screen.regions || []).find((region) => region.region === entry.region) || null
-    })];
-  }
 
   const appShell = projection.uiAppShell?.length || !sharedProjection ? concreteContract.appShell : sharedContract.appShell;
   const navigation = projection.uiNavigation?.length || !sharedProjection ? concreteContract.navigation : sharedContract.navigation;
-  const componentContracts = {
-    ...(sharedContract.components || {}),
-    ...buildComponentContractMap(graph, projection.uiComponents || [])
-  };
+  const design = projection.uiDesign?.length || !sharedProjection ? concreteContract.design : sharedContract.design;
 
   const contract = {
     projection: {
@@ -109,7 +93,8 @@ export function buildWebRealization(graph, options = {}) {
       : null,
     generatorDefaults: generatorDefaultsMap(projection),
     outputs: projection.outputs,
-    components: componentContracts,
+    components: sharedProjection ? (sharedContract.components || {}) : (concreteContract.components || {}),
+    design: design || null,
     appShell: appShell || null,
     navigation: {
       groups: navigation?.groups || [],
@@ -171,21 +156,3 @@ function mergeByKey(left, right, keyFn) {
   for (const entry of right) output.set(keyFn(entry), { ...(output.get(keyFn(entry)) || {}), ...entry });
   return [...output.values()];
 }
-
-function componentUsageFingerprint(usage) {
-  return [
-    usage?.region || "",
-    usage?.component?.id || "",
-    ...(usage?.dataBindings || []).map((binding) => `data:${binding.prop}:${binding.source?.id || ""}`),
-    ...(usage?.eventBindings || []).map((binding) => `event:${binding.event}:${binding.action}:${binding.target?.id || ""}`)
-  ].join("|");
-}
-
-function componentUsageFingerprintFromEntry(entry) {
-  return [
-    entry?.region || "",
-    entry?.component?.id || "",
-    ...(entry?.dataBindings || []).map((binding) => `data:${binding.prop}:${binding.source?.id || ""}`),
-    ...(entry?.eventBindings || []).map((binding) => `event:${binding.event}:${binding.action}:${binding.target?.id || ""}`)
-  ].join("|");
-}

package/src/resolver/index.js

@@ -503,6 +503,7 @@ function buildProjectionPlan(statement) {
     uiVisibility: statement.uiVisibility,
     uiRoutes: statement.uiRoutes,
     uiWeb: statement.uiWeb,
+    uiDesign: statement.uiDesign,
     uiComponents: statement.uiComponents,
     dbTables: statement.dbTables,
     dbColumns: statement.dbColumns,
@@ -1269,6 +1270,17 @@ function parseProjectionUiAppShellBlock(statement) {
   }));
 }
 
+function parseProjectionUiDesignBlock(statement) {
+  return blockEntries(getFieldValue(statement, "ui_design")).map((entry) => ({
+    type: "ui_design_token",
+    key: tokenValue(entry.items[0]) || null,
+    role: tokenValue(entry.items[1]) || null,
+    value: tokenValue(entry.items[2]) || null,
+    raw: normalizeSequence(entry.items),
+    loc: entry.loc
+  }));
+}
+
 function parseProjectionUiNavigationBlock(statement) {
   return blockEntries(getFieldValue(statement, "ui_navigation")).map((entry) => {
     const directives = {};
@@ -1869,6 +1881,7 @@ export function normalizeStatement(statement, registry) {
         uiWeb: parseProjectionUiWebBlock(statement, registry),
         uiIos: parseProjectionUiIosBlock(statement, registry),
         uiAppShell: parseProjectionUiAppShellBlock(statement),
+        uiDesign: parseProjectionUiDesignBlock(statement),
         uiNavigation: parseProjectionUiNavigationBlock(statement),
         uiScreenRegions: parseProjectionUiScreenRegionsBlock(statement),
         uiComponents: parseProjectionUiComponentsBlock(statement, registry),

package/src/ui/taxonomy.js

@@ -0,0 +1,201 @@
+// @ts-check
+
+export const UI_APP_SHELL_KINDS = new Set([
+  "topbar",
+  "sidebar",
+  "dual_nav",
+  "workspace",
+  "wizard",
+  "bottom_tabs",
+  "split_view",
+  "menu_bar"
+]);
+
+export const UI_WINDOWING_MODES = new Set(["single_window", "multi_window"]);
+
+export const UI_SCREEN_KINDS = new Set([
+  "list",
+  "detail",
+  "form",
+  "dashboard",
+  "job_status",
+  "board",
+  "calendar",
+  "feed",
+  "inbox",
+  "settings",
+  "wizard",
+  "report",
+  "analytics"
+]);
+
+export const UI_COLLECTION_PRESENTATIONS = new Set([
+  "table",
+  "data_grid",
+  "cards",
+  "list",
+  "board",
+  "calendar",
+  "gallery"
+]);
+
+export const UI_NAVIGATION_PATTERNS = new Set([
+  "primary",
+  "tabs",
+  "stack_navigation",
+  "bottom_tabs",
+  "segmented_control",
+  "command_palette",
+  "split_view",
+  "navigation_rail"
+]);
+
+export const UI_REGION_KINDS = new Set([
+  "hero",
+  "toolbar",
+  "filters",
+  "search",
+  "results",
+  "summary",
+  "metadata",
+  "aside",
+  "related",
+  "activity",
+  "comments",
+  "timeline",
+  "tabs",
+  "bulk_actions",
+  "footer_actions"
+]);
+
+export const UI_PATTERN_KINDS = new Set([
+  "resource_table",
+  "data_grid_view",
+  "resource_cards",
+  "detail_panel",
+  "edit_form",
+  "lookup_select",
+  "action_bar",
+  "status_badge",
+  "summary_stats",
+  "activity_feed",
+  "comment_thread",
+  "timeline_view",
+  "board_view",
+  "calendar_view",
+  "settings_section",
+  "wizard_stepper",
+  "audit_log",
+  "search_results",
+  "empty_state_panel",
+  "inspector_pane",
+  "master_detail"
+]);
+
+export const UI_ACTION_PRESENTATIONS = new Set([
+  "button",
+  "menu_item",
+  "split_button",
+  "bulk_action",
+  "modal",
+  "drawer",
+  "inline_confirm",
+  "sheet",
+  "bottom_sheet",
+  "fab",
+  "popover"
+]);
+
+export const UI_STATE_KINDS = new Set([
+  "loading",
+  "empty",
+  "error",
+  "unauthorized",
+  "not_found",
+  "success"
+]);
+
+export const UI_PLATFORM_PATTERNS = new Set([
+  "bottom_tabs",
+  "stack_navigation",
+  "split_view",
+  "master_detail",
+  "navigation_rail",
+  "fab",
+  "sheet",
+  "bottom_sheet",
+  "pull_to_refresh",
+  "segmented_control",
+  "command_palette",
+  "inspector_pane",
+  "multi_pane_layout",
+  "resizable_split",
+  "menu_bar",
+  "multi_window"
+]);
+
+export const UI_DESIGN_DENSITIES = new Set(["compact", "comfortable", "spacious"]);
+export const UI_DESIGN_TONES = new Set(["operational", "neutral", "editorial", "playful"]);
+export const UI_DESIGN_RADIUS_SCALES = new Set(["none", "small", "medium", "large"]);
+export const UI_DESIGN_COLOR_ROLES = new Set(["primary", "secondary", "surface", "text", "muted", "danger", "success", "warning", "info"]);
+export const UI_DESIGN_TYPOGRAPHY_ROLES = new Set(["body", "heading", "label", "mono", "numeric"]);
+export const UI_DESIGN_ACTION_ROLES = new Set(["primary", "secondary", "destructive", "contextual", "bulk"]);
+export const UI_DESIGN_ACCESSIBILITY_VALUES = {
+  contrast: new Set(["aa", "aaa", "high"]),
+  motion: new Set(["standard", "reduced"]),
+  focus: new Set(["visible", "required"]),
+  min_touch_target: new Set(["compact", "comfortable"])
+};
+
+export const UI_GENERATOR_RENDERED_COMPONENT_PATTERNS = new Set([
+  "summary_stats",
+  "board_view",
+  "calendar_view",
+  "resource_table",
+  "data_grid_view"
+]);
+
+/**
+ * @param {string[]} presentations
+ * @returns {string}
+ */
+export function collectionPatternFromPresentations(presentations = []) {
+  if (presentations.includes("data_grid")) return "data_grid_view";
+  if (presentations.includes("table")) return "resource_table";
+  if (presentations.includes("cards")) return "resource_cards";
+  if (presentations.includes("board")) return "board_view";
+  if (presentations.includes("calendar")) return "calendar_view";
+  if (presentations.includes("gallery")) return "resource_cards";
+  return "search_results";
+}
+
+/**
+ * @param {string|null|undefined} pattern
+ * @returns {string}
+ */
+export function presentationFromPattern(pattern) {
+  if (pattern === "data_grid_view") return "data_grid";
+  if (pattern === "resource_table") return "table";
+  if (pattern === "resource_cards") return "cards";
+  if (pattern === "board_view") return "board";
+  if (pattern === "calendar_view") return "calendar";
+  return "list";
+}
+
+/**
+ * @param {{ kind?: string|null }} screen
+ * @param {{ operation?: string|null, value?: string|null }[]} collectionEntries
+ * @returns {string|null}
+ */
+export function defaultPatternForScreen(screen, collectionEntries = []) {
+  if (screen.kind === "detail") return "detail_panel";
+  if (screen.kind === "form") return "edit_form";
+  if (screen.kind === "board") return "board_view";
+  if (screen.kind === "calendar") return "calendar_view";
+  if (screen.kind === "dashboard" || screen.kind === "analytics" || screen.kind === "report") return "summary_stats";
+  if (screen.kind === "feed" || screen.kind === "inbox") return "activity_feed";
+  const view = collectionEntries.find((entry) => entry.operation === "view")?.value;
+  if (view) return collectionPatternFromPresentations([view]);
+  if (screen.kind === "list") return "resource_table";
+  return null;
+}

package/src/validator/index.js

@@ -37,6 +37,16 @@ import {
   UI_NAVIGATION_PATTERNS,
   UI_REGION_KINDS,
   UI_PATTERN_KINDS,
+  UI_APP_SHELL_KINDS,
+  UI_WINDOWING_MODES,
+  UI_STATE_KINDS,
+  UI_DESIGN_DENSITIES,
+  UI_DESIGN_TONES,
+  UI_DESIGN_RADIUS_SCALES,
+  UI_DESIGN_COLOR_ROLES,
+  UI_DESIGN_TYPOGRAPHY_ROLES,
+  UI_DESIGN_ACTION_ROLES,
+  UI_DESIGN_ACCESSIBILITY_VALUES,
   FIELD_SPECS
 } from "./kinds.js";
 import { validateComponent } from "./per-kind/component.js";
@@ -78,6 +88,16 @@ export {
   UI_NAVIGATION_PATTERNS,
   UI_REGION_KINDS,
   UI_PATTERN_KINDS,
+  UI_APP_SHELL_KINDS,
+  UI_WINDOWING_MODES,
+  UI_STATE_KINDS,
+  UI_DESIGN_DENSITIES,
+  UI_DESIGN_TONES,
+  UI_DESIGN_RADIUS_SCALES,
+  UI_DESIGN_COLOR_ROLES,
+  UI_DESIGN_TYPOGRAPHY_ROLES,
+  UI_DESIGN_ACTION_ROLES,
+  UI_DESIGN_ACCESSIBILITY_VALUES,
   FIELD_SPECS
 } from "./kinds.js";
 
@@ -279,7 +299,7 @@ function validateFieldShapes(errors, statement, fieldMap) {
     ensureSingleValueField(errors, statement, fieldMap, key, ["list"]);
   }
 
-  for (const key of ["fields", "props", "events", "slots", "behaviors", "keys", "relations", "invariants", "rename", "overrides", "http", "http_errors", "http_fields", "http_responses", "http_preconditions", "http_idempotency", "http_cache", "http_delete", "http_async", "http_status", "http_download", "http_authz", "http_callbacks", "ui_screens", "ui_collections", "ui_actions", "ui_visibility", "ui_lookups", "ui_routes", "ui_web", "ui_ios", "ui_app_shell", "ui_navigation", "ui_screen_regions", "ui_components", "db_tables", "db_columns", "db_keys", "db_indexes", "db_relations", "db_lifecycle", "generator_defaults"]) {
+  for (const key of ["fields", "props", "events", "slots", "behaviors", "keys", "relations", "invariants", "rename", "overrides", "http", "http_errors", "http_fields", "http_responses", "http_preconditions", "http_idempotency", "http_cache", "http_delete", "http_async", "http_status", "http_download", "http_authz", "http_callbacks", "ui_screens", "ui_collections", "ui_actions", "ui_visibility", "ui_lookups", "ui_routes", "ui_web", "ui_ios", "ui_app_shell", "ui_navigation", "ui_screen_regions", "ui_components", "ui_design", "db_tables", "db_columns", "db_keys", "db_indexes", "db_relations", "db_lifecycle", "generator_defaults"]) {
     ensureSingleValueField(errors, statement, fieldMap, key, ["block"]);
   }
 
@@ -2320,18 +2340,113 @@ function validateProjectionUiAppShell(errors, statement, fieldMap) {
     }
     seenKeys.add(key);
 
-    if (key === "shell" && !["topbar", "sidebar", "dual_nav", "workspace", "wizard", "bottom_tabs", "split_view", "menu_bar"].includes(value)) {
+    if (key === "shell" && !UI_APP_SHELL_KINDS.has(value)) {
       pushError(errors, `Projection ${statement.id} ui_app_shell has invalid shell '${value}'`, entry.loc);
     }
     if (["global_search", "notifications", "account_menu", "workspace_switcher"].includes(key) && !["true", "false"].includes(value)) {
       pushError(errors, `Projection ${statement.id} ui_app_shell '${key}' must be true or false`, entry.loc);
     }
-    if (key === "windowing" && !["single_window", "multi_window"].includes(value)) {
+    if (key === "windowing" && !UI_WINDOWING_MODES.has(value)) {
       pushError(errors, `Projection ${statement.id} ui_app_shell has invalid windowing '${value}'`, entry.loc);
     }
   }
 }
 
+function validateProjectionUiDesign(errors, statement, fieldMap) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+
+  const designField = fieldMap.get("ui_design")?.[0];
+  if (!designField || designField.value.type !== "block") {
+    return;
+  }
+
+  if (symbolValue(getFieldValue(statement, "platform")) !== "ui_shared") {
+    pushError(errors, `Projection ${statement.id} ui_design belongs on shared UI projections; concrete UI projections inherit semantic design intent through 'realizes'`, designField.loc);
+  }
+
+  for (const entry of designField.value.entries) {
+    const tokens = blockSymbolItems(entry).map((item) => item.value);
+    const [key, value, extra] = tokens;
+
+    if (key === "density") {
+      if (!UI_DESIGN_DENSITIES.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ui_design density has invalid value '${value}'`, entry.loc);
+      }
+      if (tokens.length !== 2) {
+        pushError(errors, `Projection ${statement.id} ui_design density accepts exactly one value`, entry.loc);
+      }
+      continue;
+    }
+
+    if (key === "tone") {
+      if (!UI_DESIGN_TONES.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ui_design tone has invalid value '${value}'`, entry.loc);
+      }
+      if (tokens.length !== 2) {
+        pushError(errors, `Projection ${statement.id} ui_design tone accepts exactly one value`, entry.loc);
+      }
+      continue;
+    }
+
+    if (key === "radius_scale") {
+      if (!UI_DESIGN_RADIUS_SCALES.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ui_design radius_scale has invalid value '${value}'`, entry.loc);
+      }
+      if (tokens.length !== 2) {
+        pushError(errors, `Projection ${statement.id} ui_design radius_scale accepts exactly one value`, entry.loc);
+      }
+      continue;
+    }
+
+    if (key === "color_role") {
+      if (!UI_DESIGN_COLOR_ROLES.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ui_design color_role has invalid role '${value}'`, entry.loc);
+      }
+      if (tokens.length !== 3) {
+        pushError(errors, `Projection ${statement.id} ui_design color_role must use 'color_role <role> <semantic-token>'`, entry.loc);
+      }
+      continue;
+    }
+
+    if (key === "typography_role") {
+      if (!UI_DESIGN_TYPOGRAPHY_ROLES.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ui_design typography_role has invalid role '${value}'`, entry.loc);
+      }
+      if (tokens.length !== 3) {
+        pushError(errors, `Projection ${statement.id} ui_design typography_role must use 'typography_role <role> <semantic-token>'`, entry.loc);
+      }
+      continue;
+    }
+
+    if (key === "action_role") {
+      if (!UI_DESIGN_ACTION_ROLES.has(value || "")) {
+        pushError(errors, `Projection ${statement.id} ui_design action_role has invalid role '${value}'`, entry.loc);
+      }
+      if (tokens.length !== 3) {
+        pushError(errors, `Projection ${statement.id} ui_design action_role must use 'action_role <role> <semantic-token>'`, entry.loc);
+      }
+      continue;
+    }
+
+    if (key === "accessibility") {
+      const values = UI_DESIGN_ACCESSIBILITY_VALUES[value];
+      if (tokens.length !== 3) {
+        pushError(errors, `Projection ${statement.id} ui_design accessibility must use 'accessibility <setting> <value>'`, entry.loc);
+      }
+      if (!values) {
+        pushError(errors, `Projection ${statement.id} ui_design accessibility has invalid setting '${value}'`, entry.loc);
+      } else if (!values.has(extra || "")) {
+        pushError(errors, `Projection ${statement.id} ui_design accessibility '${value}' has invalid value '${extra}'`, entry.loc);
+      }
+      continue;
+    }
+
+    pushError(errors, `Projection ${statement.id} ui_design has unknown key '${key}'`, entry.loc);
+  }
+}
+
 function validateProjectionUiNavigation(errors, statement, fieldMap, registry) {
   if (statement.kind !== "projection") {
     return;
@@ -2458,7 +2573,7 @@ function validateProjectionUiScreenRegions(errors, statement, fieldMap, registry
     if (directives.has("placement") && !["primary", "secondary", "supporting"].includes(directives.get("placement"))) {
       pushError(errors, `Projection ${statement.id} ui_screen_regions for '${screenId}' has invalid placement '${directives.get("placement")}'`, entry.loc);
     }
-    if (directives.has("state") && !["loading", "empty", "error", "unauthorized", "not_found", "success"].includes(directives.get("state"))) {
+    if (directives.has("state") && !UI_STATE_KINDS.has(directives.get("state"))) {
       pushError(errors, `Projection ${statement.id} ui_screen_regions for '${screenId}' has invalid state '${directives.get("state")}'`, entry.loc);
     }
   }
@@ -2474,6 +2589,10 @@ function validateProjectionUiComponents(errors, statement, fieldMap, registry) {
     return;
   }
 
+  if (symbolValue(getFieldValue(statement, "platform")) !== "ui_shared") {
+    pushError(errors, `Projection ${statement.id} ui_components belongs on shared UI projections; concrete UI projections inherit component placement through 'realizes'`, componentsField.loc);
+  }
+
   const availableScreens = collectAvailableUiScreenIds(statement, fieldMap, registry);
   const availableRegions = collectAvailableUiRegionKeys(statement, registry);
   const availableRegionPatterns = collectAvailableUiRegionPatterns(statement, registry);
@@ -3387,6 +3506,7 @@ export function validateWorkspace(workspaceAst) {
       validateProjectionUiLookups(errors, statement, fieldMap, registry);
       validateProjectionUiRoutes(errors, statement, fieldMap, registry);
       validateProjectionUiAppShell(errors, statement, fieldMap);
+      validateProjectionUiDesign(errors, statement, fieldMap);
       validateProjectionUiNavigation(errors, statement, fieldMap, registry);
       validateProjectionUiScreenRegions(errors, statement, fieldMap, registry);
       validateProjectionUiComponents(errors, statement, fieldMap, registry);

package/src/validator/kinds.js

@@ -74,58 +74,26 @@ export const STATUS_SETS_BY_KIND = {
   bug: BUG_STATUSES
 };
 export const VERIFICATION_METHODS = new Set(["smoke", "runtime", "contract", "journey", "manual"]);
-export const UI_SCREEN_KINDS = new Set(["list", "detail", "form", "dashboard", "job_status", "board", "calendar", "feed", "inbox", "settings", "wizard", "report", "analytics"]);
-export const UI_COLLECTION_PRESENTATIONS = new Set(["table", "data_grid", "cards", "list", "board", "calendar", "gallery"]);
-export const UI_NAVIGATION_PATTERNS = new Set([
-  "primary",
-  "tabs",
-  "stack_navigation",
-  "bottom_tabs",
-  "segmented_control",
-  "command_palette",
-  "split_view",
-  "navigation_rail"
-]);
-export const UI_REGION_KINDS = new Set([
-  "hero",
-  "toolbar",
-  "filters",
-  "search",
-  "results",
-  "summary",
-  "metadata",
-  "aside",
-  "related",
-  "activity",
-  "comments",
-  "timeline",
-  "tabs",
-  "bulk_actions",
-  "footer_actions"
-]);
-export const UI_PATTERN_KINDS = new Set([
-  "resource_table",
-  "data_grid_view",
-  "resource_cards",
-  "detail_panel",
-  "edit_form",
-  "lookup_select",
-  "action_bar",
-  "status_badge",
-  "summary_stats",
-  "activity_feed",
-  "comment_thread",
-  "timeline_view",
-  "board_view",
-  "calendar_view",
-  "settings_section",
-  "wizard_stepper",
-  "audit_log",
-  "search_results",
-  "empty_state_panel",
-  "inspector_pane",
-  "master_detail"
-]);
+
+export {
+  UI_APP_SHELL_KINDS,
+  UI_WINDOWING_MODES,
+  UI_SCREEN_KINDS,
+  UI_COLLECTION_PRESENTATIONS,
+  UI_NAVIGATION_PATTERNS,
+  UI_REGION_KINDS,
+  UI_PATTERN_KINDS,
+  UI_ACTION_PRESENTATIONS,
+  UI_STATE_KINDS,
+  UI_PLATFORM_PATTERNS,
+  UI_DESIGN_DENSITIES,
+  UI_DESIGN_TONES,
+  UI_DESIGN_RADIUS_SCALES,
+  UI_DESIGN_COLOR_ROLES,
+  UI_DESIGN_TYPOGRAPHY_ROLES,
+  UI_DESIGN_ACTION_ROLES,
+  UI_DESIGN_ACCESSIBILITY_VALUES
+} from "../ui/taxonomy.js";
 
 // Kinds that may carry an optional singular `domain dom_x` field. Keep this
 // set in sync with the `allowed[]` arrays in FIELD_SPECS below; the cross-kind
@@ -221,6 +189,7 @@ export const FIELD_SPECS = {
       "ui_navigation",
       "ui_screen_regions",
       "ui_components",
+      "ui_design",
       "db_tables",
       "db_columns",
       "db_keys",