themelia-react-ui 2.0.0 → 2.0.2

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
 
@@ -22,7 +22,25 @@ These criteria allow different product layouts. Do not impose a universal card
 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:
@@ -41,7 +59,7 @@ 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. Imports of
 symbols the public index marks deprecated, nested framed subjects and repeated
@@ -49,6 +67,13 @@ literal headings produce review warnings; warnings alone do not fail CI. Message
 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.
+
+The checker also rejects faded semantic text colors and partial opacity on
+imported typography/value primitives, including aliases and namespace imports.
+Use the shared secondary/status role. Presence endpoints (0/100) and the shared
+disabled 50% treatment remain valid; component disabled props keep that dimming
+with its owner.
+
 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
@@ -61,7 +86,9 @@ semantic surface/foreground pair or a status tone. A Card title icon and an icon
 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.
+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,10 +4,20 @@ 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. `--input` is the control boundary and keeps 3:1 against every surface (WCAG 1.4.11); `--border` is for dividers and surface edges. Keep that split when rebranding.
+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 resting 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 provides at least 3:1 contrast on the declared background, card, popover, muted, accent and secondary surfaces in both modes. Focus and invalid edges retain their separate 3:1 contract. `--border` is for quieter dividers and surface edges. When rebranding, check resting controls as well as focused controls, including the outside edge of fields with their own fill.
 
 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.
 
+Pair each painted surface with its intended ink: `bg-card text-card-foreground`
+and `bg-popover text-popover-foreground` are matching pairs. Flat sections inherit
+the containing surface. For app-owned primary copy in a differently colored
+surface, use Text/Value `type="inherit"` and Label `className="text-inherit"`;
+standalone typography keeps its documented defaults. Keep secondary, link, status
+and inverse roles explicit, and use a secondary text role instead of fading text
+with opacity. Component disabled props own dimming; an extra faded wrapper can
+multiply it. Brand colors alone do not guarantee input/focus contrast: retain the
+central `--input`/`--ring` roles or verify their replacements on every host surface.
+
 The default `--radius` is 0.75rem (12px). One public root drives two shared
 roles; component owners choose the role, so ordinary callers add no radius class.
 
@@ -47,6 +57,14 @@ replacing individual components' owned corners.
 
 Action and editable-control heights are separate roles; keep roots equal for adjoining alignment. `--space-scale` multiplies structural gaps, inline insets and surface padding. `--density-scale` multiplies action/control height and collection block padding. Roots are unscaled measurements; do not pre-multiply and then apply the utility again.
 
+Control heights are nominal floors when custom typography needs more room.
+Native fields, Select and InputGroup frames fit their editable line plus the
+border, and cap vertical padding to the space remaining in the nominal height.
+The default 32/36/40px sizes and radius roles stay unchanged. Text actions grow
+under their intentionally tighter leading, so independently enlarged type can
+produce different fitted heights even with equal action/control roots. Check
+type size, leading and height roots together when exact custom pairing matters.
+
 Both surface roots default to 1.25rem. At a 16px root font and space-scale 1,
 ordinary surface insets are 20px, compact insets are 10px and large insets are
 36px. Page's default large gutters inherit that same recipe. Row insets,
@@ -65,11 +83,58 @@ Use discrete inset, density and size props for the component responsibility desc
 
 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.
+opt-in Themelia green brand (primary, its foreground and the dark accent; the first
+chart series is already that green). Rebrand by setting `--primary` and
+`--primary-foreground` in both `:root` and `.dark`; the sidebar's primary follows
+them in both modes. 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.
+The nearest explicit `.light` or `.dark` boundary governs the palette and dark
+utilities, including repeated nesting and scoped portals. This uses inherited
+custom-property container style queries, supported in Chromium 111+, Safari 18.1+
+and Firefox 151+. The internal mode marker is state derived from those classes;
+it is not another customization setting.
+
+When ThemeScope's `style` supplies `--primary`, its default `--primary-accent`
+and `--sidebar-primary` references resolve at that scope. The same applies to
+`--primary-foreground` / `--sidebar-primary-foreground`, `--foreground` /
+`--popover-foreground`, and `--font-sans` / `--font-heading`. Explicit local role
+overrides in CSS or `style` win. A child scope with no new source override
+inherits independent roles unchanged. Mode-dependent roles such as the elevated
+dark `--popover` stay owned by the palette.
+
+Package defaults and these alias references live in the `theme` cascade layer.
+Explicit Tailwind utility overrides therefore win on plain scopes and scopes
+with a mode class, as do unlayered consumer CSS and inline overrides. Keep the
+standard `theme, base, components, utilities` layer order when composing your
+application stylesheet.
+
+CSS class themes declare their source roots and dependent aliases together:
+CSS resolves aliases at their declaration boundary, and a scope cannot infer
+which declarations an arbitrary consumer stylesheet supplied.
+
+```css
+.tenant-theme {
+  --primary: oklch(0.45 0.12 250);
+  --primary-accent: var(--primary);
+  --sidebar-primary: var(--primary);
+  --primary-foreground: oklch(0.99 0 0);
+  --sidebar-primary-foreground: var(--primary-foreground);
+  --font-sans: Georgia, serif;
+  --font-heading: var(--font-sans);
+}
+```
+
+Advanced editing uses the theme-tweaker public API, editing CSS rather than
+adding another JavaScript styling system.
 
-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.
+For tenant exports, pass the whole result of
+`createScopedAdminUIThemeSelectors(scopeSelector)` to `serializeAdminUITheme`.
+Its additive `modeScope` metadata selects light/dark values by the nearest mode
+boundary, including complex selector lists. The existing `shared`, `light` and
+`dark` strings remain available; manually supplied selectors without `modeScope`
+are emitted literally. Mode-specific ChartStyle series use the same boundary
+policy, while a fixed single-color series remains independent of mode.
 
 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.
 
@@ -77,9 +142,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
 
@@ -104,4 +173,4 @@ heights. `--icon` and `--avatar` set media dimensions independently. Component
 Test these choices separately and in combination. Tables follow row insets,
 Cards and code/message bodies follow surfaces, and image containment uses generic
 spacing. Foundation directional spacing utilities ship with style.css and use
-the same seven steps as gaps; generated spellings are not new theme roots.
+the same eight steps as gaps; generated spellings are not new theme roots.

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

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "structural": [
     {
       "name": "--space-scale",

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

@@ -18,6 +18,14 @@ and explicit maximums from your column definitions. The table owns its one named
 scroll region. Verify grouped widths, sticky header rows and first-column behavior
 with real overflow in both directions, rather than adding another focusable wrapper.
 
+## Media selection
+
+For a browsing `MediaLibrary` with `bulkActions`, localize the selected-assets
+region through `strings.batchActionsLabel` (English default: `Batch actions`).
+The visible selection summary and Clear action stay in
+`strings.footer.selectedCount` and `strings.footer.clear`. The native
+`BatchActionBar` owns the region and its dismissal/focus behavior.
+
 ## Comment attachments
 
 `Comments` and `CommentComposer` announce attachment validation/upload errors.
@@ -28,9 +36,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
 
@@ -58,6 +80,23 @@ in pagination URLs. A criteria-driven business selector would be a different
 product contract. The recipe's English labels are example copy: adapt labels,
 criteria and component `strings` for app translation and permissions.
 
+DataTable accessibility copy also belongs to `strings`: use
+`accessibility.sortColumn(columnLabel)` and `accessibility.resizeColumn(columnLabel)`
+for column controls, `emptyState.ariaLabel` for the empty-result status and
+`selection.label` for the selected-row action region. Partial overrides preserve
+the other English defaults.
+
+For searchable selection, `Combobox` uses `strings.clear` and `strings.toggle`;
+both single and multiple recipes use `strings.dismiss` for the two screen-reader
+dismissal controls. `MultiCombobox` uses `strings.removeSelection(itemLabel)` for
+each removal button.
+Custom base anatomy exposes `ComboboxInputTrigger` strings `{ clear, toggle }`,
+`ComboboxClear` strings `{ clear }` and `ComboboxChip` strings `{ remove }`.
+`ComboboxRoot` preserves the supported upstream `dismissLabel` prop. This private
+build requires the companion Base UI `1.8.0-kpo.2` archive. It includes that public seam
+and preserves an existing focus target inside a parent popup during nested
+popup dismissal.
+
 Strict imported declarations require the manifest's optional peers. DataTable
 sorting is disabled because the app's server owns query order. Loading/error
 feedback occupies the empty result region while query context remains mounted;
@@ -80,13 +119,15 @@ definitions; the app then chooses appropriate destination focus.
 ## Single resource page
 
 Use `Page` from `themelia-react-ui/layout/page` for the record route's identity,
-back navigation, content bounds and commands. Pass the record's main command as
-`header.primaryAction` and supporting commands as `header.secondaryActions`;
-`PageHeader` and `PageActions` remain for custom shells and toolbars.
-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
+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.
@@ -94,6 +135,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, textOpacityDrift, textContentNames, 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']);
@@ -200,15 +200,16 @@ export function analyzeComposition(text, { filename, index, ts }) {
     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.
+  // 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']) || opening.tagName.getText(source) === 'button') return true;
+      if (isOwner(owner, 'base/buttons', ['Button', 'TextButton', 'BaseButton', 'BaseButtonLink']) || isOwner(owner, 'base/forms', ['SubmitStateButton']) || isOwner(owner, 'base/action-menu', ['ActionMenu', 'ActionButtons']) || 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);
     }
@@ -314,12 +315,26 @@ 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) {
       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 (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');
@@ -350,16 +365,20 @@ export function analyzeComposition(text, { filename, index, ts }) {
     const control = controlFamilies.has(family) && controlNames.test(owner.symbol);
     const sharedCorners = sharedCornerParts[family]?.test(owner.symbol);
     const display = owner.import === `${index.package}/typography` && displayNames.test(owner.symbol);
+    const textContent = display || owner.import === `${index.package}/primitives` && textContentNames.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);
+      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 (textContent && name === 'className' && tokens.some(token=>fadedText(token)||textOpacityDrift(token))) add(node,'faded-text','error',`${owner.symbol}: use its semantic type instead of adding an opacity tier to the text. Presence endpoints and shared disabled state remain valid.`);
+      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'))) {
@@ -370,7 +389,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       if (fixedText && (textStyle.test(name) || badge && /^border.*Radius$/.test(name))) add(node, 'fixed-text-role', 'error', `${owner.symbol}: ${name} replaces its shared text/radius recipe.`);
     }
     if ((isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'base/display', ['ContentBlock'])) && props.get('icon')) add(node, 'decorative-icon', 'warning', `${owner.symbol}: a title icon is decoration unless it encodes state or a brand; let the title name the subject.`);
-    const facts = isOwner(owner, 'blocks/data-display', ['MetadataList']) ? resolve(props.get('items')) : undefined;
+    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'])) {
@@ -380,7 +399,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.');
@@ -392,12 +411,24 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (framed && parents.some(parent => parent.framed)) add(node, 'nested-surface', 'warning', `${owner.symbol} is inside a framed owner. Review subject boundaries; use surface="flat" when the parent owns the frame.`);
     const header = properties(props.get('header'), false);
     const pageOwner = owner.import === `${index.package}/layout/page` || owner.import === `${index.package}/layout`;
-    const headerActions = pageOwner && owner.symbol === 'Page' ? new Map(header).get('actions') : pageOwner && owner.symbol === 'PageHeader' ? props.get('actions') : undefined;
+    // 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)) 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.`);
+    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/surface-policy.mjs

@@ -25,6 +25,7 @@ export const sharedCornerParts = {
   sheet: /^SheetContent$/,
 };
 export const displayNames = /^(?:Text|Heading|DisplayLabel|Label|TextLink)$/;
+export const textContentNames = /^(?:Value|SecondaryValue|MutedValue|MonoValue|EmptyValue|Number|Percent|Money|Date|DateTime|Time|Duration|Name|Email|Phone|Link|FileSize|Dimensions|DateRange|RelativeTime|Url|Initials)$/;
 export const nativeDisplayNames = /^(?:p|h[1-6])$/;
 export const marginProperty = /^margin(?:Inline|Block)?(?:Start|End)?$|^margin(?:Top|Right|Bottom|Left)$|^margin-(?:(?:inline|block)(?:-(?:start|end))?|top|right|bottom|left)$/;
 export const radiusProperty = /^border(?:(?:Top|Bottom)(?:Left|Right)|(?:Start|End)(?:Start|End))?Radius$|^border-(?:(?:top|bottom)-(?:left|right)-|(?:start|end)-(?:start|end)-)?radius$/;
@@ -57,10 +58,154 @@ export function utility(token) {
   return token.slice(start).replace(/^!|!$/g, '');
 }
 
-/** Shared focus roles are contrast-tested at full strength, unlike status tints. */
-export function attenuatedFocusRing(token) {
-  const match = utility(token).match(/^ring-(?:ring|sidebar-ring)\/(?:(\d+(?:\.\d+)?|\.\d+)|\[(\d+(?:\.\d+)?|\.\d+)(%)?\])$/);
+export function variants(token) {
+  return token.slice(0, token.length - utility(token).length - (/!$/.test(token) ? 1 : 0)).replace(/!$/, '');
+}
+
+// Text and icon colours are typography roles. Opacity on a role adds a tier under
+// the tested 4.5:1, so only the sidebar keeps its one secondary tier.
+const textRole = /^text-(?:foreground|muted-foreground|card-foreground|popover-foreground|accent-foreground|secondary-foreground|primary-foreground|primary-accent|warning-accent|link-color|success|info|warning|destructive|sidebar-foreground|sidebar-accent-foreground|sidebar-primary-foreground)\/.+$/;
+export function fadedText(token) {
+  const value = utility(token);
+  return value !== 'text-sidebar-foreground/70' && textRole.test(value);
+}
+
+/** Separate opacity on an owned text node changes its semantic ink as well. */
+export function textOpacityDrift(token) {
+  const value = utility(token);
+  const match = value.match(/^opacity-(?:(\d+(?:\.\d+)?)|\[(\d*\.?\d+)(%)?\])$/);
   if (!match) return false;
-  const opacity = Number(match[1] ?? match[2]);
-  return opacity < (match[1] !== undefined || match[3] ? 100 : 1);
+  const opacity = match[1] !== undefined ? Number(match[1]) : Number(match[2]) * (match[3] ? 1 : 100);
+  if (!(opacity > 0 && opacity < 100)) return false;
+  return !(opacity === 50 && variantSegments(variants(token)).some(segment => disabledSegment.test(segment)));
+}
+
+// Interaction fills come from one recipe owner: accent for rows, muted for toggle
+// hover, a lifted card segment and the table ladder. A neutral fill with opacity or
+// a primary tint under hover, highlight, selection, current or pressed state is a
+// second definition of that state.
+const interactionSegment = /^(?:group-|peer-)?(?:hover|focus|focus-visible|focus-within|active|data-highlighted|data-selected|data-active|data-current|data-pressed|aria-selected|aria-current|aria-pressed|aria-checked|data-\[(?:highlighted|selected|active|current|pressed|checked|state=[^\]]+)[^\]]*\])(?:\/[\w-]+)?$/;
+function variantSegments(variant) {
+  const segments = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < variant.length; i++) {
+    if ('[('.includes(variant[i])) depth++;
+    else if ('])'.includes(variant[i])) depth--;
+    else if (variant[i] === ':' && depth === 0) { segments.push(variant.slice(start, i)); start = i + 1; }
+  }
+  return segments;
+}
+export function interactionFillDrift(token) {
+  if (!variantSegments(variants(token)).some(segment => interactionSegment.test(segment))) return false;
+  const match = utility(token).match(/^bg-(muted|accent|card|background|foreground|secondary|popover|sidebar-accent|primary)\/(.+)$/);
+  return !!match && !(match[1] === 'muted' && match[2] === '50');
+}
+
+// Neutral fills have one strength per role (neutralFillRecipes in
+// src/lib/surface-recipes.ts): a wash at muted/30, a band at muted/50, a chip at
+// foreground/8, the inverse chip at background/10 and the idle marker at
+// muted-foreground/40. Opaque fills are always available; interaction states belong
+// to interaction-fill.
+const neutralTint = /^bg-(muted|muted-foreground|foreground|background|card|popover|secondary|accent|sidebar(?:-[a-z]+)*)\/(.+)$/;
+const neutralScale = new Set(['muted/30', 'muted/50', 'foreground/8', 'background/10', 'muted-foreground/40']);
+export function neutralFillDrift(token) {
+  const match = utility(token).match(neutralTint);
+  if (!match || neutralScale.has(`${match[1]}/${match[2]}`)) return false;
+  return !variantSegments(variants(token)).some(segment => interactionSegment.test(segment));
+}
+
+// Elevation takes one theme shadow per role (elevationRecipes in
+// src/lib/surface-recipes.ts): xs resting, sm card, md raised and anchored, lg lifted
+// and xl modal; shadow-none clears it. A box-shadow divider line that draws
+// var(--border) is divider mechanics, not elevation.
+export function elevationDrift(token) {
+  const value = utility(token);
+  if (!/^shadow(?:-|$)/.test(value)) return false;
+  return !/^shadow-(?:none|xs|sm|md|lg|xl)$/.test(value) && !/^shadow-\[.*var\(--border\).*\]$/.test(value);
+}
+
+// Dividers have two strengths: a surface edge draws the full border role and an
+// inner divider (one side, divide, separator) draws it at 60%. The control boundary
+// has one strength. Only src/lib/surface-recipes.ts owns other strengths (the modal
+// shell and the framed Card ring).
+export function dividerStrengthDrift(token) {
+  const match = utility(token).match(/^(?:border(?:-[trblxyse]|-bs|-be)?|divide(?:-[xy])?|ring|inset-ring|outline|bg)-(border|sidebar-border|input)\/(.+)$/);
+  return !!match && !(match[1] === 'border' && match[2] === '60');
+}
+
+// Status and emphasis tints have one scale, src/lib/tone-recipes.ts: a wash, tint,
+// edge, halo and line strength per tone, which the contrast contract tests. A
+// translucent tone spelled anywhere else is a second scale. The invalid state's
+// destructive halo belongs to the field-state and focus recipes.
+const toneTint = /^(?:bg|border(?:-[trblxyse]|-bs|-be)?|ring|inset-ring|outline|divide(?:-[xy])?)-(?:info|success|warning|destructive|primary)(?:-accent)?\/.+$/;
+export function statusTintDrift(token) {
+  return toneTint.test(utility(token)) && !/invalid|focus/.test(variants(token));
+}
+
+// State changes (colour, border and shadow) share one timing: Tailwind's default
+// 150ms transition and easing. Presence and geometry motion (enter, exit, expand,
+// slide) comes from src/lib/motion-recipes.ts. Returns the timing tokens that
+// retime a paint-only transition.
+const paintProperties = new Set(['color', 'background-color', 'background', 'border-color', 'box-shadow', 'outline-color', 'text-decoration-color', 'fill', 'stroke']);
+function paintTransition(token) {
+  const value = utility(token);
+  if (value === 'transition-colors' || value === 'transition-shadow') return true;
+  const list = value.match(/^transition-\[(.+)\]$/)?.[1];
+  return !!list && list.split(',').every(property => paintProperties.has(property.trim()));
+}
+export function stateMotionDrift(classes) {
+  const resting = classes.filter(token => variants(token) === '');
+  if (!resting.some(paintTransition) || resting.some(token => /^transition(?:-|$)/.test(utility(token)) && !paintTransition(token))) return [];
+  return resting.filter(token => /^duration-(?!150$|0$)/.test(utility(token)) || /^ease-/.test(utility(token)));
+}
+
+// Corners take a role derived from --radius: rounded-radius (outer shells) and
+// rounded-inner (controls, rows, nested bodies), plus rounded-full, rounded-none
+// and the root-derived rounded-radius-* steps. Bare rounded is a fixed 4px that
+// ignores the theme root, and the t-shirt steps are a second scale.
+export function radiusRoleDrift(token) {
+  return /^rounded(?:-(?:[trblse]|tl|tr|br|bl|ss|se|es|ee))?(?:-(?:xs|sm|md|lg|xl|2xl|3xl|4xl))?$/.test(utility(token));
+}
+
+// One stacking scale (src/lib/layer-recipes.ts): z-10 raised, z-20 sticky, z-30
+// sticky over sticky, z-40 app chrome, z-50 popups and modal layers. Local
+// ordering may also use z-0, z-[1] and z-[-1].
+export function layerScaleDrift(token) {
+  const match = utility(token).replace(/^-/, '').match(/^z-(?:(\d+)|\[(-?\d+)\])$/);
+  if (!match) return false;
+  if (match[2] !== undefined) return Math.abs(Number(match[2])) > 1;
+  return ![0, 10, 20, 30, 40, 50].includes(Number(match[1]));
+}
+
+// Disabled content dims once, at 50%; a child of a dimmed owner resets to 100%.
+const disabledSegment = /^(?:group-|peer-)?(?:disabled|data-disabled|aria-disabled|data-\[disabled[^\]]*\]|aria-\[disabled[^\]]*\])(?:\/[\w-]+)?$/;
+export function disabledDimmingDrift(token) {
+  if (!variantSegments(variants(token)).some(segment => disabledSegment.test(segment))) return false;
+  const match = utility(token).match(/^opacity-(\d+)$/);
+  return !!match && !['50', '100'].includes(match[1]);
+}
+
+const focusState = /focus|focused/;
+const ringWidth = /^ring(?:-\d+(?:\.\d+)?|-\[(?:\d+(?:\.\d+)?)(?:px|rem|em)\])?$/;
+
+/**
+ * Every focus indicator is one recipe: a 3px halo of the ring role at 50% around
+ * a full-strength 1px edge (the control's own `border-ring`, or `inset-ring-ring`
+ * on a borderless element). Returns the tokens that draw focus any other way:
+ * another focus ring width, an offset ring, a halo at another strength, an
+ * attenuated edge, or an unscoped ring colour that a focus-only width turns into
+ * a full-strength halo. Status tints (invalid, selected) keep their own colours.
+ */
+export function focusRingDrift(classes) {
+  const focused = token => focusState.test(variants(token));
+  const focusWidth = classes.some(token => focused(token) && ringWidth.test(utility(token)) && utility(token) !== 'ring-0');
+  return classes.filter(token => {
+    const value = utility(token);
+    if (!focused(token)) return focusWidth && variants(token) === '' && /^ring-(?:ring|sidebar-ring)$/.test(value);
+    if (/^ring-offset-/.test(value)) return true;
+    if (ringWidth.test(value)) return !/^ring-[03]$/.test(value);
+    const halo = value.match(/^ring-(?:ring|sidebar-ring)(?:\/(.+))?$/);
+    if (halo) return halo[1] !== '50';
+    return /^(?:border|inset-ring|outline)-(?:ring|sidebar-ring)\/.+$/.test(value);
+  });
 }