openuispec 0.2.16 → 0.2.18

package/README.md

@@ -54,8 +54,9 @@ This scaffolds a spec directory, starter tokens, and **configures the MCP server
 - **Data binding** — reactive state, format expressions, caching, and loading/error/empty states
 - **Adaptive layout** — size classes (compact/regular/expanded) with per-section overrides
 - **Platform adaptation** — per-target overrides for iOS, Android, and Web behaviors
-- **Design intent** — `design` section in the manifest captures brand personality, complexity level, and audience — generators match visual elaborateness accordingly
-- **Anti-patterns** — `must_avoid` in contracts and `generation_guidance.universal_anti_patterns` in the manifest steer AI away from generic, statistically common design mistakes
+- **Design intent** — `design` section captures brand personality, complexity level (`restrained`/`balanced`/`elaborate`), quality tier (`mvp`/`production`/`flagship`), and audience — generators match visual elaborateness and polish level accordingly
+- **Anti-patterns** — `must_avoid` in contracts and `universal_anti_patterns` in the manifest (9 domains: typography, color, spacing, motion, elevation, layout, visual, interaction, accessibility) steer AI away from generic design mistakes. Platform-scoped with `[web]`/`[ios]`/`[android]` tags
+- **Design quality audit** — `check --audit` scores the spec against 18 heuristic checks across all token and contract domains, producing a numeric score with CI-gatable thresholds
 
 ## The 7 contract families
 
@@ -101,7 +102,7 @@ Screenshots of the generated apps are in the [artifacts](./artifacts/) directory
 |-----|-------------|
 | [CLI & MCP Tools](./docs/cli.md) | All CLI commands, MCP tools, screenshot params, target workflow |
 | [File Formats & Schemas](./docs/file-formats.md) | File types, JSON schemas, output directories, spec sections |
-| [Full Specification](./spec/openuispec-v0.2.md) | Complete v0.2 spec (15 sections) |
+| [Full Specification](./spec/openuispec-v0.2.md) | Complete v0.2 spec (16 sections) |
 | [llms-full.txt](https://openuispec.rsteam.uz/llms-full.txt) | Spec + all schemas in one file (for AI consumption) |
 
 ## Status

package/check/audit.ts

@@ -10,7 +10,7 @@
  *   openuispec check --target web --audit --format json
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import YAML from "yaml";
 
@@ -31,6 +31,16 @@ export interface AuditResult {
 }
 
 const AI_DEFAULT_FONTS = new Set(["Inter", "Roboto", "Arial", "Open Sans"]);
+const REQUIRED_TOKEN_FILES = [
+  "color.yaml",
+  "typography.yaml",
+  "spacing.yaml",
+  "elevation.yaml",
+  "motion.yaml",
+  "layout.yaml",
+  "themes.yaml",
+  "icons.yaml",
+];
 
 function readYaml(path: string): any {
   try {
@@ -40,8 +50,36 @@ function readYaml(path: string): any {
   }
 }
 
+function readYamlForAudit(path: string, domain: string, findings: AuditFinding[]): any {
+  try {
+    return YAML.parse(readFileSync(path, "utf-8"));
+  } catch (err: any) {
+    if (err?.code === "ENOENT") return null;
+    findings.push({
+      domain,
+      rule: "unreadable_file",
+      severity: "error",
+      message: `Could not parse "${path}". Fix malformed YAML before relying on this audit.`,
+    });
+    return null;
+  }
+}
+
+function checkRequiredTokenFiles(tokensDir: string, findings: AuditFinding[]): void {
+  for (const filename of REQUIRED_TOKEN_FILES) {
+    if (!existsSync(join(tokensDir, filename))) {
+      findings.push({
+        domain: "tokens",
+        rule: "missing_file",
+        severity: "error",
+        message: `Required token file "${filename}" is missing.`,
+      });
+    }
+  }
+}
+
 function checkTypography(tokensDir: string, findings: AuditFinding[]): void {
-  const doc = readYaml(join(tokensDir, "typography.yaml"));
+  const doc = readYamlForAudit(join(tokensDir, "typography.yaml"), "typography", findings);
   if (!doc?.typography) return;
 
   // Font diversity: primary must NOT be a common AI default
@@ -65,10 +103,28 @@ function checkTypography(tokensDir: string, findings: AuditFinding[]): void {
       message: `Only ${scaleKeys.length} type scale level(s) defined. Use ≥4 distinct levels for clear hierarchy.`,
     });
   }
+
+  // Weight hierarchy: at least 2 distinct weights
+  if (doc.typography.scale) {
+    const weights = new Set<number>();
+    for (const level of Object.values(doc.typography.scale)) {
+      if (typeof (level as any)?.weight === "number") {
+        weights.add((level as any).weight);
+      }
+    }
+    if (weights.size > 0 && weights.size < 2) {
+      findings.push({
+        domain: "typography",
+        rule: "weight_hierarchy",
+        severity: "warning",
+        message: "Only 1 distinct font weight used across the type scale. Use ≥2 weights (e.g. 400 + 700) for clear hierarchy.",
+      });
+    }
+  }
 }
 
 function checkColor(tokensDir: string, findings: AuditFinding[]): void {
-  const doc = readYaml(join(tokensDir, "color.yaml"));
+  const doc = readYamlForAudit(join(tokensDir, "color.yaml"), "color", findings);
   if (!doc?.color) return;
 
   // Pure black/white check
@@ -101,10 +157,27 @@ function checkColor(tokensDir: string, findings: AuditFinding[]): void {
   }
   scanForPure(doc.color, "color");
 
+  // Semantic color completeness: success, warning, danger, info
+  if (doc.color.semantic) {
+    const required = ["success", "warning", "danger", "info"];
+    const defined = Object.keys(doc.color.semantic);
+    for (const name of required) {
+      if (!defined.includes(name)) {
+        findings.push({
+          domain: "color",
+          rule: "semantic_completeness",
+          severity: "warning",
+          message: `Semantic color "${name}" is missing. Define all four (success, warning, danger, info) for complete state coverage.`,
+        });
+      }
+    }
+  }
+
   // Theme coverage: check themes.yaml for both light + dark
   {
-    const themes = readYaml(join(tokensDir, "themes.yaml"));
-    const themeKeys = Object.keys(themes?.themes ?? {});
+    const themes = readYamlForAudit(join(tokensDir, "themes.yaml"), "color", findings);
+    if (!themes?.themes) return;
+    const themeKeys = Object.keys(themes.themes);
     const hasLight = themeKeys.some((k) => k.includes("light"));
     const hasDark = themeKeys.some((k) => k.includes("dark"));
     if (!hasLight || !hasDark) {
@@ -119,7 +192,7 @@ function checkColor(tokensDir: string, findings: AuditFinding[]): void {
 }
 
 function checkSpacing(tokensDir: string, findings: AuditFinding[]): void {
-  const doc = readYaml(join(tokensDir, "spacing.yaml"));
+  const doc = readYamlForAudit(join(tokensDir, "spacing.yaml"), "spacing", findings);
   if (!doc?.spacing) return;
 
   // Scale usage: at least 4 distinct values
@@ -156,7 +229,7 @@ function checkSpacing(tokensDir: string, findings: AuditFinding[]): void {
 }
 
 function checkMotion(tokensDir: string, findings: AuditFinding[]): void {
-  const doc = readYaml(join(tokensDir, "motion.yaml"));
+  const doc = readYamlForAudit(join(tokensDir, "motion.yaml"), "motion", findings);
   if (!doc?.motion) return;
 
   // Duration variety: at least 2 distinct durations
@@ -180,12 +253,110 @@ function checkMotion(tokensDir: string, findings: AuditFinding[]): void {
       message: "motion.reduced_motion is not defined. Must specify policy for prefers-reduced-motion.",
     });
   }
+
+  // Easing quality: enter + exit curves, at least one cubic-bezier
+  if (doc.motion.easing) {
+    const easings = doc.motion.easing;
+    const keys = Object.keys(easings);
+    if (!keys.includes("enter") || !keys.includes("exit")) {
+      findings.push({
+        domain: "motion",
+        rule: "easing_quality",
+        severity: "warning",
+        message: "Motion easing should define at least 'enter' and 'exit' curves for asymmetric transitions.",
+      });
+    }
+    const hasCubicBezier = Object.values(easings).some(
+      (v) => typeof v === "string" && v.includes("cubic-bezier"),
+    );
+    if (!hasCubicBezier) {
+      findings.push({
+        domain: "motion",
+        rule: "easing_quality",
+        severity: "warning",
+        message: "All easing curves are generic keywords. Use at least one cubic-bezier() for nuanced motion.",
+      });
+    }
+  }
+}
+
+function checkElevationProgression(tokensDir: string, findings: AuditFinding[]): void {
+  const doc = readYamlForAudit(join(tokensDir, "elevation.yaml"), "elevation", findings);
+  if (!doc?.elevation) return;
+  const levels = Object.keys(doc.elevation).filter((k) => k !== "none");
+  if (levels.length < 2) {
+    findings.push({
+      domain: "elevation",
+      rule: "level_count",
+      severity: "warning",
+      message: `Only ${levels.length} non-none elevation level(s) defined. Define ≥2 (e.g. sm, md, lg) for meaningful depth hierarchy.`,
+    });
+    return;
+  }
+  const androidValues: number[] = [];
+  for (const level of levels) {
+    const val = doc.elevation[level]?.platform?.android?.elevation;
+    if (typeof val === "number") androidValues.push(val);
+  }
+  if (androidValues.length >= 2) {
+    for (let i = 1; i < androidValues.length; i++) {
+      if (androidValues[i] <= androidValues[i - 1]) {
+        findings.push({
+          domain: "elevation",
+          rule: "progression",
+          severity: "warning",
+          message: "Elevation levels do not increase monotonically. Each level should cast a deeper shadow than the previous.",
+        });
+        break;
+      }
+    }
+  }
+}
+
+function checkLayoutSizeClasses(tokensDir: string, findings: AuditFinding[]): void {
+  const doc = readYamlForAudit(join(tokensDir, "layout.yaml"), "layout", findings);
+  if (!doc?.layout?.size_classes) return;
+  const classes = Object.keys(doc.layout.size_classes);
+  if (classes.length < 2) {
+    findings.push({
+      domain: "layout",
+      rule: "size_class_coverage",
+      severity: "warning",
+      message: `Only ${classes.length} size class(es) defined. Define at least compact + regular for responsive layouts.`,
+    });
+  } else if (!classes.includes("compact")) {
+    findings.push({
+      domain: "layout",
+      rule: "size_class_coverage",
+      severity: "warning",
+      message: "No 'compact' size class defined. Mobile-first layouts require a compact breakpoint.",
+    });
+  }
+}
+
+function checkContractStateCoverage(contractsDir: string, findings: AuditFinding[]): void {
+  if (!existsSync(contractsDir)) return;
+  for (const file of readdirSync(contractsDir).filter((f) => f.endsWith(".yaml") && !f.startsWith("x_"))) {
+    const doc = readYamlForAudit(join(contractsDir, file), "contracts", findings);
+    if (!doc) continue;
+    const contractName = Object.keys(doc)[0];
+    const contract = doc[contractName];
+    const mustHandle: string[] = contract?.generation?.must_handle ?? [];
+    if (mustHandle.length === 0) {
+      findings.push({
+        domain: "contracts",
+        rule: "state_coverage",
+        severity: "warning",
+        message: `Contract "${contractName}" has no generation.must_handle entries. Define required states for AI compliance.`,
+      });
+    }
+  }
 }
 
 function checkContracts(contractsDir: string, findings: AuditFinding[]): void {
   // All collections have empty_state in must_handle or variants
   {
-    const doc = readYaml(join(contractsDir, "collection.yaml"));
+    const doc = readYamlForAudit(join(contractsDir, "collection.yaml"), "contracts", findings);
     const collection = doc ? doc[Object.keys(doc)[0]] : null;
     if (collection) {
       const mustHandle: string[] = collection.generation?.must_handle ?? [];
@@ -211,11 +382,15 @@ export function buildAuditResult(projectDir: string, threshold: number = 0): Aud
   const effectiveThreshold = threshold > 0 ? threshold : (manifest?.generation_guidance?.audit_threshold ?? 0);
 
   const findings: AuditFinding[] = [];
+  checkRequiredTokenFiles(tokensDir, findings);
   checkTypography(tokensDir, findings);
   checkColor(tokensDir, findings);
   checkSpacing(tokensDir, findings);
   checkMotion(tokensDir, findings);
+  checkElevationProgression(tokensDir, findings);
+  checkLayoutSizeClasses(tokensDir, findings);
   checkContracts(contractsDir, findings);
+  checkContractStateCoverage(contractsDir, findings);
 
   const errors = findings.filter((f) => f.severity === "error").length;
   const warnings = findings.filter((f) => f.severity === "warning").length;

package/docs/cli.md

@@ -289,10 +289,15 @@ openuispec check --target web --audit --json           # machine-readable output
 
 | Domain | What's checked |
 |--------|---------------|
-| Typography | Primary font not an AI default (Inter/Roboto/Arial/Open Sans) · ≥4 scale levels defined |
-| Color | No pure #000000/#FFFFFF · Both light + dark themes present |
+| Tokens | All 8 required token files exist |
+| Typography | Primary font not an AI default · ≥4 scale levels · ≥2 distinct weights |
+| Color | No pure #000000/#FFFFFF · success/warning/danger/info semantic colors · light + dark themes |
 | Spacing | ≥4 scale values · `page_margin` and `card_padding` aliases present |
-| Motion | ≥2 distinct durations · `reduced_motion` policy defined |
-| Contracts | `collection` has `empty_state` in `must_handle` |
+| Motion | ≥2 distinct durations · `reduced_motion` policy · enter/exit easing · ≥1 cubic-bezier curve |
+| Elevation | ≥2 non-none levels · monotonically increasing progression |
+| Layout | ≥2 size classes · compact class defined |
+| Contracts | `collection` has `empty_state` in `must_handle` · all contracts have non-empty `must_handle` |
 
 The `audit_threshold` in `generation_guidance` sets the project-wide minimum score. `--min-score` overrides it per-run.
+
+See [Section 16 of the spec](../spec/openuispec-v0.2.md#16-design-intent-and-generation-guidance) for complete documentation of design intent, anti-patterns, and quality tiers.

package/docs/implementation-notes.md

@@ -166,6 +166,6 @@
 
 `openuispec check --audit` runs design quality heuristics against token and contract files, returning a numeric score (`max(0, 100 - errors × 10 - warnings × 3)`) and categorized findings. The `audit_threshold` in `generation_guidance` sets a project-wide minimum; `--min-score N` overrides per-run.
 
-`openuispec prepare` includes `anti_patterns` (universal + contract-specific + project-specific, filtered by target platform) and `design_context` (personality, complexity, audience, complexity_rule) in its output when the manifest defines `generation_guidance` and `design` sections.
+`openuispec prepare` includes `anti_patterns` (universal + contract-specific + project-specific, filtered by target platform) and `design_context` (personality, complexity, quality_tier, audience, complexity_rule, quality_tier_rule, quality_test) in its output when the manifest defines `generation_guidance` and `design` sections. The `quality_test` field is an auto-generated AI-slop checklist tuned to the project's complexity and quality tier.
 
 `generation.extra_rules` in the manifest is included in prepare output and filtered by platform tag.

package/examples/social-app/openuispec/openuispec.yaml

@@ -57,6 +57,15 @@ generation_guidance:
     layout:
       - "Do not assume large-screen layouts work on compact — every multi-pane pattern needs an explicit compact fallback"
       - "Do not use pixel breakpoints — reference size classes by name (compact, regular, expanded)"
+    visual:
+      - "Do not flatten depth — use elevation tokens to separate layers and give content visual weight"
+      - "Do not use generic drop shadows — map every shadow to a specific elevation level from tokens"
+      - "Do not apply glassmorphism to interactive controls — reserve frosted effects for non-interactive overlays only"
+    interaction:
+      - "Do not make swipe gestures the only way to access actions — provide a visible alternative"
+      - "Do not delay visual feedback on tap — social content requires instant response"
+      - "[web] Do not use :focus for focus rings — use :focus-visible to show rings only for keyboard navigation"
+      - "[ios] Do not replace native swipe-back with custom gestures — users expect system navigation"
     accessibility:
       - "Do not use color as the only differentiator between states — combine with icon, border, or text changes"
       - "Do not skip focus ring styles — keyboard users must see where focus is at all times"
@@ -66,6 +75,7 @@ generation_guidance:
 design:
   personality: "Vibrant, social, content-rich — engagement and discovery are primary, utility is secondary"
   complexity: "elaborate"
+  quality_tier: "flagship"
   audience: "Mobile-first social media users who expect rich media, smooth animations, and expressive interactions"
   avoid:
     - "Do not use muted or desaturated brand colors — the palette should feel energetic"

package/examples/taskflow/openuispec/openuispec.yaml

@@ -64,6 +64,14 @@ generation_guidance:
     layout:
       - "Do not assume large-screen layouts work on compact — every multi-pane pattern needs an explicit compact fallback"
       - "Do not use pixel breakpoints — reference size classes by name (compact, regular, expanded)"
+    visual:
+      - "Do not use glassmorphism or frosted-glass effects — this is a professional productivity tool"
+      - "Do not apply gradient text — it fails contrast checks and looks dated"
+      - "[web] Do not use box-shadow on every container — reserve elevation for interactive or raised elements"
+    interaction:
+      - "Do not treat hover and focus as the same state — keyboard users never see hover"
+      - "Do not use confirmation dialogs for reversible actions — use undo with a toast instead"
+      - "[web] Do not use :focus for focus rings — use :focus-visible to show rings only for keyboard navigation"
     accessibility:
       - "Do not use color as the only differentiator between states — combine with icon, border, or text changes"
       - "Do not skip focus ring styles — keyboard users must see where focus is at all times"
@@ -73,6 +81,7 @@ generation_guidance:
 design:
   personality: "Clean, focused, productivity-first — no decorative flourishes. Color is used for priority and status clarity, not aesthetics."
   complexity: "balanced"
+  quality_tier: "production"
   audience: "Individual contributors and small teams managing personal and shared task lists"
   avoid:
     - "Do not use playful or rounded UI patterns — this is a professional productivity tool"

package/examples/todo-orbit/openuispec/openuispec.yaml

@@ -63,6 +63,16 @@ generation_guidance:
     layout:
       - "Do not assume large-screen layouts work on compact — every multi-pane pattern needs an explicit compact fallback"
       - "Do not use pixel breakpoints — reference size classes by name (compact, regular, expanded)"
+    visual:
+      - "Do not mix rounded and sharp corners within the same card or surface — the spec uses cut-corner shapes exclusively"
+      - "Do not add decorative gradients, glows, or background textures — this is a restrained design"
+      - "Do not apply gradient text — it fails contrast checks and undermines the minimal aesthetic"
+      - "[web] Do not use box-shadow on every container — reserve elevation for interactive or raised elements"
+    interaction:
+      - "Do not treat hover and focus as the same state — keyboard users never see hover"
+      - "Do not use long-press as the primary action trigger — use explicit buttons or swipe actions"
+      - "Do not delay visual feedback on tap — the press_feedback pattern requires instant response"
+      - "[web] Do not use :focus for focus rings — use :focus-visible to show rings only for keyboard navigation"
     accessibility:
       - "Do not use color as the only differentiator between states — combine with icon, border, or text changes"
       - "Do not skip focus ring styles — keyboard users must see where focus is at all times"
@@ -72,6 +82,7 @@ generation_guidance:
 design:
   personality: "Minimal and calm — orbital metaphor suggests clarity and organization without visual noise"
   complexity: "restrained"
+  quality_tier: "production"
   audience: "Bilingual individuals who prefer a clean, low-distraction task environment"
   avoid:
     - "Do not add decorative illustrations or background patterns"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/prepare/index.ts

@@ -180,8 +180,11 @@ export interface PrepareResult {
   design_context?: {
     personality?: string;
     complexity: 'restrained' | 'balanced' | 'elaborate';
+    quality_tier: 'mvp' | 'production' | 'flagship';
     audience?: string;
     complexity_rule: string;
+    quality_tier_rule: string;
+    quality_test: string;
   };
   next_steps: string[];
 }
@@ -666,8 +669,8 @@ function generationRules(target: string, outputDir: string, manifest: Record<str
 }
 
 function matchesTargetPlatform(item: string, target: string): boolean {
-  const tagMatch = item.match(/^\[([a-z]+)\]/);
-  return !tagMatch || tagMatch[1] === target;
+  const tagMatch = item.match(/^\[([a-z]+)\]/i);
+  return !tagMatch || tagMatch[1].toLowerCase() === target;
 }
 
 function complexityRule(complexity: string): string {
@@ -681,15 +684,63 @@ function complexityRule(complexity: string): string {
   }
 }
 
+function qualityTierRule(tier: string): string {
+  switch (tier) {
+    case 'mvp':
+      return 'Functional-only. Use semantic tokens but tolerate simple layouts. Skip elevation, motion patterns, and adaptive breakpoints.';
+    case 'flagship':
+      return 'Pixel-perfect. Every token, motion pattern, elevation level, and adaptive breakpoint must be implemented. All contract states required. No shortcuts.';
+    default:
+      return 'Production-quality. Apply all tokens, handle accessibility, support adaptive breakpoints. Motion and elevation expected but minor shortcuts acceptable.';
+  }
+}
+
+function buildQualityTest(complexity: string, qualityTier: string, personality?: string): string {
+  const items: string[] = [
+    'Inter/Roboto/Arial as the primary font when the spec defines a custom font_family.',
+    'Pure black (#000000) or pure white (#FFFFFF) — all colors must resolve through tokens.',
+    'Cyan-on-dark, purple-to-blue gradient, or neon accent color schemes not in color tokens.',
+    'Card-wrapping every content group — cards are for distinct, comparable items only.',
+    'Identical spacing values throughout — the spec defines a scale with distinct levels.',
+    'Bounce or elastic easing — use only the easing curves from motion tokens.',
+    'Shadows on elements with no elevation token assigned.',
+    'A single font weight everywhere — the type scale defines multiple weights for hierarchy.',
+  ];
+
+  if (complexity === 'restrained') {
+    items.push('Any decorative animation, gradient, glassmorphism, or background effect — this is a restrained design.');
+  } else if (complexity === 'elaborate') {
+    items.push('Missing entrance animations or transition effects — this is an elaborate design that expects rich motion.');
+  }
+
+  if (qualityTier === 'flagship') {
+    items.push('Any adaptive breakpoint missing — flagship quality requires all size classes implemented.');
+    items.push('Any must_handle state not implemented — flagship requires full contract compliance.');
+  }
+
+  const numbered = items.map((item, i) => `${i + 1}. ${item}`);
+  numbered.unshift('After generation, verify the output does NOT exhibit these AI-slop indicators:');
+
+  if (personality) {
+    numbered.push(`Design personality check: "${personality}" — verify the output tone matches.`);
+  }
+
+  return numbered.join('\n');
+}
+
 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';
+  const tier = (design.quality_tier as 'mvp' | 'production' | 'flagship') ?? 'production';
   return {
     ...(design.personality ? { personality: design.personality } : {}),
     complexity,
+    quality_tier: tier,
     ...(design.audience ? { audience: design.audience } : {}),
     complexity_rule: complexityRule(complexity),
+    quality_tier_rule: qualityTierRule(tier),
+    quality_test: buildQualityTest(complexity, tier, design.personality),
   };
 }
 
@@ -710,10 +761,10 @@ function buildAntiPatterns(
 
   // Contract-specific must_avoid
   const contract_specific: Record<string, string[]> = {};
-  try {
-    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_'))) {
+  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 ?? [];
@@ -721,9 +772,11 @@ function buildAntiPatterns(
           const filtered = mustAvoid.filter((item: string) => matchesTargetPlatform(item, target));
           if (filtered.length > 0) contract_specific[contractName] = filtered;
         }
+      } catch {
+        continue;
       }
     }
-  } catch { /* skip on error */ }
+  }
 
   // Project-specific avoid from design section
   const project_specific: string[] = [];
@@ -1386,6 +1439,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);
@@ -1429,6 +1484,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/openuispec.schema.json

@@ -271,6 +271,12 @@
           "description": "How elaborate animations, effects, and visual details should be"
         },
         "audience": { "type": "string", "description": "Who uses this app — informs tone and complexity" },
+        "quality_tier": {
+          "type": "string",
+          "enum": ["mvp", "production", "flagship"],
+          "default": "production",
+          "description": "Quality bar — mvp: functional-only, production: polished with full tokens, flagship: pixel-perfect with every state and motion pattern"
+        },
         "avoid": {
           "type": "array",
           "items": { "type": "string" },
@@ -293,6 +299,8 @@
             "motion": { "type": "array", "items": { "type": "string" } },
             "elevation": { "type": "array", "items": { "type": "string" } },
             "layout": { "type": "array", "items": { "type": "string" } },
+            "visual": { "type": "array", "items": { "type": "string" } },
+            "interaction": { "type": "array", "items": { "type": "string" } },
             "accessibility": { "type": "array", "items": { "type": "string" } }
           },
           "additionalProperties": false

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

package/spec/openuispec-v0.2.md

@@ -92,19 +92,23 @@ generation:
     ios: { language: swift, framework: swiftui }
     android: { language: kotlin, framework: compose }
     web: { language: typescript, framework: react }
-  # shared:                          # optional: cross-platform shared code layers
-  #   mobile_common:
-  #     platforms: [ios, android]
-  #     language: kotlin
-  #     root: "../shared"
-  #     scope: "Business logic, data models, repositories, view models. No UI."
-  #     paths:
-  #       domain: "commonMain/domain/"
-  # structure:                       # optional: per-target directory structure (overrides heuristics)
-  #   ios:
-  #     root: "../shared"
-  #     scope: "Pure SwiftUI views and navigation."
-  #     paths: { ui: "iosApp/ui/" }
+
+generation_guidance:                 # Section 16.2
+  universal_anti_patterns:
+    typography:
+      - "Do not fall back to Inter, Roboto, Arial, or system defaults"
+    color:
+      - "Do not use pure black (#000000) or pure white (#FFFFFF)"
+    # ... additional domains: spacing, motion, elevation, layout, visual, interaction, accessibility
+  audit_threshold: 70
+
+design:                              # Section 16.1
+  personality: "Clean, focused..."
+  complexity: "balanced"             # restrained | balanced | elaborate
+  quality_tier: "production"         # mvp | production | flagship
+  audience: "..."
+  avoid:
+    - "Do not use decorative gradients"
 ```
 
 ---
@@ -4098,6 +4102,148 @@ Each `.yaml` file in the components directory defines one component. The file mu
 
 ---
 
+## 16. Design intent and generation guidance
+
+This section defines how the manifest communicates design intent, anti-patterns, and quality expectations to AI generators.
+
+### 16.1 Design section
+
+The `design` section in `openuispec.yaml` captures the project's visual identity and quality bar:
+
+```yaml
+design:
+  personality: "Minimal and calm — clarity over decoration"
+  complexity: "restrained"           # restrained | balanced | elaborate
+  quality_tier: "production"         # mvp | production | flagship
+  audience: "Professionals who prefer low-distraction tools"
+  avoid:
+    - "Do not add decorative illustrations or background patterns"
+    - "[web] Do not use CSS animations for non-interactive purposes"
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `personality` | string | — | Brief description of the brand's visual personality |
+| `complexity` | enum | `balanced` | How elaborate animations, effects, and visual details should be |
+| `quality_tier` | enum | `production` | Quality bar for this project |
+| `audience` | string | — | Who uses this app — informs tone and complexity |
+| `avoid` | string[] | — | Project-specific anti-patterns. May use `[web]`/`[ios]`/`[android]` scope tags |
+
+**Complexity levels:**
+
+| Level | Meaning |
+|-------|---------|
+| `restrained` | Minimal motion (required state transitions only). No decorative shadows. Clean whitespace. No background effects. |
+| `balanced` | Apply all motion patterns. Use elevation tokens fully. Standard state animations. |
+| `elaborate` | Rich animations with staggered reveals. Creative elevation. Platform-specific flourishes. |
+
+**Quality tiers:**
+
+| Tier | Meaning |
+|------|---------|
+| `mvp` | Functional-only. Use semantic tokens but tolerate simple layouts. Skip elevation, motion patterns, and adaptive breakpoints. |
+| `production` | Production-quality. Apply all tokens, handle accessibility, support adaptive breakpoints. Motion and elevation expected. |
+| `flagship` | Pixel-perfect. Every token, motion pattern, elevation level, and adaptive breakpoint must be implemented. All contract states required. No shortcuts. |
+
+### 16.2 Generation guidance
+
+The `generation_guidance` section in `openuispec.yaml` provides cross-contract anti-patterns and quality thresholds:
+
+```yaml
+generation_guidance:
+  universal_anti_patterns:
+    typography:
+      - "Do not fall back to Inter, Roboto, Arial, or system defaults when the spec defines a custom font_family"
+    color:
+      - "Do not use pure black (#000000) or pure white (#FFFFFF)"
+    visual:
+      - "Do not apply gradient text — it fails contrast checks"
+    interaction:
+      - "Do not treat hover and focus as the same state"
+    # ... additional domains
+  audit_threshold: 70
+```
+
+**Anti-pattern domains:**
+
+| Domain | Scope |
+|--------|-------|
+| `typography` | Font choices, weights, scale usage |
+| `color` | Palettes, contrast, pure values |
+| `spacing` | Scale adherence, alias usage |
+| `motion` | Easing, duration, reduced-motion |
+| `elevation` | Shadow usage, depth hierarchy |
+| `layout` | Size classes, breakpoints, card usage |
+| `visual` | Decoration, gradients, glassmorphism |
+| `interaction` | State handling, focus vs hover, gestures |
+| `accessibility` | Color-only differentiation, focus rings, tab order |
+
+Anti-patterns are scoped with platform tags (`[web]`, `[ios]`, `[android]`). The `prepare` command filters them to the target platform before delivery to the generator.
+
+Anti-patterns exist at three levels:
+1. **Universal** — `generation_guidance.universal_anti_patterns` in the manifest (cross-contract)
+2. **Contract-specific** — `generation.must_avoid` in each contract file
+3. **Project-specific** — `design.avoid` in the manifest
+
+### 16.3 Design quality audit
+
+The `check --audit` command scores the spec against design quality heuristics.
+
+**Score formula:** `max(0, 100 - errors × 10 - warnings × 3)`
+
+**Checks performed:**
+
+| Domain | Rule | Severity | What it catches |
+|--------|------|----------|----------------|
+| tokens | `missing_file` | error | Required token file not found |
+| typography | `font_diversity` | error | Primary font is an AI default (Inter, Roboto, Arial, Open Sans) |
+| typography | `scale_usage` | warning | Fewer than 4 type scale levels |
+| typography | `weight_hierarchy` | warning | Single font weight across the entire type scale |
+| color | `pure_black` | error | Literal #000000 in token values |
+| color | `pure_white` | error | Literal #FFFFFF in token values |
+| color | `semantic_completeness` | warning | Missing success, warning, danger, or info semantic color |
+| color | `theme_coverage` | warning | Missing light or dark theme |
+| spacing | `scale_usage` | warning | Fewer than 4 spacing scale values |
+| spacing | `alias_page_margin` | warning | No page_margin alias defined |
+| spacing | `alias_card_padding` | warning | No card_padding alias defined |
+| motion | `duration_variety` | warning | Single duration value for all animations |
+| motion | `reduced_motion` | error | No reduced_motion policy |
+| motion | `easing_quality` | warning | Missing enter/exit curves or no cubic-bezier easing |
+| elevation | `level_count` | warning | Fewer than 2 non-none elevation levels |
+| elevation | `progression` | warning | Elevation levels not monotonically increasing |
+| layout | `size_class_coverage` | warning | Fewer than 2 size classes or no compact class |
+| contracts | `collection_empty_state` | warning | Collection missing empty_state in must_handle |
+| contracts | `state_coverage` | warning | Contract with empty must_handle |
+
+The `audit_threshold` in `generation_guidance` sets the project-wide minimum score. The `--min-score` CLI flag overrides it per-run.
+
+### 16.4 Prepare output
+
+The `prepare` command includes `design_context` and `anti_patterns` in its output for AI generators:
+
+```json
+{
+  "design_context": {
+    "personality": "Minimal and calm...",
+    "complexity": "restrained",
+    "quality_tier": "production",
+    "audience": "...",
+    "complexity_rule": "Minimal motion (required state transitions only)...",
+    "quality_tier_rule": "Production-quality. Apply all tokens...",
+    "quality_test": "After generation, verify the output does NOT exhibit these AI-slop indicators:\n1. Inter/Roboto/Arial as the primary font..."
+  },
+  "anti_patterns": {
+    "universal": { "typography": ["..."], "color": ["..."] },
+    "contract_specific": { "action_trigger": ["..."] },
+    "project_specific": ["..."]
+  }
+}
+```
+
+The `quality_test` field is an auto-generated checklist tuned to the project's complexity and quality tier. AI generators should use it as a post-generation self-review step.
+
+---
+
 ## Appendix A: Type reference
 
 | Type | Description | Example |