@ggui-ai/ui-gen 0.14.0 → 0.16.0

package/src/design-mode.ts

@@ -0,0 +1,182 @@
+// packages/ui-gen/src/design-mode.ts
+//
+// The ONE definition of the `designMode` option and the rendering-canvas
+// vocabulary. Every triad surface (system prompt, boilerplate, tier-0
+// gate, axis checks, evaluator criteria) AND the visual evaluator import
+// these types from here — nothing re-declares the unions.
+//
+//   - `constrained` (default) — today's triad: the component composes
+//     from the `@ggui-ai/design` primitives, prop enums and spacing
+//     scale, and tier-0 enforces the design vocabulary. Byte-identical
+//     to the pre-`designMode` behaviour (pinned by
+//     `design-mode.pin.test.ts`).
+//   - `free` — the design vocabulary is relaxed: raw HTML elements,
+//     inline styles and `<style>` blocks are allowed; the design package
+//     is importable but optional. Every HARD contract stays: the data
+//     contract via the boilerplate-typed wire hooks, the import
+//     allowlist + security bans, the host envelope, the budgets, the
+//     blueprint-reuse shape, and brand-bearing color via the closed
+//     `--ggui-color-*` token manifest (no literals, no fallbacks).
+
+export const DESIGN_MODES = ["constrained", "free"] as const;
+
+export type DesignMode = (typeof DESIGN_MODES)[number];
+
+export const DEFAULT_DESIGN_MODE: DesignMode = "constrained";
+
+// ─── Rendering canvas ───────────────────────────────────────────────────────
+//
+// ONE canvas vocabulary shared by the prompt input (the `free` prompt
+// TELLS the agent its canvas; the `constrained` prompt keeps its
+// shell/screen descriptors byte-for-byte) and the visual evaluator (one
+// screenshot + judge score per class at `CANVAS_VIEWPORTS[class]`).
+//
+// A class is derived from DISPLAY MODE + width, never from width alone:
+// an inline chat card is `xs-chat-card` whatever the host window
+// measures (the bubble, not the window, bounds the component); a
+// fullscreen-class surface follows its width through the three
+// breakpoints. `canvasForViewportWidth` is monotonic in width per
+// display mode (pinned by `design-mode.test.ts`).
+
+export const CANVAS_CLASSES = [
+  "xs-chat-card",
+  "mobile-fullscreen-small",
+  "md",
+  "lg",
+  "xl",
+] as const;
+
+export type CanvasClass = (typeof CANVAS_CLASSES)[number];
+
+export interface CanvasViewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** The viewport (CSS px) each class is rendered + judged at. */
+export const CANVAS_VIEWPORTS: Readonly<Record<CanvasClass, CanvasViewport>> = {
+  "xs-chat-card": { width: 400, height: 640 },
+  "mobile-fullscreen-small": { width: 390, height: 844 },
+  md: { width: 768, height: 1024 },
+  lg: { width: 1024, height: 768 },
+  xl: { width: 1440, height: 900 },
+};
+
+/**
+ * The two display modes the canvas derivation distinguishes. `inline`
+ * is the chat card (MCP Apps `inline` display mode / the `chat` shell);
+ * `fullscreen` is every surface the component owns edge to edge or as
+ * a panel (`fullscreen`, `pip`, the `spatial` and `partial` shells) —
+ * there the width decides the class.
+ */
+export type CanvasDisplayMode = "inline" | "fullscreen";
+
+/**
+ * Map a shell name (`chat` / `fullscreen` / `spatial` / `partial`) or an
+ * MCP Apps display mode (`inline` / `fullscreen` / `pip`) onto the
+ * canvas display mode. Only `chat` and `inline` are the inline card;
+ * everything else is width-governed.
+ */
+export function canvasDisplayModeForShell(shell: string | undefined): CanvasDisplayMode {
+  return shell === "chat" || shell === "inline" ? "inline" : "fullscreen";
+}
+
+/** Fullscreen-class breakpoints (inclusive lower bounds), CSS px. */
+export const CANVAS_BREAKPOINTS = { md: 600, lg: 1024, xl: 1440 } as const;
+
+/**
+ * Derive the canvas class from display mode + container width.
+ *
+ *   inline      → `xs-chat-card` at every width
+ *   fullscreen  → width <  600  → `mobile-fullscreen-small`
+ *                 600 – 1023    → `md`
+ *                 1024 – 1439   → `lg`
+ *                 ≥ 1440        → `xl`
+ */
+export function canvasForViewportWidth(mode: CanvasDisplayMode, width: number): CanvasClass {
+  if (mode === "inline") return "xs-chat-card";
+  if (width < CANVAS_BREAKPOINTS.md) return "mobile-fullscreen-small";
+  if (width < CANVAS_BREAKPOINTS.lg) return "md";
+  if (width < CANVAS_BREAKPOINTS.xl) return "lg";
+  return "xl";
+}
+
+/**
+ * Map today's shell × screen descriptors onto a canvas class when no
+ * width is known. `chat` is always the inline card; `spatial` is a
+ * ~600px floating panel (`md`); `fullscreen` follows the screen. Unknown
+ * values fall back to `lg` (the widest common fullscreen), matching the
+ * skeleton's `fullscreen` / `universal` defaults.
+ */
+export function canvasForRendering(
+  shellType: string | undefined,
+  screen: string | undefined,
+): CanvasClass {
+  const shell = shellType ?? "fullscreen";
+  if (canvasDisplayModeForShell(shell) === "inline") return "xs-chat-card";
+  if (shell === "spatial") return "md";
+  switch (screen ?? "universal") {
+    case "mobile":
+      return "mobile-fullscreen-small";
+    case "tablet":
+      return "md";
+    default:
+      return "lg";
+  }
+}
+
+export interface CanvasDescriptor {
+  /** Short human label. */
+  readonly label: string;
+  /** Inclusive width range the component must look right across, CSS px. */
+  readonly minWidthPx: number;
+  readonly maxWidthPx: number;
+  /** What the host draws around the component at this canvas. */
+  readonly host: string;
+}
+
+export const CANVAS_DESCRIPTORS: Readonly<Record<CanvasClass, CanvasDescriptor>> = {
+  "xs-chat-card": {
+    label: "extra-small chat card",
+    minWidthPx: 320,
+    maxWidthPx: 480,
+    host: "an inline card inside a chat message bubble — the host draws the card border, shadow and rounded corners; the component fills the bubble width and takes its natural height",
+  },
+  "mobile-fullscreen-small": {
+    label: "small mobile fullscreen",
+    minWidthPx: 320,
+    maxWidthPx: 599,
+    host: "a phone-sized viewport the component owns edge to edge — single column, touch targets at least 44px, the component manages its own scroll",
+  },
+  md: {
+    label: "medium panel",
+    minWidthPx: 600,
+    maxWidthPx: 1023,
+    host: "a tablet viewport or a floating panel (spatial / picture-in-picture) — one or two columns, medium density",
+  },
+  lg: {
+    label: "large fullscreen",
+    minWidthPx: 1024,
+    maxWidthPx: 1439,
+    host: "a desktop viewport the component owns edge to edge — multi-column layouts, hover states and pointer interactions are available",
+  },
+  xl: {
+    label: "extra-large fullscreen",
+    minWidthPx: 1440,
+    maxWidthPx: 1920,
+    host: "a wide desktop viewport the component owns edge to edge — cap content width or use the extra room deliberately; never stretch a single column across the whole width",
+  },
+};
+
+/**
+ * The explicit sentence the `free` prompt renders for a canvas — the
+ * agent is TOLD the canvas, it never guesses it.
+ */
+export function describeCanvas(canvas: CanvasClass): string {
+  const d = CANVAS_DESCRIPTORS[canvas];
+  return (
+    `This component renders on the \`${canvas}\` canvas (${d.label}): ` +
+    `${d.minWidthPx}–${d.maxWidthPx}px wide, ${d.host}. ` +
+    `Design for the whole range — the host may size the iframe anywhere inside it.`
+  );
+}

package/src/design-system-docs.ts

@@ -36,20 +36,24 @@ These tokens adapt automatically to any theme (light, dark, branded). **ALWAYS u
 
 | Token | CSS Variable | Default | Role |
 |-------|-------------|---------|------|
-| surface | var(--ggui-color-surface) | Main content background |
-| onSurface | var(--ggui-color-onSurface) | Primary text on surface |
-| surfaceVariant | var(--ggui-color-surfaceVariant) | Card/panel background |
-| onSurfaceVariant | var(--ggui-color-onSurfaceVariant) | Muted/secondary text |
+| ground | var(--ggui-color-ground) | The page / canvas behind everything |
+| onGround | var(--ggui-color-onGround) | Text on the canvas |
+| container | var(--ggui-color-container) | A card, a bubble, a panel — the unit of content |
+| onContainer | var(--ggui-color-onContainer) | Body text on a card |
+| elevated | var(--ggui-color-elevated) | Menus, popovers, modals, toasts — floats above a card |
+| onElevated | var(--ggui-color-onElevated) | Text on an elevated surface |
+| sunken | var(--ggui-color-sunken) | Wells, inputs at rest, code blocks — recessed inside a card |
+| onSunken | var(--ggui-color-onSunken) | Muted / secondary text |
 | container | var(--ggui-color-container) | Primary-branded containers |
 | onContainer | var(--ggui-color-onContainer) | Text on branded containers |
 | outline | var(--ggui-color-outline) | Borders, dividers |
 | outlineVariant | var(--ggui-color-outlineVariant) | Subtle borders |
 
 **Usage pattern:**
-- Page/section background → \`var(--ggui-color-surface)\`
-- Body text → \`var(--ggui-color-onSurface)\`
-- Card/panel background → \`var(--ggui-color-surfaceVariant)\`
-- Secondary/muted text → \`var(--ggui-color-onSurfaceVariant)\`
+- Page/section background → \`var(--ggui-color-ground)\`
+- Body text → \`var(--ggui-color-onContainer)\`
+- Card/panel background → \`var(--ggui-color-container)\`; recessed wells / inputs → \`var(--ggui-color-sunken)\`
+- Secondary/muted text → \`var(--ggui-color-onSunken)\`
 - Branded section/header → \`var(--ggui-color-container)\` bg + \`var(--ggui-color-onContainer)\` text
 - Borders/dividers → \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 
@@ -66,11 +70,11 @@ Prefer the primitives' \`tone="success|warning|error|info"\` prop over hand-writ
 - **NEVER** use rgba(), hsl(), or other CSS color functions with hardcoded values.
 - **NEVER** use raw neutral-* or gray-* scale tokens (neutral-50, neutral-900, etc.) — these are internal to the theme and break in dark mode.
 - **ALWAYS** use semantic tokens for text and backgrounds:
-  - Text: \`var(--ggui-color-onSurface)\` or \`var(--ggui-color-onSurfaceVariant)\`
-  - Backgrounds: \`var(--ggui-color-surface)\` or \`var(--ggui-color-surfaceVariant)\`
+  - Text: \`var(--ggui-color-onContainer)\` or \`var(--ggui-color-onSunken)\`
+  - Backgrounds: \`var(--ggui-color-container)\` or \`var(--ggui-color-sunken)\`
   - Borders: \`var(--ggui-color-outline)\` or \`var(--ggui-color-outlineVariant)\`
 - For branded elements use \`var(--ggui-color-primary-*)\` scale tokens — these ARE safe because primary adapts per theme.
-- For card backgrounds use \`var(--ggui-color-surfaceVariant)\` or \`var(--ggui-color-primary-50)\`
+- For card backgrounds use \`var(--ggui-color-container)\` or \`var(--ggui-color-primary-50)\`
 
 ## Spacing
 
@@ -165,7 +169,7 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 \`\`\`
 
 ### Color usage guide
-- **Semantic roles** (surface, onSurface, container, outline): Use for all surface/text/border decisions — these adapt to any theme
+- **Layering roles** (ground, container, elevated, sunken + their on* inks; outline): one kind of AREA each — use them for every background/text/border decision; they adapt to any theme
 - **primary-50/100**: Section backgrounds, highlight strips, card headers
 - **primary-200/300**: Borders, dividers, focus rings, input outlines
 - **primary-500/600**: Icons, links, labels, badges, buttons, CTAs
@@ -174,7 +178,7 @@ Use \`var(--ggui-spacing-N)\` for all padding, gap, and margin values. **Never u
 
 The primary palette is the app's brand — use it throughout (headers, accents, borders, interactive elements), not just on the submit button.
 
-**Note:** Do NOT add fallback values to var() (e.g., var(--ggui-color-surface, #fafafa)). Just use var(--ggui-color-surface) — the theme provides all values.
+**Note:** Do NOT add fallback values to var() (e.g., var(--ggui-color-container, #fafafa)). Just use var(--ggui-color-container) — the theme provides all values.
 
 ## Motion & Animation
 

package/src/evaluation/axis-checks/dispatch.ts

@@ -7,12 +7,15 @@ import type { Classification } from "../../classifier/index.js";
 import type { EvalIssue } from "../types-public.js";
 import { REGISTRY } from "./registry.js";
 import { matches, type AxisCheckInput } from "./types.js";
+import type { DesignMode } from "../../design-mode.js";
 
 export interface RunAxisChecksInput {
   sourceCode: string;
   compiledCode: string | null;
   contract?: DataContract;
   originalPrompt: string;
+  /** Which triad produced the source — see `AxisCheckInput.designMode`. */
+  designMode?: DesignMode;
 }
 
 export function runAxisChecks(
@@ -27,6 +30,7 @@ export function runAxisChecks(
     ...(input.contract !== undefined ? { contract: input.contract } : {}),
     originalPrompt: input.originalPrompt,
     classification,
+    ...(input.designMode !== undefined ? { designMode: input.designMode } : {}),
   };
 
   const issues: EvalIssue[] = [];

package/src/evaluation/axis-checks/extras.ts

@@ -145,6 +145,11 @@ const stepperAdopted: AxisCheck = {
   values: ["multi-step"],
   run(input: AxisCheckInput): EvalIssue[] {
     if (input.compiledCode === null) return [];
+    // `free` design mode: the Stepper composite is optional (the prompt
+    // names it as a default, not a requirement), so the adoption
+    // mandate stands down. `layout.multi_step.state_present` — the
+    // behavioural rule — still fires in both modes.
+    if (input.designMode === "free") return [];
     if (/<Stepper[\s/>]/.test(input.sourceCode)) return [];
     return [
       mkIssue(

package/src/evaluation/cost-tracker.ts

@@ -15,9 +15,8 @@ import { MODEL_REGISTRY, type ModelId } from '@ggui-ai/protocol';
  * This table used to hand-maintain its own per-1K prices, and drifted:
  * on 2026-07-31 four of its six rows were wrong (Haiku 4.5 20% low,
  * gemini-3-flash-preview 5-7x low, gpt-5.4-mini ~3x low, Luna 5x high
- * after OpenAI's cut). Deriving from the registry — which the pod's
- * pricing test now pins against the vendored LiteLLM snapshot — means
- * one place to update and one place that can be wrong.
+ * after OpenAI's cut). Deriving from the registry — whose Anthropic rows
+ * `@ggui-ai/protocol`'s own tests pin — means one place to update and one place that can be wrong.
  *
  * Resolution order mirrors the benchmark harness's
  * `resolveJudgeCostModelId`: exact key, unique `/<model>` suffix, then

package/src/evaluation/index.ts

@@ -22,6 +22,8 @@ export type {
   EvalOutcome,
   EvalCategory,
   EvalResult,
+  VisualEvalSummary,
+  CanvasVisualSummary,
   EvalCriterion,
   CriterionCoverage,
   CriterionRunStatus,
@@ -39,6 +41,7 @@ export {
   priorityForIssue,
   isBlocked,
   getActionableIssues,
+  criteriaFor,
   getCriteriaByPriority,
   getCriterionById,
   getLLMCriteria,
@@ -84,5 +87,46 @@ export type { RunAxisChecksInput } from './axis-checks/index.js';
 // rubric — scoring generation on criteria the generator was never taught
 // is a constraint-alignment violation, so out-of-loop judges get this
 // seam instead of a rubric extension.
-export { callMultimodalLLM } from './visual-evaluator.js';
-export type { VisualEvalConfig } from './visual-evaluator.js';
+export {
+  callMultimodalLLM,
+  captureScreenshot,
+  resolveLaunchOptions,
+  runVisualEvaluation,
+  runVisualEval,
+  summarizeVisualResult,
+} from './visual-evaluator.js';
+export type {
+  VisualEvalConfig,
+  VisualEvalContext,
+  VisualEvalDeps,
+  VisualEvalOutcome,
+  VisualEvaluationResult,
+  CanvasVisualResult,
+  ScreenshotDeps,
+  ScreenshotLauncher,
+  ScreenshotBrowser,
+  ScreenshotPage,
+  ChromiumProvider,
+} from './visual-evaluator.js';
+
+// Canvas vocabulary — the per-canvas visual evaluation speaks it
+// (`VisualEvalConfig.canvases`, `CanvasVisualResult.canvas`); re-exported
+// here so a caller driving `runVisualEvaluation` from this subpath never
+// has to reach the package root for the class names, viewports or
+// descriptors.
+export {
+  CANVAS_CLASSES,
+  CANVAS_VIEWPORTS,
+  CANVAS_BREAKPOINTS,
+  CANVAS_DESCRIPTORS,
+  canvasForViewportWidth,
+  canvasForRendering,
+  canvasDisplayModeForShell,
+  describeCanvas,
+} from '../design-mode.js';
+export type {
+  CanvasClass,
+  CanvasViewport,
+  CanvasDisplayMode,
+  CanvasDescriptor,
+} from '../design-mode.js';

package/src/evaluation/llm-evaluator.ts

@@ -26,6 +26,7 @@ import { createAgent } from '../harness/llm-router';
 import type { AgentConfig, LLMToolDef, LLMAgent } from '../harness/llm-router';
 import type { JsonObject } from '@ggui-ai/protocol';
 import { getCriterionById } from './types-public.js';
+import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
 
 // =============================================================================
 // Helpers
@@ -66,6 +67,14 @@ export interface LLMEvalContext {
   originalPrompt: string;
   designContext?: string;
   contract?: unknown;
+  /**
+   * Which triad produced the source. Selects the criteria text
+   * (`criteriaFor`) and the mother prompt's styling rules: in `free`
+   * mode the `tokens` criterion narrows to color and the `visual`
+   * criterion + "Design System Rules" block become arm-neutral. Absent
+   * means `constrained` (byte-identical to the pre-`designMode` prompt).
+   */
+  designMode?: DesignMode;
 }
 
 export interface LLMEvalConfig {
@@ -108,14 +117,62 @@ export interface EvalContext {
   originalPrompt: string;
   contract?: unknown;
   designSystemSummary?: string;
+  /** See `LLMEvalContext.designMode`. */
+  designMode?: DesignMode;
 }
 
+/**
+ * Arm-neutral styling rules for `designMode: 'free'` — replaces the
+ * constrained "Design System Rules" block. Mirrors the free prompt: color
+ * on the closed token manifest, everything else may be literal, raw HTML
+ * + CSS is a first-class choice.
+ */
+const FREE_STYLING_RULES = `## Styling Rules (important for evaluation)
+- Color: every color must be a bare \`var(--ggui-color-*)\` token — a hardcoded #hex, rgb()/hsl() or CSS named color is a fail, and so is a literal fallback inside \`var(--ggui-*, …)\`.
+- Spacing, typography, radius, shadow geometry and layout values MAY be literals (\`padding: '20px'\`, \`fontSize: 18\`, \`borderRadius: 12\`) — NEVER flag them.
+- Raw HTML elements with inline styles or \`<style>\` blocks are a first-class choice — never flag "not using the design system" or reward using it.
+- When \`@ggui-ai/design\` primitives ARE used, their enum/scale props (\`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`tone="muted"\`, \`surface="accent"\`) are valid.
+- One \`export default function Component\` — helper components as named functions above it are fine`;
+
+const CONSTRAINED_STYLING_RULES = `## Design System Rules (important for evaluation)
+- Spacing props (\`gap\`, \`padding\`, \`margin\`) take a t-shirt-scale name: \`gap="md"\`, \`padding="lg"\` (\`none|xs|sm|md|lg|xl|2xl\`). **These ARE design tokens** — each resolves to a \`--ggui-spacing-*\` variable. A raw \`var(--ggui-spacing-*)\` string is an accepted escape hatch. NEVER flag a scale name as "hardcoded". Only a numeric prop (\`padding={24}\`) or a raw CSS length (\`gap="13px"\`) bypasses the scale and should be warned.
+- All colors must use CSS variables: \`color="var(--ggui-color-primary-600)"\` — hardcoded #hex or rgb() is a fail
+- Component props that take enum/scale values — \`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`padding="lg"\`, \`shadow="md"\`, \`radius="lg"\`, \`tone="muted"\`, \`surface="accent"\` — are all design system tokens and are always valid
+- One \`export default function Component\` — helper components as named functions above it are fine`;
+
+const CONSTRAINED_VISUAL_REFERENCE = `**visual**: Design system consistency.
+- Uses CSS variables (var(--ggui-*)) for colors, not hardcoded values
+- Consistent use of spacing tokens
+- Proper use of component variants (primary, outline, ghost)
+- Shadow, border-radius from design system tokens`;
+
+const FREE_VISUAL_REFERENCE = `**visual**: Visual composition.
+- Clear hierarchy (one focal point, headings distinct from body), consistent spacing rhythm
+- Coherent palette drawn from the theme color tokens
+- Fit to the canvas: fluid width, nothing cramped or stretched
+- No reward or penalty for using (or not using) the design-system primitives`;
+
+const CONSTRAINED_RAW_CLICK_TARGET_GAP = `- A raw \`<div>\` / \`<span>\` used as a click target without \`as={Clickable}\`
+  (no role, no keyboard) — or any hand-rolled interactive element.`;
+
+const FREE_RAW_CLICK_TARGET_GAP = `- A raw \`<div>\` / \`<span>\` used as a click target with no \`role="button"\`,
+  \`tabIndex\` and keyboard handler — a real \`<button>\` / \`<a href>\` is the
+  correct raw element and is never a gap.`;
+
 export function buildMotherPrompt(ctx: EvalContext): string {
   const parts: string[] = [];
-
-  parts.push(`You are evaluating a generated React component built with the ggui design system.
+  const designMode = ctx.designMode ?? DEFAULT_DESIGN_MODE;
+  const free = designMode === 'free';
+
+  parts.push(
+    free
+      ? `You are evaluating a generated React component. It was composed freely — raw HTML elements, inline styles and <style> blocks are allowed and the ggui design package is optional — against a data contract and a theme-token color rule.
+The code has already passed automated checks (compilation, security, imports, color tokens).
+Your job is to evaluate ONE specific quality criterion per call.`
+      : `You are evaluating a generated React component built with the ggui design system.
 The code has already passed automated checks (compilation, security, imports, design tokens).
-Your job is to evaluate ONE specific quality criterion per call.`);
+Your job is to evaluate ONE specific quality criterion per call.`,
+  );
 
   parts.push(`## About This Prompt
 This system prompt has 2 sections:
@@ -173,11 +230,7 @@ ${JSON.stringify(ctx.contract).slice(0, 6000)}
 ${ctx.designSystemSummary}`);
   }
 
-  parts.push(`## Design System Rules (important for evaluation)
-- Spacing props (\`gap\`, \`padding\`, \`margin\`) take a t-shirt-scale name: \`gap="md"\`, \`padding="lg"\` (\`none|xs|sm|md|lg|xl|2xl\`). **These ARE design tokens** — each resolves to a \`--ggui-spacing-*\` variable. A raw \`var(--ggui-spacing-*)\` string is an accepted escape hatch. NEVER flag a scale name as "hardcoded". Only a numeric prop (\`padding={24}\`) or a raw CSS length (\`gap="13px"\`) bypasses the scale and should be warned.
-- All colors must use CSS variables: \`color="var(--ggui-color-primary-600)"\` — hardcoded #hex or rgb() is a fail
-- Component props that take enum/scale values — \`variant="primary"\`, \`size="lg"\`, \`gap="md"\`, \`padding="lg"\`, \`shadow="md"\`, \`radius="lg"\`, \`tone="muted"\`, \`surface="accent"\` — are all design system tokens and are always valid
-- One \`export default function Component\` — helper components as named functions above it are fine
+  parts.push(`${free ? FREE_STYLING_RULES : CONSTRAINED_STYLING_RULES}
 
 ## Evaluation Criteria Reference
 
@@ -221,11 +274,7 @@ ${ctx.designSystemSummary}`);
 - Error boundaries or error messages for failure cases
 - Empty states ("No items found") when data arrays could be empty
 
-**visual**: Design system consistency.
-- Uses CSS variables (var(--ggui-*)) for colors, not hardcoded values
-- Consistent use of spacing tokens
-- Proper use of component variants (primary, outline, ghost)
-- Shadow, border-radius from design system tokens
+${free ? FREE_VISUAL_REFERENCE : CONSTRAINED_VISUAL_REFERENCE}
 
 ## Primitive Accessibility (built-in — do NOT flag as missing)
 
@@ -259,8 +308,7 @@ role, aria-*, label, or keyboard support — it is already there:
   to text is CORRECTLY silent — never ask for \`aria-hidden\`, it is there.
 
 REAL accessibility gaps worth flagging:
-- A raw \`<div>\` / \`<span>\` used as a click target without \`as={Clickable}\`
-  (no role, no keyboard) — or any hand-rolled interactive element.
+${free ? FREE_RAW_CLICK_TARGET_GAP : CONSTRAINED_RAW_CLICK_TARGET_GAP}
 - A hand-rolled control whose state (checked / selected / expanded /
   pressed) is conveyed ONLY by styling — e.g. a styled-div "checkbox"
   with a check icon + strikethrough label but no \`role="checkbox"\` /
@@ -329,11 +377,15 @@ function makeTier2Tool(criterion: string): LLMToolDef {
 // Per-criterion user prompts
 // =============================================================================
 
-function getCriterionPrompt(criterion: string, numberedSource: string): string {
+function getCriterionPrompt(
+  criterion: string,
+  numberedSource: string,
+  designMode: DesignMode,
+): string {
   const sourceBlock = `\nSource code (with line numbers):\n\`\`\`tsx\n${numberedSource}\n\`\`\``;
 
   // Use criteria.ts as single source of truth when available
-  const criterionDef = getCriterionById(criterion);
+  const criterionDef = getCriterionById(criterion, designMode);
   if (criterionDef && criterionDef.tier > 0) {
     return `${criterionDef.evalInstruction}
 ${sourceBlock}
@@ -489,7 +541,7 @@ Return your evaluation using the evaluate_visual tool.
 
 Example outputs:
 - Clean: {"result": "pass"}
-- Minor issues: {"result": "warn", "issues": ["Line 45: hardcoded '#f3f4f6' should use var(--ggui-color-surfaceVariant)", "Line 80: numeric padding={16} should use a scale name like padding='md'"]}
+- Minor issues: {"result": "warn", "issues": ["Line 45: hardcoded '#f3f4f6' should use var(--ggui-color-sunken)", "Line 80: numeric padding={16} should use a scale name like padding='md'"]}
 - Severe: {"result": "fail", "issues": ["Component uses entirely custom styling with no design system tokens"]}
 
 Use 'fail' only for pervasive design system violations. Use 'warn' for isolated cases.`;
@@ -553,10 +605,11 @@ async function evalCriterion(
   numberedSource: string,
   agent: LLMAgent,
   model: string,
+  designMode: DesignMode,
 ): Promise<CriterionResult> {
   const start = Date.now();
   const tool = tier === 1 ? makeTier1Tool(criterion) : makeTier2Tool(criterion);
-  const userPrompt = getCriterionPrompt(criterion, numberedSource);
+  const userPrompt = getCriterionPrompt(criterion, numberedSource, designMode);
 
   try {
     const response = await agent.callTools(
@@ -679,6 +732,7 @@ export async function preWarmEval(
     originalPrompt: context.originalPrompt,
     contract: context.contract,
     designSystemSummary: context.designContext,
+    designMode: context.designMode,
   });
 
   return { motherPrompt, dynamicCriteria: [] };
@@ -777,10 +831,12 @@ export async function runLLMEvaluation(
       : (providerName as 'openai' | 'google');
 
   // Use pre-warmed context if available, otherwise build fresh
+  const designMode = context.designMode ?? DEFAULT_DESIGN_MODE;
   const motherPrompt = preWarmedContext?.motherPrompt ?? buildMotherPrompt({
     originalPrompt: context.originalPrompt,
     contract: context.contract,
     designSystemSummary: context.designContext,
+    designMode,
   });
 
   // Add line numbers to source
@@ -810,8 +866,8 @@ export async function runLLMEvaluation(
 
   // Run ALL criteria in parallel: 7 static (2 tier 1 + 5 tier 2)
   const results = await Promise.all([
-    ...TIER_1_CRITERIA.map(c => evalCriterion(c, 1, motherPrompt, numberedSource, agent, model)),
-    ...TIER_2_CRITERIA.map(c => evalCriterion(c, 2, motherPrompt, numberedSource, agent, model)),
+    ...TIER_1_CRITERIA.map(c => evalCriterion(c, 1, motherPrompt, numberedSource, agent, model, designMode)),
+    ...TIER_2_CRITERIA.map(c => evalCriterion(c, 2, motherPrompt, numberedSource, agent, model, designMode)),
   ]);
 
   // Merge results