themelia-react-ui 1.0.2 → 2.0.1

package/docs/consumer-skill/references/review.md

@@ -1,7 +1,7 @@
 # Composition review and checks
 
-Use after selecting owners, or when auditing a screen. Read only the relevant
-workflow/declarations; this is a review aid, not a new design system.
+Use after selecting owners, when auditing a screen, and before handing back UI
+work. Read only the relevant workflow/declarations; this is not a new design system.
 
 ## Review the task and hierarchy
 
@@ -19,9 +19,28 @@ workflow/declarations; this is a review aid, not a new design system.
   empty/missing values and narrow parent width? Zero and unavailable differ.
 
 These criteria allow different product layouts. Do not impose a universal card
-count, row-line limit, primary button count or one-column form rule.
+count, row-line limit or one-column form rule. Emphasis is the exception: keep
+one solid primary command per page or surface, so the next action stays obvious.
 
-## Optional source checker
+## Done means
+
+UI work is done when the source checker below reports no errors on the files you
+changed, and the app's typecheck, lint and tests then pass. Run the checker, fix
+the owner or prop each finding names, and run it again; after three rounds, stop
+and report what remains. Warnings are review findings: fix each one or keep it
+with a reason. This is the agent's completion condition, not the build's; app CI
+may stay non-blocking on warnings. The [project instructions
+block](agents-md.md) states the same condition in the app's `AGENTS.md`.
+
+Hand back five lines, so a skipped check is visible:
+
+1. Owners used for the route, its commands and each data region.
+2. Checker: run or not run, with its error and warning counts.
+3. Typecheck, lint and tests: each run or not run, and why.
+4. Kept warnings, each with file:line and its reason.
+5. States covered or missing: loading, empty, error, disabled and validation.
+
+## Source checker
 
 The package ships a read-only script, not an npm bin/global CLI. It needs the
 consumer's TypeScript development dependency and Node matching the package engine:
@@ -40,12 +59,29 @@ Errors cover unknown package entrypoints/symbols and statically detected overrid
 of protected Card/popup insets, Card badges in headerAction/headerStart rather
 than titleSuffix, control geometry/typography, fixed DisplayLabel/Badge
 roles, cross-role shell/inner radius replacements, display-copy margins, or
-attenuated shared focus rings on imported controls. Intentional nested bodies,
+redrawn focus indicators (another ring width, offset or halo strength) on imported controls. Intentional nested bodies,
 circular owners and joined-edge corner resets retain their roles. Import ownership
-follows lexical bindings, preserving locally shadowed application components. Deprecated migration
-owners, nested framed subjects and repeated literal headings produce review
-warnings; warnings alone do not fail CI. Messages identify the owner and remedy.
+follows lexical bindings, preserving locally shadowed application components. Imports of
+symbols the public index marks deprecated, nested framed subjects and repeated
+literal headings produce review warnings; warnings alone do not fail CI. Messages
+identify the owner and remedy. Dialog-like UI outside the overlay owners warns
+too: native elements with `role="dialog"`/`"alertdialog"` or `aria-modal`, a
+`fixed inset-0` layer, and imports of another modal library.
 Standalone compact Cards and Page gutter removal also produce review warnings.
+Buttons placed in a Page or PageHeader `actions` region warn as well: pass
+commands as `primaryAction` and ordered `secondaryActions` so the header owns
+their emphasis, size and overflow. Non-command controls stay valid there.
+A Page with more than one solid primary command, counting `header.primaryAction`
+and every Button with `tone="primary"` and no other style, warns as well. Overlays own
+their own primary command and are not counted. Raw palette classes such as
+`bg-blue-500`, `text-gray-600` or `border-white` warn on any element; use a
+semantic surface/foreground pair or a status tone. A Card title icon and an icon on
+more than one MetadataList fact warn as decoration; keep a glyph only when it
+encodes state or a brand. Native `<button>` and
+`<h1>`–`<h6>` elements warn in favour of Button/TextButton and Heading, which
+own focus, loading and disabled states or margins and the heading scale. A
+native button passed as a package owner's `render`, such as an Item row
+rendered as a button, is that owner's root and does not warn.
 Verified Card-owning Metric/card-grid, UsageCard and TaskCard compositions also
 participate in nested-surface and peer-gap review. Metric without its card variant,
 compact MetricGrid, flat TaskCard, ChartCard and Receipt do not establish a frame.

package/docs/consumer-skill/references/theming.md

@@ -4,7 +4,7 @@ The [design contract](design-contract.md) records which geometry changes togethe
 and which variant choices remain independent. Retheme shared responsibilities;
 avoid overriding individual components to imitate another density or inset.
 
-Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration.
+Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the one control boundary: fields, select and date triggers, checkboxes, radios, switch tracks and outline buttons all draw it, so adjoining controls read as one family. It is deliberately soft and translucent, reading the same on every surface; focus and invalid edges carry the 3:1 contrast. `--border` is for dividers and surface edges. Keep that split when rebranding.
 
 tokens.json distinguishes 23 structural roots, advanced typography/status settings, and derived utility spellings. A utility is not another public variable. Keep overrides in one stylesheet at root or ThemeScope, without copying computed CSS into JavaScript.
 
@@ -63,6 +63,12 @@ control heights and copy gaps keep their independent roots.
 
 Use discrete inset, density and size props for the component responsibility described in [composition](composition.md). CSS scales are independent continuous theme settings. Primary row text does not shrink to xs merely because a density is compact. Public Input and Command search retain normal desktop editable text; coarse-pointer devices use text-base at mobile and tablet widths. Typography components remain margin-free.
 
+The default primary is near-black so success and other status colors never compete
+with it. `themelia-react-ui/themes/green.css`, imported after `style.css`, is the
+opt-in Themelia green brand (primary, its foreground, the dark accent and the first
+chart series). Rebrand by setting `--primary` and `--primary-foreground` in both
+`:root` and `.dark`; keep the brand hue clear of the status hues and check 4.5:1.
+
 Root overrides reach body portals. Scoped themes use ThemeScope from ui-provider. Advanced editing uses the theme-tweaker public API, editing CSS rather than adding another JavaScript styling system.
 
 Explicit portal containers take precedence over the nearest ThemeScope. Place those containers inside the intended theme boundary; a portal deliberately moved outside it cannot inherit that boundary automatically. Test the opened popup, not only its trigger.
@@ -71,9 +77,13 @@ Apps using semantic utilities in their own JSX process themelia-react-ui/theme.c
 
 The package class merger recognizes token overrides only for advertised utilities and exact class spellings emitted by the library stylesheet, including their negative, important and responsive forms. A valid Tailwind alias such as `m-space-2xl` can still be absent from that stylesheet. Unshipped aliases preserve existing fallback classes; they do not receive package override semantics merely because an app's separate Tailwind build can generate them. Use the app's own merge configuration for additional app-compiled aliases.
 
-`ring` and `sidebar-ring` are focus roles tested at full strength. Preserve that
-strength and verify at least 3:1 against adjacent surfaces when overriding the
-theme; adding opacity can invalidate contrast even when the root color passes.
+`ring` and `sidebar-ring` are the focus roles. Every focused element draws one
+indicator: a 1px edge in the role at full strength (the control's own border, an
+inset edge on borderless rows, or an outline just outside link text) inside a
+soft 3px halo of the role at 50%. The edge carries the tested 3:1 contrast
+against adjacent surfaces, so keep the root color at that strength when
+overriding the theme; the halo makes focus stand out without reading as a
+heavier border.
 
 ## Extend without drift
 

package/docs/consumer-skill/references/tokens.json

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "1.0.2",
+  "version": "2.0.1",
   "structural": [
     {
       "name": "--space-scale",
@@ -121,7 +121,7 @@
   "radius": {
     "name": "--radius",
     "default": "0.75rem",
-    "purpose": "Shared 8px corners keep short controls rectangular; nested corners derive from this root.",
+    "purpose": "Shared 12px outer corners; inner control/row corners derive from this root and stay rectangular.",
     "defaultUtility": "rounded-radius",
     "innerUtility": "rounded-inner",
     "innerFormula": "min(calc(var(--radius) * 0.75), calc(min(var(--height-action), var(--height-control)) * var(--density-scale) / 4))"
@@ -209,6 +209,7 @@
       "gap-space-lg",
       "gap-space-xl",
       "gap-space-2xl",
+      "gap-space-3xl",
       "gap-x-space-2xs",
       "gap-x-space-xs",
       "gap-x-space-sm",
@@ -216,6 +217,7 @@
       "gap-x-space-lg",
       "gap-x-space-xl",
       "gap-x-space-2xl",
+      "gap-x-space-3xl",
       "gap-y-space-2xs",
       "gap-y-space-xs",
       "gap-y-space-sm",
@@ -223,6 +225,7 @@
       "gap-y-space-lg",
       "gap-y-space-xl",
       "gap-y-space-2xl",
+      "gap-y-space-3xl",
       "p-space-2xs",
       "p-space-xs",
       "p-space-sm",

package/docs/consumer-skill/references/workflows.md

@@ -28,9 +28,23 @@ Reset/removal aborts pending uploads; the app owns transport and persistence.
 
 ## Detail and framing
 
-[AccountDetail](../examples/detail.tsx) exports `AccountDetail`, `AccountDetailProps` and `AccountDetailRecord`. Supply `account`, `onEdit(id)` and `onBack()`. Card owns the frame/header/body/footer; Name, Email, Date, Money and Value own formatting and missing-value fallbacks. `balanceMinor` uses `Money unit="minor"`; currency and date values come from the app.
-
-No optional peers are needed. The app supplies the loaded record and owns navigation, locale/provider defaults and permissions. Verify missing email/date/balance, a real minor-unit amount, Edit/Back callbacks, and the one-column mobile/two-column desktop composition in light/dark themes.
+[The detail recipe](../examples/detail.tsx) exports two owners.
+`AccountDetailPage` is the record route: Page owns the title, one status badge,
+the commands and the section tabs. `primaryAction` is Edit account,
+`secondaryActions` holds Send statement and a `destructive` Delete account that
+opens ConfirmDialog, and `header.tabs` carries Overview, Invoices with its count
+badge, and Activity. The header renders `[secondary…] [primary] [⋯]`; destructive
+and overflow commands live in the More actions menu. `AccountDetail` is the same
+facts as one framed subject for a drawer or dashboard, with Edit as its one quick
+`headerAction`. Name, Email, Date, Money and Value own formatting and
+missing-value fallbacks; `balanceMinor` uses `Money unit="minor"`.
+
+No optional peers are needed. The app supplies the loaded record, the section
+content and the delete transport, and owns navigation, locale/provider defaults
+and permissions (`visible: false` hides a command). Verify missing
+email/date/balance, a rejected delete that keeps the confirmation open, tab
+selection with keyboard arrows, the narrow layout where secondary commands
+collapse into the menu, and light/dark themes.
 
 ## Scoped directory
 
@@ -79,12 +93,16 @@ definitions; the app then chooses appropriate destination focus.
 
 ## Single resource page
 
-Use `Page`, `PageHeader` and `PageActions` from `themelia-react-ui/layout/page`
-for the record route's identity, back navigation, content bounds and commands.
-The [layout recipe](../examples/app-layout.tsx) demonstrates that route boundary;
-the [detail recipe](../examples/detail.tsx) demonstrates an independently framed
-record subject with MetadataList and value primitives. Decide whether the record
-needs that independent Card before nesting it under Page. Avoid repeating the
+Use `Page` from `themelia-react-ui/layout/page` for the record route's identity,
+back navigation, content bounds, commands and section tabs. Pass the record's
+main command as `header.primaryAction`, supporting commands as
+`header.secondaryActions` and sections as `header.tabs`; one status badge goes in
+`header.titleBadges`. `PageHeader` serves a custom shell; `PageActions` is
+deprecated. The [layout recipe](../examples/app-layout.tsx) demonstrates that
+route boundary; the [detail recipe](../examples/detail.tsx) demonstrates the
+record route and an independently framed subject with MetadataList and value
+primitives. Decide whether the record needs that independent Card before nesting
+it under Page. Avoid repeating the
 route heading just to frame the same facts. Page owns gutters; PageViewport owns
 scrolling only. App navigation, record loading/missing/error/retry, permissions,
 edit and delete callbacks remain application responsibilities.
@@ -92,6 +110,9 @@ edit and delete callbacks remain application responsibilities.
 Use `WorkspaceLayout` from `themelia-react-ui/layout/workspace` when independently composed record header,
 sidebar/main/rail regions are needed; inspect `features/resource` for complete
 resource coordination. A single record does not automatically need either.
+Their headers (`WorkspaceRecordHeader`, `ResourceHeader` and the resource shells)
+take the same `primaryAction` and `secondaryActions` as Page; keep their
+`actions` for non-command controls.
 Read [layout composition](composition.md#application-layouts) for boundary and
 parent-width behavior, then the exact selected declaration for its current props.
 

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

@@ -1,4 +1,4 @@
-import { surfaceParts, surfaceForwarders, paddingClass, paddingProperty, utility, attenuatedFocusRing, sharedCornerParts, displayNames, nativeDisplayNames, marginProperty, radiusProperty, replacesSharedRadius, cornerRole, addsCopyMargin } from './surface-policy.mjs';
+import { surfaceParts, surfaceForwarders, paddingClass, paddingProperty, utility, focusRingDrift, fadedText, sharedCornerParts, displayNames, nativeDisplayNames, marginProperty, radiusProperty, replacesSharedRadius, cornerRole, addsCopyMargin } from './surface-policy.mjs';
 
 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']);
@@ -9,6 +9,9 @@ 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) {
@@ -24,6 +27,16 @@ export function sourceBindings(source, ts) {
 }
 
 /** 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);
@@ -116,11 +129,13 @@ 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.`);
+      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(symbolFor(names.name), specifier);
   }
   function gather(node) {
+    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);
@@ -185,6 +200,67 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (ts.isJsxExpression(node)) return slotBadge(node.expression);
     return false;
   };
+  // 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.
+  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']) || isOwner(owner, 'base/action-menu', ['ActionMenu', 'ActionButtons']) || isOwner(owner, 'layout/page', ['PageActions']) || isOwner(owner, 'layout', ['PageActions']) || 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 = [];
@@ -239,10 +315,31 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (ts.isJsxSelfClosingElement(node)) inspect(node, parents);
     ts.forEachChild(node, child => visit(child, parents));
   }
+  // 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();
+  const collectRenderRoots = expression => {
+    if (!expression) return;
+    if (ts.isJsxSelfClosingElement(expression)) renderRoots.add(expression);
+    else if (ts.isJsxElement(expression)) renderRoots.add(expression.openingElement);
+    else if (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)) collectRenderRoots(expression.expression);
+    else if (ts.isConditionalExpression(expression)) { collectRenderRoots(expression.whenTrue); collectRenderRoots(expression.whenFalse); }
+    else if (ts.isBinaryExpression(expression)) collectRenderRoots(expression.right);
+    else if (ts.isArrowFunction(expression) && !ts.isBlock(expression.body)) collectRenderRoots(expression.body);
+  };
   function inspect(node, parents) {
     const owner = ownerFor(node.tagName);
+    const render = owner && node.attributes.properties.find(attribute => ts.isJsxAttribute(attribute) && attribute.name.getText(source) === 'render');
+    if (render?.initializer) collectRenderRoots(ts.isJsxExpression(render.initializer) ? render.initializer.expression : render.initializer);
+    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) {
-      if (node.tagName.getText(source) === 'div' && literal(new Map(attributes(node)).get('role')) === 'dialog') add(node, 'raw-overlay-primitive', 'warning', 'A custom dialog needs focus, dismissal and pending-state ownership. Compare ActionDialog/ConfirmDialog/ActionDrawer from features/overlays before maintaining that lifecycle.');
+      const tag = node.tagName.getText(source);
+      if (tag === 'button' && !renderRoots.has(node)) 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.');
@@ -272,12 +369,15 @@ export function analyzeComposition(text, { filename, index, ts }) {
     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);
+      const tokens = classStrings(props.get(name)).flatMap(value => value.split(/\s+/)).filter(Boolean);
+      const classes = tokens.map(utility);
+      const focusDrift = focusRingDrift(tokens);
       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 (display && name === 'className' && tokens.some(fadedText)) add(node,'faded-text','error',`${owner.symbol}: use its type prop (main, secondary) instead of ${[...new Set(tokens.filter(fadedText))].join(', ')}; an opacity-faded text role falls under 4.5:1.`);
+      if ((control || family === 'buttons' && owner.symbol === 'TextButton') && name === 'className' && focusDrift.length) add(node, 'focus-ring-recipe', 'error', `${owner.symbol}: keep the shared focus indicator (a ring-3 halo of ring-ring/50 around a full-strength ring edge); ${[...new Set(focusDrift)].join(', ')} redraws it.`);
       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,value] of properties(props.get('style'))) {
@@ -287,7 +387,9 @@ 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 (['SmartCard', 'ContentBlock'].includes(owner.symbol)) add(node, 'deprecated-owner', 'warning', `${owner.symbol} is a migration owner; prefer Card for new compositions.`);
+    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, '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'])) {
       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'}.`);
@@ -296,7 +398,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       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 (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.');
@@ -307,6 +409,25 @@ export function analyzeComposition(text, { filename, index, ts }) {
     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`;
+    // 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 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 ((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.`);
+    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.`);
+      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);
+      if (iconCommands > 1) add(headerProps.get('secondaryActions') ?? node, 'decorative-icon', 'warning', `${owner.symbol}: ${iconCommands} page commands carry icons that repeat their labels. Keep the labels; reserve an icon for + on an add command or an external link.`);
+    }
     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.`);
     const structure = owner.import === `${index.package}/base/structure` && Object.hasOwn(structureDefaults, owner.symbol);

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

@@ -21,6 +21,7 @@ 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) {
@@ -117,11 +118,18 @@ export function findComponents(index, { query, layer = null, limit = 5 }) {
     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 relevantSymbols = exactImport ? family.symbols : exactOwners.length || matchedSymbols.length ? selectedSymbols : [...new Set([...selectedSymbols, ...guidance.flatMap(guide => guideSymbols(guide, family))])];
+    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)));
-    const aliases = guidance.flatMap(guide => guide.aliases.map(alias => normalized(alias).split(/\s+/)));
+    // 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 = {
@@ -129,7 +137,7 @@ export function findComponents(index, { query, layer = null, limit = 5 }) {
       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, nextReads, guidance });
+    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;
+  }
+}