openuispec 0.2.14 → 0.2.16

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"

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

@@ -32,6 +32,46 @@ generation:
     android: { language: kotlin, framework: compose, min_sdk: 26 }
     web: { language: typescript, framework: react, bundler: vite }
 
+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"
+      - "Do not use a single font weight throughout — the typography scale defines different weights per level"
+      - "Do not use monospace fonts as shorthand for 'technical' aesthetic unless the spec explicitly calls for it"
+    color:
+      - "Do not use pure black (#000000) or pure white (#FFFFFF) — always resolve through the token layer"
+      - "Do not use the AI-default palette: cyan-on-dark, purple-to-blue gradients, neon accents"
+      - "Do not use gray text on colored backgrounds — derive text color from the on_color token or a darkened shade"
+      - "Do not apply the same opacity to all border tokens — border.default and border.emphasis have distinct opacity values"
+    spacing:
+      - "Do not use the same spacing value everywhere — the spec defines xxs through xxxl for a reason"
+      - "Do not ignore the page_margin and card_padding aliases — they exist to enforce consistent spatial rhythm"
+      - "Do not add spacing that the spec doesn't define — if a gap isn't in the token scale, it shouldn't exist in output"
+    motion:
+      - "Do not use bounce or elastic easing — these feel dated and the spec defines specific easing curves"
+      - "Do not apply the same duration to all animations — instant, quick, normal, and slow serve different purposes"
+      - "Do not ignore reduced_motion — when the user prefers reduced motion, animations must be removed entirely"
+    elevation:
+      - "Do not add shadows to elements that don't specify an elevation token"
+      - "Do not use the same shadow depth for cards and modals — cards use elevation.md, modals use elevation.lg"
+    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)"
+    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"
+      - "Do not set tab order manually unless the contract explicitly requires it — use document order"
+  audit_threshold: 70
+
+design:
+  personality: "Vibrant, social, content-rich — engagement and discovery are primary, utility is secondary"
+  complexity: "elaborate"
+  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"
+    - "[ios] Do not skip spring animations on content reveal — they are expected in this context"
+    - "[android] Do not use non-Material motion patterns — stick to the platform's shared element transitions"
+
 data_model:
   user:
     id: { type: string, required: true }

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

@@ -10,6 +10,10 @@ color:
       on_color:
         reference: "#FFFFFF"
         contrast_min: 7.0
+      generation_notes:
+        - "This is the most important brand color — use consistently for primary actions, active states, and key interactive elements"
+        - "Do not dilute by applying it to backgrounds, borders, and text simultaneously — pick one dominant usage per surface"
+        - "The on_color token exists specifically for text/icons placed on this background — do not calculate contrast manually"
     accent:
       semantic: "Accent highlights — muted indigo"
       reference: "#5B52A3"

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

@@ -18,6 +18,10 @@ motion:
       duration: "instant"
       easing: "default"
       property: "transform"
+      generation_notes:
+        - "The scale value is subtle by design — do not exaggerate to 0.9 or lower"
+        - "[ios] Complement with haptic feedback (.impact(style: .light))"
+        - "[android] Use ripple effect instead of or in addition to scale"
     slide_up:
       duration: "normal"
       easing: "enter"

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

@@ -6,6 +6,11 @@ typography:
       platform:
         ios: { system_alternative: "SF Pro" }
         android: { system_alternative: "Google Sans" }
+      generation_notes:
+        - "If the primary font is unavailable on a platform, choose a geometric sans with similar x-height — never fall back to Inter or Roboto"
+        - "[web] Use font-display: swap and a size-adjust fallback to prevent FOUT (Flash of Unstyled Text)"
+        - "[ios] Register the font in Info.plist and verify it loads before first render"
+        - "[android] Place the font in res/font/ and reference via XML font family — do not load programmatically"
 
   scale:
     display:
@@ -33,6 +38,9 @@ typography:
       size: { base: 16, range: [14, 16] }
       weight: 400
       line_height: 1.5
+      generation_notes:
+        - "This is the most-used text style — ensure line_height is comfortable for reading (1.5 default)"
+        - "On compact screens: the lower end of the size range is acceptable — do not go below 14pt/px"
     body_sm:
       semantic: "Secondary body text"
       size: { base: 14, range: [13, 15] }
@@ -43,6 +51,9 @@ typography:
       size: { base: 12, range: [11, 13] }
       weight: 400
       line_height: 1.4
+      generation_notes:
+        - "Caption text must still meet the contrast_min requirement from the text token it pairs with"
+        - "Do not use caption size for primary content — it is for metadata, timestamps, and labels only"
     button:
       semantic: "Button labels"
       size: { base: 16, range: [14, 16] }

package/examples/taskflow/openuispec/contracts/action_trigger.yaml

@@ -1,4 +1,12 @@
 # action_trigger contract extension
 # Base definition: spec Section 4.1
 
-action_trigger: {}
+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"

package/examples/taskflow/openuispec/contracts/collection.yaml

@@ -1,4 +1,12 @@
 # collection contract extension
 # Base definition: spec Section 4.7
 
-collection: {}
+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"

package/examples/taskflow/openuispec/contracts/data_display.yaml

@@ -1,4 +1,12 @@
 # data_display contract extension
 # Base definition: spec Section 4.2
 
-data_display: {}
+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"

package/examples/taskflow/openuispec/contracts/feedback.yaml

@@ -1,4 +1,12 @@
 # feedback contract extension
 # Base definition: spec Section 4.5
 
-feedback: {}
+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"

package/examples/taskflow/openuispec/contracts/input_field.yaml

@@ -3,6 +3,14 @@
 # Add project-specific variants, token overrides, and generation hints.
 
 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"
   variants:
     cut_corner:
       semantic: "Angled corner input for branded forms"

package/examples/taskflow/openuispec/contracts/nav_container.yaml

@@ -1,4 +1,13 @@
 # nav_container contract extension
 # Base definition: spec Section 4.4
 
-nav_container: {}
+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"

package/examples/taskflow/openuispec/contracts/surface.yaml

@@ -1,4 +1,12 @@
 # surface contract extension
 # Base definition: spec Section 4.6
 
-surface: {}
+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"

package/examples/taskflow/openuispec/openuispec.yaml

@@ -39,6 +39,46 @@ generation:
     android: { language: kotlin, framework: compose, min_sdk: 26 }
     web: { language: typescript, framework: react, bundler: vite }
 
+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"
+      - "Do not use a single font weight throughout — the typography scale defines different weights per level"
+      - "Do not use monospace fonts as shorthand for 'technical' aesthetic unless the spec explicitly calls for it"
+    color:
+      - "Do not use pure black (#000000) or pure white (#FFFFFF) — always resolve through the token layer"
+      - "Do not use the AI-default palette: cyan-on-dark, purple-to-blue gradients, neon accents"
+      - "Do not use gray text on colored backgrounds — derive text color from the on_color token or a darkened shade"
+      - "Do not apply the same opacity to all border tokens — border.default and border.emphasis have distinct opacity values"
+    spacing:
+      - "Do not use the same spacing value everywhere — the spec defines xxs through xxxl for a reason"
+      - "Do not ignore the page_margin and card_padding aliases — they exist to enforce consistent spatial rhythm"
+      - "Do not add spacing that the spec doesn't define — if a gap isn't in the token scale, it shouldn't exist in output"
+    motion:
+      - "Do not use bounce or elastic easing — these feel dated and the spec defines specific easing curves"
+      - "Do not apply the same duration to all animations — instant, quick, normal, and slow serve different purposes"
+      - "Do not ignore reduced_motion — when the user prefers reduced motion, animations must be removed entirely"
+    elevation:
+      - "Do not add shadows to elements that don't specify an elevation token"
+      - "Do not use the same shadow depth for cards and modals — cards use elevation.md, modals use elevation.lg"
+    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)"
+    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"
+      - "Do not set tab order manually unless the contract explicitly requires it — use document order"
+  audit_threshold: 70
+
+design:
+  personality: "Clean, focused, productivity-first — no decorative flourishes. Color is used for priority and status clarity, not aesthetics."
+  complexity: "balanced"
+  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"
+    - "Do not use color gradients — flat, token-driven color only"
+    - "[web] Do not use CSS animations for non-interactive decorative purposes"
+
 # ============================================================
 # Custom formatters & mappers (see spec Section 10.5)
 # ============================================================

package/examples/taskflow/openuispec/tokens/color.yaml

@@ -13,6 +13,10 @@ color:
       on_color:
         reference: "#FFFFFF"
         contrast_min: 4.5
+      generation_notes:
+        - "This is the most important brand color — use consistently for primary actions, active states, and key interactive elements"
+        - "Do not dilute by applying it to backgrounds, borders, and text simultaneously — pick one dominant usage per surface"
+        - "The on_color token exists specifically for text/icons placed on this background — do not calculate contrast manually"
 
     secondary:
       semantic: "Accent for highlights, badges, urgency"

package/examples/taskflow/openuispec/tokens/motion.yaml

@@ -20,6 +20,10 @@ motion:
       duration: "instant"
       property: "scale"
       value: 0.97
+      generation_notes:
+        - "The scale value is subtle by design — do not exaggerate to 0.9 or lower"
+        - "[ios] Complement with haptic feedback (.impact(style: .light))"
+        - "[android] Use ripple effect instead of or in addition to scale"
     state_change:
       duration: "quick"
       property: "opacity, background"

package/examples/taskflow/openuispec/tokens/typography.yaml

@@ -10,6 +10,11 @@ typography:
         ios: { system_alternative: "SF Pro" }
         android: { system_alternative: "Google Sans" }
         web: { load_strategy: "swap", source: "google_fonts" }
+      generation_notes:
+        - "If the primary font is unavailable on a platform, choose a geometric sans with similar x-height — never fall back to Inter or Roboto"
+        - "[web] Use font-display: swap and a size-adjust fallback to prevent FOUT (Flash of Unstyled Text)"
+        - "[ios] Register the font in Info.plist and verify it loads before first render"
+        - "[android] Place the font in res/font/ and reference via XML font family — do not load programmatically"
 
   scale:
     display:
@@ -40,6 +45,9 @@ typography:
       size: { base: 16, range: [14, 16] }
       weight: 400
       line_height: 1.5
+      generation_notes:
+        - "This is the most-used text style — ensure line_height is comfortable for reading (1.5 default)"
+        - "On compact screens: the lower end of the size range is acceptable — do not go below 14pt/px"
     body_sm:
       semantic: "Secondary text, descriptions"
       size: { base: 14, range: [13, 15] }
@@ -52,6 +60,9 @@ typography:
       weight: 400
       tracking: 0.02
       line_height: 1.35
+      generation_notes:
+        - "Caption text must still meet the contrast_min requirement from the text token it pairs with"
+        - "Do not use caption size for primary content — it is for metadata, timestamps, and labels only"
     overline:
       semantic: "Section tags, category labels"
       size: { base: 11, range: [10, 12] }

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

@@ -31,6 +31,13 @@ action_trigger:
       primary: { style: "clip-path" }
       ghost: { style: "clip-path" }
   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"
     must_handle:
       - "Cut top-left and bottom-right corners by cut_size for primary and ghost"
       - "Preserve button hit area and loading state inside the cut shape"

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

@@ -23,6 +23,13 @@ collection:
       list: { element: "ul", class: "todo-list" }
       chips: { element: "div", class: "chip-row" }
   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"
     must_handle:
       - "Preserve empty_state and pull_to_refresh behavior for task lists"
       - "Render chips as single-select filters bound to state.active_filter"

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

@@ -29,6 +29,13 @@ data_display:
       compact: { element: "li", class: "todo-row" }
       inline: { element: "div", class: "section-heading" }
   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"
     must_handle:
       - "Render compact task rows with clear title/subtitle hierarchy"
       - "Support inline title/subtitle blocks for section headers"

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

@@ -23,6 +23,13 @@ feedback:
       toast: { pattern: "toast container", position: "top-right" }
       banner: { element: "div", role: "alert", position: "inline-top" }
   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"
     must_handle:
       - "Map success and error feedback to distinct visuals and live-region behavior"
       - "Auto-dismiss toast feedback after the declared duration"

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

@@ -45,6 +45,13 @@ input_field:
       date: { style: "clip-path" }
       number: { style: "clip-path" }
   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"
     must_handle:
       - "Cut top-left and bottom-right corners by cut_size for text-like inputs"
       - "Keep focus, error, and disabled borders aligned with the cut shape"

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

@@ -58,6 +58,14 @@ nav_container:
       rail: { element: "aside", pattern: "icon rail" }
       sidebar: { element: "aside", pattern: "collapsible sidebar" }
   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"
     must_handle:
       - "Switch between tab_bar, rail, and sidebar according to adaptive screen config"
       - "Keep the selected item visually distinct with active icon/text treatment"

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

@@ -21,6 +21,13 @@ surface:
       sheet: { style: "clip-path" }
       modal: { style: "clip-path" }
   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"
     must_handle:
       - "Apply the cut-corner silhouette to sheet and modal surfaces"
       - "Maintain shadows and overlays without square corners bleeding through"

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

@@ -38,6 +38,46 @@ generation:
     android: { language: kotlin, framework: compose, min_sdk: 26 }
     web: { language: typescript, framework: react, bundler: vite }
 
+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"
+      - "Do not use a single font weight throughout — the typography scale defines different weights per level"
+      - "Do not use monospace fonts as shorthand for 'technical' aesthetic unless the spec explicitly calls for it"
+    color:
+      - "Do not use pure black (#000000) or pure white (#FFFFFF) — always resolve through the token layer"
+      - "Do not use the AI-default palette: cyan-on-dark, purple-to-blue gradients, neon accents"
+      - "Do not use gray text on colored backgrounds — derive text color from the on_color token or a darkened shade"
+      - "Do not apply the same opacity to all border tokens — border.default and border.emphasis have distinct opacity values"
+    spacing:
+      - "Do not use the same spacing value everywhere — the spec defines xxs through xxxl for a reason"
+      - "Do not ignore the page_margin and card_padding aliases — they exist to enforce consistent spatial rhythm"
+      - "Do not add spacing that the spec doesn't define — if a gap isn't in the token scale, it shouldn't exist in output"
+    motion:
+      - "Do not use bounce or elastic easing — these feel dated and the spec defines specific easing curves"
+      - "Do not apply the same duration to all animations — instant, quick, normal, and slow serve different purposes"
+      - "Do not ignore reduced_motion — when the user prefers reduced motion, animations must be removed entirely"
+    elevation:
+      - "Do not add shadows to elements that don't specify an elevation token"
+      - "Do not use the same shadow depth for cards and modals — cards use elevation.md, modals use elevation.lg"
+    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)"
+    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"
+      - "Do not set tab order manually unless the contract explicitly requires it — use document order"
+  audit_threshold: 70
+
+design:
+  personality: "Minimal and calm — orbital metaphor suggests clarity and organization without visual noise"
+  complexity: "restrained"
+  audience: "Bilingual individuals who prefer a clean, low-distraction task environment"
+  avoid:
+    - "Do not add decorative illustrations or background patterns"
+    - "Do not use more than 2 accent colors on any screen"
+    - "Do not animate list items on page load — only animate user-triggered state changes"
+
 formatters:
   priority_label:
     input: enum

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

@@ -10,6 +10,10 @@ color:
       on_color:
         reference: "#FFFFFF"
         contrast_min: 4.5
+      generation_notes:
+        - "This is the most important brand color — use consistently for primary actions, active states, and key interactive elements"
+        - "Do not dilute by applying it to backgrounds, borders, and text simultaneously — pick one dominant usage per surface"
+        - "The on_color token exists specifically for text/icons placed on this background — do not calculate contrast manually"
     secondary:
       semantic: "Warm accent for highlights and due-date emphasis"
       reference: "#F59E0B"

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

@@ -18,6 +18,10 @@ motion:
       duration: "instant"
       property: "scale"
       value: 0.98
+      generation_notes:
+        - "The scale value is subtle by design — do not exaggerate to 0.9 or lower"
+        - "[ios] Complement with haptic feedback (.impact(style: .light))"
+        - "[android] Use ripple effect instead of or in addition to scale"
     state_change:
       duration: "quick"
       property: "opacity, border-color, background"

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

@@ -8,6 +8,11 @@ typography:
         ios: { system_alternative: "SF Pro" }
         android: { system_alternative: "Google Sans" }
         web: { load_strategy: "swap", source: "google_fonts" }
+      generation_notes:
+        - "If the primary font is unavailable on a platform, choose a geometric sans with similar x-height — never fall back to Inter or Roboto"
+        - "[web] Use font-display: swap and a size-adjust fallback to prevent FOUT (Flash of Unstyled Text)"
+        - "[ios] Register the font in Info.plist and verify it loads before first render"
+        - "[android] Place the font in res/font/ and reference via XML font family — do not load programmatically"
 
   scale:
     display:
@@ -38,6 +43,9 @@ typography:
       size: { base: 16, range: [15, 17] }
       weight: 400
       line_height: 1.5
+      generation_notes:
+        - "This is the most-used text style — ensure line_height is comfortable for reading (1.5 default)"
+        - "On compact screens: the lower end of the size range is acceptable — do not go below 14pt/px"
     body_sm:
       semantic: "Supporting text and subtitles"
       size: { base: 14, range: [13, 15] }
@@ -50,3 +58,6 @@ typography:
       weight: 500
       tracking: 0.015
       line_height: 1.35
+      generation_notes:
+        - "Caption text must still meet the contrast_min requirement from the text token it pairs with"
+        - "Do not use caption size for primary content — it is for metadata, timestamps, and labels only"

package/mcp-server/index.ts

@@ -127,7 +127,12 @@ SPEC AUTHORING: spec_types → spec_schema(type, summary?) → write YAML
 PREVIEW: openuispec_preview(screen) → render spec as HTML with mock data, returns screenshot (no app needed)
 SCREENSHOTS: screenshot (web), screenshot_android, screenshot_ios — single + batch variants
 
-Skip only for purely non-UI requests.`,
+Skip only for purely non-UI requests.
+
+When generating UI code:
+1. Check anti_patterns in the prepare result — hard constraints on what NOT to produce
+2. Check design_context — match the complexity level and personality description
+3. Apply the AI Fingerprint Test: would a viewer immediately say "AI made this"? If yes, revise.`,
   }
 );
 
@@ -319,7 +324,7 @@ function buildAuditChecklist(projectDir: string, target: string, screenFilter?:
 server.registerTool(
   "openuispec_check",
   {
-    description: "Validate spec files (schema + semantic lint) and check prepare readiness. Does NOT inspect generated code. With audit=true, returns a spec-derived checklist of must_handle items, screen sections, and locale files — use it as a guide when YOU manually review the generated code.",
+    description: "Validate spec files (schema + semantic lint) and check prepare readiness. Does NOT inspect generated code. With audit=true, returns a spec-derived checklist of must_handle items, must_avoid anti-patterns, screen sections, and locale files — use it as a guide when YOU manually review the generated code. design_quality_score and audit_findings are included when audit=true.",
     inputSchema: {
       target: targetSchema,
       audit: z.boolean().optional().default(false).describe("Include the full audit checklist. Omit for a compact pass/fail summary."),
@@ -329,7 +334,7 @@ server.registerTool(
   },
   async ({ target, audit: includeAudit, screens, contracts }) => {
     try {
-      const result = buildCheckResult(target, projectCwd);
+      const result = buildCheckResult(target, projectCwd, includeAudit);
       const totalErrors = result.validation.total_errors + result.semantic.total_errors;
       const passing = totalErrors === 0 && result.prepare.ready;
 
@@ -358,6 +363,13 @@ server.registerTool(
         hints.push(buildAuditChecklist(projectDir, target, screenFilter, contractFilter));
       }
 
+      if (includeAudit && result.audit) {
+        hints.push(`DESIGN QUALITY SCORE: ${result.audit.score}/100 (${result.audit.errors} errors, ${result.audit.warnings} warnings)`);
+        if (!result.audit.passed && result.audit.threshold > 0) {
+          hints.push(`SCORE BELOW THRESHOLD: ${result.audit.score} < ${result.audit.threshold}`);
+        }
+      }
+
       if (baselineHint) hints.push(baselineHint);
       hints.push(passing ? "next_tool: openuispec_drift --snapshot (to create/update baseline)" : "Fix validation errors, then re-run openuispec_check.");
 
@@ -813,9 +825,10 @@ server.registerTool(
       full_page: z.boolean().optional().default(false).describe("Capture the full scrollable page instead of just the viewport"),
       selector: z.string().optional().describe("CSS selector to screenshot a specific element instead of the full page"),
       output_dir: z.string().optional().describe("Directory to save the screenshot PNG (relative to web app root). E.g. 'screenshots'. If omitted, only returns base64 in response."),
+      init_script: z.string().optional().describe("JavaScript to run before the page renders. Passed to the app via ?__ous_init=<base64> query param. The app's bootstrapper decodes and executes it — use for auth injection, role switching, or session setup."),
     },
   },
-  async ({ route, viewport, scale, theme, wait_for, full_page, selector, output_dir }) => {
+  async ({ route, viewport, scale, theme, wait_for, full_page, selector, output_dir, init_script }) => {
     try {
       return await takeScreenshot(projectCwd, {
         route,
@@ -826,6 +839,7 @@ server.registerTool(
         full_page,
         selector,
         output_dir,
+        init_script,
       });
     } catch (err) {
       return toolError(err);
@@ -894,6 +908,7 @@ const webBatchCaptureSchema = z.object({
   selector: z.string().optional().describe("CSS selector to screenshot a specific element"),
   full_page: z.boolean().optional().describe("Capture full scrollable page"),
   wait_for: z.number().optional().describe("Per-capture wait time in ms"),
+  init_script: z.string().optional().describe("Per-capture init script (overrides shared init_script for this capture)"),
 });
 
 server.registerTool(
@@ -906,11 +921,12 @@ server.registerTool(
       scale: z.number().optional().default(2).describe("Device pixel ratio for all captures (default 2)"),
       theme: z.enum(["light", "dark"]).optional().describe("Force color scheme for all captures"),
       output_dir: z.string().optional().describe("Directory to save all PNGs (relative to web app root)"),
+      init_script: z.string().optional().describe("Shared init script for all captures. Passed via ?__ous_init=<base64>. Per-capture init_script overrides this."),
     },
   },
-  async ({ captures, viewport, scale, theme, output_dir }) => {
+  async ({ captures, viewport, scale, theme, output_dir, init_script }) => {
     try {
-      return await takeScreenshotBatch(projectCwd, { captures, viewport, scale, theme, output_dir });
+      return await takeScreenshotBatch(projectCwd, { captures, viewport, scale, theme, output_dir, init_script });
     } catch (err) {
       return toolError(err);
     }