themelia-react-ui 1.0.0 → 1.0.2

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

@@ -0,0 +1,317 @@
+import { surfaceParts, surfaceForwarders, paddingClass, paddingProperty, utility, attenuatedFocusRing, sharedCornerParts, displayNames, nativeDisplayNames, marginProperty, radiusProperty, replacesSharedRadius, cornerRole, addsCopyMargin } from './surface-policy.mjs';
+
+const controlNames = /^(?:Base)?(?:Button|ButtonLink|IconButton)$|^(Input|InputGroup|InputGroupInput|InputGroupTextarea|Textarea|PasswordInput|Select|SelectTrigger|ComboboxInput|ComboboxInputTrigger|ComboboxTrigger)$/;
+const controlFamilies = new Set(['buttons', 'text-inputs', 'choice-inputs', 'combobox']);
+const fixedControlClass = /^(?:h|min-h|size|p[xytrblse]?)-|^rounded-(?:xs|sm|md|lg|xl|[2-9]xl|\[)|^text-(?:xs|sm|base|lg|xl|[2-9]xl|\[(?:length:|[\d.]+(?:px|rem|em)))|^(?:font|leading|tracking)-/;
+const controlStyle = /^(height|minHeight|fontSize|fontWeight|fontFamily|lineHeight|letterSpacing|borderRadius)$/;
+const fixedTextClass = /^text-(?:xs|sm|base|lg|xl|[2-9]xl|\[(?:length:|[\d.]+(?:px|rem|em)))|^(?:font|leading|tracking)-/;
+const textStyle = /^(fontSize|fontWeight|fontFamily|lineHeight|letterSpacing)$/;
+const smallPeerGaps = new Set(['none', 'normal', 'dense', '2xs', 'xs', 'sm', 'md']);
+const structureDefaults = { Stack: 'md', Grid: 'xl', AdaptiveGrid: 'xl' };
+const breakpoints = ['base', 'sm', 'md', 'lg', 'xl', '2xl'];
+
+/** Bind this source only; never resolve imports, read libraries or run app code. */
+export function sourceBindings(source, ts) {
+  const options = { noResolve: true, noLib: true, allowJs: true, jsx: ts.JsxEmit.Preserve };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = filename => filename === source.fileName ? source : undefined;
+  const checker = ts.createProgram([source.fileName], options, host).getTypeChecker();
+  return node => {
+    if (!node) return undefined;
+    if (ts.isIdentifier(node) && ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node) return checker.getShorthandAssignmentValueSymbol(node.parent);
+    return checker.getSymbolAtLocation(node);
+  };
+}
+
+/** Small static review: TypeScript is supplied by the app, never a runtime peer. */
+export function analyzeComposition(text, { filename, index, ts }) {
+  const kind = /\.jsx?$/.test(filename) ? ts.ScriptKind.JSX : filename.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+  const source = ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true, kind);
+  const symbolFor = sourceBindings(source, ts);
+  const families = new Map(index.families.map(owner => [owner.import, owner]));
+  const bindings = new Map();
+  const namespaces = new Map();
+  const declarations = new Map();
+  const findings = [];
+  const unresolved = [];
+  const seen = new Set();
+  const add = (node, rule, severity, message) => {
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    const key = `${node.pos}:${rule}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push({ file: filename, line: position.line + 1, column: position.character + 1, rule, severity, message });
+  };
+  const unknown = node => {
+    const key = `${node.pos}:unresolved`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    unresolved.push({ file: filename, line: position.line + 1, expression: node.getText(source).slice(0, 120) });
+  };
+  const resolve = (node, visiting = new Set()) => {
+    if (!node || visiting.has(node)) return undefined;
+    visiting.add(node);
+    if (ts.isIdentifier(node)) return resolve(declarations.get(symbolFor(node)), visiting);
+    if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return resolve(node.expression, visiting);
+    return node;
+  };
+  const properties = (expression, mark = true, visited = new Set()) => {
+    const node = resolve(expression);
+    if (!node || !ts.isObjectLiteralExpression(node) || visited.has(node)) {
+      if (mark && expression) unknown(expression);
+      return [];
+    }
+    visited.add(node);
+    return node.properties.flatMap(property => {
+      if (ts.isSpreadAssignment(property)) return properties(property.expression, mark, visited);
+      const name = property.name;
+      const key = ts.isComputedPropertyName(name) ? resolve(name.expression) : name;
+      if (!key || !(ts.isIdentifier(key) || ts.isStringLiteralLike(key))) {
+        if (mark) unknown(property);
+        return [];
+      }
+      return [[key.text, ts.isShorthandPropertyAssignment(property) ? property.name : property.initializer]];
+    });
+  };
+  const classStrings = (expression, visited = new Set()) => {
+    const node = resolve(expression);
+    if (!node || visited.has(node)) { if (expression) unknown(expression); return []; }
+    visited.add(node);
+    if (ts.isStringLiteralLike(node)) return [node.text];
+    if (ts.isTemplateExpression(node)) {
+      // Keep complete static class tokens. A token split by a dynamic span is
+      // unresolved rather than an invented class from one of its fragments.
+      const chunks = [node.head.text];
+      for (const span of node.templateSpans) {
+        const resolved = resolve(span.expression);
+        if (resolved && (ts.isStringLiteralLike(resolved) || ts.isNumericLiteral(resolved))) chunks[chunks.length - 1] += resolved.text + span.literal.text;
+        else { unknown(span.expression); chunks.push(span.literal.text); }
+      }
+      return chunks.map((chunk, index) => {
+        const value = index > 0 ? chunk.replace(/^\S*/, '') : chunk;
+        return index < chunks.length - 1 ? value.replace(/\S*$/, '') : value;
+      });
+    }
+    if (ts.isConditionalExpression(node)) return [...classStrings(node.whenTrue, visited), ...classStrings(node.whenFalse, visited)];
+    if (ts.isBinaryExpression(node) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) return classStrings(node.right, visited);
+    if (ts.isArrayLiteralExpression(node)) return node.elements.flatMap(item => classStrings(item, visited));
+    if (ts.isCallExpression(node) && /^(cn|clsx|classNames|twMerge)$/.test(node.expression.getText(source))) return node.arguments.flatMap(item => classStrings(item, visited));
+    if ([ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind)) return [];
+    unknown(expression);
+    return [];
+  };
+  const literal = expression => {
+    const node = resolve(expression);
+    return node && ts.isStringLiteralLike(node) ? node.text : undefined;
+  };
+  function importOwner(node, specifier) {
+    if (specifier !== index.package && !specifier.startsWith(index.package + '/')) return;
+    if (index.stylesheets?.includes(specifier)) return;
+    const family = families.get(specifier);
+    if (!family) { add(node, 'public-import', 'error', `No published owner for ${specifier}; discover the version-matched public entrypoint.`); return; }
+    const names = ts.isImportDeclaration(node) ? node.importClause?.namedBindings : node.exportClause;
+    if (ts.isImportDeclaration(node) && node.importClause?.name && !family.symbols.includes('default')) add(node.importClause.name, 'public-symbol', 'error', `${specifier} has no default export; use its named public symbols.`);
+    const elements = names && (ts.isNamedImports(names) || ts.isNamedExports(names)) ? names.elements : [];
+    for (const item of elements) {
+      const symbol = (item.propertyName ?? item.name).text;
+      if (!family.symbols.includes(symbol)) add(item, 'public-symbol', 'error', `${specifier} does not export ${symbol}; inspect its declaration.`);
+      if (ts.isImportDeclaration(node)) bindings.set(symbolFor(item.name), { symbol, import: specifier });
+    }
+    if (names && ts.isNamespaceImport(names)) namespaces.set(symbolFor(names.name), specifier);
+  }
+  function gather(node) {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) declarations.set(symbolFor(node.name), node.initializer);
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) importOwner(node, node.moduleSpecifier.text);
+    if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal)) importOwner(node, node.argument.literal.text);
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && ts.isStringLiteralLike(node.arguments[0])) importOwner(node, node.arguments[0].text);
+    ts.forEachChild(node, gather);
+  }
+  gather(source);
+  for (const diagnostic of source.parseDiagnostics) add(source, 'syntax', 'error', ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+  const ownerFor = tag => {
+    if (ts.isIdentifier(tag)) return bindings.get(symbolFor(tag));
+    if (ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression)) {
+      const specifier = namespaces.get(symbolFor(tag.expression));
+      return specifier ? { symbol: tag.name.text, import: specifier } : undefined;
+    }
+  };
+  const attributes = node => node.attributes.properties.flatMap(attribute => {
+    if (ts.isJsxSpreadAttribute(attribute)) return properties(attribute.expression);
+    if (!attribute.initializer) return [[attribute.name.getText(source), undefined]];
+    const expression = ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
+    return [[attribute.name.getText(source), expression]];
+  });
+  const isOwner = (owner, suffix, names) => owner?.import === `${index.package}/${suffix}` && names.includes(owner.symbol);
+  const framedOwner = (owner, props) => {
+    if (literal(props.get('surface')) === 'flat') return false;
+    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
+    if (isOwner(owner, 'blocks/analytics', ['Metric'])) return literal(props.get('variant')) === 'card';
+    if (isOwner(owner, 'blocks/analytics', ['MetricGrid'])) return !props.has('variant') || literal(props.get('variant')) === 'card';
+    return isOwner(owner, 'blocks/analytics/usage-card', ['UsageCard']) || isOwner(owner, 'blocks/analytics', ['UsageCard']) || isOwner(owner, 'blocks/planning', ['TaskCard']);
+  };
+  // Examine lexical JSX only. Names ending in Card are not evidence of framing;
+  // ChartCard is card-free; Receipt's flat paper has no ordinary Card frame.
+  const contentElements = element => {
+    const found = [];
+    function collect(child) {
+      if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
+        const opening = ts.isJsxElement(child) ? child.openingElement : child;
+        const owner = ownerFor(opening.tagName);
+        found.push({ opening, owner, props: new Map(attributes(opening)), element: child });
+        if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) return;
+        if (ts.isJsxElement(child)) child.children.forEach(collect);
+        return;
+      }
+      if (ts.isJsxFragment(child)) child.children.forEach(collect);
+      else if (ts.isJsxExpression(child) && child.expression) { const resolved = resolve(child.expression); if (resolved) collect(resolved); }
+    }
+    if (ts.isJsxElement(element.parent)) element.parent.children.forEach(collect);
+    return found;
+  };
+  const renderedText = element => ts.isJsxElement(element) ? element.children.map(child => ts.isJsxText(child) ? child.text : ts.isJsxExpression(child) ? literal(child.expression) ?? '' : '').join(' ').trim() : '';
+  const slotBadge = expression => {
+    const node = resolve(expression);
+    if (!node) return false;
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const owner = ownerFor(opening.tagName);
+      if (isOwner(owner, 'base/badge', ['Badge'])) return true;
+      if (owner?.import === `${index.package}/base/buttons` || /^(button|a)$/.test(opening.tagName.getText(source))) return false;
+      if (!/^(div|span)$/.test(opening.tagName.getText(source)) && !isOwner(owner, 'base/structure', ['Stack', 'Grid'])) return false;
+      return ts.isJsxElement(node) && node.children.some(slotBadge);
+    }
+    if (ts.isJsxFragment(node)) return node.children.some(slotBadge);
+    if (ts.isJsxExpression(node)) return slotBadge(node.expression);
+    return false;
+  };
+  const peerCards = element => {
+    if (!ts.isJsxElement(element.parent)) return new Set();
+    const cards = [];
+    function collect(child) {
+      if (ts.isJsxFragment(child)) { child.children.forEach(collect); return; }
+      const opening = ts.isJsxElement(child) ? child.openingElement : ts.isJsxSelfClosingElement(child) ? child : undefined;
+      if (!opening) return;
+      const owner = ownerFor(opening.tagName);
+      if (framedOwner(owner, new Map(attributes(opening)))) cards.push(opening);
+      else if (owner?.symbol === 'GridCell' && owner.import === `${index.package}/base/structure` && ts.isJsxElement(child)) child.children.forEach(collect);
+    }
+    element.parent.children.forEach(collect);
+    return new Set(cards);
+  };
+  const gapEntries = (expression, fallback) => {
+    if (!expression) return { base: fallback };
+    const node = resolve(expression);
+    if (node && ts.isStringLiteralLike(node)) return { base: node.text };
+    if (node && ts.isObjectLiteralExpression(node)) return { base: fallback, ...Object.fromEntries(properties(node).filter(([key]) => breakpoints.includes(key)).map(([key, value]) => {
+      const gap = literal(value);
+      if (gap === undefined && value) unknown(value);
+      return [key, gap];
+    })) };
+    if (node && node.kind === ts.SyntaxKind.NullKeyword || ts.isIdentifier(expression) && expression.text === 'undefined' && !symbolFor(expression)) return { base: fallback };
+    unknown(expression);
+    return { base: undefined };
+  };
+  const smallGap = (props, symbol, unknownProps) => {
+    // Unknown spread props may replace a missing gap. Report them as unresolved
+    // instead of treating the live default as a proven effective value.
+    if (!props.has('gap') && unknownProps) return false;
+    const gaps = gapEntries(props.get('gap'), structureDefaults[symbol]);
+    const rows = symbol === 'Stack' ? {} : gapEntries(props.get('rowGap'));
+    const columns = symbol === 'Stack' ? {} : gapEntries(props.get('columnGap'));
+    let gap; let row; let column;
+    return breakpoints.some(breakpoint => {
+      if (Object.hasOwn(gaps, breakpoint)) gap = gaps[breakpoint];
+      if (Object.hasOwn(rows, breakpoint)) row = rows[breakpoint];
+      if (Object.hasOwn(columns, breakpoint)) column = columns[breakpoint];
+      return smallPeerGaps.has(row ?? gap) || smallPeerGaps.has(column ?? gap);
+    });
+  };
+  function visit(node, parents = []) {
+    if (ts.isJsxElement(node)) {
+      const element = node.openingElement;
+      const context = inspect(element, parents);
+      for (const child of node.children) visit(child, context ? [...parents, context] : parents);
+      // JSX in props is a separate region, not a child frame.
+      for (const attribute of element.attributes.properties) ts.forEachChild(attribute, child => visit(child, parents));
+      return;
+    }
+    if (ts.isJsxSelfClosingElement(node)) inspect(node, parents);
+    ts.forEachChild(node, child => visit(child, parents));
+  }
+  function inspect(node, parents) {
+    const owner = ownerFor(node.tagName);
+    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.');
+      if (/^(?:input|textarea)$/.test(node.tagName.getText(source))) {
+        const props = new Map(attributes(node));
+        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'inner'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-inner; change the global theme root, not per-field corners.');
+        if (props.has('style') && properties(props.get('style')).some(([name])=>radiusProperty.test(name))) add(node,'shared-radius','error','Native editable corners belong to the global radius root, not inline styles.');
+      }
+      if (nativeDisplayNames.test(node.tagName.getText(source))) {
+        const props = new Map(attributes(node));
+        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(addsCopyMargin)) add(node,'copy-margin','error','Display copy is margin-free; use the surrounding structure for copy gaps.');
+        if (props.has('style') && properties(props.get('style')).some(([name,value])=>marginProperty.test(name)&&!/^['"]?0(?:px|rem|em|%)?['"]?$/.test(resolve(value)?.getText(source)??''))) add(node,'copy-margin','error','Display copy is margin-free; use the surrounding structure for copy gaps.');
+      }
+      return;
+    }
+    if (!families.get(owner.import)?.symbols.includes(owner.symbol)) {
+      add(node, 'public-symbol', 'error', `${owner.import} does not export ${owner.symbol}.`);
+      return;
+    }
+    const unresolvedBeforeProps = unresolved.length;
+    const props = new Map(attributes(node));
+    const unknownProps = unresolved.length !== unresolvedBeforeProps;
+    const family = owner.import.split('/base/')[1];
+    const anatomy = surfaceParts[family]?.test(owner.symbol);
+    const forwarder = surfaceForwarders[family] === owner.symbol;
+    const control = controlFamilies.has(family) && controlNames.test(owner.symbol);
+    const sharedCorners = sharedCornerParts[family]?.test(owner.symbol);
+    const display = owner.import === `${index.package}/typography` && displayNames.test(owner.symbol);
+    const fixedText = owner.import === `${index.package}/typography` && owner.symbol === 'DisplayLabel' || family === 'badge' && owner.symbol === 'Badge';
+    const badge = family === 'badge' && owner.symbol === 'Badge';
+    for (const name of ['className', 'headerClassName', 'contentClassName', 'footerClassName', 'subHeadingClassName']) {
+      if (!props.has(name)) continue;
+      const classes = classStrings(props.get(name)).flatMap(value => value.split(/\s+/)).map(utility);
+      if ((anatomy || forwarder && name === 'contentClassName') && classes.some(value => paddingClass.test(value))) add(node, 'surface-padding', 'error', `${owner.symbol}: use inset/type/density and public regions; padding overrides replace owned anatomy.`);
+      if (control && name === 'className' && classes.some(value => fixedControlClass.test(value))) add(node, 'control-anatomy', 'error', `${owner.symbol}: use its size/variant props; preserve shared control height, inset, corners and typography.`);
+      if ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'inner' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-radius; controls and collection rows use bounded rounded-inner. Preserve the owning role and joined-edge resets.`);
+      if (display && classes.some(addsCopyMargin)) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; use textGap on the headed owner or gap on Stack/Grid.`);
+      if ((control || family === 'buttons' && owner.symbol === 'TextButton') && name === 'className' && classes.some(attenuatedFocusRing)) add(node, 'focus-ring-contrast', 'error', `${owner.symbol}: keep the shared ring-ring/sidebar-ring focus color at full strength; numeric opacity weakens its tested contrast.`);
+      if (fixedText && name === 'className' && classes.some(value => fixedTextClass.test(value) || badge && /^rounded(?:-|$)/.test(value))) add(node, 'fixed-text-role', 'error', `${owner.symbol}: preserve its shared typography${badge ? ' and radius' : ''}; use its public variants and className for placement.`);
+    }
+    if (props.has('style')) for (const [name,value] of properties(props.get('style'))) {
+      if (anatomy && paddingProperty.test(name)) add(node, 'surface-padding', 'error', `${owner.symbol}: ${name} replaces the region inset; use its public surface props.`);
+      if (control && (paddingProperty.test(name) || controlStyle.test(name))) add(node, 'control-anatomy', 'error', `${owner.symbol}: ${name} belongs to shared control geometry/typography.`);
+      if ((control || sharedCorners) && radiusProperty.test(name)) add(node,'shared-radius','error',`${owner.symbol}: corners follow the global radius theme root, not inline styles.`);
+      if (display && marginProperty.test(name) && !/^['"]?0(?:px|rem|em|%)?['"]?$/.test(resolve(value)?.getText(source)??'')) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; the surrounding structure owns its copy gap.`);
+      if (fixedText && (textStyle.test(name) || badge && /^border.*Radius$/.test(name))) add(node, 'fixed-text-role', 'error', `${owner.symbol}: ${name} replaces its shared text/radius recipe.`);
+    }
+    if (['SmartCard', 'ContentBlock'].includes(owner.symbol)) add(node, 'deprecated-owner', 'warning', `${owner.symbol} is a migration owner; prefer Card for new compositions.`);
+    const framed = framedOwner(owner, props);
+    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) {
+      for (const slot of ['headerAction', 'headerStart']) if (slotBadge(props.get(slot))) add(node, 'card-badge-placement', 'error', `${owner.symbol}: put status/count/version badges in titleSuffix; ${slot} owns ${slot === 'headerAction' ? 'commands' : 'pre-title context'}.`);
+      const contents = contentElements(node);
+      const role = (item, names) => isOwner(item.owner, 'typography', names);
+      const valueHeading = contents.some(item => role(item, ['Heading']) && /[$€£¥]|\d/.test(renderedText(item.element)));
+      if (valueHeading && contents.some(item => role(item, ['Text', 'DisplayLabel'])) && contents.some(item => isOwner(item.owner, 'base/badge', ['Badge']) && /[%+−-]|\d/.test(renderedText(item.element)))) add(node, 'reinvented-metric-card', 'warning', 'This label/value/change composition resembles a KPI. Compare Metric/MetricGrid from blocks/analytics or InlineStat from blocks/data-display; retain a custom subject when their metric lifecycle does not fit.');
+      const factRows = contents.filter(item => isOwner(item.owner, 'base/structure', ['Stack']) && literal(item.props.get('direction')) === 'horizontal' && literal(item.props.get('justify')) === 'between' && contentElements(item.opening).filter(child => role(child, ['Text', 'DisplayLabel'])).length >= 2);
+      if (factRows.length >= 2) add(node, 'reinvented-metadata-list', 'warning', 'Repeated label/value rows resemble record facts. Compare MetadataList or InlineStat from blocks/data-display; preserve custom rows when they own distinct interactions or content.');
+      if (contents.some(item => role(item, ['Heading']) && /^(?:no\b|nothing\b|empty\b)/i.test(renderedText(item.element))) && contents.some(item => isOwner(item.owner, 'base/structure', ['Stack']) && literal(item.props.get('align')) === 'center') && contents.some(item => isOwner(item.owner, 'base/buttons', ['Button', 'ButtonLink']))) add(node, 'reinvented-empty-state', 'warning', 'This centered empty region may fit EmptyState from blocks/data-display, with media, title, description and actions. Review the product state before choosing the complete owner.');
+    }
+    if (isOwner(owner, 'base/feedback', ['Empty'])) add(node, 'reinvented-empty-state', 'warning', 'Empty exposes lower-level anatomy. Compare EmptyState from blocks/data-display for a routine no-data/no-results region; keep Empty when custom anatomy is required.');
+    if (isOwner(owner, 'base/sheet', ['Sheet', 'SheetContent']) || isOwner(owner, 'base/display', ['Dialog', 'DialogContent', 'AlertDialog', 'AlertDialogContent'])) add(node, 'raw-overlay-primitive', 'warning', 'This lower-level modal needs application lifecycle coordination. Prefer ActionDialog, ConfirmDialog or ActionDrawer from features/overlays when their workflow fits.');
+    if (owner.symbol === 'Page' && literal(props.get('gutter')) === 'none' && !parents.some(parent => parent.framed)) add(node, 'page-gutter', 'warning', 'Page gutter="none" delegates inline padding to a real parent. PageViewport owns scrolling, not padding; verify the parent inset.');
+    if (owner.symbol === 'Card' && framed && literal(props.get('padding')) === 'sm' && !parents.some(parent => parent.framed)) add(node, 'compact-card', 'warning', 'Standalone Card padding="sm" halves the normal inset. Omit padding for ordinary subjects; retain sm only for an intentional compact composition.');
+    const peers = parents.findLast(parent => parent.structure);
+    if (framed && (!props.has('surface') || literal(props.get('surface')) === 'framed') && peers?.cards.size > 1 && peers.cards.has(node) && peers.smallGap) add(node, 'card-peer-gap', 'warning', 'Small peer gaps can be consumed by framed Card rings. Use lg/xl for independent surfaces and inspect visible edge clearance; tighter grouping needs an intentional surface policy.');
+    if (framed && parents.some(parent => parent.framed)) add(node, 'nested-surface', 'warning', `${owner.symbol} is inside a framed owner. Review subject boundaries; use surface="flat" when the parent owns the frame.`);
+    const header = properties(props.get('header'), false);
+    const 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);
+    return { framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
+  }
+  visit(source);
+  return { findings, unresolved };
+}

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

@@ -3,11 +3,16 @@ const requireFormat = (condition, message) => { if (!condition) throw new Error(
 const stringList = value => Array.isArray(value) && value.every(item => typeof item === 'string');
 const text = value => typeof value === 'string' && value.trim().length > 0;
 const normalized = value => value.toLowerCase();
+const words = value => value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z])([A-Z][a-z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+const symbolKey = value => words(value).join('');
+const searchable = value => words(value).join(' ');
+const containsTerms = (value, terms) => { const tokens = new Set(words(value)); return terms.every(term => tokens.has(term)); };
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 
 export function validateIndex(index) {
   requireFormat(index?.schemaVersion === 1 && index?.discoveryVersion === 1, 'unsupported schema/format; expected schemaVersion 1 and discoveryVersion 1');
   requireFormat(text(index.package) && text(index.version) && Array.isArray(index.families), 'package, version and families are required');
+  if (index.stylesheets !== undefined) requireFormat(stringList(index.stylesheets) && index.stylesheets.every(file => file.startsWith(index.package + '/') && file.endsWith('.css') && !file.includes('..')), 'invalid public stylesheets');
   const seen = new Set();
   for (const family of index.families) {
     requireFormat(text(family?.import) && (family.import === index.package || family.import.startsWith(`${index.package}/`)) && !/[\\\s]|(?:^|\/)\.\.(?:\/|$)/.test(family.import), 'invalid public import');
@@ -16,7 +21,17 @@ 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.references !== undefined) requireFormat(stringList(family.references) && family.references.every(file => /^references\/[\w/-]+\.md(?:#[\w-]+)?$/.test(file) && !file.split('/').includes('..')), `invalid focused references for ${family.import}`);
     requireFormat(family.optionalPeers.every(peer => index.peers?.some(owner => owner.name === peer && owner.optional)), `unknown optional peer for ${family.import}`);
+    if (family.recipes !== undefined) {
+      requireFormat(Array.isArray(family.recipes), `invalid recipes for ${family.import}`);
+      for (const recipe of family.recipes) {
+        requireFormat(text(recipe?.file) && /^examples\/[\w/-]+\.tsx$/.test(recipe.file) && !recipe.file.split('/').includes('..'), 'invalid recipe file');
+        requireFormat(stringList(recipe.exports) && recipe.exports.length > 0 && stringList(recipe.symbols) && recipe.symbols.every(symbol => family.symbols.includes(symbol)), `unknown recipe symbol for ${family.import}`);
+        requireFormat(stringList(recipe.references) && recipe.references.every(file => /^references\/[\w/-]+\.md(?:#[\w-]+)?$/.test(file) && !file.split('/').includes('..')), 'invalid recipe references');
+        if (recipe.optionalPeers !== undefined) requireFormat(stringList(recipe.optionalPeers) && recipe.optionalPeers.every(peer => index.peers?.some(owner => owner.name === peer && owner.optional)), 'invalid recipe optional peers');
+      }
+    }
     requireFormat(Array.isArray(family.guidance), `invalid guidance for ${family.import}`);
     for (const guide of family.guidance) {
       requireFormat(text(guide?.title) && typeof guide.description === 'string' && typeof guide.section === 'string', 'invalid guidance title/description/section');
@@ -55,24 +70,66 @@ export function parseArguments(args) {
   return { query, ...options };
 }
 
-const guideText = guide => normalized([guide.title, guide.description, ...Object.values(guide.browse), ...guide.jobs, ...guide.tags, ...guide.aliases, ...guide.chooseWhen, ...guide.appOwned, ...guide.sections.flatMap(section => [section.title, ...section.symbols])].join(' '));
+const guideText = guide => searchable([guide.title, guide.description, ...Object.values(guide.browse), ...guide.jobs, ...guide.tags, ...guide.aliases, ...guide.chooseWhen, ...guide.appOwned, ...guide.sections.flatMap(section => [section.title, ...section.symbols])].join(' '));
+const guideSymbols = (guide, family) => [...new Set(guide.sections.flatMap(section => section.symbols))].filter(symbol => family.symbols.includes(symbol));
+
+function relevantGuidance(family, needle, terms, matchedSymbols, exactImport) {
+  const ranked = family.guidance.map(guide => {
+    const haystack = guideText(guide);
+    const count = terms.filter(term => containsTerms(haystack, [term])).length;
+    const symbol = matchedSymbols.some(value => guideSymbols(guide, family).includes(value));
+    const alias = guide.aliases.some(value => normalized(value) === needle);
+    const complete = count === terms.length;
+    const score = Number(alias) * 10000 + Number(symbol) * 1000 + Number(complete) * 100 + count;
+    return { guide, score, symbol, alias, complete };
+  }).sort((a, b) => b.score - a.score || Number(guideSymbols(b.guide, family).length > 0) - Number(guideSymbols(a.guide, family).length > 0) || compare(a.guide.title, b.guide.title));
+  // Exact owner and curated task matches supply their own narrow reading path.
+  // Generic intent can still combine terms across fields/family guidance.
+  const selected = ranked.filter(item => ranked.some(item => item.alias) ? item.alias : matchedSymbols.length ? item.symbol : ranked.some(item => item.complete) ? item.complete : item.score > 0);
+  return (selected.length || !exactImport ? selected : ranked).slice(0, 3).map(item => item.guide);
+}
 
 export function findComponents(index, { query, layer = null, limit = 5 }) {
   validateIndex(index);
   const needle = normalized(query);
-  const terms = [...new Set(needle.split(/\s+/).filter(Boolean))];
+  const terms = [...new Set(words(query))];
+  const key = symbolKey(query);
+  // Cased API names and explicit imports request a precise contract. Ordinary
+  // nouns such as table/empty remain task searches with richer alternatives.
+  const exactOwners = index.families.filter(family => (!layer || layer === family.layer) && (normalized(family.import) === needle || family.symbols.includes(query.trim())));
   const ranked = [];
   for (const family of index.families) {
     if (layer && layer !== family.layer) continue;
+    if (exactOwners.length && !exactOwners.includes(family)) continue;
     const exactImport = normalized(family.import) === needle;
-    const matchedSymbols = family.symbols.filter(symbol => normalized(symbol) === needle);
-    const haystack = normalized([family.import, family.responsibility, ...family.symbols, ...family.jobs, ...family.tags, ...family.aliases, ...family.sections, ...family.guidance.map(guideText)].join(' '));
+    const matchedSymbols = family.symbols.filter(symbol => symbolKey(symbol) === key);
+    const documented = new Set(family.guidance.flatMap(guide => guideSymbols(guide, family)));
+    const focusedSymbols = [...documented].filter(symbol => containsTerms(symbol, terms));
+    const haystack = searchable([family.import, family.responsibility, ...documented, ...family.jobs, ...family.tags, ...family.aliases, ...family.sections, ...family.guidance.map(guideText)].join(' '));
     // AND matching prevents a familiar term from inventing results for an
     // otherwise unknown query. Avoidance/alternatives do not recommend owners.
-    if (!exactImport && !matchedSymbols.length && !terms.every(term => haystack.includes(term))) continue;
-    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 : terms.reduce((sum, term) => sum + (family.guidance.some(guide => normalized(guide.title).includes(term)) ? 20 : family.tags.some(tag => normalized(tag).includes(term)) ? 10 : 1), 0);
-    const guidance = family.guidance.map(guide => ({ guide, score: terms.filter(term => guideText(guide).includes(term)).length })).sort((a, b) => b.score - a.score || compare(a.guide.title, b.guide.title)).slice(0, 3).map(({ guide }) => guide);
-    ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', matchedSymbols, guidance });
+    if (!exactImport && !matchedSymbols.length && !containsTerms(haystack, terms)) continue;
+    // A dedicated, documented owner precedes an aggregate re-export of the
+    // same symbol. Explicit import queries still select the requested family.
+    const documentedSymbol = matchedSymbols.some(symbol => documented.has(symbol));
+    const exactFamily = searchable(family.import.split('/').at(-1)) === terms.join(' ');
+    const exactIntent = family.aliases.some(alias => normalized(alias) === needle);
+    const score = exactImport ? 10000 : matchedSymbols.length ? 9000 + Number(documentedSymbol) : exactFamily ? 8500 : exactIntent ? 8000 : focusedSymbols.length ? 7100 + 1 / Math.min(...focusedSymbols.map(symbol => words(symbol).length)) : terms.reduce((sum, term) => sum + (family.guidance.some(guide => containsTerms(guide.title, [term])) ? 20 : family.tags.some(tag => containsTerms(tag, [term])) ? 10 : 1), 0);
+    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 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+/)));
+    const aliasRecipes = matchedSymbols.length || exactImport ? [] : candidates.filter(recipe => aliases.some(intent => intent.every(term => recipeText(recipe).includes(term))));
+    const recipes = taskRecipes.length ? taskRecipes : aliasRecipes.length ? aliasRecipes : candidates;
+    const nextReads = {
+      declaration: family.declaration,
+      references: [...new Set([...(family.references ?? []), ...recipes.flatMap(recipe => recipe.references)])].sort(compare),
+      examples: recipes.map(({ file, exports, symbols, optionalPeers = [] }) => ({ file, exports, symbols: symbols.filter(symbol => relevantSymbols.includes(symbol)), optionalPeers })),
+    };
+    ranked.push({ score, import: family.import, declaration: family.declaration, layer: family.layer, responsibility: family.responsibility, optionalPeers: family.optionalPeers, match: exactImport ? 'import' : matchedSymbols.length ? 'symbol' : 'intent', matchedSymbols, relevantSymbols, 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/surface-policy.mjs

@@ -0,0 +1,66 @@
+// One public anatomy vocabulary, shared by repository and opt-in consumer checks.
+export const surfaceParts = {
+  cards: /^Card(?:Header|Content|Footer)?$/,
+  popover: /^(PopoverContent|PopoverHeader|PopoverFooter)$/,
+  command: /^Command(Input|List|Group|Item|Empty|Separator)?$/,
+  navigation: /^DropdownMenu(Content|SubContent|Label|Item|LinkItem|SubTrigger|CheckboxItem|RadioItem|Separator)$/,
+  'choice-inputs': /^SelectPopup(Content|Group|Item|Label|Separator)?$/,
+  combobox: /^Combobox(Popup|Content|List|Item|GroupLabel|Separator)$/,
+};
+export const surfaceForwarders = { 'choice-inputs': 'Select', 'popover-menu': 'PopoverMenu', 'action-menu': 'ActionMenu' };
+export const paddingClass = /^(?:p[xytrblse]?|p(?:bs|be)|padding)-|^\[padding/;
+export const paddingProperty = /^padding(?:Inline|Block)?(?:Start|End)?$|^padding(?:Top|Right|Bottom|Left)$|^padding-(?:(?:inline|block)(?:-(?:start|end))?|top|right|bottom|left)$/;
+
+// One root, two owned roles: outer shells and inner controls/collection rows.
+// Circular shapes and joined-edge resets retain their explicit mechanics.
+export const sharedCornerParts = {
+  cards: /^Card$/,
+  popover: /^PopoverContent$/,
+  command: /^Command(?:Item)?$/,
+  navigation: /^(?:DropdownMenu(?:Content|SubContent|Item|LinkItem|SubTrigger|CheckboxItem|RadioItem)|TabsList|TabsTrigger)$/,
+  'choice-inputs': /^SelectPopup(?:Content|Item)$/,
+  item: /^Item$/,
+  combobox: /^Combobox(?:Popup|Content|Item)$/,
+  display: /^(?:DialogContent|AlertDialogContent)$/,
+  sheet: /^SheetContent$/,
+};
+export const displayNames = /^(?:Text|Heading|DisplayLabel|Label|TextLink)$/;
+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$/;
+
+export function cornerRole(family, symbol) {
+  if (family === 'item' && symbol === 'Item' || family === 'navigation' && /^(?:TabsList|TabsTrigger)$/.test(symbol)) return 'inner';
+  return sharedCornerParts[family]?.test(symbol) && /(?:Item|SubTrigger)$/.test(symbol) ? 'inner' : 'radius';
+}
+
+export function replacesSharedRadius(token, role = 'radius') {
+  const value = utility(token);
+  if (new RegExp(`^rounded(?:-[trblse]{1,2})?-(?:${role}|none)$`).test(value)) return false;
+  return /^rounded(?:-|$)/.test(value) || /^\[border-(?:(?:top|bottom)-(?:left|right)-|(?:start|end)-(?:start|end)-)?radius:/.test(value);
+}
+
+export function addsCopyMargin(token) {
+  const value = utility(token);
+  const match = value.match(/^-?m(?:[xytrblse]|bs|be)?-(.+)$|^\[margin[^:]*:(.+)\]$/);
+  return !!match && !/^(?:0(?:px|rem|em|%)?|\[0(?:px|rem|em|%)?\])$/.test(match[1] ?? match[2]);
+}
+
+export function utility(token) {
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < token.length; i++) {
+    if (token[i] === '[' || token[i] === '(') depth++;
+    if (token[i] === ']' || token[i] === ')') depth--;
+    if (token[i] === ':' && depth === 0) start = i + 1;
+  }
+  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+)(%)?\])$/);
+  if (!match) return false;
+  const opacity = Number(match[1] ?? match[2]);
+  return opacity < (match[1] !== undefined || match[3] ? 100 : 1);
+}

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "themelia-react-ui",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A composable React UI library for modern admin applications, built on Base UI and Tailwind with shadcn-compatible themes, shared design tokens, reusable layouts, blocks and workflows.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "keywords": ["react", "ui", "admin", "dashboard", "base-ui", "tailwindcss", "shadcn", "design-system"],
+  "keywords": [
+    "react",
+    "ui",
+    "admin",
+    "dashboard",
+    "base-ui",
+    "tailwindcss",
+    "shadcn",
+    "design-system"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nicolasvlachos/themelia-react-ui.git"
@@ -413,6 +422,18 @@
     "./features/questionnaire": {
       "types": "./dist/components/features/questionnaire/index.d.ts",
       "import": "./dist/features/questionnaire.js"
+    },
+    "./base/inline-edit": {
+      "types": "./dist/components/base/inline-edit/index.d.ts",
+      "import": "./dist/base/inline-edit.js"
+    },
+    "./blocks/planning": {
+      "types": "./dist/components/blocks/planning/index.d.ts",
+      "import": "./dist/blocks/planning.js"
+    },
+    "./blocks/analytics/usage-card": {
+      "types": "./dist/components/blocks/analytics/usage-card/index.d.ts",
+      "import": "./dist/blocks/analytics/usage-card.js"
     }
   },
   "scripts": {
@@ -426,7 +447,7 @@
     "test:browser": "npm run build:preview && node scripts/run-browser.mjs",
     "check:package": "node scripts/check-package.mjs",
     "check": "npm run check:contract && npm run check:preview && npm run check:docs && npm run lint && npm run check:design-lint && npm run typecheck && npm test && npm run build && npm run check:skill && npm run check:maps && npm run check:package && npm run build:preview",
-    "check:contract": "node --test scripts/test-runtime-ownership.mjs scripts/test-primitive-geometry.mjs scripts/test-source-entrypoints.mjs && node scripts/check-contract.mjs",
+    "check:contract": "node --test scripts/test-runtime-ownership.mjs scripts/test-primitive-geometry.mjs scripts/test-source-entrypoints.mjs scripts/test-utility-vocabulary.mjs scripts/test-theme-contrast.mjs && node scripts/check-contract.mjs",
     "lint": "node scripts/generate-utilities.mjs && oxlint src/components src/lib src/preview docs/consumer-skill/examples --deny-warnings",
     "check:design-lint": "node scripts/generate-utilities.mjs && node scripts/check-design-lint.mjs",
     "check:preview": "node scripts/check-preview.mjs",
@@ -442,7 +463,7 @@
     "check:maps": "node scripts/test-client-boundaries.mjs --built",
     "build:docs": "node scripts/build-static-docs.mjs",
     "check:static-docs": "node scripts/check-static-docs.mjs",
-    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
+    "check:agent": "node --test scripts/test-consumer-discovery.mjs scripts/test-consumer-composition.mjs scripts/test-consumer-skill-assets.mjs scripts/test-static-docs.mjs scripts/test-fixture-install.mjs && npm run check:skill",
     "check:release": "npm run check:all && npm run check:agent && npm run build:docs && npm run check:static-docs"
   },
   "peerDependencies": {
@@ -495,6 +516,8 @@
     "@mdx-js/rollup": "^3.1.1",
     "@playwright/test": "^1.63.0",
     "@shadcn/lint": "0.2.0",
+    "@tailwindcss/node": "^4.3.3",
+    "@tailwindcss/oxide": "^4.3.3",
     "@tailwindcss/vite": "^4.3.3",
     "@tanstack/react-table": "^8.21.3",
     "@testing-library/jest-dom": "^6.0.0",
@@ -519,7 +542,9 @@
     "leaflet-draw": "^1.0.4",
     "leaflet.fullscreen": "^5.3.1",
     "leaflet.markercluster": "^1.5.3",
+    "lightningcss": "^1.33.0",
     "lucide-react": "^1.14.0",
+    "magic-string": "^0.30.21",
     "oxlint": "1.87.0",
     "qrcode": "^1.5.4",
     "react": "^19.2.5",
@@ -535,8 +560,7 @@
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.9.3",
     "vite": "^8.0.0",
-    "vitest": "^5.0.3",
-    "magic-string": "^0.30.21"
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=22.12.0"