@ggui-ai/ui-gen 0.28.0 → 0.29.0

package/src/boilerplate/system-prompt.ts

@@ -445,9 +445,10 @@ EXACT primitive prop values (other values are silently ignored — the design sy
 - \`<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 | 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.
+- \`<Box surface="...">\` — same surface slots as Card. \`surface\` (layout slots) and \`tint\` (data categories) are the ONLY theme-tracking background props; the legacy \`background="..."\` prop has been removed. To colour by a DATA CATEGORY (series, lanes, kinds, tags, element groups), use \`tint="tint-1"\`…\`"tint-8"\` (see "Categorical tint" below). 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"\`).
+- **One content edge per card** — on \`Card\` and \`Box\`, \`padding\` sets the VERTICAL rhythm; the card owns the horizontal inset. Every block's content sits on the card's one left edge, and a filled or bordered surface steps its own content in by exactly one inset. So never use \`paddingX\` to push content sideways or a padded unstyled wrapper to indent a list. A badge, date or action on the right of a line belongs in a \`<Row justify="between">\` with content on its left, never alone on its own line.
 - \`<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\`.
@@ -457,6 +458,14 @@ EXACT primitive prop values (other values are silently ignored — the design sy
 
 **Asset-color escape (Box only).** When you genuinely need a non-theme color — a partner's exact brand hex (Stripe purple \`#635BFF\`, Slack aubergine \`#4A154B\`), a fixed product surface — use \`<Box assetColor="#635BFF" assetSemantic="stripe-brand-purple">…</Box>\`. The \`assetSemantic\` is REQUIRED and MUST be a non-empty human-readable label that documents intent. Tier-0 allows hex inside this typed pair; one without the other fails the check. Reach for \`surface\` first — \`assetColor\` is rare.
 
+**Categorical tint (data categories).** When cells, rows or swatches must be told apart by a data category — element groups in a periodic table, lanes on a board, series in a chart legend, tags — set \`tint="tint-1"\` … \`tint="tint-8"\` on the Box or Card. The eight steps are theme colours: they follow the operator's theme in light and dark, and the tinted surface sets its own readable text colour. Rules:
+- Tints are for **data categories only** — never for state (a status takes live, draft or signal, not a tint) and never as decoration.
+- The category is **always also in words** — a label in the cell or a legend on the card. Colour is never the only way to tell categories apart.
+- **Text on a tint is the theme's ink only, one short line** — a label, a symbol or a value, never \`tone="subtle"\` or muted text. Secondary or muted text sits beside the cell or in the legend, never on the tint.
+- **A category keeps its tint for the life of the card.** Assign tints deterministically from the data, in the order the categories are first listed or sorted, never by render order, so an update or repaint never recolours a category.
+- **More than eight categories:** group them to eight before assigning, or show the category in words only.
+- Never put a theme colour through \`assetColor\` — that escape is only for an exact external brand hex.
+
 ## Accessibility (REQUIRED)
 
 The design-system primitives are accessible by construction — they emit their own roles, labels, keyboard handlers, and error wiring. Your job is to USE them correctly, NOT to re-declare ARIA on top of them.
@@ -481,7 +490,7 @@ MANDATORY:
 2. NEVER use CSS gradients with custom colors. If you need a gradient: \`linear-gradient(to bottom, var(--ggui-color-primary-500), var(--ggui-color-primary-700))\`.
 3. NEVER invent your own palette. The system provides primary, neutral, success, warning, error, and info — use ONLY these.
 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.
-5. NEVER set an inline \`border\`, \`borderColor\`, \`borderWidth\` or \`borderStyle\` on a kit control — \`Button\`, \`Input\`, \`Select\`, \`TextArea\`, \`Checkbox\`, \`RadioGroup\`, \`Toggle\`, \`SearchField\`. The control draws its own boundary, and it clears 3:1 on its surface in every theme: an outline chip is \`<Button variant="outline">\` exactly as it comes (its edge is \`controlAccentOutline\`). Where you draw a control-like edge on your own element, use \`var(--ggui-color-controlOutline)\`. A ramp step such as \`primary-200\` as a control's border is nearly invisible (about 1.1:1).
+5. NEVER set an inline \`border\`, \`borderColor\`, \`borderWidth\` or \`borderStyle\` on a kit control — \`Button\`, \`Input\`, \`Select\`, \`TextArea\`, \`Checkbox\`, \`RadioGroup\`, \`Toggle\`, \`SearchField\`. The control draws its own boundary, and it clears 3:1 on its surface in every theme: an outline chip is \`<Button variant="outline">\` exactly as it comes (its edge is \`controlAccentOutline\`). Where you draw a control-like edge on your own element, use \`var(--ggui-color-controlOutline)\`. A ramp step such as \`primary-200\` as a control's border is nearly invisible (about 1.1:1). Its ink and fill are the variant's too: NEVER set an inline \`color\`, \`background\` or \`backgroundColor\` on a kit control, a token as much as a literal — pick the variant that carries the look.
 
 Token categories:
 - Brand fills: \`var(--ggui-color-primary-600)\`, \`var(--ggui-color-primary-50)\`
@@ -584,7 +593,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 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
+- **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
 

package/src/check/run-tier0.ts

@@ -571,6 +571,171 @@ function detectComponentNeverReturns(
  * Wraps the same logic as runSelfChecks (adapters/tools.ts) but emits EvalIssue[].
  * Also runs contract validation when contract are provided.
  */
+/**
+ * ggui#1977 / #1981: an opening band that lost its edge. The card keeps one content edge in every fit; only a hero
+ * Box that is the root's FIRST child, a hero Card that is its ONLY child (the runtime's legacy inference) or a root
+ * child that declares `bleed` meets the card's edge (design's `EXPANDED_FRAME_BLEEDS`). The shapes that miss it (the
+ * #1981 corpus analyzer's version of `hero-not-first` read 14 of 14 true on dev + staging, by the CDO; the cases
+ * added since, and `hero-card-first`, are pinned by unit tests and were not counted on the corpus, which is compiled
+ * JS this source reader does not parse):
+ *   - `hero-not-first`: a band (a `surface="hero"` Box with no edge of its own: no `radius` but `none`, no style
+ *     radius, shadow or border; a Card is a tile, never a band) that is a root child but not the first and does not
+ *     declare `bleed`, OR the first child of a plain wrapper (a Stack, Box, Container or div that paints no ground
+ *     and is not a horizontal Stack) that opens the root, `bleed` or not: the runtime honours `bleed` on root
+ *     children only. It renders inside the inset, a box floating in the card.
+ *   - `hero-card-first` (#1981 c.6314477145): a `surface="hero"` Card without `bleed` that is the root's first child
+ *     AMONG siblings. A Card there is a tile and keeps the inset; if it is meant as the opening band, the band is a
+ *     Box. Never a sole child: a Card that is the root's only child is the card's body and keeps its bleed.
+ * A root that already opens on a band is left alone (a second band is not this shape). Conditional children are read
+ * where they render: `a && <El/>`, `a || <El/>` and every ternary branch. When the band renders conditionally, or
+ * every slot before it does, the warning says so. The component is `export default function`, or
+ * `export default C` naming a function or an arrow in the file. Read from the source, never from a helper's JSX.
+ * A `warn`, not a `fail`.
+ * Retired (#1981, the CDO's read): `painted-band`, 7 of 8 served hits were contained Cards (tiles), not bands.
+ */
+function detectBandEdgeLost(
+  sourceCode: string,
+): { readonly shape: 'hero-not-first' | 'hero-card-first'; readonly line: number; readonly conditional: boolean } | null {
+  const sf = ts.createSourceFile('source.tsx', sourceCode, ts.ScriptTarget.Latest, /* setParentNodes */ true, ts.ScriptKind.TSX);
+  type El = ts.JsxElement | ts.JsxSelfClosingElement;
+  const unwrap = (e: ts.Expression): ts.Expression => (ts.isParenthesizedExpression(e) ? unwrap(e.expression) : e);
+  const isEl = (n: ts.Node): n is El => ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n);
+  const opening = (el: El): ts.JsxOpeningElement | ts.JsxSelfClosingElement => (ts.isJsxElement(el) ? el.openingElement : el);
+  const tag = (el: El): string => opening(el).tagName.getText(sf);
+  const attr = (el: El, name: string): ts.JsxAttribute | undefined =>
+    opening(el).attributes.properties.find((a): a is ts.JsxAttribute => ts.isJsxAttribute(a) && a.name.getText(sf) === name);
+  const stringAttr = (el: El, name: string): string | undefined => {
+    const a = attr(el, name);
+    if (a?.initializer === undefined) return undefined;
+    if (ts.isStringLiteral(a.initializer)) return a.initializer.text;
+    if (ts.isJsxExpression(a.initializer) && a.initializer.expression !== undefined && ts.isStringLiteral(a.initializer.expression)) {
+      return a.initializer.expression.text;
+    }
+    return undefined;
+  };
+  const flagOn = (el: El, name: string): boolean => {
+    const a = attr(el, name);
+    if (a === undefined) return false;
+    if (a.initializer === undefined) return true;
+    return !(ts.isJsxExpression(a.initializer) && a.initializer.expression?.kind === ts.SyntaxKind.FalseKeyword);
+  };
+  type Slot = { readonly alts: El[]; readonly conditional: boolean };
+  /**
+   * The elements a JSX child can render: itself, or every element branch of `a && <El/>`, `a || <El/>` and
+   * `a ? <El/> : <Other/>` (nested ternaries included).
+   */
+  const branches = (x: ts.Expression): El[] => {
+    const e = unwrap(x);
+    if (isEl(e)) return [e];
+    const guard = ts.isBinaryExpression(e) && (e.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken || e.operatorToken.kind === ts.SyntaxKind.BarBarToken);
+    if (guard) return branches(e.right);
+    if (ts.isConditionalExpression(e)) return [...branches(e.whenTrue), ...branches(e.whenFalse)];
+    return [];
+  };
+  /** One rendered slot per JSX child; an expression child is conditional and lists the elements it may render. */
+  const slots = (el: El): Slot[] => {
+    if (!ts.isJsxElement(el)) return [];
+    const out: Slot[] = [];
+    for (const n of el.children) {
+      if (isEl(n)) out.push({ alts: [n], conditional: false });
+      else if (ts.isJsxExpression(n) && n.expression !== undefined) {
+        const alts = branches(n.expression);
+        if (alts.length > 0) out.push({ alts, conditional: true });
+      }
+    }
+    return out;
+  };
+  const lineOf = (el: El): number => sf.getLineAndCharacterOfPosition(el.getStart(sf)).line + 1;
+
+  const styleKeys = (el: El): string[] => {
+    const style = attr(el, 'style')?.initializer;
+    if (style === undefined || !ts.isJsxExpression(style) || style.expression === undefined) return [];
+    const obj = unwrap(style.expression);
+    if (!ts.isObjectLiteralExpression(obj)) return [];
+    return obj.properties.filter(ts.isPropertyAssignment).map((pr) => pr.name.getText(sf).replace(/['"]/g, ''));
+  };
+  const paints = (el: El): boolean => {
+    const surface = stringAttr(el, 'surface');
+    if (surface !== undefined && surface !== 'transparent') return true;
+    if (attr(el, 'tint') !== undefined) return true;
+    return styleKeys(el).some((k) => k === 'background' || k === 'backgroundColor');
+  };
+  /** A Box with an edge of its own is a tile: a `radius` other than `none`, or a style radius, shadow or border. */
+  const hasOwnEdge = (el: El): boolean => {
+    if (attr(el, 'radius') !== undefined && stringAttr(el, 'radius') !== 'none') return true;
+    return styleKeys(el).some((k) => k === 'borderRadius' || k === 'boxShadow' || /^border(Top|Bottom|Left|Right)?(Width|Style|Color)?$/.test(k));
+  };
+  /** A hero Box with no edge of its own: a band. A Card is a tile, never a band. */
+  const isHeroBand = (el: El): boolean => tag(el) === 'Box' && stringAttr(el, 'surface') === 'hero' && !hasOwnEdge(el);
+  const isHeroCard = (el: El): boolean => tag(el) === 'Card' && stringAttr(el, 'surface') === 'hero' && !flagOn(el, 'bleed');
+  /** A wrapper that only stacks its children: it paints nothing and does not lay them out side by side. */
+  const isPlainWrapper = (el: El): boolean =>
+    ['Stack', 'Box', 'Container', 'div'].includes(tag(el)) && !paints(el) && !(tag(el) === 'Stack' && stringAttr(el, 'direction') === 'horizontal');
+
+  // The default export's component: `export default function`, or `export default C` naming a function or a
+  // `const C = (…) => …` in this file, or an inline arrow / function expression.
+  type Fn = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+  const byName = new Map<string, Fn>();
+  let component: Fn | undefined;
+  for (const st of sf.statements) {
+    if (ts.isFunctionDeclaration(st)) {
+      if (st.name !== undefined) byName.set(st.name.text, st);
+      if (st.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) component = st;
+    } else if (ts.isVariableStatement(st)) {
+      for (const d of st.declarationList.declarations) {
+        const init = d.initializer === undefined ? undefined : unwrap(d.initializer);
+        if (ts.isIdentifier(d.name) && init !== undefined && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) byName.set(d.name.text, init);
+      }
+    }
+  }
+  for (const st of sf.statements) {
+    if (component !== undefined || !ts.isExportAssignment(st) || st.isExportEquals === true) continue;
+    const e = unwrap(st.expression);
+    if (ts.isIdentifier(e)) component = byName.get(e.text);
+    else if (ts.isArrowFunction(e) || ts.isFunctionExpression(e)) component = e;
+  }
+  if (component?.body === undefined) return null;
+  let root: El | undefined;
+  if (!ts.isBlock(component.body)) {
+    const e = unwrap(component.body);
+    if (isEl(e)) root = e;
+  } else {
+    for (const st of component.body.statements) {
+      if (ts.isReturnStatement(st) && st.expression !== undefined) {
+        const e = unwrap(st.expression);
+        if (isEl(e)) root = e;
+      }
+    }
+  }
+  if (root === undefined) return null;
+
+  const kids = slots(root);
+  const first = kids[0];
+  if (first === undefined) return null;
+  // A root that already opens on a band (always rendered) has its band; a second one is not this shape.
+  if (!first.conditional && first.alts.some(isHeroBand)) return null;
+  // A hero Card first AMONG siblings is a tile: it keeps the inset. Never a sole child (that Card is the card's body).
+  const heroCard = kids.length > 1 ? first.alts.find(isHeroCard) : undefined;
+  if (heroCard !== undefined) return { shape: 'hero-card-first', line: lineOf(heroCard), conditional: first.conditional };
+  // A band that is a later root child: the root's inset holds it unless it declares `bleed` (honoured on a root
+  // child). Conditional when it, or every slot before it, renders conditionally.
+  for (let i = 1; i < kids.length; i++) {
+    const k = kids[i]!;
+    const band = k.alts.find((a) => isHeroBand(a) && !flagOn(a, 'bleed'));
+    if (band !== undefined) {
+      return { shape: 'hero-not-first', line: lineOf(band), conditional: k.conditional || kids.slice(0, i).every((s) => s.conditional) };
+    }
+  }
+  // A band first inside a plain wrapper that opens the root: `bleed` is not honoured that deep, so it warns either way.
+  const opener = first.alts.find(isPlainWrapper);
+  const inner = opener === undefined ? undefined : slots(opener)[0];
+  const wrapped = inner?.alts.find(isHeroBand);
+  if (wrapped !== undefined && inner !== undefined) {
+    return { shape: 'hero-not-first', line: lineOf(wrapped), conditional: first.conditional || inner.conditional };
+  }
+  return null;
+}
+
 /** The kit controls whose boundary the design system draws (ggui#1697). */
 const KIT_CONTROLS = ['Button', 'Input', 'Select', 'TextArea', 'Checkbox', 'RadioGroup', 'Toggle', 'SearchField'] as const;
 
@@ -600,18 +765,22 @@ function kitControlTags(source: string): { name: string; attrs: string; line: nu
   return out;
 }
 
-/** A border key (not a radius) in the tag's inline style, or in a same-file object its `style={name}` points at. */
-function inlineBorderKey(attrs: string, source: string): string | null {
-  const BORDER = /\b(border(?:Top|Right|Bottom|Left)?(?:Color|Width|Style)?)\s*:/;
+/** A border key, never a radius (ggui#1697). */
+const CONTROL_BORDER_KEY = /\b(border(?:Top|Right|Bottom|Left)?(?:Color|Width|Style)?)\s*:/;
+/** An ink or fill key (ggui#1966): a kit control's variant carries its ink and its fill, token or not. */
+const CONTROL_COLOR_KEY = /\b(color|background|backgroundColor)\s*:/;
+
+/** A matching key in the tag's inline style, or in a same-file object its `style={name}` points at. */
+function inlineStyleKey(attrs: string, source: string, key: RegExp): string | null {
   const style = attrs.match(/\bstyle=\{\{([\s\S]*)\}\}/);
   if (style !== null) {
-    const hit = (style[1] ?? '').match(BORDER);
+    const hit = (style[1] ?? '').match(key);
     if (hit !== null) return hit[1] ?? null;
   }
   const named = attrs.match(/\bstyle=\{\s*([A-Za-z_$][\w$]*)\s*\}/);
   if (named === null) return null;
   const decl = source.match(new RegExp(`\\b(?:const|let)\\s+${named[1]}\\b[^=]*=\\s*\\{([^{}]*)\\}`));
-  const hit = decl !== null ? (decl[1] ?? '').match(BORDER) : null;
+  const hit = decl !== null ? (decl[1] ?? '').match(key) : null;
   return hit !== null ? hit[1] ?? null : null;
 }
 
@@ -703,6 +872,27 @@ export async function runTier0Checks(
     const assetSemanticAttr = tagAttrs.match(/\bassetSemantic\s*=\s*["']([^"']*)["']/);
     const startLine = sourceCode.slice(0, match.index ?? 0).split('\n').length;
     const tagLineCount = match[0].split('\n').length;
+    // ggui#1846 — the escape is for an exact EXTERNAL brand colour. A theme
+    // token through it (`assetColor="var(--ggui-…)"`, or an expression whose
+    // text carries one) bypasses the door the theme already has: a categorical
+    // fill is `tint`, a theme-tracking fill is `surface`. Deterministic from the
+    // tag's own text, and always satisfiable, so it fails.
+    if (/var\(\s*--ggui-/.test(assetColorAttr[0])) {
+      issues.push({
+        tier: 0,
+        result: 'fail',
+        category: 'tokens',
+        subcategory: 'asset-color-theme-token',
+        severity: 'critical',
+        description:
+          'Box `assetColor` carries a theme token (`var(--ggui-…)`) — the brand-color escape is only for an exact external brand hex, and the theme already has its own doors.',
+        fix:
+          'To colour by a data category, use `tint="tint-1"` … `tint="tint-8"` (one step per category, in the data\'s order). ' +
+          'For a theme-tracking fill, use `surface="..."`. Drop `assetColor` and `assetSemantic`.',
+        line: startLine,
+      });
+      continue;
+    }
     // Both attributes must be present, AND assetSemantic must be a
     // non-empty string literal. A `{expr}` value for assetSemantic is
     // treated as not-statically-verifiable; the escape is opt-in
@@ -722,8 +912,8 @@ export async function runTier0Checks(
           '`assetSemantic` is a human-readable label that documents why this color bypasses the theme.',
         fix:
           'Pair the `assetColor` with a non-empty `assetSemantic` literal, e.g. ' +
-          '`<Box assetColor="#635BFF" assetSemantic="stripe-brand-purple">`. Reach for `surface="..."` first ' +
-          'whenever the color SHOULD track the operator\'s theme.',
+          '`<Box assetColor="#635BFF" assetSemantic="stripe-brand-purple">`. The escape is only for an exact external brand hex: ' +
+          'to colour by a data category use `tint="tint-1"` … `tint="tint-8"`, and use `surface="..."` whenever the color SHOULD track the operator\'s theme.',
         line: startLine,
       });
       continue;
@@ -1220,7 +1410,7 @@ export async function runTier0Checks(
   // this check enforces what the model was told. The description starts with the check's id so the
   // generator's logged violation lines (`✗ …`) count its fires per generation, in-turn repairs included.
   for (const tag of enforceDesignVocabulary ? kitControlTags(sourceCode) : []) {
-    const key = inlineBorderKey(tag.attrs, sourceCode);
+    const key = inlineStyleKey(tag.attrs, sourceCode, CONTROL_BORDER_KEY);
     if (key === null) continue;
     issues.push({
       tier: 0, result: 'fail', category: 'tokens', subcategory: 'control-inline-border', severity: 'critical',
@@ -1230,6 +1420,41 @@ export async function runTier0Checks(
     });
   }
 
+  // ── A kit control's ink and fill are the kit's (ggui#1966) ──
+  // The variant carries a control's ink and fill, derived to read on its surface in every theme; an inline
+  // `color` or `background` paints over it, a token as much as a literal (`var(--ggui-color-onContainer)` on an
+  // outline Button is still a restyle). The prompt's rule 5 says the same.
+  for (const tag of enforceDesignVocabulary ? kitControlTags(sourceCode) : []) {
+    const key = inlineStyleKey(tag.attrs, sourceCode, CONTROL_COLOR_KEY);
+    if (key === null) continue;
+    issues.push({
+      tier: 0, result: 'fail', category: 'tokens', subcategory: 'control-inline-color', severity: 'critical',
+      description: `control-inline-color: <${tag.name}> sets an inline \`${key}\` — a kit control's variant carries its ink and fill, and an inline one paints over it`,
+      fix: `Remove \`${key}\` from <${tag.name}>'s style and pick the variant that carries the look (e.g. <Button variant="primary"> for the main action, variant="outline" for a chip). Colour your own element, not the kit's control.`,
+      line: tag.line,
+    });
+  }
+
+  // ── An opening band that lost its edge (ggui#1977 / #1981) ──
+  // Only a first-child hero Box, a sole-child hero Card or a root-child `bleed` element meets the card's edge. The
+  // prompt (FRAME_SIZING) teaches the band as a hero Box, the root's first child; this names a hero band placed
+  // anywhere else, and a hero Card opening the root among siblings. A warn.
+  const bandEdge = enforceDesignVocabulary ? detectBandEdgeLost(sourceCode) : null;
+  if (bandEdge !== null) {
+    issues.push({
+      tier: 0, result: 'warn', category: 'layout', subcategory: `band-edge-lost:${bandEdge.shape}`, severity: 'major',
+      description:
+        bandEdge.shape === 'hero-card-first'
+          ? `band-edge-lost: a surface="hero" Card opens the card among other children; a Card is a tile and keeps the card's inset (read from the source${bandEdge.conditional ? '; it renders conditionally' : ''})`
+          : `band-edge-lost: a surface="hero" band that is not the root's first child floats inside the card's inset (read from the source${bandEdge.conditional ? '; it, or everything before it, renders conditionally, and it was read where it renders' : ''})`,
+      fix:
+        bandEdge.shape === 'hero-card-first'
+          ? 'If this is the opening band, make it <Box surface="hero" bleed> (a Box, no radius, shadow or border of its own). A hero tile belongs among other tiles, in a grid or a row, not opening the card.'
+          : 'Make the opening band the root\'s FIRST child as <Box surface="hero" bleed> (not wrapped in a Stack, not after other content). A band is a Box with no radius, shadow or border of its own; a hero Card is a tile and stays where it is. Put a conditional notice after the band, not before it.',
+      line: bandEdge.line,
+    });
+  }
+
   // ── Missing Props interface ───────────────────────────────
   if (!sourceCode.includes('interface Props') && !sourceCode.includes('type Props')) {
     issues.push({

package/src/check/type-checker.ts

@@ -59,7 +59,9 @@ import ts from 'typescript';
 import fs from 'fs';
 import path from 'path';
 import { createRequire } from 'module';
+import { TINT_STEPS } from '@ggui-ai/design';
 import { describeAllowedImports } from '../validation/allowed-imports.js';
+import { BOILERPLATE_REACT_HOOKS, BOILERPLATE_REACT_IMPORT } from '../boilerplate/react-hooks.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -83,11 +85,12 @@ export interface TypeCheckResult {
 
 const BLOCKING_CODES = new Set([
   2304, // Cannot find name
-  // 2307 (Cannot find module) is NOT blocking — Lambda bundles code without
-  // type declarations, so the VFS can't resolve react/@ggui-ai/design.
-  // Forbidden imports are caught by runSelfChecks regex instead.
+  // 2307 (Cannot find module) is NOT blocking: a third-party gadget package
+  // with no `.d.ts` overlay can't be resolved by design, and forbidden imports
+  // are caught by runSelfChecks regex instead.
   2305, // Module has no exported member
   2322, // Type not assignable
+  2820, // Type not assignable — the "did you mean '…'?" form of 2322, for a near-miss literal (ggui#1849)
   2339, // Property does not exist on type
   2741, // Missing required property
   2769, // No overload matches this call
@@ -100,6 +103,50 @@ const BLOCKING_CODES = new Set([
 // Fix suggestions per error code
 // ---------------------------------------------------------------------------
 
+/**
+ * ggui#1933 — props a model reaches for from other kits, mapped to the design primitive's own name for the
+ * same thing. Applied only when the component's props type (read from the checker) actually has the target.
+ */
+const PROP_INTENT_ALIASES: Readonly<Record<string, string>> = { spacing: 'gap', space: 'gap', gutter: 'gap', color: 'tone' };
+
+/**
+ * ggui#1933 — fix text for a prop the component does not take: TypeScript says the prop does not exist, never
+ * what the component accepts, so the generic text sent the model guessing (a fast arm looped on `<Stack spacing>`).
+ * `accepted` is the component's own props, read from its props type.
+ */
+export function unknownPropFix(component: string, prop: string, accepted: readonly string[], sourceHint: string, native = false): string {
+  const meant = PROP_INTENT_ALIASES[prop];
+  const named = meant !== undefined && accepted.includes(meant) ? ` For what \`${prop}\` does in other kits, \`<${component}>\` takes \`${meant}\`.` : '';
+  return `\`<${component}>\` takes no \`${prop}\` prop.${named} Its props: ${accepted.map((a) => `\`${a}\``).join(', ')}${native ? ', plus the native HTML attributes' : ''}. Use one of these or drop the prop.${sourceHint}`;
+}
+
+/**
+ * The JSX element a diagnostic sits in, and the prop names its component declares; `undefined` when unreadable.
+ * Props inherited from React's own attribute types (a control extending `InputHTMLAttributes`) are not listed one
+ * by one, so a native-extending control's list stays its own props; `native` says the native set is also accepted.
+ */
+function acceptedPropsAt(program: ts.Program, file: ts.SourceFile, pos: number): { component: string; accepted: string[]; native: boolean } | undefined {
+  const find = (node: ts.Node): ts.Node | undefined =>
+    pos >= node.getStart(file) && pos < node.getEnd() ? (ts.forEachChild(node, find) ?? node) : undefined;
+  let node = find(file);
+  while (node !== undefined && !ts.isJsxOpeningElement(node) && !ts.isJsxSelfClosingElement(node)) node = node.parent;
+  if (node === undefined) return undefined;
+  const checker = program.getTypeChecker();
+  const tagType = checker.getTypeAtLocation(node.tagName);
+  const signature = [...tagType.getCallSignatures(), ...tagType.getConstructSignatures()][0];
+  const param = signature?.getParameters()[0];
+  if (param === undefined) return undefined;
+  const propsType = checker.getTypeOfSymbolAtLocation(param, node);
+  const listed = checker
+    .getPropertiesOfType(propsType)
+    .filter((p) => !['children', 'key', 'ref'].includes(p.getName()) && !p.getName().startsWith('aria-') && !p.getName().startsWith('data-'));
+  const fromReact = (p: ts.Symbol): boolean =>
+    (p.getDeclarations() ?? []).every((d) => /[\\/]@types[\\/]react[\\/]/.test(d.getSourceFile().fileName));
+  const own = listed.filter((p) => !fromReact(p));
+  const accepted = own.map((p) => p.getName()).sort();
+  return accepted.length > 0 ? { component: node.tagName.getText(file), accepted, native: own.length < listed.length } : undefined;
+}
+
 function generateFix(code: number, message?: string, sourceLine?: string): string {
   // Source-line hint: when the failing line is short and self-contained,
   // appending it gives the LLM a precise target. Skip for very long lines
@@ -122,11 +169,32 @@ function generateFix(code: number, message?: string, sourceLine?: string): strin
     return `You renamed a prop with a leading underscore to silence \`no-unused-vars\`, but the prop on \`Props\` doesn't have that prefix. Restore the original name; better, don't destructure props you won't render — access them via \`props.fieldName\` only when needed.${sourceHint}`;
   }
 
+  // A React hook the boilerplate always imports is missing: the DO NOT EDIT React import line was
+  // dropped or rewritten. The generic text below (props / a removed helper) points the model away
+  // from the one line that fixes it, and it loops (google-fast × chat-interface reached 30 turns).
+  const missing = code === 2304 && message !== undefined ? /Cannot find name '([^']+)'/.exec(message)?.[1] : undefined;
+  if (missing !== undefined && BOILERPLATE_REACT_HOOKS.some((h) => h === missing)) {
+    return `\`${missing}\` is a React hook, and the boilerplate's React import lists it: \`${BOILERPLATE_REACT_IMPORT}\` is a DO NOT EDIT line. This patch dropped or rewrote it. Restore that line exactly as the boilerplate wrote it, at the top of the file; do not import the hook a second way.${sourceHint}`;
+  }
+
   // Detect "Cannot find name" for destructured props
   if (code === 2304 && message && !message.includes('module') && !message.includes('import')) {
     return `This name is not defined in scope. Either you destructured props (use \`props.fieldName\` directly instead) OR you removed a helper declaration in this patch but kept a JSX/expression reference to it. Read your full patch and either restore the declaration or remove the reference.${sourceHint}`;
   }
 
+  // ggui#1846 — a categorical tint passed to `surface`. `surface` takes a layout slot; a data
+  // category takes `tint`. TypeScript names the slot union but never the prop, and the line it
+  // reports is the attribute's own (`surface={tint}`), so the key is that line plus a
+  // string-literal target type. A wrong prop on the same line reports the props object instead
+  // (`Type '{ … }' is not assignable to …`) and keeps the generic text. With both colour props on
+  // one line, the target tells them apart: the `tint` prop's union is the tint steps, the surface
+  // union never contains one. Only the TARGET is read, because the rejected value may itself be a
+  // tint (`Type '"tint-3"' is not assignable to type '"default" | …'`).
+  const target = message === undefined ? undefined : /is not assignable to type '(.*)/.exec(message)?.[1];
+  if ((code === 2322 || code === 2820) && target !== undefined && target.startsWith('"') && sourceLine && /(?<![\w-])surface=/.test(sourceLine) && !TINT_STEPS.some((s) => target.includes(`"${s}"`))) {
+    return `\`surface\` takes a layout slot only, one of the values the message lists. To colour by a data category (series, lanes, kinds, element groups), set \`tint\` instead, on the same Box or Card: ${TINT_STEPS.map((s) => `tint="${s}"`).join(', ')}. When the value comes from a map or a helper, type it as the tint union (${TINT_STEPS.map((s) => `'${s}'`).join(' | ')}), not \`string\`. Never cast it.${sourceHint}`;
+  }
+
   // Detect "unknown is not assignable to ReactNode"
   if ((code === 2322 || code === 2769) && message && /unknown.*ReactNode|ReactNode.*unknown/.test(message)) {
     return `This value has type 'unknown' and cannot be rendered in JSX. Cast it: String(value) or add a type annotation.${sourceHint}`;
@@ -136,6 +204,7 @@ function generateFix(code: number, message?: string, sourceLine?: string): strin
     case 2307:
       return `Only these imports are allowed: ${describeAllowedImports()}${sourceHint}`;
     case 2322:
+    case 2820:
     case 2769:
       return `Type mismatch on this expression. Check the offending line below — the prop name in JSX is what TypeScript is rejecting; the message tells you the expected type.${sourceHint}`;
     case 2339:
@@ -163,6 +232,12 @@ interface VfsEntry {
 
 let vfsCache: Map<string, VfsEntry> | null = null;
 
+/**
+ * Where `csstype`'s declarations sit in the sandbox (ggui#1871). `@types/react`'s
+ * `import … from "csstype"` resolves here through the generic bare-specifier lookup.
+ */
+const CSSTYPE_VFS_PATH = 'node_modules/csstype/index.d.ts';
+
 function parseAndStore(
   vfs: Map<string, VfsEntry>,
   virtualPath: string,
@@ -204,14 +279,41 @@ function walkDir(dir: string, filter: (f: string) => boolean): string[] {
  * walk lands in the wrong place).
  */
 function findReactTypesDir(): string | null {
-  try {
-    // `@types/react` doesn't expose `package.json` as a public subpath,
-    // so resolve via the always-present `index.d.ts`.
-    const indexDts = createRequire(import.meta.url).resolve('@types/react/index.d.ts');
-    return path.dirname(indexDts);
-  } catch {
-    return null;
+  // `@types/react` (19.2+) declares an `exports` map whose entries carry only
+  // `types` conditions, so `require.resolve` refuses every subpath of it —
+  // `@types/react/index.d.ts` included. That made this function return null
+  // and the sandbox ran WITHOUT React's types (ggui#1849). Plain components
+  // kept their own props through the global JSX shim, but every prop typed
+  // through React (`ref`, `style`, handlers) degraded to `any` (`style` needs
+  // `csstype` as well — {@link findCsstypeDir}, ggui#1871), and so did every
+  // prop of the trait-composed primitives (Box, Card, Grid, Row, Stack): their
+  // `WithTrait` union has an arm built from React's types, and a union with an
+  // `any` arm is `any`. Walk Node's own
+  // lookup paths for the package directory instead; `resolve.paths` applies no
+  // `exports` restriction, and the index file is checked on disk.
+  const lookup = createRequire(import.meta.url).resolve.paths('@types/react') ?? [];
+  for (const dir of lookup) {
+    const candidate = path.join(dir, '@types', 'react');
+    if (fs.existsSync(path.join(candidate, 'index.d.ts'))) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Resolve `csstype`'s root directory (ggui#1871). `@types/react/index.d.ts`
+ * opens with `import * as CSS from "csstype"`; without it `CSS` is unresolved,
+ * `CSSProperties` has no members and every `style={{…}}` goes unchecked.
+ * `csstype` is `@types/react`'s own dependency, so it is looked up from that
+ * package's real directory — the same place Node would find it for React's
+ * types, nested or hoisted.
+ */
+function findCsstypeDir(reactDir: string): string | null {
+  const lookup = createRequire(path.join(fs.realpathSync(reactDir), 'index.d.ts')).resolve.paths('csstype') ?? [];
+  for (const dir of lookup) {
+    const candidate = path.join(dir, 'csstype');
+    if (fs.existsSync(path.join(candidate, 'index.d.ts'))) return candidate;
   }
+  return null;
 }
 
 /**
@@ -249,11 +351,13 @@ async function loadVfs(): Promise<Map<string, VfsEntry>> {
   }
 
   // ---- 2. React types ----
-  // Resolved through `createRequire(import.meta.url).resolve('@types/
-  // react/index.d.ts')` — position-independent. Works the same in
-  // monorepo (hoisted to root) and in standalone `packages/`-only
-  // installs (the projected public OSS repo strips the `packages/`
-  // prefix, so a hardcoded `../../../..` walk would miss).
+  // Found by `findReactTypesDir` (Node's lookup paths, no `exports`
+  // restriction) — position-independent: the same in the monorepo
+  // (hoisted to root), in a deployed closure, and in standalone
+  // `packages/`-only installs. `@types/react` is a runtime DEPENDENCY of
+  // this package, not a dev one (ggui#1849): a deployed closure never
+  // installs devDependencies, and without these types every JSX prop
+  // degrades to `any`.
   const reactDir = findReactTypesDir();
   if (reactDir) {
     const reactDts = fs.readdirSync(reactDir).filter((f) => f.endsWith('.d.ts'));
@@ -261,6 +365,10 @@ async function loadVfs(): Promise<Map<string, VfsEntry>> {
       const content = fs.readFileSync(path.join(reactDir, file), 'utf-8');
       parseAndStore(vfs, `node_modules/@types/react/${file}`, content);
     }
+    const csstypeDir = findCsstypeDir(reactDir);
+    if (csstypeDir) {
+      parseAndStore(vfs, CSSTYPE_VFS_PATH, fs.readFileSync(path.join(csstypeDir, 'index.d.ts'), 'utf-8'));
+    }
   }
 
   // ---- 3. Design system types ----
@@ -664,11 +772,15 @@ export async function typecheck(
         ? sourceLines[rawLine - 1]?.trim() ?? ''
         : '';
 
+    // ggui#1933 — a prop the component does not take: name the props it does take, from its own props type.
+    const unknownProp = code_ === 2322 ? /Property '([^']+)' does not exist on type '[^']*Props[^']*'/.exec(message)?.[1] : undefined;
+    const props = unknownProp !== undefined ? acceptedPropsAt(program, diag.file, diag.start ?? 0) : undefined;
+    const hint = sourceLine.length > 0 && sourceLine.length <= 140 ? ` Offending line: \`${sourceLine}\`` : '';
     const entry: TypeCheckDiagnostic = {
       code: code_,
       line,
       message,
-      fix: generateFix(code_, message, sourceLine),
+      fix: unknownProp !== undefined && props !== undefined ? unknownPropFix(props.component, unknownProp, props.accepted, hint, props.native) : generateFix(code_, message, sourceLine),
     };
 
     if (BLOCKING_CODES.has(code_)) {

package/src/coding-agent/tools.ts

@@ -11,9 +11,10 @@
 import * as esbuild from 'esbuild';
 import { AgentWorkspace } from './workspace';
 import { getSoftWarnings } from './self-check';
+import { restoreReactImport } from '../boilerplate/react-hooks.js';
 import { runTier0Checks } from '../check/index.js';
 import { runGatedAxisChecks, traceAxisChecksSkipped } from '../evaluation/axis-checks/dispatch.js';
-import type { AxisCheck, AxisCheckInput } from '../evaluation/types-public.js';
+import type { AxisCheck, AxisCheckInput, EvalIssue } from '../evaluation/types-public.js';
 import type { Classification } from '../classifier/axes.js';
 import type { CanvasClass } from '../design-mode.js';
 import { PRIMITIVES_DOCUMENTATION } from '../validation/index.js';
@@ -24,6 +25,21 @@ import type {
 } from './types';
 import { DEFAULT_DESIGN_MODE, type DesignMode } from '../design-mode.js';
 
+/**
+ * ggui#1876 — the auto-commit line's axis field: the F/W counts, then the check ids behind them, so a
+ * WARN the model saw at a turn is attributable in the log (the `[WARN]` text otherwise appears only at
+ * the final evaluation). `0F/1W[W:universal.tint_category_in_words]`; nothing appended at `0F/0W`.
+ * The `<n>F/<n>W` prefix is unchanged, so anything that reads the counts reads them as before. An
+ * issue with no `subcategory` (the axis checks always set one, as their id) is named by its category.
+ */
+export function axisCountsWithIds(issues: readonly EvalIssue[]): string {
+  const idOf = (i: EvalIssue): string => i.subcategory ?? i.category;
+  const warns = issues.filter((i) => i.result === 'warn').map(idOf);
+  const fails = issues.filter((i) => i.result !== 'warn').map(idOf);
+  const groups = [...(fails.length > 0 ? [`F:${fails.join(',')}`] : []), ...(warns.length > 0 ? [`W:${warns.join(',')}`] : [])];
+  return `${fails.length}F/${warns.length}W${groups.length > 0 ? `[${groups.join(' ')}]` : ''}`;
+}
+
 /**
  * Extract documentation for a single component from the full primitives docs.
  * Returns ~200-500 tokens instead of 43K.
@@ -106,7 +122,14 @@ async function autoCommit(
   // No post-compile formatting — the generated TSX is built as-is.
   // (Prettier auto-format was removed; it added a dependency + repair
   // churn without a quality gain.)
-  const formatted = raw;
+  // ggui#1932: the boilerplate's DO NOT EDIT React import is code's to keep — restored here, before
+  // the build and tier-0, so a dropped hook never becomes a refusal the model spends a turn on.
+  const restore = restoreReactImport(raw);
+  if (restore.added.length > 0) {
+    workspace.write(restore.source);
+    console.log(`[coding-agent] react-import restored: ${restore.added.map((h) => `+${h}`).join(',')}`);
+  }
+  const formatted = restore.source;
 
   // Build with esbuild — keep all imports (react, @ggui-ai/design)
   // esbuild.transform() passes them through as-is, the runtime resolves them
@@ -197,7 +220,7 @@ async function autoCommit(
 
   const status = buildSuccess && selfCheckPassed ? 'PASS' : 'FAIL';
   console.log(
-    `[coding-agent] auto-commit: ${status} | build=${buildMs}ms self-check=${selfCheckMs}ms git=${gitMs}ms total=${Date.now() - commitStart}ms | violations=${violations.length} | axis=${axisRun === undefined ? 'off' : `${axisIssues.length - axisWarnings.length}F/${axisWarnings.length}W`}`,
+    `[coding-agent] auto-commit: ${status} | build=${buildMs}ms self-check=${selfCheckMs}ms git=${gitMs}ms total=${Date.now() - commitStart}ms | violations=${violations.length} | axis=${axisRun === undefined ? 'off' : axisCountsWithIds(axisIssues)}`,
   );
   if (violations.length > 0) {
     for (const v of violations) {