openuispec 0.2.15 → 0.2.17

package/prepare/index.ts

@@ -172,6 +172,17 @@ export interface PrepareResult {
   shared_layers?: SharedLayerInfo[];
   bootstrap?: PrepareBootstrapBundle;
   spec_contents?: SpecFileContent[];
+  anti_patterns?: {
+    universal: Record<string, string[]>;
+    contract_specific: Record<string, string[]>;
+    project_specific: string[];
+  };
+  design_context?: {
+    personality?: string;
+    complexity: 'restrained' | 'balanced' | 'elaborate';
+    audience?: string;
+    complexity_rule: string;
+  };
   next_steps: string[];
 }
 
@@ -643,9 +654,92 @@ function generationRules(target: string, outputDir: string, manifest: Record<str
     rules.push(`Target "${target}" scope: ${structure.scope}`);
   }
 
+  // Include extra_rules from manifest, filtered by target platform tag
+  const extraRules: string[] = Array.isArray(manifest.generation?.extra_rules)
+    ? manifest.generation.extra_rules.filter((rule: any): rule is string => typeof rule === "string")
+    : [];
+  for (const rule of extraRules) {
+    if (matchesTargetPlatform(rule, target)) rules.push(rule);
+  }
+
   return rules;
 }
 
+function matchesTargetPlatform(item: string, target: string): boolean {
+  const tagMatch = item.match(/^\[([a-z]+)\]/i);
+  return !tagMatch || tagMatch[1].toLowerCase() === target;
+}
+
+function complexityRule(complexity: string): string {
+  switch (complexity) {
+    case 'restrained':
+      return 'Minimal motion (required state transitions only). No decorative shadows. Clean whitespace. Precise token application. No background effects.';
+    case 'elaborate':
+      return 'Rich animations with staggered reveals. Creative elevation. Platform-specific flourishes.';
+    default:
+      return 'Apply all motion.patterns. Use elevation tokens fully. Standard state animations.';
+  }
+}
+
+function buildDesignContext(manifest: Record<string, any>): PrepareResult['design_context'] {
+  const design = manifest.design;
+  if (!design) return undefined;
+  const complexity = (design.complexity as 'restrained' | 'balanced' | 'elaborate') ?? 'balanced';
+  return {
+    ...(design.personality ? { personality: design.personality } : {}),
+    complexity,
+    ...(design.audience ? { audience: design.audience } : {}),
+    complexity_rule: complexityRule(complexity),
+  };
+}
+
+function buildAntiPatterns(
+  manifest: Record<string, any>,
+  projectDir: string,
+  target: string
+): PrepareResult['anti_patterns'] {
+  // Universal anti-patterns from generation_guidance
+  const universal: Record<string, string[]> = {};
+  const universalRaw = manifest.generation_guidance?.universal_anti_patterns ?? {};
+  for (const [domain, items] of Object.entries(universalRaw)) {
+    if (Array.isArray(items)) {
+      const filtered = (items as string[]).filter((item) => matchesTargetPlatform(item, target));
+      if (filtered.length > 0) universal[domain] = filtered;
+    }
+  }
+
+  // Contract-specific must_avoid
+  const contract_specific: Record<string, string[]> = {};
+  const contractsDir = resolve(projectDir, manifest.includes?.contracts ?? './contracts/');
+  if (existsSync(contractsDir)) {
+    for (const file of readdirSync(contractsDir).filter((f) => f.endsWith('.yaml') && !f.startsWith('x_'))) {
+      try {
+        const content = YAML.parse(readFileSync(join(contractsDir, file), 'utf-8'));
+        const contractName = Object.keys(content)[0];
+        const mustAvoid: string[] = content[contractName]?.generation?.must_avoid ?? [];
+        if (mustAvoid.length > 0) {
+          const filtered = mustAvoid.filter((item: string) => matchesTargetPlatform(item, target));
+          if (filtered.length > 0) contract_specific[contractName] = filtered;
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  // Project-specific avoid from design section
+  const project_specific: string[] = [];
+  const designAvoid: string[] = manifest.design?.avoid ?? [];
+  for (const item of designAvoid) {
+    if (matchesTargetPlatform(item, target)) project_specific.push(item);
+  }
+
+  const hasContent = Object.keys(universal).length > 0 || Object.keys(contract_specific).length > 0 || project_specific.length > 0;
+  if (!hasContent) return undefined;
+
+  return { universal, contract_specific, project_specific };
+}
+
 function localizationConstraints(
   target: string,
   platformConfig?: Pick<PreparePlatformConfig, "framework">
@@ -1228,6 +1322,8 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
   const outputDirExists = existsSync(outputDir);
   const snapshotPath = join(outputDir, ".openuispec-state.json");
   const snapshotFileExists = existsSync(snapshotPath);
+  const antiPatterns = buildAntiPatterns(manifest, projectDir, target);
+  const designContext = buildDesignContext(manifest);
 
   return {
     mode: "bootstrap",
@@ -1259,6 +1355,8 @@ function buildBootstrapPrepareResult(cwd: string, target: string, includeContent
     items: [],
     ...(sharedLayerInfos.length > 0 ? { shared_layers: sharedLayerInfos } : {}),
     ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
+    ...(antiPatterns ? { anti_patterns: antiPatterns } : {}),
+    ...(designContext ? { design_context: designContext } : {}),
     bootstrap: {
       output_exists: existsSync(outputDir),
       generation_ready: missingDecisions.length === 0 && backendContextReady && !pendingUserConfirmation,
@@ -1290,6 +1388,8 @@ function buildUpdatePrepareResult(cwd: string, target: string, includeContents:
   const sharedLayerConfigs = sharedLayersForTarget(projectDir, target);
   const codeRoots = suggestCodeRoots(target, outputDir, projectDir, sharedLayerConfigs);
   const manifest = readManifest(projectDir);
+  const antiPatterns = buildAntiPatterns(manifest, projectDir, target);
+  const designContext = buildDesignContext(manifest);
   const sharedLayerInfos = buildSharedLayerInfos(projectDir, target, sharedLayerConfigs);
   const platformDef = readPlatformDefinition(projectDir, manifest, target);
   const platformConfig = buildPlatformConfig(target, platformDef);
@@ -1333,6 +1433,8 @@ function buildUpdatePrepareResult(cwd: string, target: string, includeContents:
     items,
     ...(sharedLayerInfos.length > 0 ? { shared_layers: sharedLayerInfos } : {}),
     ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
+    ...(antiPatterns ? { anti_patterns: antiPatterns } : {}),
+    ...(designContext ? { design_context: designContext } : {}),
     next_steps: nextSteps,
   };
 }

package/schema/component.schema.json

@@ -107,6 +107,11 @@
             "may_handle": {
               "type": "array",
               "items": { "type": "string" }
+            },
+            "must_avoid": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Anti-patterns for AI generators. Strings may start with [web], [ios], or [android] to scope to a platform. Unmarked items apply to all platforms."
             }
           },
           "additionalProperties": false

package/schema/contract.schema.json

@@ -71,6 +71,11 @@
             "may_handle": {
               "type": "array",
               "items": { "type": "string" }
+            },
+            "must_avoid": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Anti-patterns for AI generators. Strings may start with [web], [ios], or [android] to scope to a platform. Unmarked items apply to all platforms."
             }
           },
           "additionalProperties": false
@@ -116,7 +121,12 @@
           "properties": {
             "must_handle": { "type": "array", "items": { "type": "string" } },
             "should_handle": { "type": "array", "items": { "type": "string" } },
-            "may_handle": { "type": "array", "items": { "type": "string" } }
+            "may_handle": { "type": "array", "items": { "type": "string" } },
+            "must_avoid": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Anti-patterns for AI generators. Strings may start with [web], [ios], or [android] to scope to a platform. Unmarked items apply to all platforms."
+            }
           },
           "additionalProperties": false
         }

package/schema/custom-contract.schema.json

@@ -112,6 +112,11 @@
               "type": "array",
               "items": { "type": "string" },
               "description": "Optional enhancements the generator MAY implement"
+            },
+            "must_avoid": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Anti-patterns for AI generators. Strings may start with [web], [ios], or [android] to scope to a platform. Unmarked items apply to all platforms."
             }
           },
           "additionalProperties": false

package/schema/openuispec.schema.json

@@ -259,6 +259,53 @@
         "type": "string"
       }
     },
+    "design": {
+      "type": "object",
+      "description": "Design intent and anti-patterns for this project",
+      "properties": {
+        "personality": { "type": "string", "description": "Brief description of the brand's visual personality" },
+        "complexity": {
+          "type": "string",
+          "enum": ["restrained", "balanced", "elaborate"],
+          "default": "balanced",
+          "description": "How elaborate animations, effects, and visual details should be"
+        },
+        "audience": { "type": "string", "description": "Who uses this app — informs tone and complexity" },
+        "avoid": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Project-specific anti-patterns. May use [web]/[ios]/[android] scope tags."
+        }
+      },
+      "additionalProperties": false
+    },
+    "generation_guidance": {
+      "type": "object",
+      "description": "Universal anti-patterns and audit config for AI generators",
+      "properties": {
+        "universal_anti_patterns": {
+          "type": "object",
+          "description": "Cross-contract anti-patterns by domain",
+          "properties": {
+            "typography": { "type": "array", "items": { "type": "string" } },
+            "color": { "type": "array", "items": { "type": "string" } },
+            "spacing": { "type": "array", "items": { "type": "string" } },
+            "motion": { "type": "array", "items": { "type": "string" } },
+            "elevation": { "type": "array", "items": { "type": "string" } },
+            "layout": { "type": "array", "items": { "type": "string" } },
+            "accessibility": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": false
+        },
+        "audit_threshold": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Minimum design quality score. Default 0 (informational). --min-score CLI flag takes precedence."
+        }
+      },
+      "additionalProperties": false
+    },
     "api": {
       "type": "object",
       "description": "API endpoint definitions",

package/schema/tokens/color.schema.json

@@ -75,6 +75,11 @@
         },
         "contrast_min": {
           "type": "number"
+        },
+        "generation_notes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Sparse guidance for AI generators. Use [web]/[ios]/[android] tags for platform-specific notes."
         }
       },
       "required": [

package/schema/tokens/motion.schema.json

@@ -75,6 +75,11 @@
         "pattern": {
           "type": "string",
           "description": "Named animation pattern"
+        },
+        "generation_notes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Sparse guidance for AI generators. Use [web]/[ios]/[android] tags for platform-specific notes."
         }
       },
       "additionalProperties": false

package/schema/tokens/typography.schema.json

@@ -60,6 +60,11 @@
             }
           },
           "additionalProperties": false
+        },
+        "generation_notes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Sparse guidance for AI generators. Use [web]/[ios]/[android] tags for platform-specific notes."
         }
       },
       "required": [
@@ -93,6 +98,11 @@
             "capitalize",
             "none"
           ]
+        },
+        "generation_notes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Sparse guidance for AI generators. Use [web]/[ios]/[android] tags for platform-specific notes."
         }
       },
       "required": [

package/schema/validate.ts

@@ -399,6 +399,16 @@ function buildAjv(): AjvInstance {
 }
 
 const BASE = "https://openuispec.rsteam.uz/schema/";
+const TOKEN_FILE_SCHEMAS: Record<string, string> = {
+  "color.yaml": "color.schema.json",
+  "typography.yaml": "typography.schema.json",
+  "spacing.yaml": "spacing.schema.json",
+  "elevation.yaml": "elevation.schema.json",
+  "motion.yaml": "motion.schema.json",
+  "layout.yaml": "layout.schema.json",
+  "themes.yaml": "themes.schema.json",
+  "icons.yaml": "icons.schema.json",
+};
 
 // ── validate one file ────────────────────────────────────────────────
 
@@ -536,20 +546,13 @@ const GROUPS: Record<string, ValidationGroup> = {
     run(ajv, projectDir, includes) {
       let errors = 0;
       const tokensDir = resolveInclude(projectDir, includes.tokens);
-      const tokenMap: Record<string, string> = {
-        "color.yaml": "color.schema.json",
-        "typography.yaml": "typography.schema.json",
-        "spacing.yaml": "spacing.schema.json",
-        "elevation.yaml": "elevation.schema.json",
-        "motion.yaml": "motion.schema.json",
-        "layout.yaml": "layout.schema.json",
-        "themes.yaml": "themes.schema.json",
-        "icons.yaml": "icons.schema.json",
-      };
-      for (const [data, schema] of Object.entries(tokenMap)) {
+      for (const [data, schema] of Object.entries(TOKEN_FILE_SCHEMAS)) {
         const filePath = join(tokensDir, data);
         if (existsSync(filePath)) {
           errors += validateFile(ajv, filePath, `${BASE}tokens/${schema}`);
+        } else {
+          console.log(`  FAIL  ${data} (required token file is missing)`);
+          errors += 1;
         }
       }
       return errors;
@@ -557,20 +560,16 @@ const GROUPS: Record<string, ValidationGroup> = {
     collectJson(ajv, projectDir, includes, groupKey) {
       const errors: JsonError[] = [];
       const tokensDir = resolveInclude(projectDir, includes.tokens);
-      const tokenMap: Record<string, string> = {
-        "color.yaml": "color.schema.json",
-        "typography.yaml": "typography.schema.json",
-        "spacing.yaml": "spacing.schema.json",
-        "elevation.yaml": "elevation.schema.json",
-        "motion.yaml": "motion.schema.json",
-        "layout.yaml": "layout.schema.json",
-        "themes.yaml": "themes.schema.json",
-        "icons.yaml": "icons.schema.json",
-      };
-      for (const [data, schema] of Object.entries(tokenMap)) {
+      for (const [data, schema] of Object.entries(TOKEN_FILE_SCHEMAS)) {
         const filePath = join(tokensDir, data);
         if (existsSync(filePath)) {
           errors.push(...collectValidateFile(ajv, filePath, `${BASE}tokens/${schema}`));
+        } else {
+          errors.push({
+            file: data,
+            path: "(root)",
+            message: "required token file is missing",
+          });
         }
       }
       return { group: groupKey, errors };