themelia-react-ui 1.0.1 → 2.0.0

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

@@ -1,14 +1,46 @@
-import { surfaceParts, surfaceForwarders, paddingClass, paddingProperty, utility } from './surface-policy.mjs';
+import { surfaceParts, surfaceForwarders, paddingClass, paddingProperty, utility, attenuatedFocusRing, sharedCornerParts, displayNames, nativeDisplayNames, marginProperty, radiusProperty, replacesSharedRadius, cornerRole, addsCopyMargin } from './surface-policy.mjs';
 
-const controlNames = /^(?:Base)?(?:Button|ButtonLink|IconButton)$|^(Input|InputGroupInput|Textarea|SelectTrigger|ComboboxTrigger)$/;
+const controlNames = /^(?:Base)?(?:Button|ButtonLink|IconButton)$|^(Input|InputGroup|InputGroupInput|InputGroupTextarea|Textarea|PasswordInput|Select|SelectTrigger|ComboboxInput|ComboboxInputTrigger|ComboboxTrigger)$/;
 const controlFamilies = new Set(['buttons', 'text-inputs', 'choice-inputs', 'combobox']);
 const fixedControlClass = /^(?:h|min-h|size|p[xytrblse]?)-|^rounded-(?:xs|sm|md|lg|xl|[2-9]xl|\[)|^text-(?:xs|sm|base|lg|xl|[2-9]xl|\[(?:length:|[\d.]+(?:px|rem|em)))|^(?:font|leading|tracking)-/;
-const controlStyle = /^(height|minHeight|fontSize|fontWeight|lineHeight|letterSpacing|borderRadius)$/;
+const controlStyle = /^(height|minHeight|fontSize|fontWeight|fontFamily|lineHeight|letterSpacing|borderRadius)$/;
+const fixedTextClass = /^text-(?:xs|sm|base|lg|xl|[2-9]xl|\[(?:length:|[\d.]+(?:px|rem|em)))|^(?:font|leading|tracking)-/;
+const textStyle = /^(fontSize|fontWeight|fontFamily|lineHeight|letterSpacing)$/;
+const smallPeerGaps = new Set(['none', 'normal', 'dense', '2xs', 'xs', 'sm', 'md']);
+const structureDefaults = { Stack: 'md', Grid: 'xl', AdaptiveGrid: 'xl' };
+const breakpoints = ['base', 'sm', 'md', 'lg', 'xl', '2xl'];
+const paletteHues = 'slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|mauve|olive|mist|taupe';
+const rawPaletteClass = new RegExp(`^!?(?:bg|text|border(?:-[xytrblse])?|ring|ring-offset|outline|fill|stroke|from|via|to|divide|decoration|caret|accent|placeholder)-(?:(?:${paletteHues})-(?:50|[1-9]00|950)|black|white)(?:/\\d{1,3})?$`);
+const overlayOwners = ['ActionDialog', 'ConfirmDialog', 'ActionDrawer'];
+
+/** Bind this source only; never resolve imports, read libraries or run app code. */
+export function sourceBindings(source, ts) {
+  const options = { noResolve: true, noLib: true, allowJs: true, jsx: ts.JsxEmit.Preserve };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = filename => filename === source.fileName ? source : undefined;
+  const checker = ts.createProgram([source.fileName], options, host).getTypeChecker();
+  return node => {
+    if (!node) return undefined;
+    if (ts.isIdentifier(node) && ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node) return checker.getShorthandAssignmentValueSymbol(node.parent);
+    return checker.getSymbolAtLocation(node);
+  };
+}
 
 /** Small static review: TypeScript is supplied by the app, never a runtime peer. */
+const overlayRemedy = 'Use ActionDialog, ConfirmDialog or ActionDrawer with useOverlayVisibility from themelia-react-ui/features/overlays; they own focus, dismissal, pending state and portal theming.';
+const modalLibrary = /^(?:@radix-ui\/react-(?:alert-)?dialog|react-modal|vaul|@base-ui(?:-components)?\/react\/(?:alert-)?dialog)$/;
+const modalExports = { '@headlessui/react': /^(?:Dialog|DialogPanel)$/, 'react-aria-components': /^(?:Dialog|Modal|ModalOverlay)$/ };
+const importsModal = (node, ts) => {
+  const specifier = node.moduleSpecifier.text;
+  if (modalLibrary.test(specifier)) return true;
+  const names = node.importClause?.namedBindings;
+  return !!modalExports[specifier] && !!names && ts.isNamedImports(names) && names.elements.some(item => modalExports[specifier].test((item.propertyName ?? item.name).text));
+};
+
 export function analyzeComposition(text, { filename, index, ts }) {
   const kind = /\.jsx?$/.test(filename) ? ts.ScriptKind.JSX : filename.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
   const source = ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true, kind);
+  const symbolFor = sourceBindings(source, ts);
   const families = new Map(index.families.map(owner => [owner.import, owner]));
   const bindings = new Map();
   const namespaces = new Map();
@@ -33,7 +65,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
   const resolve = (node, visiting = new Set()) => {
     if (!node || visiting.has(node)) return undefined;
     visiting.add(node);
-    if (ts.isIdentifier(node)) return resolve(declarations.get(node.text), visiting);
+    if (ts.isIdentifier(node)) return resolve(declarations.get(symbolFor(node)), visiting);
     if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return resolve(node.expression, visiting);
     return node;
   };
@@ -60,6 +92,20 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (!node || visited.has(node)) { if (expression) unknown(expression); return []; }
     visited.add(node);
     if (ts.isStringLiteralLike(node)) return [node.text];
+    if (ts.isTemplateExpression(node)) {
+      // Keep complete static class tokens. A token split by a dynamic span is
+      // unresolved rather than an invented class from one of its fragments.
+      const chunks = [node.head.text];
+      for (const span of node.templateSpans) {
+        const resolved = resolve(span.expression);
+        if (resolved && (ts.isStringLiteralLike(resolved) || ts.isNumericLiteral(resolved))) chunks[chunks.length - 1] += resolved.text + span.literal.text;
+        else { unknown(span.expression); chunks.push(span.literal.text); }
+      }
+      return chunks.map((chunk, index) => {
+        const value = index > 0 ? chunk.replace(/^\S*/, '') : chunk;
+        return index < chunks.length - 1 ? value.replace(/\S*$/, '') : value;
+      });
+    }
     if (ts.isConditionalExpression(node)) return [...classStrings(node.whenTrue, visited), ...classStrings(node.whenFalse, visited)];
     if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return classStrings(node.right, visited);
     if (ts.isArrayLiteralExpression(node)) return node.elements.flatMap(item => classStrings(item, visited));
@@ -83,12 +129,14 @@ export function analyzeComposition(text, { filename, index, ts }) {
     for (const item of elements) {
       const symbol = (item.propertyName ?? item.name).text;
       if (!family.symbols.includes(symbol)) add(item, 'public-symbol', 'error', `${specifier} does not export ${symbol}; inspect its declaration.`);
-      if (ts.isImportDeclaration(node)) bindings.set(item.name.text, { symbol, import: specifier });
+      else if (family.deprecated?.[symbol]) add(item, 'deprecated-owner', 'warning', `${symbol} is deprecated: ${family.deprecated[symbol]}`);
+      if (ts.isImportDeclaration(node)) bindings.set(symbolFor(item.name), { symbol, import: specifier });
     }
-    if (names && ts.isNamespaceImport(names)) namespaces.set(names.name.text, specifier);
+    if (names && ts.isNamespaceImport(names)) namespaces.set(symbolFor(names.name), specifier);
   }
   function gather(node) {
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) declarations.set(node.name.text, node.initializer);
+    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.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);
@@ -97,10 +145,11 @@ export function analyzeComposition(text, { filename, index, ts }) {
   gather(source);
   for (const diagnostic of source.parseDiagnostics) add(source, 'syntax', 'error', ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
   const ownerFor = tag => {
-    if (bindings.has(tag)) return bindings.get(tag);
-    const [namespace, symbol] = tag.split('.');
-    const specifier = namespaces.get(namespace);
-    return specifier && symbol ? { symbol, import: specifier } : undefined;
+    if (ts.isIdentifier(tag)) return bindings.get(symbolFor(tag));
+    if (ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression)) {
+      const specifier = namespaces.get(symbolFor(tag.expression));
+      return specifier ? { symbol: tag.name.text, import: specifier } : undefined;
+    }
   };
   const attributes = node => node.attributes.properties.flatMap(attribute => {
     if (ts.isJsxSpreadAttribute(attribute)) return properties(attribute.expression);
@@ -108,6 +157,151 @@ 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 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';
+    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.
+  const contentElements = element => {
+    const found = [];
+    function collect(child) {
+      if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
+        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 (ts.isJsxElement(child)) child.children.forEach(collect);
+        return;
+      }
+      if (ts.isJsxFragment(child)) child.children.forEach(collect);
+      else if (ts.isJsxExpression(child) && child.expression) { const resolved = resolve(child.expression); if (resolved) collect(resolved); }
+    }
+    if (ts.isJsxElement(element.parent)) element.parent.children.forEach(collect);
+    return found;
+  };
+  const renderedText = element => ts.isJsxElement(element) ? element.children.map(child => ts.isJsxText(child) ? child.text : ts.isJsxExpression(child) ? literal(child.expression) ?? '' : '').join(' ').trim() : '';
+  const slotBadge = expression => {
+    const node = resolve(expression);
+    if (!node) return false;
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const owner = ownerFor(opening.tagName);
+      if (isOwner(owner, 'base/badge', ['Badge'])) return true;
+      if (owner?.import === `${index.package}/base/buttons` || /^(button|a)$/.test(opening.tagName.getText(source))) return false;
+      if (!/^(div|span)$/.test(opening.tagName.getText(source)) && !isOwner(owner, 'base/structure', ['Stack', 'Grid'])) return false;
+      return ts.isJsxElement(node) && node.children.some(slotBadge);
+    }
+    if (ts.isJsxFragment(node)) return node.children.some(slotBadge);
+    if (ts.isJsxExpression(node)) return slotBadge(node.expression);
+    return false;
+  };
+  // Buttons placed directly, conditionally or inside a passive row of a page
+  // header's actions region. Unknown local components are custom controls.
+  const commandButtons = expression => {
+    const node = resolve(expression);
+    if (!node) return false;
+    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']) || 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);
+    }
+    if (ts.isJsxFragment(node)) return node.children.some(commandButtons);
+    if (ts.isJsxExpression(node)) return commandButtons(node.expression);
+    if (ts.isConditionalExpression(node)) return commandButtons(node.whenTrue) || commandButtons(node.whenFalse);
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return commandButtons(node.right);
+    return false;
+  };
+  // Static class tokens only; dynamic parts are skipped rather than reported.
+  const staticClasses = (expression, visited = new Set()) => {
+    const node = resolve(expression);
+    if (!node || visited.has(node)) return [];
+    visited.add(node);
+    if (ts.isStringLiteralLike(node)) return [node.text];
+    if (ts.isTemplateExpression(node)) return [node.head.text, ...node.templateSpans.map(span => span.literal.text)];
+    if (ts.isConditionalExpression(node)) return [...staticClasses(node.whenTrue, visited), ...staticClasses(node.whenFalse, visited)];
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return staticClasses(node.right, visited);
+    if (ts.isArrayLiteralExpression(node)) return node.elements.flatMap(item => staticClasses(item, visited));
+    if (ts.isCallExpression(node) && /^(cn|clsx|classNames|twMerge)$/.test(node.expression.getText(source))) return node.arguments.flatMap(item => staticClasses(item, visited));
+    return [];
+  };
+  const classTokens = opening => {
+    const attribute = opening.attributes.properties.find(property => ts.isJsxAttribute(property) && property.name.getText(source) === 'className');
+    if (!attribute?.initializer) return [];
+    const expression = ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
+    // Template chunks may split a token; keep only complete-looking words.
+    return staticClasses(expression).flatMap(value => value.split(/\s+/)).filter(token => token && !token.startsWith('-') && !token.endsWith('-')).map(utility);
+  };
+  // 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 props = new Map(attributes(opening));
+    const style = props.has('buttonStyle') ? literal(props.get('buttonStyle')) : 'solid';
+    return literal(props.get('tone')) === 'primary' && style === 'solid';
+  };
+  // Overlays are separate surfaces with their own primary command.
+  const solidPrimaryCount = root => {
+    let count = 0;
+    const walk = child => {
+      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++;
+      }
+      ts.forEachChild(child, walk);
+    };
+    ts.forEachChild(root, walk);
+    return count;
+  };
+  const peerCards = element => {
+    if (!ts.isJsxElement(element.parent)) return new Set();
+    const cards = [];
+    function collect(child) {
+      if (ts.isJsxFragment(child)) { child.children.forEach(collect); return; }
+      const opening = ts.isJsxElement(child) ? child.openingElement : ts.isJsxSelfClosingElement(child) ? child : undefined;
+      if (!opening) return;
+      const owner = ownerFor(opening.tagName);
+      if (framedOwner(owner, new Map(attributes(opening)))) cards.push(opening);
+      else if (owner?.symbol === 'GridCell' && owner.import === `${index.package}/base/structure` && ts.isJsxElement(child)) child.children.forEach(collect);
+    }
+    element.parent.children.forEach(collect);
+    return new Set(cards);
+  };
+  const gapEntries = (expression, fallback) => {
+    if (!expression) return { base: fallback };
+    const node = resolve(expression);
+    if (node && ts.isStringLiteralLike(node)) return { base: node.text };
+    if (node && ts.isObjectLiteralExpression(node)) return { base: fallback, ...Object.fromEntries(properties(node).filter(([key]) => breakpoints.includes(key)).map(([key, value]) => {
+      const gap = literal(value);
+      if (gap === undefined && value) unknown(value);
+      return [key, gap];
+    })) };
+    if (node && node.kind === ts.SyntaxKind.NullKeyword || ts.isIdentifier(expression) && expression.text === 'undefined' && !symbolFor(expression)) return { base: fallback };
+    unknown(expression);
+    return { base: undefined };
+  };
+  const smallGap = (props, symbol, unknownProps) => {
+    // Unknown spread props may replace a missing gap. Report them as unresolved
+    // instead of treating the live default as a proven effective value.
+    if (!props.has('gap') && unknownProps) return false;
+    const gaps = gapEntries(props.get('gap'), structureDefaults[symbol]);
+    const rows = symbol === 'Stack' ? {} : gapEntries(props.get('rowGap'));
+    const columns = symbol === 'Stack' ? {} : gapEntries(props.get('columnGap'));
+    let gap; let row; let column;
+    return breakpoints.some(breakpoint => {
+      if (Object.hasOwn(gaps, breakpoint)) gap = gaps[breakpoint];
+      if (Object.hasOwn(rows, breakpoint)) row = rows[breakpoint];
+      if (Object.hasOwn(columns, breakpoint)) column = columns[breakpoint];
+      return smallPeerGaps.has(row ?? gap) || smallPeerGaps.has(column ?? gap);
+    });
+  };
   function visit(node, parents = []) {
     if (ts.isJsxElement(node)) {
       const element = node.openingElement;
@@ -121,34 +315,93 @@ export function analyzeComposition(text, { filename, index, ts }) {
     ts.forEachChild(node, child => visit(child, parents));
   }
   function inspect(node, parents) {
-    const owner = ownerFor(node.tagName.getText(source));
-    if (!owner) return;
+    const owner = ownerFor(node.tagName);
+    if (classTokens(node).some(token => rawPaletteClass.test(token))) add(node, 'raw-palette-color', 'warning', 'Raw palette colors bypass the theme and dark mode. Use semantic classes such as bg-primary, bg-muted, text-muted-foreground, border-border or a status tone (text-destructive, bg-success/10).');
+    if (!owner) {
+      const tag = node.tagName.getText(source);
+      if (tag === 'button') add(node, 'raw-button', 'warning', 'Use Button or TextButton from themelia-react-ui/base/buttons: they own size, focus ring, loading and disabled states.');
+      if (/^h[1-6]$/.test(tag)) add(node, 'raw-heading', 'warning', 'Use Heading from themelia-react-ui/typography (tag for the level, size for emphasis): it resets native margins and keeps the shared heading scale.');
+      const nativeProps = new Map(attributes(node));
+      const modalRole = /^(?:dialog|alertdialog)$/.test(literal(nativeProps.get('role')) ?? '') || nativeProps.has('aria-modal');
+      const scrim = classTokens(node).includes('fixed') && classTokens(node).includes('inset-0');
+      if (modalRole || scrim) add(node, 'raw-overlay-primitive', 'warning', `A hand-rolled ${modalRole ? 'dialog' : 'full-screen layer'} must own focus, dismissal, pending state and theming itself. ${overlayRemedy}`);
+      if (/^(?:input|textarea)$/.test(node.tagName.getText(source))) {
+        const props = new Map(attributes(node));
+        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'inner'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-inner; change the global theme root, not per-field corners.');
+        if (props.has('style') && properties(props.get('style')).some(([name])=>radiusProperty.test(name))) add(node,'shared-radius','error','Native editable corners belong to the global radius root, not inline styles.');
+      }
+      if (nativeDisplayNames.test(node.tagName.getText(source))) {
+        const props = new Map(attributes(node));
+        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(addsCopyMargin)) add(node,'copy-margin','error','Display copy is margin-free; use the surrounding structure for copy gaps.');
+        if (props.has('style') && properties(props.get('style')).some(([name,value])=>marginProperty.test(name)&&!/^['"]?0(?:px|rem|em|%)?['"]?$/.test(resolve(value)?.getText(source)??''))) add(node,'copy-margin','error','Display copy is margin-free; use the surrounding structure for copy gaps.');
+      }
+      return;
+    }
     if (!families.get(owner.import)?.symbols.includes(owner.symbol)) {
       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;
     const family = owner.import.split('/base/')[1];
     const anatomy = surfaceParts[family]?.test(owner.symbol);
     const forwarder = surfaceForwarders[family] === owner.symbol;
     const control = controlFamilies.has(family) && controlNames.test(owner.symbol);
-    for (const name of ['className', 'contentClassName']) {
+    const sharedCorners = sharedCornerParts[family]?.test(owner.symbol);
+    const display = owner.import === `${index.package}/typography` && displayNames.test(owner.symbol);
+    const fixedText = owner.import === `${index.package}/typography` && owner.symbol === 'DisplayLabel' || family === 'badge' && owner.symbol === 'Badge';
+    const badge = family === 'badge' && owner.symbol === 'Badge';
+    for (const name of ['className', 'headerClassName', 'contentClassName', 'footerClassName', 'subHeadingClassName']) {
       if (!props.has(name)) continue;
       const classes = classStrings(props.get(name)).flatMap(value => value.split(/\s+/)).map(utility);
       if ((anatomy || forwarder && name === 'contentClassName') && classes.some(value => paddingClass.test(value))) add(node, 'surface-padding', 'error', `${owner.symbol}: use inset/type/density and public regions; padding overrides replace owned anatomy.`);
       if (control && name === 'className' && classes.some(value => fixedControlClass.test(value))) add(node, 'control-anatomy', 'error', `${owner.symbol}: use its size/variant props; preserve shared control height, inset, corners and typography.`);
+      if ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'inner' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-radius; controls and collection rows use bounded rounded-inner. Preserve the owning role and joined-edge resets.`);
+      if (display && classes.some(addsCopyMargin)) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; use textGap on the headed owner or gap on Stack/Grid.`);
+      if ((control || family === 'buttons' && owner.symbol === 'TextButton') && name === 'className' && classes.some(attenuatedFocusRing)) add(node, 'focus-ring-contrast', 'error', `${owner.symbol}: keep the shared ring-ring/sidebar-ring focus color at full strength; numeric opacity weakens its tested contrast.`);
+      if (fixedText && name === 'className' && classes.some(value => fixedTextClass.test(value) || badge && /^rounded(?:-|$)/.test(value))) add(node, 'fixed-text-role', 'error', `${owner.symbol}: preserve its shared typography${badge ? ' and radius' : ''}; use its public variants and className for placement.`);
     }
-    if (props.has('style')) for (const [name] of properties(props.get('style'))) {
+    if (props.has('style')) for (const [name,value] of properties(props.get('style'))) {
       if (anatomy && paddingProperty.test(name)) add(node, 'surface-padding', 'error', `${owner.symbol}: ${name} replaces the region inset; use its public surface props.`);
       if (control && (paddingProperty.test(name) || controlStyle.test(name))) add(node, 'control-anatomy', 'error', `${owner.symbol}: ${name} belongs to shared control geometry/typography.`);
+      if ((control || sharedCorners) && radiusProperty.test(name)) add(node,'shared-radius','error',`${owner.symbol}: corners follow the global radius theme root, not inline styles.`);
+      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 (['SmartCard', 'ContentBlock'].includes(owner.symbol)) add(node, 'deprecated-owner', 'warning', `${owner.symbol} is a migration owner; prefer Card for new compositions.`);
-    const framed = ['Card', 'SmartCard', 'ContentBlock', 'DataTable', 'DataView'].includes(owner.symbol) && literal(props.get('surface')) !== 'flat';
+    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.`);
+    const facts = 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'])) {
+      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.');
+      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 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 (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.');
+    const peers = parents.findLast(parent => parent.structure);
+    if (framed && (!props.has('surface') || literal(props.get('surface')) === 'framed') && peers?.cards.size > 1 && peers.cards.has(node) && peers.smallGap) add(node, 'card-peer-gap', 'warning', 'Small peer gaps can be consumed by framed Card rings. Use lg/xl for independent surfaces and inspect visible edge clearance; tighter grouping needs an intentional surface policy.');
     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 headerActions = pageOwner && owner.symbol === 'Page' ? new Map(header).get('actions') : pageOwner && owner.symbol === 'PageHeader' ? props.get('actions') : 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 (headerActions && commandButtons(headerActions)) add(node, 'page-command-roles', 'warning', `${owner.symbol}: buttons in the header actions region choose their own emphasis, size and overflow. Pass commands as primaryAction (one) and ordered secondaryActions; keep actions for non-command controls.`);
     const title = literal(props.get('title')) ?? literal(new Map(header).get('title'));
     if (title && parents.some(parent => parent.title === title)) add(node, 'duplicate-heading', 'warning', `The heading "${title}" repeats its ancestor. Keep one route/subject title unless a distinct task warrants repetition.`);
-    return { framed, title };
+    const structure = owner.import === `${index.package}/base/structure` && Object.hasOwn(structureDefaults, owner.symbol);
+    return { framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
   }
   visit(source);
   return { findings, unresolved };

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

@@ -3,6 +3,10 @@ const requireFormat = (condition, message) => { if (!condition) throw new Error(
 const stringList = value => Array.isArray(value) && value.every(item => typeof item === 'string');
 const text = value => typeof value === 'string' && value.trim().length > 0;
 const normalized = value => value.toLowerCase();
+const words = value => value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z])([A-Z][a-z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+const symbolKey = value => words(value).join('');
+const searchable = value => words(value).join(' ');
+const containsTerms = (value, terms) => { const tokens = new Set(words(value)); return terms.every(term => tokens.has(term)); };
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 
 export function validateIndex(index) {
@@ -17,7 +21,18 @@ export function validateIndex(index) {
     requireFormat(text(family.declaration) && /^dist\/[\w./-]+\.d\.ts$/.test(family.declaration) && !family.declaration.split('/').includes('..'), `invalid declaration ${family.declaration}`);
     requireFormat(layers.includes(family.layer) && text(family.responsibility), `missing layer/responsibility for ${family.import}`);
     for (const field of ['symbols', 'jobs', 'tags', 'aliases', 'sections', 'optionalPeers']) requireFormat(stringList(family[field]), `invalid ${field} for ${family.import}`);
+    if (family.deprecated !== undefined) requireFormat(family.deprecated !== null && typeof family.deprecated === 'object' && !Array.isArray(family.deprecated) && Object.entries(family.deprecated).every(([symbol, note]) => family.symbols.includes(symbol) && text(note)), `invalid deprecated symbols for ${family.import}`);
+    if (family.references !== undefined) requireFormat(stringList(family.references) && family.references.every(file => /^references\/[\w/-]+\.md(?:#[\w-]+)?$/.test(file) && !file.split('/').includes('..')), `invalid focused references for ${family.import}`);
     requireFormat(family.optionalPeers.every(peer => index.peers?.some(owner => owner.name === peer && owner.optional)), `unknown optional peer for ${family.import}`);
+    if (family.recipes !== undefined) {
+      requireFormat(Array.isArray(family.recipes), `invalid recipes for ${family.import}`);
+      for (const recipe of family.recipes) {
+        requireFormat(text(recipe?.file) && /^examples\/[\w/-]+\.tsx$/.test(recipe.file) && !recipe.file.split('/').includes('..'), 'invalid recipe file');
+        requireFormat(stringList(recipe.exports) && recipe.exports.length > 0 && stringList(recipe.symbols) && recipe.symbols.every(symbol => family.symbols.includes(symbol)), `unknown recipe symbol for ${family.import}`);
+        requireFormat(stringList(recipe.references) && recipe.references.every(file => /^references\/[\w/-]+\.md(?:#[\w-]+)?$/.test(file) && !file.split('/').includes('..')), 'invalid recipe references');
+        if (recipe.optionalPeers !== undefined) requireFormat(stringList(recipe.optionalPeers) && recipe.optionalPeers.every(peer => index.peers?.some(owner => owner.name === peer && owner.optional)), 'invalid recipe optional peers');
+      }
+    }
     requireFormat(Array.isArray(family.guidance), `invalid guidance for ${family.import}`);
     for (const guide of family.guidance) {
       requireFormat(text(guide?.title) && typeof guide.description === 'string' && typeof guide.section === 'string', 'invalid guidance title/description/section');
@@ -56,28 +71,73 @@ export function parseArguments(args) {
   return { query, ...options };
 }
 
-const guideText = guide => normalized([guide.title, guide.description, ...Object.values(guide.browse), ...guide.jobs, ...guide.tags, ...guide.aliases, ...guide.chooseWhen, ...guide.appOwned, ...guide.sections.flatMap(section => [section.title, ...section.symbols])].join(' '));
+const guideText = guide => searchable([guide.title, guide.description, ...Object.values(guide.browse), ...guide.jobs, ...guide.tags, ...guide.aliases, ...guide.chooseWhen, ...guide.appOwned, ...guide.sections.flatMap(section => [section.title, ...section.symbols])].join(' '));
+const guideSymbols = (guide, family) => [...new Set(guide.sections.flatMap(section => section.symbols))].filter(symbol => family.symbols.includes(symbol));
+
+function relevantGuidance(family, needle, terms, matchedSymbols, exactImport) {
+  const ranked = family.guidance.map(guide => {
+    const haystack = guideText(guide);
+    const count = terms.filter(term => containsTerms(haystack, [term])).length;
+    const symbol = matchedSymbols.some(value => guideSymbols(guide, family).includes(value));
+    const alias = guide.aliases.some(value => normalized(value) === needle);
+    const complete = count === terms.length;
+    const score = Number(alias) * 10000 + Number(symbol) * 1000 + Number(complete) * 100 + count;
+    return { guide, score, symbol, alias, complete };
+  }).sort((a, b) => b.score - a.score || Number(guideSymbols(b.guide, family).length > 0) - Number(guideSymbols(a.guide, family).length > 0) || compare(a.guide.title, b.guide.title));
+  // Exact owner and curated task matches supply their own narrow reading path.
+  // Generic intent can still combine terms across fields/family guidance.
+  const selected = ranked.filter(item => ranked.some(item => item.alias) ? item.alias : matchedSymbols.length ? item.symbol : ranked.some(item => item.complete) ? item.complete : item.score > 0);
+  return (selected.length || !exactImport ? selected : ranked).slice(0, 3).map(item => item.guide);
+}
 
 export function findComponents(index, { query, layer = null, limit = 5 }) {
   validateIndex(index);
   const needle = normalized(query);
-  const terms = [...new Set(needle.split(/\s+/).filter(Boolean))];
+  const terms = [...new Set(words(query))];
+  const key = symbolKey(query);
+  // Cased API names and explicit imports request a precise contract. Ordinary
+  // nouns such as table/empty remain task searches with richer alternatives.
+  const exactOwners = index.families.filter(family => (!layer || layer === family.layer) && (normalized(family.import) === needle || family.symbols.includes(query.trim())));
   const ranked = [];
   for (const family of index.families) {
     if (layer && layer !== family.layer) continue;
+    if (exactOwners.length && !exactOwners.includes(family)) continue;
     const exactImport = normalized(family.import) === needle;
-    const matchedSymbols = family.symbols.filter(symbol => normalized(symbol) === needle);
-    const haystack = normalized([family.import, family.responsibility, ...family.symbols, ...family.jobs, ...family.tags, ...family.aliases, ...family.sections, ...family.guidance.map(guideText)].join(' '));
+    const matchedSymbols = family.symbols.filter(symbol => symbolKey(symbol) === key);
+    const documented = new Set(family.guidance.flatMap(guide => guideSymbols(guide, family)));
+    const focusedSymbols = [...documented].filter(symbol => containsTerms(symbol, terms));
+    const haystack = searchable([family.import, family.responsibility, ...documented, ...family.jobs, ...family.tags, ...family.aliases, ...family.sections, ...family.guidance.map(guideText)].join(' '));
     // AND matching prevents a familiar term from inventing results for an
     // otherwise unknown query. Avoidance/alternatives do not recommend owners.
-    if (!exactImport && !matchedSymbols.length && !terms.every(term => haystack.includes(term))) continue;
+    if (!exactImport && !matchedSymbols.length && !containsTerms(haystack, terms)) continue;
     // A dedicated, documented owner precedes an aggregate re-export of the
     // same symbol. Explicit import queries still select the requested family.
-    const documentedSymbol = family.guidance.some(guide => guide.sections.some(section => section.symbols.some(symbol => normalized(symbol) === needle)));
+    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) : exactIntent ? 8000 : terms.reduce((sum, term) => sum + (family.guidance.some(guide => normalized(guide.title).includes(term)) ? 20 : family.tags.some(tag => normalized(tag).includes(term)) ? 10 : 1), 0);
-    const guidance = family.guidance.map(guide => ({ guide, score: terms.filter(term => guideText(guide).includes(term)).length })).sort((a, b) => b.score - a.score || compare(a.guide.title, b.guide.title)).slice(0, 3).map(({ guide }) => guide);
-    ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', matchedSymbols, guidance });
+    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);
+    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))])];
+    // Intent searches recommend current names only. Exact queries keep the
+    // requested symbol; either way the result reports deprecated candidates.
+    const lifecycle = family.deprecated ?? {};
+    const relevantSymbols = exactImport || matchedSymbols.length ? candidateSymbols : candidateSymbols.filter(symbol => !Object.hasOwn(lifecycle, symbol));
+    const deprecated = Object.fromEntries(candidateSymbols.filter(symbol => Object.hasOwn(lifecycle, symbol)).map(symbol => [symbol, lifecycle[symbol]]));
+    const candidates = (family.recipes ?? []).filter(recipe => recipe.symbols.some(symbol => relevantSymbols.includes(symbol)));
+    const recipeText = recipe => normalized([recipe.file, ...recipe.exports, ...recipe.references].join(' ')).replace(/[-/#]/g, ' ');
+    const taskRecipes = matchedSymbols.length || exactImport ? [] : candidates.filter(recipe => terms.every(term => recipeText(recipe).includes(term)));
+    // Retain related task synonyms without routing through an unrelated alias
+    // on the same broad family (for example, website versus main/aside layout).
+    const aliases = guidance.flatMap(guide => guide.aliases.filter(alias => terms.some(term => containsTerms(alias, [term]))).map(alias => normalized(alias).split(/\s+/)));
+    const aliasRecipes = matchedSymbols.length || exactImport ? [] : candidates.filter(recipe => aliases.some(intent => intent.every(term => recipeText(recipe).includes(term))));
+    const recipes = taskRecipes.length ? taskRecipes : aliasRecipes.length ? aliasRecipes : candidates;
+    const nextReads = {
+      declaration: family.declaration,
+      references: [...new Set([...(family.references ?? []), ...recipes.flatMap(recipe => recipe.references)])].sort(compare),
+      examples: recipes.map(({ file, exports, symbols, optionalPeers = [] }) => ({ file, exports, symbols: symbols.filter(symbol => relevantSymbols.includes(symbol)), optionalPeers })),
+    };
+    ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', matchedSymbols, relevantSymbols, ...(Object.keys(deprecated).length ? { deprecated } : {}), nextReads, guidance });
   }
   ranked.sort((a, b) => b.score - a.score || compare(a.import, b.import));
   return { package: index.package, version: index.version, query, layer, limit, total: ranked.length, results: ranked.slice(0, limit) };

package/docs/consumer-skill/scripts/pin-button-defaults.mjs

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { sourceBindings } from './composition-policy.mjs';
+
+// An untoned Button now renders as the secondary outline, and a Button with a
+// tone but no buttonStyle keeps that tone's solid treatment. Writing the old
+// default tone onto untoned Buttons therefore keeps an existing screen's look.
+// It edits only with --write; otherwise it reports what it would change.
+// --solid-only pins only Buttons that also set no buttonStyle, so untoned
+// outline and ghost Buttons (often brand-coloured by accident) turn neutral.
+const usage = 'Usage: pin-button-defaults.mjs [--write] [--solid-only] [--tone=primary] [--source-root=<dir>] <files or directories>';
+const owners = new Set(['Button', 'BaseButton', 'BaseButtonLink']);
+const packageImports = new Set(['themelia-react-ui', 'themelia-react-ui/base/buttons']);
+
+export function pinButtonDefaults(text, { filename, ts, tone = 'primary', solidOnly = false, sourceRoot }) {
+  const kind = /\.jsx?$/.test(filename) ? ts.ScriptKind.JSX : filename.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const source = ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true, kind);
+  const symbolFor = sourceBindings(source, ts);
+  // Library maintainers pass --source-root so relative imports of the buttons family count too.
+  const buttonsDir = sourceRoot && path.resolve(sourceRoot, 'components/base/buttons');
+  const isButtonsImport = specifier => packageImports.has(specifier)
+    || (!!buttonsDir && specifier.startsWith('.') && `${path.resolve(path.dirname(filename), specifier)}/`.startsWith(`${buttonsDir}/`));
+  const named = new Set();
+  const namespaces = new Set();
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !isButtonsImport(statement.moduleSpecifier.text)) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) namespaces.add(symbolFor(bindings.name));
+    if (bindings && ts.isNamedImports(bindings)) for (const item of bindings.elements) {
+      if (!item.isTypeOnly && owners.has((item.propertyName ?? item.name).text)) named.add(symbolFor(item.name));
+    }
+  }
+  const isOwner = tag => (ts.isIdentifier(tag) && named.has(symbolFor(tag)))
+    || (ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression) && namespaces.has(symbolFor(tag.expression)) && owners.has(tag.name.text));
+  const edits = [];
+  const pinned = [];
+  const unresolved = [];
+  const line = node => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+  const visit = node => {
+    if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && isOwner(node.tagName)) {
+      const props = node.attributes.properties;
+      const has = name => props.some(attribute => ts.isJsxAttribute(attribute) && attribute.name.getText(source) === name);
+      const toned = has('tone') || (solidOnly && has('buttonStyle'));
+      if (!toned && props.some(ts.isJsxSpreadAttribute)) {
+        // A spread may already carry tone; leave it to review.
+        unresolved.push({ file: filename, line: line(node) });
+      } else if (!toned) {
+        edits.push({ at: (node.typeArguments ?? node.tagName).end, text: ` tone="${tone}"` });
+        pinned.push({ file: filename, line: line(node), tone });
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  let output = text;
+  for (const edit of edits.sort((a, b) => b.at - a.at)) output = output.slice(0, edit.at) + edit.text + output.slice(edit.at);
+  return { output, pinned, unresolved };
+}
+
+function collect(target, files) {
+  const info = fs.lstatSync(target);
+  if (info.isSymbolicLink()) throw new Error(`Use a real source path instead of a symlink: ${target}`);
+  if (info.isDirectory()) {
+    for (const entry of fs.readdirSync(target).sort()) if (!['node_modules', '.git', 'dist', 'build'].includes(entry)) collect(path.join(target, entry), files);
+  } else if (/\.[jt]sx?$/.test(target) && !/\.d\.ts$/.test(target)) files.add(path.resolve(target));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try {
+    const args = process.argv.slice(2);
+    const option = name => args.find(arg => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+    const targets = args.filter(arg => !arg.startsWith('--'));
+    const unknown = args.filter(arg => arg.startsWith('--') && !/^--(?:write|solid-only|tone=.+|source-root=.+)$/.test(arg));
+    if (!targets.length || unknown.length) throw new Error(unknown.length ? `Unknown option: ${unknown.join(', ')}\n${usage}` : usage);
+    const ts = createRequire(path.join(process.cwd(), 'package.json'))('typescript');
+    const files = new Set();
+    targets.forEach(target => collect(target, files));
+    if (!files.size) throw new Error('No supported source files found in the supplied paths.');
+    const write = args.includes('--write');
+    const sourceRoot = option('source-root') && path.resolve(option('source-root'));
+    const results = [...files].sort().map(filename => {
+      const text = fs.readFileSync(filename, 'utf8');
+      const result = pinButtonDefaults(text, { filename, ts, tone: option('tone'), solidOnly: args.includes('--solid-only'), sourceRoot });
+      if (write && result.output !== text) fs.writeFileSync(filename, result.output);
+      return result;
+    });
+    const pinned = results.flatMap(result => result.pinned);
+    process.stdout.write(JSON.stringify({ mode: write ? 'write' : 'dry-run', files: files.size, pinned: pinned.length, changedFiles: new Set(pinned.map(item => item.file)).size, unresolved: results.flatMap(result => result.unresolved), details: pinned }, null, 2) + '\n');
+  } catch (error) {
+    process.stderr.write(`pin-button-defaults: ${error.message}\nRun from the consumer app with its TypeScript development dependency installed.\n`);
+    process.exitCode = 1;
+  }
+}