openuispec 0.2.17 → 0.2.19

package/README.md

@@ -19,19 +19,11 @@ The result: each platform feels native, but every app stays semantically consist
 
 ## How it works
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/how-it-works-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/how-it-works-light.png">
-  <img alt="How OpenUISpec works" src="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/how-it-works-light.png">
-</picture>
+<img alt="How OpenUISpec works" src="./docs/images/how-it-works.svg">
 
 ## Workflows
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/workflows-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/workflows-light.png">
-  <img alt="OpenUISpec workflows" src="https://raw.githubusercontent.com/rsktash/openuispec/main/docs/images/workflows-light.png">
-</picture>
+<img alt="OpenUISpec workflows" src="./docs/images/workflows.svg">
 
 ## Quick start
 
@@ -54,8 +46,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 +94,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 { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import YAML from "yaml";
 
@@ -103,6 +103,24 @@ 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 {
@@ -139,6 +157,22 @@ 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 = readYamlForAudit(join(tokensDir, "themes.yaml"), "color", findings);
@@ -219,6 +253,104 @@ 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 {
@@ -255,7 +387,10 @@ export function buildAuditResult(projectDir: string, threshold: number = 0): Aud
   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/images/how-it-works.svg

@@ -0,0 +1,56 @@
+<svg width="100%" viewBox="0 0 680 470" xmlns="http://www.w3.org/2000/svg">
+<defs>
+<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></marker>
+
+<mask id="imagine-text-gaps-o7de63" maskUnits="userSpaceOnUse"><rect x="0" y="0" width="680" height="470" fill="white"/><rect x="256.6324462890625" y="12.305379867553711" width="166.73512268066406" height="20.52798843383789" fill="black" rx="2"/><rect x="69.6505126953125" y="62.305381774902344" width="90.69898223876953" height="20.527990341186523" fill="black" rx="2"/><rect x="46.96881103515625" y="84.19429016113281" width="136.0624237060547" height="18.16684913635254" fill="black" rx="2"/><rect x="91.05573272705078" y="120.19429779052734" width="47.88853454589844" height="18.16684913635254" fill="black" rx="2"/><rect x="83.20494079589844" y="156.1942901611328" width="63.590126037597656" height="18.16684913635254" fill="black" rx="2"/><rect x="75.04055786132812" y="192.19430541992188" width="79.91889953613281" height="18.16684913635254" fill="black" rx="2"/><rect x="88.12275695800781" y="228.19430541992188" width="53.75449752807617" height="18.16684913635254" fill="black" rx="2"/><rect x="94.92210388183594" y="264.1943054199219" width="40.15579605102539" height="18.16684913635254" fill="black" rx="2"/><rect x="69.73905181884766" y="300.1943054199219" width="90.52189636230469" height="18.16684913635254" fill="black" rx="2"/><rect x="67.63247680664062" y="336.1943054199219" width="94.73506164550781" height="18.16684913635254" fill="black" rx="2"/><rect x="73.51688385009766" y="372.1943054199219" width="82.96624755859375" height="18.16684913635254" fill="black" rx="2"/><rect x="217" y="214.1942901611328" width="35.17526435852051" height="18.16684913635254" fill="black" rx="2"/><rect x="292.1412048339844" y="152.30538940429688" width="89.71763610839844" height="20.527990341186523" fill="black" rx="2"/><rect x="300.2318115234375" y="174.1942901611328" width="73.53643798828125" height="18.16684913635254" fill="black" rx="2"/><rect x="280.6084899902344" y="208.1942901611328" width="112.78303527832031" height="18.16684913635254" fill="black" rx="2"/><rect x="272.58062744140625" y="244.1942901611328" width="128.83879852294922" height="18.16684913635254" fill="black" rx="2"/><rect x="288.5773620605469" y="280.1943054199219" width="96.84532928466797" height="18.16684913635254" fill="black" rx="2"/><rect x="442.0000305175781" y="138.1942901611328" width="36.606706619262695" height="18.16684913635254" fill="black" rx="2"/><rect x="442.0000305175781" y="214.1942901611328" width="39.89016914367676" height="18.16684913635254" fill="black" rx="2"/><rect x="442.0000305175781" y="304.1943054199219" width="69.11670303344727" height="18.16684913635254" fill="black" rx="2"/><rect x="519.6734619140625" y="106.30538177490234" width="98.65308380126953" height="20.527990341186523" fill="black" rx="2"/><rect x="507.6279602050781" y="128.1942901611328" width="122.74410247802734" height="18.16684913635254" fill="black" rx="2"/><rect x="497.83660888671875" y="208.30538940429688" width="142.3268280029297" height="20.527990341186523" fill="black" rx="2"/><rect x="505.4365234375" y="230.1942901611328" width="127.12696838378906" height="18.16684913635254" fill="black" rx="2"/><rect x="521.5771484375" y="314.3053894042969" width="94.84574127197266" height="20.527990341186523" fill="black" rx="2"/><rect x="499.4488220214844" y="336.1943054199219" width="139.10238647460938" height="18.16684913635254" fill="black" rx="2"/><rect x="138.05886840820312" y="434.1943054199219" width="403.8822937011719" height="18.16684913635254" fill="black" rx="2"/></mask></defs>
+
+<rect width="680" height="460" rx="12" fill="#F5F1E8" style="fill:rgb(245, 241, 232);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+
+<text x="340" y="28" text-anchor="middle" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">How OpenUISpec works</text>
+
+<rect x="40" y="52" width="150" height="370" rx="12" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="115" y="78" text-anchor="middle" fill="#633806" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">OpenUISpec</text>
+<text x="115" y="98" text-anchor="middle" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Semantic spec (YAML)</text>
+
+<rect x="56" y="116" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="134" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Tokens</text>
+<rect x="56" y="152" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="170" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Contracts</text>
+<rect x="56" y="188" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="206" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Components</text>
+<rect x="56" y="224" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="242" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Screens</text>
+<rect x="56" y="260" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="278" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Flows</text>
+<rect x="56" y="296" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="314" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Actions &amp; data</text>
+<rect x="56" y="332" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="350" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Platform config</text>
+<rect x="56" y="368" width="118" height="28" rx="6" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="115" y="386" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Design intent</text>
+
+<line x1="194" y1="237" x2="248" y2="237" stroke="#BA7517" stroke-width="1.5" stroke-dasharray="4 3" marker-end="url(#arrow)" style="fill:rgb(0, 0, 0);stroke:rgb(186, 117, 23);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-dasharray:4px, 3px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="221" y="228" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:start;dominant-baseline:auto">spec</text>
+
+<rect x="252" y="140" width="170" height="194" rx="12" fill="#EEEDFE" stroke="#7F77DD" stroke-width="0.5" style="fill:rgb(238, 237, 254);stroke:rgb(127, 119, 221);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="337" y="168" text-anchor="middle" fill="#26215C" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">AI generator</text>
+<text x="337" y="188" text-anchor="middle" fill="#534AB7" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">MCP server</text>
+
+<rect x="268" y="204" width="138" height="28" rx="6" fill="#EEEDFE" stroke="#7F77DD" stroke-width="0.5" style="fill:rgb(238, 237, 254);stroke:rgb(127, 119, 221);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="337" y="222" text-anchor="middle" fill="#3C3489" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Read spec context</text>
+<rect x="268" y="240" width="138" height="28" rx="6" fill="#EEEDFE" stroke="#7F77DD" stroke-width="0.5" style="fill:rgb(238, 237, 254);stroke:rgb(127, 119, 221);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="337" y="258" text-anchor="middle" fill="#3C3489" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Generate native code</text>
+<rect x="268" y="276" width="138" height="28" rx="6" fill="#EEEDFE" stroke="#7F77DD" stroke-width="0.5" style="fill:rgb(238, 237, 254);stroke:rgb(127, 119, 221);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="337" y="294" text-anchor="middle" fill="#3C3489" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Validate &amp; audit</text>
+
+<line x1="426" y1="198" x2="490" y2="134" stroke="#534AB7" stroke-width="1.5" marker-end="url(#arrow)" mask="url(#imagine-text-gaps-o7de63)" style="fill:rgb(0, 0, 0);stroke:rgb(83, 74, 183);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<line x1="426" y1="237" x2="490" y2="237" stroke="#534AB7" stroke-width="1.5" marker-end="url(#arrow)" style="fill:rgb(0, 0, 0);stroke:rgb(83, 74, 183);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<line x1="426" y1="276" x2="490" y2="340" stroke="#534AB7" stroke-width="1.5" marker-end="url(#arrow)" mask="url(#imagine-text-gaps-o7de63)" style="fill:rgb(0, 0, 0);stroke:rgb(83, 74, 183);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+
+<text x="446" y="152" fill="#5F5E5A" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:start;dominant-baseline:auto">Swift</text>
+<text x="446" y="228" fill="#5F5E5A" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:start;dominant-baseline:auto">Kotlin</text>
+<text x="446" y="318" fill="#5F5E5A" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:start;dominant-baseline:auto">TypeScript</text>
+
+<rect x="494" y="92" width="150" height="80" rx="10" fill="#E6F1FB" stroke="#85B7EB" stroke-width="0.5" style="fill:rgb(230, 241, 251);stroke:rgb(133, 183, 235);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="569" y="122" text-anchor="middle" fill="#042C53" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">iOS — SwiftUI</text>
+<text x="569" y="142" text-anchor="middle" fill="#185FA5" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Native, platform feel</text>
+
+<rect x="494" y="198" width="150" height="80" rx="10" fill="#EAF3DE" stroke="#97C459" stroke-width="0.5" style="fill:rgb(234, 243, 222);stroke:rgb(151, 196, 89);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="569" y="224" text-anchor="middle" fill="#173404" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">Android — Compose</text>
+<text x="569" y="244" text-anchor="middle" fill="#3B6D11" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Material You theming</text>
+
+<rect x="494" y="304" width="150" height="80" rx="10" fill="#FAECE7" stroke="#F0997B" stroke-width="0.5" style="fill:rgb(250, 236, 231);stroke:rgb(240, 153, 123);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="569" y="330" text-anchor="middle" fill="#4A1B0C" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">Web — React</text>
+<text x="569" y="350" text-anchor="middle" fill="#993C1D" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Responsive, accessible</text>
+
+<text x="340" y="448" text-anchor="middle" fill="#888780" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Share the intent · generate native code · each platform feels like home</text>
+</svg>

package/docs/images/workflows.svg

@@ -0,0 +1,76 @@
+<svg width="100%" viewBox="0 0 680 530" xmlns="http://www.w3.org/2000/svg">
+<defs>
+<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></marker>
+
+</defs>
+
+<rect width="680" height="520" rx="12" fill="#F5F1E8" style="fill:rgb(245, 241, 232);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+
+<text x="340" y="28" text-anchor="middle" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">Workflows</text>
+
+<rect x="40" y="48" width="106" height="26" rx="13" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="93" y="65" text-anchor="middle" fill="#633806" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Design mode</text>
+<text x="158" y="65" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:start;dominant-baseline:auto">Spec-first — new features, design system changes</text>
+
+<rect x="40" y="86" width="152" height="106" rx="10" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="116" y="108" text-anchor="middle" fill="#633806" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">1 · Define</text>
+<text x="116" y="128" text-anchor="middle" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Author spec YAML</text>
+<text x="116" y="144" text-anchor="middle" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Tokens, contracts,</text>
+<text x="116" y="160" text-anchor="middle" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">screens, flows</text>
+<text x="116" y="208" text-anchor="middle" fill="#888780" font-style="italic" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;font-style:italic;text-anchor:middle;dominant-baseline:auto">openuispec validate</text>
+
+<line x1="196" y1="139" x2="228" y2="139" stroke="#BA7517" stroke-width="1.5" marker-end="url(#arrow)" style="fill:rgb(0, 0, 0);stroke:rgb(186, 117, 23);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+
+<rect x="232" y="86" width="162" height="106" rx="10" fill="#EEEDFE" stroke="#7F77DD" stroke-width="0.5" style="fill:rgb(238, 237, 254);stroke:rgb(127, 119, 221);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="313" y="108" text-anchor="middle" fill="#26215C" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">2 · Generate</text>
+<text x="313" y="128" text-anchor="middle" fill="#534AB7" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">AI reads spec via MCP</text>
+<text x="313" y="144" text-anchor="middle" fill="#534AB7" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Produces native code</text>
+<text x="313" y="160" text-anchor="middle" fill="#534AB7" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">per platform target</text>
+<text x="313" y="208" text-anchor="middle" fill="#888780" font-style="italic" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;font-style:italic;text-anchor:middle;dominant-baseline:auto">openuispec prepare</text>
+
+<line x1="398" y1="139" x2="430" y2="139" stroke="#BA7517" stroke-width="1.5" marker-end="url(#arrow)" style="fill:rgb(0, 0, 0);stroke:rgb(186, 117, 23);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+
+<rect x="434" y="86" width="152" height="106" rx="10" fill="#EAF3DE" stroke="#97C459" stroke-width="0.5" style="fill:rgb(234, 243, 222);stroke:rgb(151, 196, 89);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="510" y="108" text-anchor="middle" fill="#173404" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">3 · Refine</text>
+<text x="510" y="128" text-anchor="middle" fill="#3B6D11" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Platform teams adjust</text>
+<text x="510" y="144" text-anchor="middle" fill="#3B6D11" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">for native polish</text>
+<text x="510" y="160" text-anchor="middle" fill="#3B6D11" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Snapshot baseline</text>
+<text x="510" y="208" text-anchor="middle" fill="#888780" font-style="italic" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;font-style:italic;text-anchor:middle;dominant-baseline:auto">openuispec drift --snapshot</text>
+
+<line x1="590" y1="139" x2="610" y2="139" stroke="#B4B2A9" stroke-width="0.5" stroke-dasharray="3 2" style="fill:rgb(0, 0, 0);stroke:rgb(180, 178, 169);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-dasharray:3px, 2px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<rect x="614" y="115" width="52" height="48" rx="8" fill="#E1F5EE" stroke="#5DCAA5" stroke-width="0.5" style="fill:rgb(225, 245, 238);stroke:rgb(93, 202, 165);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="640" y="135" text-anchor="middle" fill="#085041" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Native</text><text x="640" y="149" text-anchor="middle" fill="#085041" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">apps</text>
+
+<line x1="40" y1="242" x2="640" y2="242" stroke="#D3D1C7" stroke-width="0.5" stroke-dasharray="6 4" style="fill:rgb(0, 0, 0);stroke:rgb(211, 209, 199);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-dasharray:6px, 4px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="340" y="258" text-anchor="middle" fill="#888780" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">or</text>
+
+<rect x="40" y="274" width="132" height="26" rx="13" fill="#E6F1FB" stroke="#85B7EB" stroke-width="0.5" style="fill:rgb(230, 241, 251);stroke:rgb(133, 183, 235);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="106" y="291" text-anchor="middle" fill="#0C447C" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Development mode</text>
+<text x="184" y="291" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:start;dominant-baseline:auto">Platform-first — day-to-day iteration, fixes, polish</text>
+
+<rect x="40" y="312" width="152" height="106" rx="10" fill="#EAF3DE" stroke="#97C459" stroke-width="0.5" style="fill:rgb(234, 243, 222);stroke:rgb(151, 196, 89);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="116" y="334" text-anchor="middle" fill="#173404" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">1 · Code</text>
+<text x="116" y="354" text-anchor="middle" fill="#3B6D11" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Edit native code</text>
+<text x="116" y="370" text-anchor="middle" fill="#3B6D11" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Live preview, hot reload</text>
+<text x="116" y="386" text-anchor="middle" fill="#3B6D11" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Fix, tweak, polish</text>
+
+<line x1="196" y1="365" x2="228" y2="365" stroke="#185FA5" stroke-width="1.5" marker-end="url(#arrow)" style="fill:rgb(0, 0, 0);stroke:rgb(24, 95, 165);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+
+<rect x="232" y="312" width="162" height="106" rx="10" fill="#FAEEDA" stroke="#EF9F27" stroke-width="0.5" style="fill:rgb(250, 238, 218);stroke:rgb(239, 159, 39);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="313" y="334" text-anchor="middle" fill="#633806" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">2 · Sync</text>
+<text x="313" y="354" text-anchor="middle" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">AI reads code changes</text>
+<text x="313" y="370" text-anchor="middle" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Updates spec YAML</text>
+<text x="313" y="386" text-anchor="middle" fill="#854F0B" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">to match platform code</text>
+<text x="313" y="434" text-anchor="middle" fill="#888780" font-style="italic" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;font-style:italic;text-anchor:middle;dominant-baseline:auto">openuispec drift --explain</text>
+
+<line x1="398" y1="365" x2="430" y2="365" stroke="#185FA5" stroke-width="1.5" marker-end="url(#arrow)" style="fill:rgb(0, 0, 0);stroke:rgb(24, 95, 165);color:rgb(0, 0, 0);stroke-width:1.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+
+<rect x="434" y="312" width="152" height="106" rx="10" fill="#EEEDFE" stroke="#7F77DD" stroke-width="0.5" style="fill:rgb(238, 237, 254);stroke:rgb(127, 119, 221);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="510" y="334" text-anchor="middle" fill="#26215C" style="fill:rgb(44, 44, 42);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:14px;font-weight:500;text-anchor:middle;dominant-baseline:auto">3 · Propagate</text>
+<text x="510" y="354" text-anchor="middle" fill="#534AB7" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Other platforms see</text>
+<text x="510" y="370" text-anchor="middle" fill="#534AB7" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">spec diff and update</text>
+<text x="510" y="386" text-anchor="middle" fill="#534AB7" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">their code accordingly</text>
+<text x="510" y="434" text-anchor="middle" fill="#888780" font-style="italic" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;font-style:italic;text-anchor:middle;dominant-baseline:auto">openuispec status</text>
+
+<line x1="590" y1="365" x2="610" y2="365" stroke="#B4B2A9" stroke-width="0.5" stroke-dasharray="3 2" style="fill:rgb(0, 0, 0);stroke:rgb(180, 178, 169);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-dasharray:3px, 2px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<rect x="614" y="341" width="52" height="48" rx="8" fill="#E1F5EE" stroke="#5DCAA5" stroke-width="0.5" style="fill:rgb(225, 245, 238);stroke:rgb(93, 202, 165);color:rgb(0, 0, 0);stroke-width:0.5px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/><text x="640" y="361" text-anchor="middle" fill="#085041" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">All in</text><text x="640" y="375" text-anchor="middle" fill="#085041" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">sync</text>
+
+<text x="340" y="500" text-anchor="middle" fill="#888780" style="fill:rgb(95, 94, 90);stroke:none;color:rgb(0, 0, 0);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:system-ui, -apple-system, sans-serif;font-size:12px;font-weight:400;text-anchor:middle;dominant-baseline:auto">Spec lives in version control · diffs are human-readable · drift is detected, not hidden</text>
+</svg>

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.17",
+  "version": "0.2.19",
   "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[];
 }
@@ -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),
   };
 }
 

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/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 |