themelia-react-ui 2.0.5 → 3.0.0

package/docs/consumer-skill/scripts/composition-policy.mjs

@@ -44,6 +44,8 @@ export function analyzeComposition(text, { filename, index, ts }) {
   const families = new Map(index.families.map(owner => [owner.import, owner]));
   const bindings = new Map();
   const namespaces = new Map();
+  const portalBindings = new Set();
+  const portalNamespaces = new Set();
   const declarations = new Map();
   const findings = [];
   const unresolved = [];
@@ -135,14 +137,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (names && ts.isNamespaceImport(names)) namespaces.set(symbolFor(names.name), specifier);
   }
   function gather(node) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier) && node.moduleSpecifier.text === 'react-dom') {
+      const names = node.importClause?.namedBindings;
+      if (names && ts.isNamedImports(names)) for (const item of names.elements) if ((item.propertyName ?? item.name).text === 'createPortal') portalBindings.add(symbolFor(item.name));
+      if (names && ts.isNamespaceImport(names)) portalNamespaces.add(symbolFor(names.name));
+      if (node.importClause?.name) portalNamespaces.add(symbolFor(node.importClause.name));
+    }
     if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier) && importsModal(node, ts)) add(node, 'raw-overlay-primitive', 'warning', `${node.moduleSpecifier.text} builds a second dialog system. ${overlayRemedy}`);
     if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) declarations.set(symbolFor(node.name), node.initializer);
+    if (ts.isFunctionDeclaration(node) && node.name && node.body) declarations.set(symbolFor(node.name), node);
     if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) importOwner(node, node.moduleSpecifier.text);
     if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal)) importOwner(node, node.argument.literal.text);
     if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && ts.isStringLiteralLike(node.arguments[0])) importOwner(node, node.arguments[0].text);
     ts.forEachChild(node, gather);
   }
   gather(source);
+  const portalCall = node => ts.isCallExpression(node) && (ts.isIdentifier(node.expression) && portalBindings.has(symbolFor(node.expression))
+    || ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'createPortal' && ts.isIdentifier(node.expression.expression) && portalNamespaces.has(symbolFor(node.expression.expression)));
   for (const diagnostic of source.parseDiagnostics) add(source, 'syntax', 'error', ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
   const ownerFor = tag => {
     if (ts.isIdentifier(tag)) return bindings.get(symbolFor(tag));
@@ -157,16 +168,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     const expression = ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
     return [[attribute.name.getText(source), expression]];
   });
+  const unknownSpread = (expression, visiting = new Set()) => {
+    const value = resolve(expression);
+    if (!value || !ts.isObjectLiteralExpression(value) || visiting.has(value)) return true;
+    const next = new Set(visiting).add(value);
+    return value.properties.some(property => ts.isSpreadAssignment(property) && unknownSpread(property.expression, next));
+  };
   const isOwner = (owner, suffix, names) => owner?.import === `${index.package}/${suffix}` && names.includes(owner.symbol);
   const framedOwner = (owner, props) => {
-    if (literal(props.get('surface')) === 'flat') return false;
-    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
-    if (isOwner(owner, 'blocks/analytics', ['Metric'])) return literal(props.get('variant')) === 'card';
-    if (isOwner(owner, 'blocks/analytics', ['MetricGrid'])) return !props.has('variant') || literal(props.get('variant')) === 'card';
+    if (props.has('surface') && (literal(props.get('surface')) === undefined || literal(props.get('surface')) === 'flat')) return false;
+    if (isOwner(owner, 'base/cards', ['Card']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
+    if (isOwner(owner, 'blocks/analytics/charts', ['ChartCard'])) return props.has('surface');
+    if (isOwner(owner, 'blocks/analytics/charts', ['Metric'])) return literal(props.get('variant')) === 'card';
+    if (isOwner(owner, 'blocks/analytics/charts', ['MetricGrid'])) return !props.has('variant') || literal(props.get('variant')) === 'card';
     return isOwner(owner, 'blocks/analytics/usage-card', ['UsageCard']) || isOwner(owner, 'blocks/analytics', ['UsageCard']) || isOwner(owner, 'blocks/planning', ['TaskCard']);
   };
   // Examine lexical JSX only. Names ending in Card are not evidence of framing;
-  // ChartCard is card-free; Receipt's flat paper has no ordinary Card frame.
+  // ChartCard is card-free by default; Receipt's paper has no ordinary Card frame.
   const contentElements = element => {
     const found = [];
     function collect(child) {
@@ -174,7 +192,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
         const opening = ts.isJsxElement(child) ? child.openingElement : child;
         const owner = ownerFor(opening.tagName);
         found.push({ opening, owner, props: new Map(attributes(opening)), element: child });
-        if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) return;
+        if (isOwner(owner, 'base/cards', ['Card'])) return;
         if (ts.isJsxElement(child)) child.children.forEach(collect);
         return;
       }
@@ -196,7 +214,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       const owner = ownerFor(node.tagName);
       found.push({node, owner, tag: node.tagName.getText(source), scope, subject});
       const provider = isOwner(owner, 'features/filters', ['FilterProvider']);
-      const card = isOwner(owner, 'base/cards', ['Card', 'SmartCard']);
+      const card = isOwner(owner, 'base/cards', ['Card']);
       // Cards delimit independent subjects; providers delimit query state.
       if (deep && ts.isJsxElement(child) && (/^(div|section|form)$/.test(node.tagName.getText(source)) || isOwner(owner, 'base/structure', ['Stack', 'Grid', 'AdaptiveGrid', 'GridCell']) || card || provider)) child.children.forEach(item => collect(item, provider ? node : scope, card ? node : subject));
     };
@@ -221,14 +239,24 @@ export function analyzeComposition(text, { filename, index, ts }) {
   };
   // Buttons, command rows and command menus placed directly, conditionally or
   // inside a passive row of a page header's actions region. Unknown local
-  // components are custom controls.
+  // components are custom controls. A slot callback, such as `slots.actions`
+  // wrapping `defaultContent`, is read through what it returns.
+  const slotCallbacks = new Set();
   const commandButtons = expression => {
     const node = resolve(expression);
     if (!node) return false;
+    if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node)) && node.body) {
+      // A callback that returns itself is not followed twice.
+      if (slotCallbacks.has(node)) return false;
+      slotCallbacks.add(node);
+      const found = ts.isBlock(node.body) ? node.body.statements.some(statement => ts.isReturnStatement(statement) && commandButtons(statement.expression)) : commandButtons(node.body);
+      slotCallbacks.delete(node);
+      return found;
+    }
     if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
       const opening = ts.isJsxElement(node) ? node.openingElement : node;
       const owner = ownerFor(opening.tagName);
-      if (isOwner(owner, 'base/buttons', ['Button', 'TextButton', 'BaseButton', 'BaseButtonLink']) || isOwner(owner, 'base/forms', ['SubmitStateButton']) || isOwner(owner, 'base/action-menu', ['ActionMenu', 'ActionButtons']) || isOwner(owner, 'layout/page', ['PageActions']) || isOwner(owner, 'layout', ['PageActions']) || opening.tagName.getText(source) === 'button') return true;
+      if (isOwner(owner, 'base/buttons', ['Button', 'TextButton', 'BaseButton', 'BaseButtonLink']) || isOwner(owner, 'base/forms', ['SubmitStateButton']) || isOwner(owner, 'base/action-menu', ['ActionMenu', 'ActionButtons']) || opening.tagName.getText(source) === 'button') return true;
       if (!/^(div|span)$/.test(opening.tagName.getText(source)) && !isOwner(owner, 'base/structure', ['Stack', 'Grid'])) return false;
       return ts.isJsxElement(node) && node.children.some(commandButtons);
     }
@@ -260,25 +288,43 @@ export function analyzeComposition(text, { filename, index, ts }) {
   };
   // tone="primary" is solid unless a buttonStyle says otherwise; untoned Buttons are neutral.
   const solidPrimary = (opening, owner) => {
-    if (!isOwner(owner, 'base/buttons', ['Button'])) return false;
+    const submit = isOwner(owner, 'base/forms', ['SubmitStateButton']);
+    if (!submit && !isOwner(owner, 'base/buttons', ['Button'])) return false;
     const props = new Map(attributes(opening));
     const style = props.has('buttonStyle') ? literal(props.get('buttonStyle')) : 'solid';
-    return literal(props.get('tone')) === 'primary' && style === 'solid';
+    return (literal(props.get('tone')) ?? (submit && !props.has('tone') ? 'primary' : undefined)) === 'primary' && style === 'solid';
   };
-  // Overlays are separate surfaces with their own primary command.
+  const formRoot = opening => {
+    if (opening.tagName.getText(source) === 'form') return true;
+    const render = resolve(new Map(attributes(opening)).get('render'));
+    return render && (ts.isJsxElement(render) ? render.openingElement : ts.isJsxSelfClosingElement(render) ? render : undefined)?.tagName.getText(source) === 'form';
+  };
+  // A form owns its submit command; overlays and exclusive branches are not
+  // simultaneously competing page commands. Follow same-file slot values only.
   const solidPrimaryCount = root => {
-    let count = 0;
-    const walk = child => {
+    const count = (expression, visiting = new Set()) => {
+      if (!expression) return 0;
+      const child = resolve(expression) ?? expression;
+      if (visiting.has(child)) return 0;
+      const next = new Set(visiting).add(child);
+      if (portalCall(child)) return 0;
+      if (ts.isConditionalExpression(child)) return Math.max(count(child.whenTrue, next), count(child.whenFalse, next));
+      if (ts.isBinaryExpression(child) && [ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(child.operatorToken.kind)) return Math.max(count(child.left, next), count(child.right, next));
       if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
         const opening = ts.isJsxElement(child) ? child.openingElement : child;
         const owner = ownerFor(opening.tagName);
-        if (isOwner(owner, 'features/overlays', overlayOwners)) return;
-        if (solidPrimary(opening, owner)) count++;
+        if (isOwner(owner, 'features/overlays', overlayOwners) || formRoot(opening) || !owner && /^[A-Z]/.test(opening.tagName.getText(source))) return 0;
+        const props = new Map(attributes(opening));
+        if (resolve(props.get('hidden'))?.kind === ts.SyntaxKind.TrueKeyword || props.has('hidden') && props.get('hidden') === undefined) return 0;
+        const children = ts.isJsxElement(child) ? child.children.reduce((total, item) => total + count(item, next), 0) : 0;
+        const slots = [...props].filter(([name]) => !['header', 'render'].includes(name)).reduce((total, [, value]) => total + count(value, next), 0);
+        return Number(solidPrimary(opening, owner)) + children + slots;
       }
-      ts.forEachChild(child, walk);
+      let total = 0;
+      ts.forEachChild(child, item => { total += count(item, next); });
+      return total;
     };
-    ts.forEachChild(root, walk);
-    return count;
+    return count(root);
   };
   const peerCards = element => {
     if (!ts.isJsxElement(element.parent)) return new Set();
@@ -322,18 +368,84 @@ export function analyzeComposition(text, { filename, index, ts }) {
       return smallPeerGaps.has(row ?? gap) || smallPeerGaps.has(column ?? gap);
     });
   };
-  function visit(node, parents = []) {
+  const separateRegion = owner => isOwner(owner, 'features/overlays', overlayOwners)
+    || isOwner(owner, 'base/popover', ['PopoverContent'])
+    || isOwner(owner, 'base/navigation', ['DropdownMenuContent', 'DropdownMenuSubContent', 'ContextMenuContent', 'ContextMenuSubContent'])
+    || isOwner(owner, 'base/combobox', ['ComboboxContent', 'ComboboxPopup'])
+    || isOwner(owner, 'base/choice-inputs', ['SelectPopupContent']);
+  function regionParents(element, parents, context, slot) {
+    if (slot === 'render') return parents;
+    if (separateRegion(context?.owner) || !context && /^[A-Z]/.test(element.tagName.getText(source))) parents = [];
+    return context ? [...parents, { ...context, slot }] : parents;
+  }
+  function visitValue(value, parents, visiting) {
+    if (value) visit(resolve(value) ?? value, parents, visiting);
+  }
+  function visit(node, parents = [], visiting = new Set()) {
+    if (visiting.has(node)) return;
+    const next = new Set(visiting).add(node);
     if (ts.isJsxElement(node)) {
       const element = node.openingElement;
       const context = inspect(element, parents);
-      for (const child of node.children) visit(child, context ? [...parents, context] : parents);
-      // JSX in props is a separate region, not a child frame.
-      for (const attribute of element.attributes.properties) ts.forEachChild(attribute, child => visit(child, parents));
+      for (const child of node.children) visit(child, regionParents(element, parents, context, 'children'), next);
+      for (const [slot, value] of attributes(element)) visitValue(value, regionParents(element, parents, context, slot), next);
+      return;
+    }
+    if (ts.isJsxSelfClosingElement(node)) {
+      const context = inspect(node, parents);
+      for (const [slot, value] of attributes(node)) visitValue(value, regionParents(node, parents, context, slot), next);
+      return;
+    }
+    if (ts.isJsxExpression(node)) { visitValue(node.expression, parents, next); return; }
+    if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node) || ts.isMethodDeclaration(node)) {
+      const member = ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name) ? node.name.text : undefined;
+      // columns contains header/footer renderers as well as cells. Only a cell
+      // owns the table-row height addressed by heavy-cell-disclosure.
+      const nextParents = parents.map(parent => parent.slot === 'columns' && ['cell', 'header', 'footer'].includes(member) ? {...parent, member} : parent);
+      if (ts.isMethodDeclaration(node)) { if (node.body) visit(node.body, nextParents, next); }
+      else visitValue(ts.isShorthandPropertyAssignment(node) ? node.name : node.initializer, nextParents, next);
+      return;
+    }
+    if (portalCall(node)) {
+      for (const [index, value] of node.arguments.entries()) visitValue(value, index === 0 ? [] : parents, next);
       return;
     }
-    if (ts.isJsxSelfClosingElement(node)) inspect(node, parents);
-    ts.forEachChild(node, child => visit(child, parents));
+    ts.forEachChild(node, child => visit(child, parents, next));
   }
+  const surfaceOwner = owner => isOwner(owner, 'base/cards', ['Card', 'CardFooter']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'blocks/analytics/charts', ['ChartCard']);
+  const footerRegion = parent => surfaceOwner(parent.owner) && (['footerSlot', 'footer'].includes(parent.slot) || parent.owner.symbol === 'CardFooter');
+  const paddedRegion = parent => {
+    if (!surfaceOwner(parent.owner) || parent.unknownProps) return false;
+    // Card contentPadding sets the body inset alone, keeping the header inset:
+    // the seam for a titled card around a table or list that owns its edge.
+    if (isOwner(parent.owner, 'base/cards', ['Card']) && parent.props.has('contentPadding') && !['footerSlot', 'footer'].includes(parent.slot)) {
+      const padding = literal(parent.props.get('contentPadding'));
+      return padding !== undefined && padding !== 'none';
+    }
+    if (parent.props.has('padding')) {
+      const padding = literal(parent.props.get('padding'));
+      return padding !== undefined && padding !== 'none';
+    }
+    // Flat removes the frame, not Card/FormSection's ordinary region insets.
+    // ChartCard instead defaults to no inset when card-free.
+    return isOwner(parent.owner, 'base/cards', ['Card', 'CardFooter']) || isOwner(parent.owner, 'base/forms', ['FormSection']) || parent.framed;
+  };
+  const remoteSubmit = expression => {
+    const calls = new Set();
+    const walk = (node, visiting = new Set()) => {
+      if (!node) return;
+      const value = resolve(node) ?? node;
+      if (visiting.has(value)) return;
+      const next = new Set(visiting).add(value);
+      if (ts.isCallExpression(value) && ts.isPropertyAccessExpression(value.expression)) {
+        if (value.expression.name.text === 'requestSubmit') calls.add('submit');
+        if (value.expression.name.text === 'getElementById' && value.expression.expression.getText(source) === 'document' && !symbolFor(value.expression.expression)) calls.add('lookup');
+      }
+      ts.forEachChild(value, child => walk(child, next));
+    };
+    walk(expression);
+    return calls.size === 2;
+  };
   // A native element passed as a package owner's `render` is that owner's root, such as
   // an Item row rendered as a button; the owner keeps its focus, hover and row anatomy.
   const renderRoots = new Set();
@@ -375,9 +487,10 @@ export function analyzeComposition(text, { filename, index, ts }) {
       add(node, 'public-symbol', 'error', `${owner.import} does not export ${owner.symbol}.`);
       return;
     }
-    const unresolvedBeforeProps = unresolved.length;
     const props = new Map(attributes(node));
-    const unknownProps = unresolved.length !== unresolvedBeforeProps;
+    // Other reviews can have already disclosed this spread. Deduplication of
+    // unresolved output must not turn an unknown value into a known default.
+    const unknownProps = node.attributes.properties.some(attribute => ts.isJsxSpreadAttribute(attribute) && unknownSpread(attribute.expression));
     const family = owner.import.split('/base/')[1];
     const anatomy = surfaceParts[family]?.test(owner.symbol);
     const forwarder = surfaceForwarders[family] === owner.symbol;
@@ -407,38 +520,52 @@ export function analyzeComposition(text, { filename, index, ts }) {
       if (display && marginProperty.test(name) && !/^['"]?0(?:px|rem|em|%)?['"]?$/.test(resolve(value)?.getText(source)??'')) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; the surrounding structure owns its copy gap.`);
       if (fixedText && (textStyle.test(name) || badge && /^border.*Radius$/.test(name))) add(node, 'fixed-text-role', 'error', `${owner.symbol}: ${name} replaces its shared text/radius recipe.`);
     }
-    if ((isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'base/display', ['ContentBlock'])) && props.get('icon')) add(node, 'decorative-icon', 'warning', `${owner.symbol}: a title icon is decoration unless it encodes state or a brand; let the title name the subject.`);
+    if ((isOwner(owner, 'base/cards', ['Card'])) && props.get('icon')) add(node, 'decorative-icon', 'warning', `${owner.symbol}: a title icon is decoration unless it encodes state or a brand; let the title name the subject.`);
     const facts = isOwner(owner, 'base/metadata-list', ['MetadataList']) || isOwner(owner, 'blocks/data-display', ['MetadataList']) ? resolve(props.get('items')) : undefined;
     if (facts && ts.isArrayLiteralExpression(facts) && facts.elements.filter(item => properties(item, false).some(([name]) => name === 'icon')).length > 1) add(node, 'decorative-icon', 'warning', 'MetadataList: an icon on every fact repeats what its label says; keep labels and drop the icons.');
-    const framed = framedOwner(owner, props);
-    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) {
+    const framed = !unknownProps && framedOwner(owner, props);
+    if (isOwner(owner, 'base/cards', ['Card'])) {
       for (const slot of ['headerAction', 'headerStart']) if (slotBadge(props.get(slot))) add(node, 'card-badge-placement', 'error', `${owner.symbol}: put status/count/version badges in titleSuffix; ${slot} owns ${slot === 'headerAction' ? 'commands' : 'pre-title context'}.`);
       const contents = contentElements(node);
       const role = (item, names) => isOwner(item.owner, 'typography', names);
       const valueHeading = contents.some(item => role(item, ['Heading']) && /[$€£¥]|\d/.test(renderedText(item.element)));
-      if (valueHeading && contents.some(item => role(item, ['Text', 'DisplayLabel'])) && contents.some(item => isOwner(item.owner, 'base/badge', ['Badge']) && /[%+−-]|\d/.test(renderedText(item.element)))) add(node, 'reinvented-metric-card', 'warning', 'This label/value/change composition resembles a KPI. Compare Metric/MetricGrid from blocks/analytics or InlineStat from blocks/data-display; retain a custom subject when their metric lifecycle does not fit.');
+      if (valueHeading && contents.some(item => role(item, ['Text', 'DisplayLabel'])) && contents.some(item => isOwner(item.owner, 'base/badge', ['Badge']) && /[%+−-]|\d/.test(renderedText(item.element)))) add(node, 'reinvented-metric-card', 'warning', 'This label/value/change composition resembles a KPI. Compare Metric/MetricGrid from blocks/analytics/charts or InlineStat from blocks/data-display; retain a custom subject when their metric lifecycle does not fit.');
       const factRows = contents.filter(item => isOwner(item.owner, 'base/structure', ['Stack']) && literal(item.props.get('direction')) === 'horizontal' && literal(item.props.get('justify')) === 'between' && contentElements(item.opening).filter(child => role(child, ['Text', 'DisplayLabel'])).length >= 2);
       if (factRows.length >= 2) add(node, 'reinvented-metadata-list', 'warning', 'Repeated label/value rows resemble record facts. Compare MetadataList from base/metadata-list or InlineStat from blocks/data-display; preserve custom rows when they own distinct interactions or content.');
       if (contents.some(item => role(item, ['Heading']) && /^(?:no\b|nothing\b|empty\b)/i.test(renderedText(item.element))) && contents.some(item => isOwner(item.owner, 'base/structure', ['Stack']) && literal(item.props.get('align')) === 'center') && contents.some(item => isOwner(item.owner, 'base/buttons', ['Button', 'ButtonLink']))) add(node, 'reinvented-empty-state', 'warning', 'This centered empty region may fit EmptyState from blocks/data-display, with media, title, description and actions. Review the product state before choosing the complete owner.');
     }
     if (isOwner(owner, 'base/feedback', ['Empty'])) add(node, 'reinvented-empty-state', 'warning', 'Empty exposes lower-level anatomy. Compare EmptyState from blocks/data-display for a routine no-data/no-results region; keep Empty when custom anatomy is required.');
-    if (isOwner(owner, 'base/sheet', ['Sheet', 'SheetContent']) || isOwner(owner, 'base/display', ['Dialog', 'DialogContent', 'AlertDialog', 'AlertDialogContent'])) add(node, 'raw-overlay-primitive', 'warning', 'This lower-level modal needs application lifecycle coordination. Prefer ActionDialog, ConfirmDialog or ActionDrawer from features/overlays when their workflow fits.');
-    if (isOwner(owner, 'features/table', ['DataTable'])) {
-      const parent = parents.at(-1);
-      let ancestor = ts.isJsxOpeningElement(node) ? node.parent.parent : node.parent;
-      while (ancestor && !ts.isJsxElement(ancestor)) ancestor = ancestor.parent;
-      const directOwner = ancestor && ownerFor(ancestor.openingElement.tagName);
-      if (isOwner(directOwner, 'base/cards', ['Card', 'SmartCard']) && isOwner(parent?.owner, 'base/cards', ['Card', 'SmartCard']) && literal(parent.props.get('padding')) !== 'none' && !parent.unknownProps) add(node, 'uncontained-table-in-card', 'warning', 'DataTable owns its surface, topbar and edge-to-edge header band. Render it directly in Page or a layout region; a deliberate Card host must use padding="none".');
+    if (isOwner(owner, 'base/display', ['Dialog', 'DialogContent', 'AlertDialog', 'AlertDialogContent'])) add(node, 'raw-overlay-primitive', 'warning', 'This lower-level modal needs application lifecycle coordination. Prefer ActionDialog, ConfirmDialog or ActionDrawer from features/overlays when their workflow fits.');
+    if (isOwner(owner, 'base/forms', ['FormActionsBar'])) {
+      const footer = parents.findLast(footerRegion);
+      const padded = parents.findLast(paddedRegion);
+      if (footer || padded) add(node, 'form-actions-bar-placement', 'warning', `FormActionsBar owns a divider, background and inset; ${footer ? `${footer.owner.symbol}.${footer.slot} already owns footer geometry` : `${padded.owner.symbol} already owns body padding`}. Put action buttons directly in the footer slot, or place the bar at the end of the form inside Card padding="none" with flat FormSection siblings. Review intentional custom hosts.`);
+    }
+    if (isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'base/table', ['Table'])) {
+      const footer = parents.findLast(footerRegion);
+      const padded = parents.findLast(paddedRegion);
+      if (footer || padded) add(node, 'uncontained-table-in-card', 'warning', `${owner.symbol} is inside ${footer ? `${footer.owner.symbol}.${footer.slot}` : `a padded ${padded.owner.symbol}`}. Keep substantial tables in a body or peer region; a titled Card host uses contentPadding="none" (padding="none" without a header) around a flat table. Review the actual surface and inset ownership.`);
+    }
+    if ((isOwner(owner, 'base/accordion', ['Accordion', 'SmartAccordion']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'base/code-block', ['CodeBlock'])) && parents.some(parent => isOwner(parent.owner, 'features/table', ['DataTable']) && parent.slot === 'columns' && parent.member === 'cell')) {
+      add(node, 'heavy-cell-disclosure', 'warning', `${owner.symbol} in a DataTable cell can disrupt row scanning. Prefer a compact summary with rowActions opening an ActionDrawer, ActionDialog or detail route; retain an intentional inline disclosure after checking expanded rows and keyboard access.`);
+    }
+    if (isOwner(owner, 'base/choice-inputs', ['CardCheckboxGroup', 'CardRadioGroup', 'ListRadioGroup', 'PillRadioGroup'])) {
+      const options = resolve(props.get('options'));
+      if (options && ts.isArrayLiteralExpression(options) && options.elements.length === 1 && !ts.isSpreadElement(options.elements[0])) add(node, 'single-option-choice-group', 'warning', `${owner.symbol} has one static option. For a boolean setting prefer Checkbox, Switch, ToggleField or SwitchCard; retain a genuine choice set whose available options happen to contain one item.`);
     }
     const routeOwner = isOwner(owner, 'layout/page', ['Page']) || isOwner(owner, 'layout', ['Page']);
     if (routeOwner) {
+      for (const name of ['narrow', 'maxWidth']) {
+        const value = resolve(props.get(name));
+        if (value && (ts.isConditionalExpression(value) || ts.isBinaryExpression(value) || ts.isPrefixUnaryExpression(value))) add(props.get(name), 'dynamic-page-measure', 'warning', `Page ${name} depends on an expression and may resize the header and tabs when sections change. Keep the route measure stable and constrain a focused tab panel with Container maxWidth="md" gutter="none"; responsive route sizing can be intentional.`);
+      }
       const children = regionElements(node);
       const contents = regionElements(node, true);
       const tables = contents.filter(child => isOwner(child.owner, 'features/table', ['DataTable']));
       for (const child of contents) if (isOwner(child.owner, 'features/filters', ['FilterLayout']) && tables.some(table => table.scope === child.scope && (!child.subject || table.subject === child.subject))) add(child.node, 'detached-filter-layout', 'warning', 'Pass FilterLayout into DataTable topbarContent with variant="compact", or use DataView so filters and table chrome share one surface.');
       const hasAsideSlot = properties(props.get('slots'), false).some(([name]) => name === 'aside');
       const onlyForms = children.length > 0 && children.every(child => child.tag === 'form' || isOwner(child.owner, 'base/forms', ['FormSection']));
-      if (onlyForms && !unknownProps && !['narrow', 'maxWidth', 'aside'].some(name => props.has(name)) && !hasAsideSlot) add(node, 'wide-single-column-form', 'warning', 'A single-column form should use Page narrow (48rem centered), an explicit maxWidth, or a supporting aside so fields do not stretch across the default route measure.');
+      if (onlyForms && !unknownProps && !['narrow', 'maxWidth', 'aside'].some(name => props.has(name)) && !hasAsideSlot) add(node, 'wide-single-column-form', 'warning', 'Review this single-column form measure: a focused form can use Page narrow (48rem centered), an explicit maxWidth, or a supporting aside. In a mixed/tabbed route, keep Page stable and constrain only the form panel with Container maxWidth="md" gutter="none".');
     }
     if (owner.symbol === 'Page' && literal(props.get('gutter')) === 'none' && !parents.some(parent => parent.framed)) add(node, 'page-gutter', 'warning', 'Page gutter="none" delegates inline padding to a real parent. PageViewport owns scrolling, not padding; verify the parent inset.');
     if (owner.symbol === 'Card' && framed && literal(props.get('padding')) === 'sm' && !parents.some(parent => parent.framed)) add(node, 'compact-card', 'warning', 'Standalone Card padding="sm" halves the normal inset. Omit padding for ordinary subjects; retain sm only for an intentional compact composition.');
@@ -447,19 +574,26 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (framed && parents.some(parent => parent.framed)) add(node, 'nested-surface', 'warning', `${owner.symbol} is inside a framed owner. Review subject boundaries; use surface="flat" when the parent owns the frame.`);
     const header = properties(props.get('header'), false);
     const pageOwner = owner.import === `${index.package}/layout/page` || owner.import === `${index.package}/layout`;
+    const headerValue = resolve(props.get('header'));
+    if (routeOwner && props.has('header') && headerValue && !ts.isObjectLiteralExpression(headerValue)) unknown(props.get('header'));
     // Every header owner takes role-based commands; its free-form regions hold
     // non-command controls only.
-    const commandHeader = (pageOwner && owner.symbol === 'PageHeader') || isOwner(owner, 'base/navigation', ['PageHeading']) || isOwner(owner, 'features/resource', ['ResourceHeader', 'ResourceIndexShell', 'ResourceShowShell', 'TabbedResourceShell']) || isOwner(owner, 'layout/settings', ['SettingsShell', 'AsideNavShell']) || isOwner(owner, 'layout', ['SettingsShell', 'AsideNavShell']) || isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']);
-    const headerActions = pageOwner && owner.symbol === 'Page' ? new Map(header).get('actions') : commandHeader ? props.get('actions') : undefined;
+    const commandHeader = (pageOwner && owner.symbol === 'PageHeader') || isOwner(owner, 'base/navigation', ['PageHeading']) || isOwner(owner, 'layout/settings', ['AsideNavShell']) || isOwner(owner, 'layout', ['AsideNavShell']) || isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']);
+    // Page and PageHeader take free-form header content through `slots.actions`;
+    // the other header owners keep an `actions` prop.
+    const slotActions = slots => new Map(properties(slots, false)).get('actions');
+    const headerActions = pageOwner && owner.symbol === 'Page' ? slotActions(new Map(header).get('slots'))
+      : pageOwner && owner.symbol === 'PageHeader' ? slotActions(props.get('slots'))
+      : commandHeader ? props.get('actions') : undefined;
     const elementSecondary = isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']) ? props.get('secondaryActions') : undefined;
     if (pageOwner && owner.symbol === 'Page') {
       const primaries = solidPrimaryCount(ts.isJsxSelfClosingElement(node) ? node : node.parent) + (new Map(header).has('primaryAction') ? 1 : 0);
-      if (primaries > 1) add(node, 'multiple-primary-commands', 'warning', `Page has ${primaries} solid primary commands. Keep one primary per page as header.primaryAction; leave other commands untoned (the neutral button) or list them in secondaryActions.`);
+      if (primaries > 1) add(node, 'multiple-primary-commands', 'warning', `Page has ${primaries} solid primary commands in the same task scope. Keep one leading command per task/surface; forms keep their local SubmitStateButton or FormActionsBar. Use header.primaryAction for route-level commands and secondaryActions for supporting route commands.`);
     }
-    if ((headerActions && commandButtons(headerActions)) || (elementSecondary && commandButtons(elementSecondary))) add(node, 'page-command-roles', 'warning', `${owner.symbol}: buttons, command rows and menus in the header actions region choose their own emphasis, order and overflow. Pass commands as primaryAction (one) and ordered secondaryActions; keep actions for non-command controls.`);
+    if ((headerActions && commandButtons(headerActions)) || (elementSecondary && commandButtons(elementSecondary))) add(node, 'page-command-roles', 'warning', `${owner.symbol}: buttons, command rows and menus in the header actions region choose their own emphasis, order and overflow. Pass commands as primaryAction (one) and ordered secondaryActions; keep the actions region for non-command controls.`);
     const headerProps = pageOwner && owner.symbol === 'Page' ? new Map(header) : pageOwner && owner.symbol === 'PageHeader' ? props : undefined;
     if (headerProps) {
-      if (headerProps.has('titleIcon') && !headerProps.has('titleIconHref') && !headerProps.has('onTitleIconClick')) add(headerProps.get('titleIcon') ?? node, 'decorative-icon', 'warning', `${owner.symbol}: titleIcon decorates the page title; let the title name the page, or link the icon with titleIconHref.`);
+      for (const name of ['primaryAction', 'secondaryActions']) if (headerProps.has(name) && remoteSubmit(headerProps.get(name))) add(headerProps.get(name), 'remote-header-form-submit', 'warning', `${owner.symbol}: ${name} submits a form through document.getElementById(...).requestSubmit(). Keep task-local submission beside its fields or in the form footer. A single full-page editor can deliberately own a header submit; preserve native validation and avoid duplicate commands.`);
       const hasIcon = action => properties(action, false).some(([name]) => name === 'icon');
       const secondary = resolve(headerProps.get('secondaryActions'));
       const iconCommands = (headerProps.has('primaryAction') && hasIcon(headerProps.get('primaryAction')) ? 1 : 0) + (secondary && ts.isArrayLiteralExpression(secondary) ? secondary.elements.filter(hasIcon).length : 0);

package/docs/consumer-skill/scripts/composition.mjs

@@ -115,7 +115,10 @@ export function mapComposition(index, contracts, rawOptions) {
   : /^[A-Z][A-Za-z0-9]*$/.test(request) || /[\/#]/.test(request) ? []
    : mappings.filter(mapping => mapping.roles.includes(roleKey(request)));
  if (options.roles) {
-  const roles = unique(mappings.flatMap(mapping => mapping.roles)).map(role => ({role, owners: mappings.filter(mapping => mapping.roles.includes(role)).length}));
+  const roles = unique(mappings.flatMap(mapping => mapping.roles)).map(role => {
+   const owners = mappings.filter(mapping => mapping.roles.includes(role));
+   return {role, owners: owners.length, symbols: unique(owners.map(mapping => mapping.symbol))};
+  });
   return {...base, mode: 'roles', total: roles.length, roles};
  }
  if (options.role !== undefined) {

package/docs/consumer-skill/scripts/discovery.mjs

@@ -132,7 +132,9 @@ function rankComponents(index, { query, layer = null, limit = 5 }, partial = fal
     const documentedSymbol = matchedSymbols.some(symbol => documented.has(symbol));
     const exactFamily = searchable(family.import.split('/').at(-1)) === terms.join(' ');
     const exactIntent = family.aliases.some(alias => normalized(alias) === needle);
-    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 + Number(documentedSymbol) : exactFamily ? 8500 : exactIntent ? 8000 : focusedSymbols.length ? 7100 + 1 / Math.min(...focusedSymbols.map(symbol => words(symbol).length)) : terms.reduce((sum, term) => sum + (family.guidance.some(guide => containsTerms(guide.title, [term])) ? 20 : family.tags.some(tag => containsTerms(tag, [term])) ? 10 : 1), 0);
+    // The family whose curated alias is the query is that symbol's owner too,
+    // even when the matched name is an undocumented alias export.
+    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 + Number(documentedSymbol || exactIntent) : exactFamily ? 8500 : exactIntent ? 8000 : focusedSymbols.length ? 7100 + 1 / Math.min(...focusedSymbols.map(symbol => words(symbol).length)) : terms.reduce((sum, term) => sum + (family.guidance.some(guide => containsTerms(guide.title, [term])) ? 20 : family.tags.some(tag => containsTerms(tag, [term])) ? 10 : 1), 0);
     const selectedSymbols = matchedSymbols.length ? matchedSymbols : focusedSymbols;
     const guidance = relevantGuidance(family, needle, terms, exactOwners.length ? selectedSymbols : [], exactImport);
     const candidateSymbols = exactImport ? family.symbols : exactOwners.length || matchedSymbols.length ? selectedSymbols : [...new Set([...selectedSymbols, ...guidance.flatMap(guide => guideSymbols(guide, family))])];

package/docs/consumer-skill/scripts/setup-skills.mjs

@@ -6,6 +6,8 @@ import { fileURLToPath } from 'node:url';
 export const focusedSkills = ['themelia-components', 'themelia-tokenization', 'themelia-composition', 'themelia-design'];
 export const sharedSkillName = 'themelia-react-ui-consumer';
 export const agentFiles = ['themelia-ui-designer.md'];
+/** Earlier releases copied these; a refresh removes them so no stale guidance remains. */
+export const retiredSkills = ['themelia-foundation', 'themelia-forms'];
 
 /** One metadata/example copy, four small discoverable entrypoints, and real templates. */
 export function consumerBundleFiles(packageRoot, destination) {
@@ -53,12 +55,23 @@ export function checkCopiedConsumerBundle({ packageRoot, destination }) {
     assert(fs.existsSync(target) && !fs.lstatSync(target).isSymbolicLink(), `Copied consumer bundle is stale: missing or linked asset ${target}`);
     assert(content.equals(fs.readFileSync(target)), `Copied consumer bundle is stale: refresh the whole bundle (${target})`);
   }
+  // A file the package no longer ships is stale guidance too.
+  const shipped = new Set(files.map(file => file.target));
+  for (const name of [sharedSkillName, ...focusedSkills]) {
+    for (const entry of fs.readdirSync(path.resolve(destination, name), { recursive: true, withFileTypes: true })) {
+      const file = path.join(entry.parentPath, entry.name);
+      assert(entry.isDirectory() || entry.name === '.DS_Store' || shipped.has(file), `Copied consumer bundle is stale: the package no longer ships ${file}`);
+    }
+  }
+  for (const name of retiredSkills) assert(!pathExists(path.resolve(destination, name)), `Copied consumer bundle is stale: ${name} was retired; copy again to remove it`);
   return { skills: [sharedSkillName, ...focusedSkills], assets: files.length };
 }
 
 export function copyConsumerBundle({ packageRoot, destination }) {
   const files = consumerBundleFiles(packageRoot, destination);
-  for (const name of [sharedSkillName, ...focusedSkills]) assert(!fs.existsSync(path.join(destination, name)), `Destination exists: ${name}. Preserve or move the previous skill before copying.`);
+  assertSkillDestination(destination);
+  // Replace, never merge: files a newer release dropped must not survive.
+  for (const name of [sharedSkillName, ...focusedSkills, ...retiredSkills]) fs.rmSync(path.resolve(destination, name), { recursive: true, force: true });
   for (const { target, content } of files) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, content);
@@ -66,6 +79,21 @@ export function copyConsumerBundle({ packageRoot, destination }) {
   return checkCopiedConsumerBundle({ packageRoot, destination });
 }
 
+function assertSkillDestination(destination) {
+  assertDirectoryPath(destination);
+}
+
+function pathExists(target) {
+  try { fs.lstatSync(target); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+function assertDirectoryPath(destination) {
+  let directory = path.resolve(destination);
+  while (!pathExists(directory)) directory = path.dirname(directory);
+  assert(fs.statSync(directory).isDirectory(), `Destination is not a directory: ${directory}`);
+}
+
 /** Agent definitions are single files copied into an agents directory, such as `.claude/agents`. */
 function agentBundleFiles(packageRoot, destination) {
   return agentFiles.map(name => {
@@ -85,27 +113,63 @@ export function checkCopiedAgents({ packageRoot, destination }) {
 
 export function copyAgents({ packageRoot, destination }) {
   const files = agentBundleFiles(packageRoot, destination);
-  for (const { target } of files) assert(!fs.existsSync(target), `Destination exists: ${path.basename(target)}. Preserve or move the previous agent before copying.`);
+  assertAgentDestination(files);
   fs.mkdirSync(destination, { recursive: true });
-  for (const { target, content } of files) fs.writeFileSync(target, content);
+  for (const { target, content } of files) { fs.rmSync(target, { force: true }); fs.writeFileSync(target, content); }
   return checkCopiedAgents({ packageRoot, destination });
 }
 
+function assertAgentDestination(files) {
+  for (const { target } of files) {
+    assertDirectoryPath(path.dirname(target));
+  }
+}
+
+/**
+ * The project instructions block for the app's AGENTS.md or CLAUDE.md. It is
+ * printed, never written: project instructions belong to the app.
+ */
+export function agentsBlock(packageRoot) {
+  const reference = fs.readFileSync(path.resolve(packageRoot, 'docs/consumer-skill/references/agents-md.md'), 'utf8');
+  const block = reference.match(/<!-- [\w@/.-]+:start \S+ -->[\s\S]*?<!-- [\w@/.-]+:end -->/);
+  assert(block, 'The packaged AGENTS.md block is missing');
+  return block[0];
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
-    const usage = 'Usage: node setup-skills.mjs --copy|--check [--destination <agent-skills-directory>] [--agents <agent-definitions-directory>]';
+    const usage = 'Usage: node setup-skills.mjs --copy|--check [--destination <agent-skills-directory>] [--agents <markdown-agent-directory> | --no-agents]\n       node setup-skills.mjs --agents-block';
     const [mode, ...rest] = process.argv.slice(2);
+    if (mode === '--agents-block') {
+      assert(rest.length === 0, usage);
+      process.stdout.write(agentsBlock(fileURLToPath(new URL('../../..', import.meta.url))) + '\n');
+      process.exit(0);
+    }
     const options = {};
-    for (let index = 0; index < rest.length; index += 2) {
-      assert(['--destination', '--agents'].includes(rest[index]) && rest[index + 1] && !(rest[index] in options), usage);
-      options[rest[index]] = path.resolve(rest[index + 1]);
+    for (let index = 0; index < rest.length; index++) {
+      const flag = rest[index];
+      assert(!(flag in options), usage);
+      if (flag === '--no-agents') { options[flag] = true; continue; }
+      assert(['--destination', '--agents'].includes(flag) && rest[index + 1] && !rest[index + 1].startsWith('--'), usage);
+      options[flag] = path.resolve(rest[++index]);
     }
-    assert(['--copy', '--check'].includes(mode) && Object.keys(options).length, usage);
+    assert(['--copy', '--check'].includes(mode) && (options['--destination'] || options['--agents']) && !(options['--agents'] && options['--no-agents']), usage);
     const packageRoot = fileURLToPath(new URL('../../..', import.meta.url));
     const copy = mode === '--copy';
+    const destination = options['--destination'];
+    // `.agents/skills` is shared by Codex and Antigravity. It cannot identify
+    // a Markdown-agent host; Codex custom agents have a different TOML format.
+    const claudeSkills = destination && path.basename(destination) === 'skills' && path.basename(path.dirname(destination)) === '.claude';
+    const agentsDestination = options['--agents'] ?? (!options['--no-agents'] && claudeSkills ? path.join(path.dirname(destination), 'agents') : undefined);
+    // Validate every source and destination first: an agent conflict must not
+    // leave a newly copied skill bundle behind after reporting failure.
+    if (copy) {
+      if (destination) { consumerBundleFiles(packageRoot, destination); assertSkillDestination(destination); }
+      if (agentsDestination) assertAgentDestination(agentBundleFiles(packageRoot, agentsDestination));
+    }
     const result = {};
-    if (options['--destination']) Object.assign(result, (copy ? copyConsumerBundle : checkCopiedConsumerBundle)({ packageRoot, destination: options['--destination'] }), { destination: options['--destination'] });
-    if (options['--agents']) Object.assign(result, (copy ? copyAgents : checkCopiedAgents)({ packageRoot, destination: options['--agents'] }), { agentsDestination: options['--agents'] });
+    if (destination) Object.assign(result, (copy ? copyConsumerBundle : checkCopiedConsumerBundle)({ packageRoot, destination }), { destination });
+    if (agentsDestination) Object.assign(result, (copy ? copyAgents : checkCopiedAgents)({ packageRoot, destination: agentsDestination }), { agentsDestination });
     console.log(JSON.stringify(result, null, 2));
   } catch (error) { console.error(error.message); process.exitCode = 1; }
 }

package/docs/consumer-skills/themelia-components/SKILL.md

@@ -1,22 +1,26 @@
 ---
 name: themelia-components
-description: Use when finding or integrating themelia-react-ui components, compound parts, blocks, features or typed forms in React apps; not library maintenance.
+description: Use before writing any React UI in an app that installs themelia-react-ui, to find the component, block or feature that already covers each region, then integrate it with its exact API and typed forms; not library maintenance.
 ---
 
 # Themelia components
 
 Installed types own the API. Resolve package/version and copied-skill freshness through [installation](../../consumer-skill/references/installation.md). Set up CSS, peers and UIProvider when missing. Skills share assets.
 
+## Start from what exists
+
+Simple views are 100% Themelia owners; domain views about 70%, the rest app-owned subjects made from its parts. Read [building views](../../consumer-skill/references/building-views.md): reach order, need → owner map, coverage plan. The [catalogue](../../consumer-skill/references/catalogue.md) lists every component; read Features and Blocks before deciding something is missing.
+
 ## Find and verify
 
-Split the task into responsibilities: facts, selection, editing, collection, disclosure or navigation. Search each separately. Empty strict results do not establish missing support; inspect related suggestions and unmatched terms, then shorten the query. See [discovery](../../consumer-skill/references/discovery.md).
+Split the task into responsibilities: facts, selection, editing, collection, disclosure or navigation. Search each separately, by its domain noun (invoice, shipment, quota) as well as its control noun. Empty strict results do not establish missing support; inspect related suggestions and unmatched terms, then shorten the query. See [discovery](../../consumer-skill/references/discovery.md).
 
 ```sh
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs "expandable form sections" --limit 3
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs AccordionContent --import themelia-react-ui/base/accordion --prop keepMounted
 ```
 
-Imports keep each family's published spelling (`base/cards`, `base/buttons`, `base/chart`); a near miss reports `importResolution`. Read choose/avoid, ownership and peers for the exact export. Qualify ambiguous names. Default inspection includes relevant inherited behavior; --prop retrieves exact callbacks/slots, and installed declarations cover omitted types/overloads. Unknown defaults stay unknown. Preserve generic/discriminated contracts and prefer canonical exports over migration names.
+Imports keep each family's published spelling (`base/cards`, `base/buttons`, `base/chart`); a near miss reports `importResolution`. Read choose/avoid, ownership and peers for the exact export. Qualify ambiguous names. Default inspection includes relevant inherited behavior; --prop retrieves exact callbacks/slots, and installed declarations cover omitted types/overloads. Unknown defaults stay unknown. Preserve generic/discriminated contracts.
 
 Search task-specific subjects/workflows as well as controls: options, variant editing and attached media have dedicated owners. Before rebuilding, compare their data contract, controlled/default state, mounting, callbacks, refs and render seams. A missing prop on a convenience wrapper can exist on its public parts. A custom badge/retained field does not establish a disclosure gap. See [capability comparison](../../consumer-skill/references/custom-composition.md).
 
@@ -28,4 +32,4 @@ Search task-specific subjects/workflows as well as controls: options, variant ed
 
 Use a fitting complete feature; otherwise compose public owners. Base controls and blocks already own local interaction/accessibility. Features coordinate a complete workflow. Data, routing, permissions and translations stay app-owned; see [integration](../../consumer-skill/references/integration.md). Dialogs/drawers/confirmations use features/overlays at the app/feature boundary.
 
-Use **themelia-composition** for hierarchy and custom composites, **themelia-tokenization** for theme roles and token-backed app geometry, and **themelia-design** for data-led view specs and rendered critique. Run app checks and [review](../../consumer-skill/references/review.md); execute relevant focus, validation and failure/retry paths. Report source, inspected appearance and executed behavior separately.
+Use **themelia-composition** for hierarchy, **themelia-tokenization** for theme roles and **themelia-design** for view specs and critique. Run app checks and [review](../../consumer-skill/references/review.md); execute relevant focus, validation and failure/retry paths. Report source, inspected appearance and executed behavior separately.