openuispec 0.2.15 → 0.2.17

package/README.md

@@ -46,7 +46,7 @@ This scaffolds a spec directory, starter tokens, and **configures the MCP server
 ## Key concepts
 
 - **Tokens** — design values (color, typography, spacing, elevation, motion) with semantic names and constrained ranges
-- **Contracts** — 7 reusable UI component families defined by role, props, interaction states, and accessibility
+- **Contracts** — 7 reusable UI component families defined by role, props, interaction states, accessibility, and `must_avoid` anti-patterns for AI generators
 - **Components** — reusable compositions of contracts with named slots, states, and variants
 - **Screens** — compositions of contracts and components with data bindings, adaptive layout, and conditional rendering
 - **Flows** — multi-screen navigation journeys, intent-based and platform-agnostic
@@ -54,6 +54,8 @@ 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
 
 ## The 7 contract families
 
@@ -75,7 +77,7 @@ OpenUISpec includes an **MCP server** that AI assistants call automatically duri
 openuispec init → configures MCP for your agent → AI calls tools automatically
 ```
 
-When you ask your AI to "add a settings page" or "update the home feed," the MCP server provides spec context before generation, feeds authoritative spec contents during generation, validates spec integrity after edits, and returns a spec-derived checklist for the AI to review the generated code against.
+When you ask your AI to "add a settings page" or "update the home feed," the MCP server provides spec context before generation, feeds authoritative spec contents during generation, validates spec integrity after edits, and returns a spec-derived checklist — including `must_avoid` anti-patterns and design quality score — for the AI to review the generated code against.
 
 16 tools are available as both MCP tools and CLI commands — see the [full reference](./docs/cli.md).
 

package/check/audit.ts

@@ -0,0 +1,291 @@
+/**
+ * Design quality audit for OpenUISpec projects.
+ *
+ * Checks token patterns and contract completeness to produce a numeric quality score.
+ * Score formula: max(0, 100 - errors × 10 - warnings × 3)
+ *
+ * Usage:
+ *   openuispec check --target web --audit
+ *   openuispec check --target ios --audit --min-score 70
+ *   openuispec check --target web --audit --format json
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import YAML from "yaml";
+
+export interface AuditFinding {
+  domain: string;
+  rule: string;
+  severity: "error" | "warning";
+  message: string;
+}
+
+export interface AuditResult {
+  score: number;
+  errors: number;
+  warnings: number;
+  findings: AuditFinding[];
+  passed: boolean;
+  threshold: number;
+}
+
+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 {
+    return YAML.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+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 = readYamlForAudit(join(tokensDir, "typography.yaml"), "typography", findings);
+  if (!doc?.typography) return;
+
+  // Font diversity: primary must NOT be a common AI default
+  const primaryFont = doc.typography.font_family?.primary?.value;
+  if (typeof primaryFont === "string" && AI_DEFAULT_FONTS.has(primaryFont)) {
+    findings.push({
+      domain: "typography",
+      rule: "font_diversity",
+      severity: "error",
+      message: `Primary font "${primaryFont}" is an AI-default choice. Use a distinctive brand font.`,
+    });
+  }
+
+  // Scale usage: at least 4 distinct scale levels defined
+  const scaleKeys = Object.keys(doc.typography.scale ?? {});
+  if (scaleKeys.length > 0 && scaleKeys.length < 4) {
+    findings.push({
+      domain: "typography",
+      rule: "scale_usage",
+      severity: "warning",
+      message: `Only ${scaleKeys.length} type scale level(s) defined. Use ≥4 distinct levels for clear hierarchy.`,
+    });
+  }
+}
+
+function checkColor(tokensDir: string, findings: AuditFinding[]): void {
+  const doc = readYamlForAudit(join(tokensDir, "color.yaml"), "color", findings);
+  if (!doc?.color) return;
+
+  // Pure black/white check
+  function scanForPure(obj: any, path: string): void {
+    if (typeof obj !== "object" || obj === null) return;
+    if (typeof obj.reference === "string") {
+      const ref = obj.reference.toUpperCase();
+      if (ref === "#000000" || ref === "#000") {
+        findings.push({
+          domain: "color",
+          rule: "pure_black",
+          severity: "error",
+          message: `Token at ${path} uses pure black (#000000). Use a near-black with hue instead.`,
+        });
+      }
+      if (ref === "#FFFFFF" || ref === "#FFF") {
+        findings.push({
+          domain: "color",
+          rule: "pure_white",
+          severity: "error",
+          message: `Token at ${path} uses pure white (#FFFFFF). Use a slightly tinted white instead.`,
+        });
+      }
+    }
+    for (const [key, value] of Object.entries(obj)) {
+      if (key !== "reference" && typeof value === "object") {
+        scanForPure(value, `${path}.${key}`);
+      }
+    }
+  }
+  scanForPure(doc.color, "color");
+
+  // Theme coverage: check themes.yaml for both light + dark
+  {
+    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) {
+      findings.push({
+        domain: "color",
+        rule: "theme_coverage",
+        severity: "warning",
+        message: "Both light and dark themes should be defined in tokens/themes.yaml.",
+      });
+    }
+  }
+}
+
+function checkSpacing(tokensDir: string, findings: AuditFinding[]): void {
+  const doc = readYamlForAudit(join(tokensDir, "spacing.yaml"), "spacing", findings);
+  if (!doc?.spacing) return;
+
+  // Scale usage: at least 4 distinct values
+  const scale = doc.spacing.scale ?? {};
+  const scaleCount = Object.keys(scale).length;
+  if (scaleCount > 0 && scaleCount < 4) {
+    findings.push({
+      domain: "spacing",
+      rule: "scale_usage",
+      severity: "warning",
+      message: `Only ${scaleCount} spacing scale value(s) defined. Define ≥4 for meaningful spatial rhythm.`,
+    });
+  }
+
+  // Alias usage: page_margin and card_padding should exist
+  const aliases = doc.spacing.aliases ?? {};
+  const aliasKeys = Object.keys(aliases).map((k) => k.toLowerCase());
+  if (!aliasKeys.some((k) => k.includes("page_margin") || k.includes("page"))) {
+    findings.push({
+      domain: "spacing",
+      rule: "alias_page_margin",
+      severity: "warning",
+      message: "No page_margin alias found in spacing tokens. Define it for consistent screen padding.",
+    });
+  }
+  if (!aliasKeys.some((k) => k.includes("card_padding") || k.includes("card"))) {
+    findings.push({
+      domain: "spacing",
+      rule: "alias_card_padding",
+      severity: "warning",
+      message: "No card_padding alias found in spacing tokens. Define it for consistent card spacing.",
+    });
+  }
+}
+
+function checkMotion(tokensDir: string, findings: AuditFinding[]): void {
+  const doc = readYamlForAudit(join(tokensDir, "motion.yaml"), "motion", findings);
+  if (!doc?.motion) return;
+
+  // Duration variety: at least 2 distinct durations
+  const durations = doc.motion.duration ?? {};
+  const distinctDurations = new Set(Object.values(durations));
+  if (Object.keys(durations).length > 0 && distinctDurations.size < 2) {
+    findings.push({
+      domain: "motion",
+      rule: "duration_variety",
+      severity: "warning",
+      message: "Only 1 distinct duration value found. Use ≥2 distinct durations (e.g. quick + normal).",
+    });
+  }
+
+  // Reduced motion: must be defined
+  if (!doc.motion.reduced_motion) {
+    findings.push({
+      domain: "motion",
+      rule: "reduced_motion",
+      severity: "error",
+      message: "motion.reduced_motion is not defined. Must specify policy for prefers-reduced-motion.",
+    });
+  }
+}
+
+function checkContracts(contractsDir: string, findings: AuditFinding[]): void {
+  // All collections have empty_state in must_handle or variants
+  {
+    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 ?? [];
+      const hasEmptyState = mustHandle.some((s: string) => s.toLowerCase().includes("empty"));
+      if (!hasEmptyState) {
+        findings.push({
+          domain: "contracts",
+          rule: "collection_empty_state",
+          severity: "warning",
+          message: "collection contract does not list empty_state handling in generation.must_handle.",
+        });
+      }
+    }
+  }
+}
+
+export function buildAuditResult(projectDir: string, threshold: number = 0): AuditResult {
+  const manifest = readYaml(join(projectDir, "openuispec.yaml"));
+  const tokensDir = resolve(projectDir, manifest?.includes?.tokens ?? "./tokens/");
+  const contractsDir = resolve(projectDir, manifest?.includes?.contracts ?? "./contracts/");
+
+  // Use audit_threshold from manifest if no CLI override
+  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);
+  checkContracts(contractsDir, findings);
+
+  const errors = findings.filter((f) => f.severity === "error").length;
+  const warnings = findings.filter((f) => f.severity === "warning").length;
+  const score = Math.max(0, 100 - errors * 10 - warnings * 3);
+
+  return {
+    score,
+    errors,
+    warnings,
+    findings,
+    passed: score >= effectiveThreshold,
+    threshold: effectiveThreshold,
+  };
+}
+
+export function formatAuditResult(result: AuditResult): string {
+  const lines: string[] = [
+    `Design Quality Score: ${result.score}/100`,
+    `Errors: ${result.errors}  Warnings: ${result.warnings}`,
+    result.threshold > 0 ? `Threshold: ${result.threshold} — ${result.passed ? "PASS" : "FAIL"}` : "",
+    "",
+  ].filter((l) => l !== "" || lines?.length === 0);
+
+  if (result.findings.length === 0) {
+    lines.push("No issues found.");
+  } else {
+    for (const f of result.findings) {
+      lines.push(`[${f.severity.toUpperCase()}] [${f.domain}] ${f.message}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/check/index.ts

@@ -29,6 +29,7 @@ import {
   type JsonGroupResult,
 } from "../schema/validate.js";
 import { collectSemanticLint } from "../schema/semantic-lint.js";
+import { buildAuditResult, formatAuditResult, type AuditResult } from './audit.js';
 
 // ── types ─────────────────────────────────────────────────────────────
 
@@ -54,6 +55,7 @@ export interface CheckResult {
   validation: CheckValidation;
   semantic: CheckSemantic;
   prepare: CheckPrepare;
+  audit?: AuditResult;
 }
 
 // ── prepare readiness helpers ─────────────────────────────────────────
@@ -178,7 +180,7 @@ function determinePrepare(
 
 // ── core (importable, no process.exit) ───────────────────────────────
 
-export function buildCheckResult(target: string, cwd: string = process.cwd()): CheckResult {
+export function buildCheckResult(target: string, cwd: string = process.cwd(), includeAudit: boolean = false): CheckResult {
   const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const includes = readIncludes(projectDir);
@@ -210,7 +212,8 @@ export function buildCheckResult(target: string, cwd: string = process.cwd()): C
   // 3. Prepare readiness
   const prepare = determinePrepare(projectDir, projectName, target);
 
-  return { target, validation, semantic, prepare };
+  const audit = includeAudit ? buildAuditResult(projectDir) : undefined;
+  return { target, validation, semantic, prepare, audit };
 }
 
 // ── main ──────────────────────────────────────────────────────────────
@@ -227,12 +230,25 @@ export function runCheck(argv: string[]): void {
     process.exit(1);
   }
 
-  const result = buildCheckResult(target);
+  const includeAudit = argv.includes("--audit");
+  const minScoreIdx = argv.indexOf("--min-score");
+  const minScore = minScoreIdx !== -1 && argv[minScoreIdx + 1] ? parseInt(argv[minScoreIdx + 1], 10) : 0;
+
+  const result = buildCheckResult(target, undefined, includeAudit);
 
   if (isJson) {
     console.log(JSON.stringify(result, null, 2));
   } else {
     printReport(result);
+    if (result.audit) {
+      console.log("\nDesign Quality Audit");
+      console.log("====================");
+      console.log(formatAuditResult(result.audit));
+      if (minScore > 0 && result.audit.score < minScore) {
+        console.error(`\nFAIL: Score ${result.audit.score} is below --min-score ${minScore}`);
+        process.exit(1);
+      }
+    }
   }
 
   // Exit codes: 0 = clean + ready, 2 = validation errors, 1 = config error

package/docs/cli.md

@@ -62,8 +62,8 @@ Or run directly: `openuispec mcp`
 | Tool | What it does |
 |------|-------------|
 | `openuispec_validate` | Validate spec files against JSON Schemas, optionally filtered by group |
-| `openuispec_check` | Validate spec files (schema + semantic) and check target generation readiness. `audit=true` returns a spec-derived review checklist |
-| `openuispec_prepare` | Returns spec context, platform config, constraints. Optional `include_specs` embeds all spec contents |
+| `openuispec_check` | Validate spec files (schema + semantic) and check target generation readiness. `audit=true` returns a spec-derived review checklist including `must_avoid` anti-patterns and a design quality score |
+| `openuispec_prepare` | Returns spec context, platform config, constraints, `anti_patterns`, and `design_context`. Optional `include_specs` embeds all spec contents |
 | `openuispec_drift` | Detect drift, or `snapshot=true` to create/update baseline |
 
 ### Visual verification
@@ -97,7 +97,9 @@ openuispec configure-target <t> [--defaults]  # Configure target stack
 ```bash
 openuispec validate [group...] [--json]    # Validate spec files against JSON Schemas
 openuispec validate semantic               # Lint cross-references (locale keys, icons, contracts, tokens)
-openuispec check --target <t> [--json]     # Validate spec files + check target generation readiness
+openuispec check --target <t> [--json]         # Validate spec files + check target generation readiness
+openuispec check --target <t> --audit          # Also run design quality audit (score + findings)
+openuispec check --target <t> --audit --min-score 70  # Fail if score below threshold
 ```
 
 ### Status & generation workflow
@@ -270,3 +272,27 @@ openuispec drift --snapshot --target ios
 - `prepare` runs in `bootstrap` mode for first-time generation and `update` mode after a snapshot exists
 - `drift --snapshot` is bookkeeping — it does not prove code matches the spec, and requires the output directory to exist. Only run it after reviewing the generated output.
 - Run `openuispec status` between targets to see what still needs updating
+
+## Design Quality Audit
+
+`openuispec check --audit` scores the spec against design quality heuristics and returns findings grouped by domain.
+
+```bash
+openuispec check --target web --audit
+openuispec check --target ios --audit --min-score 70   # exit 1 if score < 70
+openuispec check --target web --audit --json           # machine-readable output
+```
+
+**Score formula:** `max(0, 100 - errors × 10 - warnings × 3)`
+
+**Checks performed:**
+
+| 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 |
+| 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` |
+
+The `audit_threshold` in `generation_guidance` sets the project-wide minimum score. `--min-score` overrides it per-run.

package/docs/file-formats.md

@@ -168,3 +168,86 @@ Mock files are not validated by `openuispec validate` and are excluded from drif
 | 12. Custom contract extensions | `x_` prefixed domain-specific contracts |
 | 13. Form validation | Validation rules, field dependencies, cross-field checks |
 | 14. Development workflow | Dual-workflow model, drift detection, spec as sync layer |
+
+## Manifest: `design` and `generation_guidance`
+
+Two new top-level sections in `openuispec.yaml` shape how AI generators approach design quality.
+
+### `design` — Project brand intent
+
+```yaml
+design:
+  personality: "Clean, focused, productivity-first — no decorative flourishes"
+  complexity: "balanced"          # restrained | balanced | elaborate
+  audience: "Individual contributors and small teams"
+  avoid:
+    - "Do not use color gradients — flat, token-driven color only"
+    - "[web] Do not use CSS animations for non-interactive decorative purposes"
+```
+
+`complexity` controls how generators apply motion, elevation, and decorative detail:
+- `restrained` — required state transitions only, no decorative shadows, clean whitespace
+- `balanced` — all motion patterns, full elevation token usage, standard state animations
+- `elaborate` — rich animations with staggered reveals, creative elevation, platform flourishes
+
+`avoid` items may use `[web]`/`[ios]`/`[android]` scope tags — same convention as `extra_rules`.
+
+### `generation_guidance` — Universal anti-patterns
+
+```yaml
+generation_guidance:
+  universal_anti_patterns:
+    typography:
+      - "Do not fall back to Inter, Roboto, Arial when the spec defines a custom font_family"
+    color:
+      - "Do not use pure black (#000000) or pure white (#FFFFFF) — resolve through the token layer"
+    spacing:
+      - "Do not ignore the page_margin and card_padding aliases"
+    motion:
+      - "Do not ignore reduced_motion — remove animations entirely when the user prefers it"
+    elevation:
+      - "Do not add shadows to elements that don't specify an elevation token"
+    layout:
+      - "Do not use pixel breakpoints — reference size classes by name"
+    accessibility:
+      - "Do not use color as the only differentiator between states"
+  audit_threshold: 70             # Minimum score for openuispec check --audit
+```
+
+`universal_anti_patterns` appear in the `openuispec prepare` output under `anti_patterns.universal`, filtered by target platform tag. `audit_threshold` is the default minimum score for `openuispec check --audit`.
+
+## Contract and component: `must_avoid`
+
+The `generation` block in contracts, custom contracts, and components now supports `must_avoid` alongside `must_handle`, `should_handle`, and `may_handle`:
+
+```yaml
+action_trigger:
+  generation:
+    must_avoid:
+      - "Do not apply gradient backgrounds to buttons — use flat token-defined colors"
+      - "Do not use bounce or elastic easing on press feedback"
+      - "[ios] Do not add drop shadows to every button variant"
+```
+
+Items may use `[web]`/`[ios]`/`[android]` scope tags. Untagged items apply to all platforms. `must_avoid` appears in the `openuispec prepare` output under `anti_patterns.contract_specific`, filtered by target.
+
+## Token: `generation_notes`
+
+Token entries in `typography`, `color`, and `motion` files support sparse `generation_notes` for AI generators:
+
+```yaml
+typography:
+  font_family:
+    primary:
+      value: "DM Sans"
+      generation_notes:
+        - "Never fall back to Inter or Roboto — choose a geometric sans with similar x-height"
+        - "[web] Use font-display: swap to prevent FOUT"
+        - "[ios] Register the font in Info.plist before first render"
+  scale:
+    body:
+      generation_notes:
+        - "This is the most-used text style — ensure line_height is comfortable (1.5 default)"
+```
+
+`generation_notes` are sparse — only add them for tokens where AI generators consistently make wrong choices.

package/docs/implementation-notes.md

@@ -161,3 +161,11 @@
   9. `openuispec drift --snapshot --target <target>`
 - `drift --snapshot` should continue to be described as bookkeeping/baselining, not as proof that the target implementation matches the spec.
 - If the target output directory does not exist yet, the CLI should direct the user to run code generation first instead of implying that snapshot can initialize an empty target.
+
+## Design quality audit
+
+`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.
+
+`generation.extra_rules` in the manifest is included in prepare output and filtered by platform tag.

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

@@ -3,6 +3,14 @@
 # Rounded Cap: primary diagonal rounds TR+BL, alternate rounds TL+BR
 
 action_trigger:
+  generation:
+    must_avoid:
+      - "Do not apply gradient backgrounds to buttons — use flat token-defined colors"
+      - "Do not make primary and secondary variants visually identical — they must be immediately distinguishable by background, border, or text color"
+      - "Do not use bounce or elastic easing on press feedback — use the motion.easing tokens"
+      - "Do not add drop shadows to every button variant — only elevated contexts use elevation tokens"
+      - "Do not use pure black (#000) or pure white (#fff) — always resolve through color.text and color.surface tokens"
+      - "Do not set identical min_height across all size variants — sm, md, lg must feel proportionally different"
   tokens:
     shape: "rounded_cap_primary"
     shape_note: "TR+BL pill-rounded (~40-60% of element height), TL+BR sharp (2-4px)"

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

@@ -2,6 +2,14 @@
 # Base definition: spec Section 4.7
 
 collection:
+  generation:
+    must_avoid:
+      - "Do not omit empty states — every collection must render the empty_state component when data is empty"
+      - "Do not use infinite scroll without a visible loading indicator at the bottom"
+      - "Do not render loading skeletons that mismatch the actual item layout — skeleton shapes must reflect the item_contract variant"
+      - "Do not use identical item spacing for list and grid variants — grid uses gap, list uses separator"
+      - "Do not render table headers with the same visual weight as table rows — headers use header_background and header_weight tokens"
+      - "[web] Do not skip keyboard navigation support — lists need ArrowUp/ArrowDown, grids need 2D arrow navigation"
   variants:
     list:
       semantic: "Vertical list — items use card shape from data_display"

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

@@ -3,6 +3,14 @@
 # Rounded Cap: cards use 3px 20px 3px 20px (primary diagonal, scaled for card size)
 
 data_display:
+  generation:
+    must_avoid:
+      - "Do not nest cards inside cards — use flat hierarchy with spacing and subtle background shifts"
+      - "Do not give every card variant the same border-radius and shadow — vary by emphasis level"
+      - "Do not use gray text on colored backgrounds — use a darker shade of the background color or the on_color token"
+      - "Do not make all stat cards identical size with centered text — vary layout to match the data shape"
+      - "Do not use the same skeleton shape for all variants — skeleton must match the specific variant layout (card vs compact vs hero)"
+      - "Do not omit the highlighted state visual differentiation — unread/new items must be visually distinct from default items"
   variants:
     card:
       semantic: "Content card — rounded cap primary diagonal, subtle border, warm cream background"

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

@@ -3,6 +3,14 @@
 # Rounded Cap: toasts and dialogs use primary diagonal
 
 feedback:
+  generation:
+    must_avoid:
+      - "Do not use the same visual treatment for all severity levels — info, success, warning, and error must be immediately distinguishable by color, icon, and border"
+      - "Do not stack multiple toasts without spacing or queue management — overlapping toasts are a usability failure"
+      - "Do not use alert dialogs for non-blocking informational feedback — use toasts or banners per the variant definition"
+      - "Do not skip enter/exit animations — feedback appearing or disappearing instantly feels broken"
+      - "Do not use the same position for toasts and banners — toasts float, banners are inline"
+      - "Do not auto-dismiss error-severity feedback with a short timer — errors need manual dismissal or a longer duration"
   variants:
     toast:
       semantic: "Toast notification — rounded cap primary diagonal, auto-dismiss"

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

@@ -3,6 +3,14 @@
 # Rounded Cap: inputs match button diagonal (primary: 2px 24px 2px 24px)
 
 input_field:
+  generation:
+    must_avoid:
+      - "Do not use placeholder text as the only label — always render a persistent visible label"
+      - "Do not use a single generic gray border for all states — focused, error, and disabled must each have distinct visual treatment"
+      - "Do not hardcode red for error states — use color.semantic.danger which may differ from pure red per the token definition"
+      - "Do not skip the label animation between resting and active positions — this is a must_handle requirement"
+      - "Do not use the same visual weight for required and optional fields — required fields need a visible indicator"
+      - "Do not render select fields identically across platforms — respect the render_hint and platform_mapping"
   tokens:
     shape: "2px 24px 2px 24px"
     background: "color.surface.primary"

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

@@ -2,6 +2,15 @@
 # Base definition: spec Section 4.4
 
 nav_container:
+  generation:
+    must_avoid:
+      - "Do not use the same icon treatment for active and inactive items — differentiate with fill/outline variants, color, or both"
+      - "Do not center-align sidebar items — use leading alignment with consistent padding per the item_padding_h token"
+      - "Do not ignore the collapsed state for sidebar and rail variants — collapsed mode must show only icons with proper spacing"
+      - "Do not use a generic hamburger menu icon when the spec defines a specific drawer trigger"
+      - "Do not render tab_bar and sidebar with the same visual weight — tab_bar is compact and subordinate, sidebar is prominent"
+      - "[ios] Do not forget safe area insets on tab_bar — iOS bottom inset must be respected"
+      - "[android] Do not ignore gesture navigation bar insets on tab_bar and bottom navigation"
   variants:
     tab_bar:
       semantic: "Bottom tab bar — standard platform tab bar with badge support"

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

@@ -3,6 +3,14 @@
 # Rounded Cap: surfaces use 3px 24px 3px 24px (primary diagonal, largest scale)
 
 surface:
+  generation:
+    must_avoid:
+      - "Do not use the same overlay opacity for modal, sheet, and popover — each has a distinct tokens definition"
+      - "Do not omit the drag indicator on sheet variants — it signals that the surface is interactive and dismissible"
+      - "Do not use glassmorphism or frosted-glass effects unless the project's design personality explicitly calls for it"
+      - "Do not skip focus trapping on modal and sheet variants — keyboard users must not be able to tab behind the surface"
+      - "Do not render popover without an arrow/caret pointing to its trigger element"
+      - "Do not present fullscreen surfaces without a clear close affordance"
   tokens:
     shape: "3px 24px 3px 24px"
     background: "color.surface.secondary"