openuispec 0.2.12 → 0.2.14

package/schema/custom-contract.schema.json

@@ -30,7 +30,7 @@
         },
         "states": {
           "type": "object",
-          "description": "State machine definition — each key is a state name",
+          "description": "UI interaction states (e.g. idle, active, disabled, loading, error) — each key is a state name. These are visual/interaction states, not business logic states.",
           "additionalProperties": {
             "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/state_def"
           }
@@ -165,7 +165,7 @@
     },
     "state_def": {
       "type": "object",
-      "description": "A single state in the state machine",
+      "description": "A single UI interaction state",
       "properties": {
         "semantic": {
           "type": "string"

package/schema/openuispec.schema.json

@@ -38,22 +38,32 @@
       "description": "Paths to spec component directories",
       "properties": {
         "tokens": {
-          "type": "string"
+          "type": "string",
+          "description": "Visual design tokens — colors, typography, spacing, elevation, motion. Affects UI rendering only, not business logic."
         },
         "contracts": {
-          "type": "string"
+          "type": "string",
+          "description": "Reusable UI component definitions — buttons, inputs, lists, surfaces. Each contract specifies visual props, UI interaction states (pressed, disabled, loading), and accessibility. These are UI rendering specifications, not business logic or domain state machines."
         },
         "screens": {
-          "type": "string"
+          "type": "string",
+          "description": "Screen layouts composed from contracts — defines what UI components appear on each screen, their data bindings, and visual arrangement."
         },
         "flows": {
-          "type": "string"
+          "type": "string",
+          "description": "Multi-screen navigation journeys — defines screen sequences, transitions, and navigation triggers. UI navigation structure, not business workflow logic."
         },
         "platform": {
-          "type": "string"
+          "type": "string",
+          "description": "Per-target platform overrides — native UI behavior, framework-specific generation config. One file per target (ios.yaml, android.yaml, web.yaml)."
         },
         "locales": {
-          "type": "string"
+          "type": "string",
+          "description": "Localization string files — one JSON file per supported locale containing translated UI text."
+        },
+        "components": {
+          "type": "string",
+          "description": "Reusable component compositions — each YAML file defines a component as a composition of contracts with named slots, states, and variants."
         }
       },
       "required": [
@@ -175,10 +185,10 @@
               },
               "tracks": {
                 "type": "array",
-                "description": "Spec categories this shared layer tracks for drift. Must be explicit — choose which categories actually affect the shared code.",
+                "description": "Spec categories this shared layer tracks for hash-based drift detection. Optional — when omitted, the layer relies on scope alone. Categories: manifest (project config, data models, API endpoints), tokens (visual design tokens — UI only), contracts (reusable UI component definitions — UI only, not business logic), screens (screen layouts — UI only), flows (navigation journeys — UI only), platform (per-target overrides — UI only), locales (translated UI strings).",
                 "items": {
                   "type": "string",
-                  "enum": ["manifest", "tokens", "contracts", "screens", "flows", "platform", "locales"]
+                  "enum": ["manifest", "tokens", "contracts", "components", "screens", "flows", "platform", "locales"]
                 }
               },
               "scope": {

package/schema/screen.schema.json

@@ -171,7 +171,7 @@
       "additionalProperties": false
     },
     "section_item": {
-      "description": "A section item \u2014 either a contract instance or a section group with children",
+      "description": "A section item \u2014 a contract instance, component instance, or section group with children",
       "type": "object",
       "properties": {
         "id": {
@@ -180,6 +180,17 @@
         "contract": {
           "type": "string"
         },
+        "component": {
+          "type": "string",
+          "description": "Component name (alternative to contract). References a component defined in components/*.yaml."
+        },
+        "slots": {
+          "type": "object",
+          "description": "Slot overrides when using a component. Each key is a slot name.",
+          "additionalProperties": {
+            "$ref": "https://openuispec.rsteam.uz/schema/component.schema.json#/$defs/slot_override"
+          }
+        },
         "variant": {
           "type": "string"
         },

package/schema/semantic-lint.ts

@@ -25,6 +25,7 @@ function collectLocaleKeys(data: unknown, prefix = ""): string[] {
 export interface Includes {
   tokens: string;
   contracts: string;
+  components: string;
   screens: string;
   flows: string;
   platform: string;
@@ -43,6 +44,7 @@ interface SemanticContext {
   formatterNames: Set<string>;
   mapperNames: Set<string>;
   contractNames: Set<string>;
+  componentNames: Set<string>;
   tokenRefs: Set<string>;
   iconRefs: Set<string>;
   iconVariantSuffixes: string[];
@@ -253,6 +255,15 @@ function buildContext(projectDir: string, includes: Includes, manifest: UnknownR
     }
   }
 
+  // Components are also valid references in screen sections (via "component:" key)
+  const componentNames = new Set<string>();
+  const componentsDir = resolve(projectDir, includes.components);
+  for (const filePath of listFiles(componentsDir, ".yaml")) {
+    for (const key of rootKeys(filePath)) {
+      componentNames.add(key);
+    }
+  }
+
   const tokenRefs = new Set<string>();
   const tokensDir = resolve(projectDir, includes.tokens);
   for (const filePath of listFiles(tokensDir, ".yaml")) {
@@ -300,6 +311,7 @@ function buildContext(projectDir: string, includes: Includes, manifest: UnknownR
     formatterNames,
     mapperNames,
     contractNames,
+    componentNames,
     tokenRefs,
     iconRefs: iconData.refs,
     iconVariantSuffixes: iconData.suffixes,
@@ -429,6 +441,10 @@ function validateStringValue(
     errors.push({ path, message: `unknown contract "${value}"` });
   }
 
+  if (key === "component" && !path.includes("platform_mapping") && !context.componentNames.has(value)) {
+    errors.push({ path, message: `unknown component "${value}"` });
+  }
+
   if (
     (key === "icon" || key === "icon_active") &&
     !isDynamicReference(value) &&
@@ -617,6 +633,7 @@ export function collectSemanticLint(projectDir: string, includes: Includes): Usa
   const manifest = readManifest(projectDir) as UnknownRecord;
   const context = buildContext(projectDir, includes, manifest);
   const contractsDir = resolve(projectDir, includes.contracts);
+  const componentsDir = resolve(projectDir, includes.components);
 
   const allErrors: UsageLint[] = [
     ...lintLocaleCoverage(context),
@@ -629,11 +646,13 @@ export function collectSemanticLint(projectDir: string, includes: Includes): Usa
     ...listFiles(resolve(projectDir, includes.flows), ".yaml"),
     ...listFiles(resolve(projectDir, includes.platform), ".yaml"),
     ...listFiles(resolve(projectDir, includes.contracts), ".yaml"),
+    ...listFiles(componentsDir, ".yaml"),
   ];
 
   for (const filePath of files) {
+    const isContractOrComponent = filePath.startsWith(contractsDir) || filePath.startsWith(componentsDir);
     allErrors.push(
-      ...lintFile(filePath, context, { validateTokens: !filePath.startsWith(contractsDir) })
+      ...lintFile(filePath, context, { validateTokens: !isContractOrComponent })
     );
   }
 
@@ -645,6 +664,7 @@ export function runSemanticLint(projectDir: string, includes: Includes): number
   const context = buildContext(projectDir, includes, manifest);
   let total = 0;
   const contractsDir = resolve(projectDir, includes.contracts);
+  const componentsDir = resolve(projectDir, includes.components);
 
   total += printSemanticErrors("locales", lintLocaleCoverage(context));
   total += printSemanticErrors("openuispec.yaml", lintManifestGenerationContext(projectDir, context.manifest));
@@ -655,12 +675,14 @@ export function runSemanticLint(projectDir: string, includes: Includes): number
     ...listFiles(resolve(projectDir, includes.flows), ".yaml"),
     ...listFiles(resolve(projectDir, includes.platform), ".yaml"),
     ...listFiles(resolve(projectDir, includes.contracts), ".yaml"),
+    ...listFiles(componentsDir, ".yaml"),
   ];
 
   for (const filePath of files) {
+    const isContractOrComponent = filePath.startsWith(contractsDir) || filePath.startsWith(componentsDir);
     total += printSemanticErrors(
       basename(filePath),
-      lintFile(filePath, context, { validateTokens: !filePath.startsWith(contractsDir) })
+      lintFile(filePath, context, { validateTokens: !isContractOrComponent })
     );
   }
 

package/schema/validate.ts

@@ -478,6 +478,7 @@ function validateFile(
 const DEFAULT_INCLUDES: Includes = {
   tokens: "./tokens/",
   contracts: "./contracts/",
+  components: "./components/",
   screens: "./screens/",
   flows: "./flows/",
   platform: "./platform/",
@@ -702,6 +703,26 @@ const GROUPS: Record<string, ValidationGroup> = {
     },
   },
 
+  components: {
+    label: "Components",
+    run(ajv, projectDir, includes) {
+      let errors = 0;
+      const dir = resolveInclude(projectDir, includes.components);
+      for (const f of listFiles(dir, ".yaml")) {
+        errors += validateFile(ajv, f, `${BASE}component.schema.json`);
+      }
+      return errors;
+    },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const dir = resolveInclude(projectDir, includes.components);
+      for (const f of listFiles(dir, ".yaml")) {
+        errors.push(...collectValidateFile(ajv, f, `${BASE}component.schema.json`));
+      }
+      return { group: groupKey, errors };
+    },
+  },
+
   semantic: {
     label: "Semantic",
     run(_ajv, projectDir, includes) {

package/scripts/regenerate-previews.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env npx tsx
+/**
+ * Regenerates all preview PNGs for the 3 example projects using the
+ * preview renderer (preview-render.ts → preview.ts → Puppeteer).
+ *
+ * Outputs to examples/<project>/previews/<screen>_<sizeClass>[_<theme>].png
+ *
+ * Usage:  npx tsx scripts/regenerate-previews.ts
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { renderPreview } from "../mcp-server/preview.js";
+import { closeBrowser } from "../mcp-server/screenshot-shared.js";
+
+const ROOT = resolve(import.meta.dirname!, "..");
+
+interface Capture {
+  screen: string;
+  sizeClass: "compact" | "regular" | "expanded";
+  theme?: "light" | "dark";
+}
+
+interface ProjectDef {
+  name: string;
+  captures: Capture[];
+}
+
+function allSizes(screen: string): Capture[] {
+  return [
+    { screen, sizeClass: "compact" },
+    { screen, sizeClass: "expanded" },
+  ];
+}
+
+function allSizesWithThemes(screen: string): Capture[] {
+  return [
+    { screen, sizeClass: "compact" },
+    { screen, sizeClass: "expanded" },
+    { screen, sizeClass: "compact", theme: "light" },
+    { screen, sizeClass: "compact", theme: "dark" },
+    { screen, sizeClass: "expanded", theme: "light" },
+    { screen, sizeClass: "expanded", theme: "dark" },
+  ];
+}
+
+const PROJECTS: ProjectDef[] = [
+  {
+    name: "social-app",
+    captures: [
+      ...allSizes("home_feed"),
+      ...allSizes("discover"),
+      ...allSizes("notifications"),
+      ...allSizes("messages_inbox"),
+      ...allSizes("profile_self"),
+      ...allSizes("profile_user"),
+      ...allSizes("settings"),
+      ...allSizes("post_detail"),
+      ...allSizes("chat_detail"),
+      ...allSizes("search_results"),
+      ...allSizes("edit_profile"),
+    ],
+  },
+  {
+    name: "taskflow",
+    captures: [
+      ...allSizesWithThemes("home"),
+      ...allSizes("projects"),
+      ...allSizes("calendar"),
+      ...allSizesWithThemes("settings"),
+      ...allSizesWithThemes("task_detail"),
+      ...allSizes("project_detail"),
+      ...allSizes("profile_edit"),
+    ],
+  },
+  {
+    name: "todo-orbit",
+    captures: [
+      ...allSizes("home"),
+      ...allSizes("analytics"),
+      ...allSizes("settings"),
+      ...allSizes("task_detail"),
+    ],
+  },
+];
+
+function log(msg: string) { console.log(`\x1b[36m▸\x1b[0m ${msg}`); }
+function logOk(msg: string) { console.log(`\x1b[32m✔\x1b[0m ${msg}`); }
+function logErr(msg: string) { console.error(`\x1b[31m✖\x1b[0m ${msg}`); }
+
+async function main() {
+  let total = 0;
+  let failures = 0;
+
+  for (const project of PROJECTS) {
+    console.log(`\n\x1b[1m=== ${project.name} ===\x1b[0m\n`);
+    const projectCwd = join(ROOT, "examples", project.name);
+    const outDir = join(projectCwd, "previews");
+    mkdirSync(outDir, { recursive: true });
+
+    for (const cap of project.captures) {
+      const theme = cap.theme ?? "light";
+      const suffix = cap.theme ? `_${cap.theme}` : "";
+      const filename = `${cap.screen}_${cap.sizeClass}${suffix}.png`;
+      log(`${filename}...`);
+      total++;
+
+      try {
+        const result = await renderPreview(projectCwd, {
+          screen: cap.screen,
+          size_class: cap.sizeClass,
+          theme,
+        });
+
+        for (const item of result.content) {
+          if (item.type === "image" && "data" in item) {
+            writeFileSync(join(outDir, filename), Buffer.from(item.data, "base64"));
+            logOk(filename);
+          }
+        }
+      } catch (err: any) {
+        logErr(`${filename}: ${err.message}`);
+        failures++;
+      }
+    }
+  }
+
+  await closeBrowser();
+  console.log(`\n\x1b[${failures ? "31" : "32"}m${total - failures}/${total} previews generated, ${failures} failures\x1b[0m\n`);
+  process.exit(failures > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});