@ggui-ai/ui-gen 0.15.0 → 0.17.0

package/src/boilerplate/system-prompt.ts

@@ -14,6 +14,8 @@
 // string — the skeleton still renders cleanly for OSS callers who don't
 // pass doc blocks.
 
+import type { GenerationProfileInput } from "./styling-profile.js";
+import { buildStylingProfileSection, withStylingProfile } from "./styling-profile.js";
 import { resolveAppGadgets } from "@ggui-ai/protocol";
 import type {
   GadgetDescriptor,
@@ -22,6 +24,27 @@ import type {
   GadgetComponentExport,
 } from "@ggui-ai/protocol";
 import { buildCodingCriteriaSummary } from "../evaluation/types-public.js";
+import {
+  DEFAULT_DESIGN_MODE,
+  canvasForRendering,
+  type DesignMode,
+  type CanvasClass,
+} from "../design-mode.js";
+import { buildFreeDesignPrompt } from "./free-design-prompt.js";
+import {
+  ANTI_PATTERNS,
+  COMPONENT_STRUCTURE,
+  CONTEXT_SPEC_SECTION,
+  CONTRACT_SURFACE,
+  CROSS_REFERENCE_RULES,
+  DATA_PARAMETERIZATION,
+  DEFENSIVE_CODING,
+  FRAME_SIZING,
+  GESTURE_ROUTING,
+  INTERACTIVE_TRAITS,
+  PROTOCOL_NOTES,
+  renderGadgetCatalogSection,
+} from "./hard-sections.js";
 import {
   extractCallSignaturesFromDts,
   extractComponentPropsFromDts,
@@ -92,11 +115,28 @@ export interface SystemPromptInputs {
    * callers (the section stays byte-identical).
    */
   gadgetTypes?: Readonly<Record<string, string>>;
+  /**
+   * Which triad the prompt teaches. `constrained` (default) is today's
+   * design-system prompt, byte-identical to the pre-`designMode`
+   * output; `free` relaxes only the design vocabulary — see
+   * `./free-design-prompt.ts` and `../design-mode.ts`.
+   */
+  designMode?: DesignMode;
+  /**
+   * Rendering canvas class — `free` mode only. Rendered as an explicit
+   * width-range sentence so the agent is TOLD its canvas. When omitted
+   * it is derived from `shellType` × `screen`. Ignored in `constrained`
+   * mode (that prompt keeps its shell/screen descriptors verbatim).
+   */
+  canvas?: CanvasClass;
+  /** The app's generation profile (#991) — one bounded section, both arms; absent = byte-identical. */
+  profile?: GenerationProfileInput;
 }
 
 const SHELL_DESCRIPTIONS: Record<string, string> = {
   chat: "inline component inside ChatShell message bubble (~400px wide, compact)",
-  fullscreen: "full viewport, responsive layout",
+  fullscreen:
+    "the full host viewport, responsive layout — the frame stretches your root to its height; size to content, never to the viewport",
   spatial: "floating AR/VR panel (~600px, touch-friendly)",
 };
 
@@ -283,7 +323,9 @@ export function buildSystemPrompt(inputs: SystemPromptInputs): string {
   const shellDesc = SHELL_DESCRIPTIONS[shell] ?? SHELL_DESCRIPTIONS.fullscreen;
   const screenDesc = SCREEN_DESCRIPTIONS[scr] ?? SCREEN_DESCRIPTIONS.universal;
 
-  const criteriaBlock = inputs.criteriaBlock ?? buildCodingCriteriaSummary();
+  const designMode = inputs.designMode ?? DEFAULT_DESIGN_MODE;
+  const criteriaBlock =
+    inputs.criteriaBlock ?? buildCodingCriteriaSummary(designMode);
   const pitfallsBlock = inputs.pitfallsBlock ?? "";
   const designSystemDocs = inputs.designSystemDocs ?? "";
   const primitivesDoc = inputs.primitivesDoc ?? "";
@@ -299,11 +341,26 @@ export function buildSystemPrompt(inputs: SystemPromptInputs): string {
     inputs.gadgetTypes,
   );
 
+  const profileSection = buildStylingProfileSection(inputs.profile);
+
   const axisSection =
     inputs.axisDelta && inputs.axisDelta.trim().length > 0
       ? `\n## Shape Guidance\n${inputs.axisDelta}\n`
       : "";
 
+  if (designMode === "free") {
+    return buildFreeDesignPrompt({
+      userRequest: inputs.userRequest,
+      canvas: inputs.canvas ?? canvasForRendering(inputs.shellType, inputs.screen),
+      axisSection,
+      criteriaBlock,
+      wireDoc,
+      primitivesDoc,
+      gadgetsSection,
+      profileSection,
+    });
+  }
+
   return `You are ggui's UI builder. You receive a typed boilerplate and fill it in using apply_changes.
 
 ## Your Task
@@ -320,179 +377,26 @@ ${inputs.userRequest}
 
 ${criteriaBlock}
 ${axisSection}
-## Protocol Notes
-The boilerplate pre-declares every wire hook the contract requires (\`useAction\`, \`useStream\`, \`useGguiContext\`, plus capability hooks from \`@ggui-ai/gadgets\` when the contract declares \`clientCapabilities\`). Three rules:
-1. **Do NOT delete any pre-declared hook.** \`self_check\` fails with \`wire_preservation:<kind>:<name>\` if you remove one.
-2. **Consume every hook binding** somewhere in the component — in JSX, a callback, or an effect. Unused bindings fail lint with \`no-unused-vars\`.
-3. **Do NOT invent new wire calls.** Every \`useAction('X')\`, \`useStream('X')\`, \`useGguiContext('X')\` etc. MUST correspond to a declared entry on the contract. Calling one that isn't declared fails \`self_check\` with \`wire_undeclared:<kind>:<name>\` because the runtime has no Context/registration for it and would throw at first paint. If you need a new wire surface, that's a contract authoring step the agent owns — your job is to honor what's declared.
-
-Renaming a binding is fine — the wiring is the string-literal argument, not the identifier.
-
-## Contract surface — four specs + two catalogs
-
-A \`DataContract\` declares everything a GguiSession exchanges with the outside world. **Four typed specs** for the four data-flow directions, **two reference catalogs** for tool / hook lookups:
-
-| Surface              | Direction                  | Role                                                                 |
-| -------------------- | -------------------------- | -------------------------------------------------------------------- |
-| \`propsSpec\`         | server → UI (one-shot)     | Initial render values delivered once at \`ggui_render\`              |
-| \`streamSpec\`        | agent → UI (many)          | Typed channels for live updates via \`ggui_emit\`                    |
-| \`actionSpec\`        | UI → agent (events)        | Discrete events driving the agent's next turn (consumed via \`ggui_consume\`) |
-| \`contextSpec\`       | UI → server (state mirror) | UI state the agent observes between turns                            |
-| \`agentCapabilities.tools\`     | catalog                    | Tools the contract references via \`actionSpec[*].nextStep\` and \`streamSpec[*].source.tool\` |
-| \`clientCapabilities.gadgets\` | catalog                    | Browser-capability gadget hooks the component code mounts (e.g., \`useGeolocation\`) |
-
-**Placement rule for inbound specs**: actions drive turns; context observes state. There is no third category.
-
-**Data vs behavior**: the contract describes data flow; the component code describes behavior. Scroll, focus, toast, animation, clipboard write — all component code, never contract fields.
-
-## Defensive coding for absent / late-arriving data
-
-Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
-
-- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY — the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
-- **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
-- **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
-- **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
-- **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives — guard before reading \`.foo\`.
-- **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed — your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list — and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
-- **Props re-sync on repaint**: props the agent owns are the source of truth for display — prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change — \`useEffect(() => setCount(props.count ?? 0), [props.count])\` — or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
-- **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders — never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
-- **Empty state**: when a list or results array is empty, render \`<EmptyState title="…" description="…" />\` — a region that renders nothing when empty looks broken to the user.
-
-Unhandled \`Cannot read properties of undefined\` errors trip the iframe error boundary and the user sees "Something went wrong" — a regression class the runtime can't recover from.
-
-## Picking the right primitive for user gestures
-
-Choose by what the user is DOING, not where the result goes — the runtime handles the routing.
-
-| Gesture intent | LLM writes | Notes |
-| -------------- | ---------- | ----- |
-| Fire a server-side action | \`useAction(name)\` + call \`dispatch(name, payload)\` | Every action is agent-routed. The runtime emits an event on \`ggui_consume\`; the agent reacts on its next turn. If the contract entry declares \`nextStep: 'X'\`, that names the tool the agent SHOULD call next — advisory hint forwarded as event metadata. |
-| Surface state to the agent's context | the auto-generated \`setSlotName\` setter (from the boilerplate's \`useGguiContext\` line) | The runtime owns useState + Provider; the boilerplate emits one \`const [slot, setSlot] = useGguiContext<T>('slot')\` line per declared \`contextSpec\` slot. Write plain JSX, no \`useState\`, no Provider wrap. Every value change auto-flows to the host LLM (debounced). One-way client → agent — see "Observable state via \`contextSpec\`" below. |
-| Use a browser capability (camera, mic, geolocation, clipboard, file picker, notifications) | call the hook the contract declared, e.g., \`const loc = useGeolocation();\` and \`await loc.start()\` | The contract's \`clientCapabilities.gadgets\` declares which gadget exports the UI uses. The hook implementations live in \`@ggui-ai/gadgets\` (or a third-party package named in the \`Package\` column). Read \`status\` ("idle" / "prompting" / "active" / "completed" / "denied" / "error") to gate UI, and thread the resolved \`value\` into a contextSpec slot or actionSpec payload if the agent needs to see it. |
-| Open external link | Plain \`<a href="https://...">\` (or \`target="_blank"\`) | External cross-origin clicks are intercepted and routed through the host (security warnings, app-internal navigation, audit). Same-origin links and \`#fragment\` jumps stay native. |
-| Toggle fullscreen / chrome | Plain \`el.requestFullscreen()\` / \`document.exitFullscreen()\` | The native browser API is intercepted; the host adjusts iframe chrome accordingly. Returns a resolved promise so \`.then()\` / \`await\` chains don't break. |
-
-Every gesture fires a uniform server-side audit envelope (\`ggui_runtime_submit_action\`) so operators see all three patterns in RenderInspector with the same shape.
-
-**Don't import wire hooks for link / display-mode.** \`useAction\` is the only wire hook for user gestures; links and fullscreen use plain HTML / browser APIs.
-
-**All actions are agent-routed.** Every action emits an event the agent reacts to on its next turn via \`ggui_consume\`. The optional \`nextStep: '<tool>'\` field on an \`actionSpec\` entry is a HINT naming the tool the agent SHOULD call next — the contract author's recommendation, NOT a binding directive. The agent decides whether to honor it. If you want to declare a tool catalog entry the contract references, add it to \`agentCapabilities.tools[<name>]\` with input/output schemas; the cross-ref linter rejects dangling \`nextStep\` values that don't resolve to a declared catalog entry.
-
-## Making a primitive interactive — \`as={Trait}\`
-
-Structural primitives (\`Box\`, \`Stack\`, \`Row\`, \`Card\`) have NO \`onClick\` by default. Add interactivity with the \`as\` prop — a trait, not a wrapper:
-
-\`\`\`tsx
-<Card as={Clickable} onClick={() => dispatch('select', { id })}
-      hoverStyle={{ boxShadow: 'var(--ggui-shape-shadow-lg)' }}>…</Card>
-\`\`\`
-
-- \`as={Clickable}\` → \`onClick\` + keyboard activation (Enter/Space) + \`role="button"\` + \`hoverStyle\`/\`activeStyle\`/\`cursor\`.
-- \`as={Hoverable}\` → \`hoverStyle\` only (no click). \`as={Pressable}\` → \`onPress\` + \`pressStyle\`.
-
-\`as={Trait}\` is a PROP — it does NOT re-nest the JSX. Never write \`<Clickable>…</Clickable>\` around a primitive; put \`as={Clickable}\` on the primitive itself. The trait carries the keyboard + ARIA wiring, so don't hand-write \`onKeyDown\` / \`role\`. Trait components (\`Clickable\`, \`Hoverable\`, \`Pressable\`) import from \`@ggui-ai/design\` like everything else — the boilerplate already imports them.
-
-**Semantic components are already interactive** — \`Button\` (\`onClick\`), \`Link\` (\`href\`), \`Input\` / \`Select\` (\`onChange\`). Use their own props; never put \`as\` on them. \`Text\` picks its element with \`is\` (\`<Text is="label">\`), not \`as\`.
-
-**Never nest two interactive elements.** Interactive content MUST NOT contain other interactive content — a gesture on the inner control bubbles to the outer one and fires BOTH handlers (one user click → the action dispatched twice). Do NOT put a \`Button\`, \`Checkbox\`, \`Input\`, \`Select\`, \`Link\`, or another \`as={Clickable}\` primitive inside a \`Card\` / \`Box\` / \`Row\` / \`Stack\` that is itself \`as={Clickable}\`. Wire each \`useAction\` callback to exactly ONE surface: EITHER the whole card is the trigger (interactive container, no interactive children) OR an inner control is the trigger (plain container, no \`as={Clickable}\`) — never both. A row with a checkbox: put the action on the \`Checkbox onChange\` and leave the row plain.
-
-**\`Text\` / \`Heading\` accept NO event handlers and NO \`as\` — only \`style\` / \`className\` plus their own typed props.** \`onClick\`, \`onDoubleClick\`, \`as={Clickable}\`, \`color\` are all type errors on \`Text\`. When the request says a label is "clickable", "editable", "edit on click / double-click", or "tap to …", do ONE of these — never put the handler on \`Text\`:
-
-\`\`\`tsx
-// Click-to-edit a label: wrap the Text in a Clickable structural primitive.
-<Box as={Clickable} onClick={() => setEditingId(task.id)}
-     style={{ cursor: 'pointer' }}>
-  <Text weight="semibold">{task.title}</Text>
-</Box>
-
-// Or pair the label with an explicit edit Button (clearer affordance).
-<Row gap="xs" align="center">
-  <Text weight="semibold">{task.title}</Text>
-  <Button variant="ghost" size="xs" aria-label="Edit title"
-          onClick={() => setEditingId(task.id)}>Edit</Button>
-</Row>
-
-// In edit mode, swap the Text for an Input.
-{editingId === task.id
-  ? <Input value={draftTitle} onChange={setDraftTitle} label="Task title" />
-  : <Text weight="semibold">{task.title}</Text>}
-\`\`\`
-
-## Anti-patterns — DO NOT WRITE
-
-The following identifiers / shapes are RETIRED from the contract surface as of 2026-05-11. Pre-2026-05-11 examples in your training data may include them; do not reproduce. The linter / CI grep gate rejects:
-
-- \`useWiredTool\`, \`useClientTool\` — retired hooks. Replace with \`useAction\` (events) and the named hook from \`@ggui-ai/gadgets\` (browser capabilities).
-- \`dispatch: { kind: 'tool', tool: '...' }\` / \`dispatch: { kind: 'agent', intendedTool: '...' }\` — retired discriminated-union. Use the flat optional \`nextStep?: '<tool>'\` instead.
-- \`mode: 'host-routed'\` / \`mode: 'tool'\` — retired \`mode\` field. Same fix: flat \`nextStep?\`.
-- \`broadcast: {...}\` on the contract — retired top-level field. Use \`streamSpec[channel].source: {tool, args?}\` to declare a tool-fed channel.
-- \`wiredTools\` / \`agentTools\` (top-level) — retired catalog names. Use \`agentCapabilities.tools\`.
-- \`clientTools\` / \`clientCapabilities.capabilities\` — retired catalog shapes. Use \`clientCapabilities.gadgets\` (entries declare hooks, not RPC).
-- \`@ggui-ai/client-tools\` — retired package name. Import gadget hooks from \`@ggui-ai/gadgets\`.
-- \`intendedTool\` — retired. Use \`nextStep\` (flat).
-- \`props: { properties: {...} }\` as a CONTRACT field — retired. The contract field is \`propsSpec\` (the wire \`props\` field on render / update still carries VALUES).
-
-## Cross-reference rules
-
-When you declare a reference, also declare the catalog entry it points at:
-
-- \`actionSpec[X].nextStep = 'fetch_inbox'\` → \`agentCapabilities.tools.fetch_inbox = { toolInfo: { inputSchema, description?, outputSchema? }, usage?, example? }\` MUST exist. Cross-ref code: \`CTR_REF_NEXT_STEP\`.
-- \`streamSpec[X].source.tool = 'list_messages'\` → \`agentCapabilities.tools.list_messages\` MUST exist. Cross-ref code: \`CTR_REF_STREAM_SOURCE\`.
-- The catalog entry's schemas MUST be a superset of the referencing spec's schema. Cross-ref code: \`CTR_SCHEMA_INCOMPAT\`.
-
-## clientCapabilities — registered catalog
-
-${gadgetsSection}
-
-Each hook conforms to \`GadgetHook<TOutput, TOptions>\`: call \`start(opts?)\` to fire, read \`{value, status, error, stop?}\`. \`status\` walks through \`idle → prompting → active|completed\` or routes to \`denied\` / \`error\` on failure.
-
-3rd-party plugins (Leaflet maps, Mapbox, Stripe, Chart.js, …) are registered via \`createGguiGadget\` from \`@ggui-ai/gadgets\` and surface in this same table when the operator has added them to \`App.gadgets\`. Reference any registered hook by name — render validation rejects hooks not in this catalog with \`gadget_not_registered\`.
-
-## Observable state via \`contextSpec\`
-
-When the contract declares \`contextSpec\`, the boilerplate auto-generates one \`useGguiContext\` call per slot at the top of your component. The runtime owns the underlying \`useState\` and the Provider tree — **you do NOT write \`useState\` or any \`<Provider>\` wrap yourself**:
-
-\`\`\`tsx
-import { useGguiContext } from '@ggui-ai/wire';
-
-export default function Component(props: Props) {
-  // AUTO-GENERATED — do not remove or rename:
-  const [currentStep, setCurrentStep] = useGguiContext<number>('currentStep');
-  const [draftText, setDraftText] = useGguiContext<string>('draftText');
-
-  // Plain JSX. No Provider wrap. The runtime already wrapped your
-  // component in nested SingleSlotProviders before this code ran.
-  return (
-    <Container>
-      <Text>Step {currentStep}</Text>
-      <Input value={draftText} onChange={(e) => setDraftText(e.target.value)} />
-      <Button onClick={() => setCurrentStep((s) => s + 1)}>Next</Button>
-    </Container>
-  );
-}
-\`\`\`
-
-For every declared slot you have **\`slotName\` + \`setSlotName\`** in scope:
-- **Read** the value to render: \`<Text>Step {currentStep}</Text>\`
-- **Write** via the setter: \`setCurrentStep(s => s + 1)\` (in callbacks, effects, anywhere)
-
-Every value change is mirrored to the host LLM's context automatically (debounced, default 300ms — adjustable per-slot via \`entry.debounceMs\` in the contract). The agent sees the user's interaction state — drafts, current step, hover, selection — without you calling any API.
-
-**When to use the auto-generated state.** Any slot the contract declared. If \`contextSpec.draftText\` exists, bind \`<Input value={draftText} onChange={e => setDraftText(e.target.value)}>\` so the agent sees the typing live. If \`contextSpec.currentStep\` exists, render the step indicator from \`currentStep\` and bump it via \`setCurrentStep\` in your "next" callback.
-
-**When NOT to use it.** Local UI state the contract did NOT declare — \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
-
-**\`contextSpec\` direction is one-way: client → agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` — there is no return path.
-
-**Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.
+` +
+    [
+      PROTOCOL_NOTES,
+      CONTRACT_SURFACE,
+      DEFENSIVE_CODING,
+      GESTURE_ROUTING,
+      INTERACTIVE_TRAITS,
+      ANTI_PATTERNS,
+      CROSS_REFERENCE_RULES,
+      renderGadgetCatalogSection(gadgetsSection),
+      CONTEXT_SPEC_SECTION,
+    ].join("\n\n") +
+    `
 
 ${pitfallsBlock}
 
 ## Reference: Wire Hooks
 ${wireDoc}
 
-${DESIGN_SYSTEM_GUIDANCE}
+${withStylingProfile(DESIGN_SYSTEM_GUIDANCE, profileSection)}
 
 ### CSS Token Documentation
 ${designSystemDocs}
@@ -510,7 +414,7 @@ ${primitivesDoc}
  * primitive *names*. Exported so `prompt-type-drift.test.ts` can
  * verify its enum claims against the auto-generated primitive catalog.
  */
-export const DESIGN_SYSTEM_GUIDANCE = `## Imports & Component Surface
+const DESIGN_SYSTEM_GUIDANCE_SURFACE_AND_TOKENS = `## Imports & Component Surface
 
 Import ONLY from: \`react\`, \`@ggui-ai/design\`, \`@ggui-ai/wire\`. The ENTIRE design system — every primitive, component, composition and trait — is exported from the single \`@ggui-ai/design\` entry: \`import { Card, Grid, Stack, Modal, Clickable } from '@ggui-ai/design'\`. There are NO subpaths (\`/primitives\`, \`/components\`, …) — never import from them. Use the design components — DO NOT use raw HTML elements (\`<button>\`, \`<input>\`, \`<div>\` for layout) or Tailwind classes; those render unstyled in the iframe runtime.
 
@@ -538,14 +442,14 @@ EXACT primitive prop values (other values are silently ignored — the design sy
 - \`<Heading level={1|2|3|4|5|6}>\` — sizes are preset by level (h1 = 4xl bold, h2 = 3xl bold, h3 = 2xl semibold). Pass a number, not \`level="h1"\`. Heading uses the same \`tone\` slot vocabulary as Text.
 - \`<Icon name="..." tone="...">\` / \`<Spinner tone="...">\` / \`<Link href="..." tone="...">\` / \`<Divider tone="...">\` — same \`tone\` vocabulary as Text. Default = \`currentColor\` (Icon), primary-tinted (Spinner / Link), outlineVariant (Divider). Use \`tone="inherit"\` when you want the element to track the parent's foreground color (e.g. an Icon next to muted text).
 - \`<Button variant="...">\` — \`primary | secondary | outline | ghost | danger\`. Sizes \`xs | sm | md | lg\`. Use \`primary\` for the main action — renders in the brand color automatically.
-- \`<Card padding="lg" shadow="md" radius="lg" surface="default">\` — shadow \`none|sm|md|lg|xl\`, radius \`none|sm|md|lg|xl\`. \`surface\` slot picks the fill: \`default | elevated | sunken | accent | inverted | transparent\`. Use \`inverted\` for dark testimonial-style cards on a light theme; \`accent\` for branded fills.
+- \`<Card padding="lg" shadow="md" radius="lg" surface="default">\` — shadow \`none|sm|md|lg|xl\`, radius \`none|sm|md|lg|xl\`. \`surface\` slot picks the fill: \`default | elevated | sunken | accent | inverted | hero | transparent\`. Use \`inverted\` for dark testimonial-style cards on a light theme; \`accent\` for branded fills; \`hero\` for the one hero / greeting panel (the theme's hero ground: brand-tinted on a light host, the ink pair on a dark one). \`inverted\` and \`hero\` OWN their ground — never set \`background\` in their \`style\` (tier-0 fails it); the surface paints it.
 - \`<Box surface="...">\` — same surface slots as Card. \`surface\` is the ONLY theme-tracking background prop; the legacy \`background="..."\` prop has been removed. For non-theme-mapped brand colors (a partner's exact brand hex like Stripe purple), use the typed escape \`<Box assetColor="#635BFF" assetSemantic="stripe-brand-purple">\` — both props are required, and \`assetSemantic\` MUST be a non-empty human-readable label. Tier-0 self-check rejects every other hex / rgba on Box.
 - \`<Stack gap="...">\` / \`<Row gap="...">\` — \`gap\` takes the **spacing scale** (next bullet). \`align\` (cross-axis) is ONLY \`start | center | end | stretch\` and \`justify\` (main-axis) is ONLY \`start | center | end | between | around | evenly\` — NEVER the raw CSS values \`flex-start\` / \`flex-end\` / \`space-between\`, which are type errors.
 - **Spacing scale** — \`gap\` (Stack / Row / Grid) and \`padding\` (Card / Box / Container) take a t-shirt size: \`none | xs | sm | md | lg | xl | 2xl\`. Each resolves to a \`--ggui-spacing-*\` token (xs≈4px, sm≈8px, md≈16px, lg≈24px, xl≈32px, 2xl≈48px). A bare number is treated as pixels. NEVER pass a raw CSS length such as \`gap="8px"\` — it is silently dropped by the browser and the gap collapses to 0; use the scale name (\`gap="sm"\`).
 - \`<Grid columns={N} gap="md">\` — 2-D layout (rows AND columns). Reach for it for card galleries, stat grids and dashboards — NEVER hand-roll \`style={{ display: 'grid' }}\`. When the request names exact per-breakpoint counts ("3 per row on desktop, 1 on mobile"), pass a map: \`<Grid columns={{ base: 1, md: 3 }}>\` (breakpoints \`sm\`/\`md\`/\`lg\`/\`xl\`; the design system emits the media queries). For an open-ended gallery where any column count is fine, use \`<Grid minColumnWidth={220}>\` — it fits as many equal columns as the width allows. \`radius\` (Card / Box / Image) takes the scale \`none | sm | md | lg | xl\`.
 - \`<Stat label="…" value="…" delta="+12%" trend="up">\` — KPI display (label + big value + trend-coloured delta + optional \`icon\`). \`trend\` is \`up | down | neutral\` (delta renders green / red / muted). Reach for it for any "show a number" UI; drop several into a \`<Grid>\` for a stat grid instead of hand-building label+value pairs.
 - \`<Stepper steps={STEPS} current={step} />\` — display-only step indicator for wizards/checkouts. \`steps\` is a top-level \`const\` array of labels; \`current\` is YOUR zero-indexed \`useState\` value; \`orientation\` is \`horizontal | vertical\`; optional \`onStepClick={(i) => …}\` makes steps clickable. Stepper never owns navigation state — your Next/Back handlers move \`current\`.
-- \`<Badge variant="...">\` — \`default | primary | secondary | success | warning | error | info\` for colored pills. Great for status/condition labels. There is NO \`neutral\` variant — use \`default\` (or \`secondary\`) for an un-tinted pill.
+- \`<Badge variant="...">\` — \`default | primary | secondary | tertiary | success | warning | error | info\` for colored pills. Great for status/condition labels. There is NO \`neutral\` variant — use \`default\` (or \`secondary\`) for an un-tinted pill.
 
 **Color choice rule of thumb.** Reach for typed slots first: Button \`variant\`, Badge \`variant\`, Alert \`variant\`, Text/Heading/Icon/Spinner/Link/Divider \`tone\`, Box/Card \`surface\`. NEVER hardcode hex \`#XXXXXX\`, rgba, or hsl — tier-0 self-check rejects them with \`tokens:hex-color\` / \`tokens:hardcoded-color-fn\` and the LLM must remediate. Hardcoded colors break the operator's theme switch (Indigo → Claudic → Cyberpunk preset has zero effect on a card hardcoded with \`background: '#000'\`).
 
@@ -577,9 +481,10 @@ MANDATORY:
 4. NEVER include literal fallback values in ANY token reference — colors, spacing, typography, radius, shadows alike. Write \`var(--ggui-spacing-4)\` bare, never \`var(--ggui-spacing-4, 16px)\`; \`var(--ggui-color-primary-600)\` bare, never \`var(--ggui-color-primary-600, #0284c7)\`. The runtime injects every token; a literal fallback paints the wrong value exactly when the operator's theme matters most.
 
 Token categories:
-- Brand: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
-- Text: \`var(--ggui-color-onSurface)\`, \`var(--ggui-color-onSurfaceVariant)\`
-- Backgrounds: \`var(--ggui-color-surface)\`, \`var(--ggui-color-surfaceVariant)\`
+- Brand fills: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
+- Accent text: \`var(--ggui-color-link)\` — eyebrows, taglines, links, labels; readable per mode (never a bare \`primary-<stop>\` as a text color)
+- Text: \`var(--ggui-color-onContainer)\`, \`var(--ggui-color-onSunken)\`
+- Backgrounds: \`var(--ggui-color-container)\`, \`var(--ggui-color-sunken)\`
 - Borders: \`var(--ggui-color-outline)\`
 - Spacing: \`var(--ggui-spacing-4)\`, \`var(--ggui-spacing-6)\`
 - Typography: \`var(--ggui-font-size-sm)\`, \`var(--ggui-font-weight-semibold)\`
@@ -596,11 +501,12 @@ Use the FULL primary palette throughout the component — NOT only on submit but
 |---------|-------|---------|
 | Section headers, hero areas, highlight strips | \`primary-50\` / \`primary-100\` | Subtle branded backgrounds |
 | Borders, dividers, focus rings, input focus | \`primary-200\` / \`primary-300\` | Branded structure |
-| Icons, links, labels, active indicators | \`primary-500\` / \`primary-600\` | Core accent color |
+| Accent TEXT — eyebrows, taglines, links, labels, inline arrows | \`link\` (\`var(--ggui-color-link)\`) or \`<Text tone="emphasized">\` | The brand's READABLE ink, derived per mode to clear 4.5:1 — a bare \`primary-300…600\` as a text color fails tier-0 |
+| Icon fills, badges, active indicators | \`primary-500\` / \`primary-600\` | Core accent fill |
 | Buttons, CTAs, filled interactive elements | \`primary-600\` / \`primary-700\` | Primary actions |
 | Headings on light primary backgrounds | \`primary-800\` / \`primary-900\` | High-contrast branded text |
 
-Use semantic tokens (\`onSurface\`, \`onSurfaceVariant\`) for body text and secondary info. NEVER use raw \`neutral-*\` or \`gray-*\` for body text — they break in dark themes.
+Use the layering roles' inks (\`onContainer\` for body text on a card, \`onSunken\` for secondary text, captions, labels) — never raw neutrals. NEVER use raw \`neutral-*\` or \`gray-*\` for body text — they break in dark themes.
 
 ### Theme-Agnostic Design
 
@@ -609,7 +515,7 @@ Components MUST be theme-agnostic — they reference CSS variables but NEVER ass
 DO:
 - Use \`var(--ggui-color-primary-*)\` for brand elements — the theme controls what "primary" means
 - Use \`var(--ggui-shape-shadow-*)\` for depth, \`var(--ggui-shape-radius-*)\` for corners
-- Use semantic color roles: primary for brand, surface/onSurface for structure, success/error/warning for state
+- Use semantic color roles: primary for brand; the layering roles (ground / container / elevated / sunken + their on* inks) for structure; success/error/warning for state
 
 DON'T:
 - Don't assume primary is blue — could be red, green, purple
@@ -620,7 +526,7 @@ Visual hierarchy via tokens:
 - Elevated sections: \`var(--ggui-shape-shadow-md)\` + \`var(--ggui-shape-radius-lg)\`
 - Highlighted regions: \`var(--ggui-color-primary-50)\` background
 - Active/selected: \`var(--ggui-color-primary-100)\` background
-- Section headers: \`var(--ggui-color-primary-600)\` text or border-bottom
+- Section headers / eyebrows: \`var(--ggui-color-link)\` text, or a \`var(--ggui-color-primary-600)\` border-bottom
 
 ## Responsive Design (CRITICAL)
 
@@ -630,59 +536,9 @@ Generated components become reusable blueprints — the same blueprint serves ph
 2. Relative/fluid units — prefer \`%\`, \`em\`, \`rem\`, \`min()\`, \`max()\`, \`clamp()\` over fixed \`px\`.
 3. Fluid widths — \`max-width\` with \`width: 100%\`. Never set a fixed width.
 4. Compact padding — components are embedded in containers that provide their own chrome.
-5. No raw \`@media\` queries in component code — for a layout that must change by breakpoint, use \`<Grid columns={{ base: 1, md: 3 }}>\` (the design system emits the media queries for you) or a fluid \`minColumnWidth\` grid.
+5. No raw \`@media\` queries in component code — for a layout that must change by breakpoint, use \`<Grid columns={{ base: 1, md: 3 }}>\` (the design system emits the media queries for you) or a fluid \`minColumnWidth\` grid.`;
 
-## Data Parameterization (CRITICAL)
-
-Generated components are CACHED blueprints reused across requests. NEVER hardcode request-specific data (names, cities, numbers, dates) into the component body. Define data as default prop values so the blueprint works for ANY similar request:
-
-\`\`\`tsx
-// BAD — hardcoded, only works for Tokyo
-const city = "Tokyo";
-const temp = 18;
-
-// GOOD — parameterized via props with defaults from the request
-interface Props {
-  city?: string;
-  temperature?: number;
-}
-export default function WeatherCard({ city = "Tokyo", temperature = 18 }: Props) {
-  // A controller can override for Seoul, Paris, etc.
-}
-\`\`\`
-
-Rules:
-1. All request-specific data → props with defaults. City names, tickers, user names, dates, counts.
-2. Layout and styling are universal. Colors, spacing, structure — these are the reusable part.
-3. Default values come from the current request — so the component renders correctly standalone.
-4. Props interface must be typed and exported.
-
-## Component Structure
-
-Keep JSX nesting depth to 3–5 levels. When deeper, extract repeated/complex sections into helper components — named functions defined above the main Component in the same file. Helpers take data + callbacks via props; they don't own state.
-
-\`\`\`tsx
-import { useState } from 'react';
-import { Container, Card, Stack, Text, Button, Input } from '@ggui-ai/design';
-
-interface Props {
-  onSubmit?: (data: unknown) => void;
-}
-
-function ItemCard({ item, onEdit }: { item: Item; onEdit: (id: string) => void }) {
-  return <Card padding="md">…</Card>;
-}
-
-export default function GeneratedComponent({ onSubmit }: Props) {
-  return (
-    <Container>
-      {items.map((item) => <ItemCard key={item.id} item={item} onEdit={handleEdit} />)}
-    </Container>
-  );
-}
-\`\`\`
-
-## Aesthetic Guidance (READ CAREFULLY — this is what separates "polished" from "ok")
+const DESIGN_SYSTEM_GUIDANCE_AESTHETICS_AND_CHECKLIST = `## Aesthetic Guidance (READ CAREFULLY — this is what separates "polished" from "ok")
 
 ### Visual hierarchy — the SCALE GAP rule
 
@@ -704,11 +560,11 @@ A polished UI has ONE hero that dominates. Everything else supports it. Bad layo
 ### Color discipline — the 60/30/10 rule
 
 Don't paint everything in primary. Use:
-- **60% surface** (\`var(--ggui-color-surface)\` / \`onSurface\`) — body text, default backgrounds, structure
-- **30% surfaceVariant + onSurfaceVariant** — secondary text, captions, labels, dividers
+- **60% container** (\`var(--ggui-color-container)\` / \`onContainer\`) — body text, default backgrounds, structure
+- **30% sunken + onSunken** — wells, secondary text, captions, labels, dividers
 - **10% primary** — hero number, ONE highlight element, CTAs, brand accent
 
-If your component is 100% purple text on purple backgrounds, you've lost the eye. Headings can be \`onSurface\` (dark neutral) — they'll still feel weighty. Save the primary palette for one or two STAR moments.
+If your component is 100% purple text on purple backgrounds, you've lost the eye. Headings can be \`onContainer\` (the card's ink) — they'll still feel weighty. Save the primary palette for one or two STAR moments.
 
 \`\`\`tsx
 // BAD — everything purple, eye has no anchor
@@ -717,7 +573,7 @@ If your component is 100% purple text on purple backgrounds, you've lost the eye
 <Text tone="emphasized">all body text</Text>
 
 // GOOD — hero pops, body is neutral, primary is reserved
-<Heading>Title</Heading>  {/* defaults to onSurface */}
+<Heading>Title</Heading>  {/* defaults to onContainer */}
 <Text size="4xl" weight="bold" tone="emphasized">42</Text>
 <Text tone="muted">all body text</Text>
 \`\`\`
@@ -725,7 +581,7 @@ If your component is 100% purple text on purple backgrounds, you've lost the eye
 ### Visual rhythm — vary your card treatments
 
 A row of identical flat tiles feels monotone. Use card-treatment variation to create rhythm:
-- **Hero card**: \`<Card padding="xl" shadow="lg" radius="xl">\` with branded gradient background — anchors the eye
+- **Hero card**: \`<Card surface="hero" padding="xl" shadow="lg" radius="xl">\` — the theme's hero ground (brand-tinted on a light host, the ink pair on a dark one); anchors the eye
 - **Stat tiles**: \`<Card padding="md" shadow="sm" radius="md">\` with surface bg — secondary
 - **Inline rows / list items**: no card chrome at all, just \`<Stack gap="sm">\` with dividers — tertiary
 
@@ -745,7 +601,7 @@ Don't render text-only metrics. A weather widget without a sun/cloud, a stock ca
 </Row>
 \`\`\`
 
-Use \`<Icon name="..." />\` (Lucide icon names in kebab-case) for line icons; emoji directly for status/weather/mood. Both are valid. For per-stat tiny accents, use a small icon next to the label.
+Use \`<Icon name="..." />\` for line icons — ONLY the curated Lucide subset renders (call \`get_available_icons\` for the exact kebab-case names; a name outside it renders an empty box and fails the check); emoji directly for status/weather/mood. Both are valid. For per-stat tiny accents, use a small icon next to the label.
 
 ### Spacing — generosity beats compactness
 
@@ -775,3 +631,11 @@ Hero sections should feel airy. Use \`padding="xl"\` (32px) on the main card, no
 - [ ] Live/streaming regions wrapped in \`aria-live="polite"\`
 - [ ] Headings nest — one \`level={1}\`, then \`level={2}\`/\`{3}\` — never skipped or inverted
 - [ ] Wire hooks (\`useAction\`, \`useStream\`) imported from \`@ggui-ai/wire\` and consumed`;
+
+export const DESIGN_SYSTEM_GUIDANCE = [
+  DESIGN_SYSTEM_GUIDANCE_SURFACE_AND_TOKENS,
+  DATA_PARAMETERIZATION,
+  FRAME_SIZING,
+  COMPONENT_STRUCTURE,
+  DESIGN_SYSTEM_GUIDANCE_AESTHETICS_AND_CHECKLIST,
+].join("\n\n");

package/src/boilerplate/templates/base-free.tsx.tmpl

@@ -0,0 +1,24 @@
+// DO NOT EDIT imports — the wire + gadget imports below are runtime-resolution anchors.
+// prettier-ignore-start
+/* eslint-disable no-unused-vars */
+{{REACT_IMPORT}}
+// Compose freely: raw HTML elements, inline `style` props and <style> blocks.
+// The `@ggui-ai/design` package is importable but OPTIONAL — add your own
+// import only when a primitive (Skeleton, EmptyState, Icon, …) saves you work.
+// Color stays on bare var(--ggui-color-*) tokens; everything else may be literal.
+{{WIRE_IMPORT}}/* eslint-enable no-unused-vars */
+// prettier-ignore-end
+
+// DO NOT EDIT Props — auto-generated from the data contract
+{{PROPS_INTERFACE}}
+{{ACTION_TYPES}}
+{{STREAM_TYPES}}
+
+// Place helper components here if needed
+
+export default function Component(props: Props) {
+{{CONTEXT_HOOKS}}{{WIRE_HOOKS}}{{AXIS_SECTIONS}}
+  return (
+{{LAYOUT}}
+  );
+}