@usefragments/core 1.6.0 → 1.7.0

package/src/facts/facts.test.ts

@@ -370,7 +370,7 @@ describe("FactIndex — query layer", () => {
     expect(unknownProps?.severity).toBe("error");
   });
 
-  it("activates prefer-library from top-level canonical sources", () => {
+  it("activates canonical-component rules from top-level canonical sources", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -397,6 +397,43 @@ describe("FactIndex — query layer", () => {
         ],
       },
     });
+    expect(ix.policy.ruleConfig("components/shadow-component")).toMatchObject({
+      enabled: true,
+      severity: "warn",
+      options: {
+        canonicalSources: [
+          {
+            kind: "npm",
+            specifier: "@usefragments/ui",
+            include: ["Button"],
+          },
+        ],
+      },
+    });
+  });
+
+  it("preserves an explicit shadow-component disable when canonical sources are declared", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        canonicalSources: [
+          {
+            kind: "npm",
+            specifier: "@usefragments/ui",
+            include: ["Button"],
+          },
+        ],
+        rules: {
+          "components/shadow-component": false,
+        },
+      })
+    );
+
+    expect(ix.policy.ruleConfig("components/prefer-library")?.enabled).toBe(true);
+    expect(ix.policy.ruleConfig("components/shadow-component")).toMatchObject({
+      enabled: false,
+      ruleId: "components/shadow-component",
+    });
   });
 
   it("resolves preferred import and component policy facts", () => {

package/src/facts/index.ts

@@ -48,6 +48,7 @@ export type {
   GovernanceRuleConfigFact,
   UsageNodeFact,
   UsageComponentFact,
+  UsageChildContentFact,
   UsageImportFact,
   UsagePropResolvedFact,
   UsageInlineStyleFact,
@@ -106,6 +107,7 @@ export {
   makeGovernanceRuleConfigFact,
   makeUsageNodeFact,
   makeUsageComponentFact,
+  makeUsageChildContentFact,
   makeUsageImportFact,
   makeUsagePropResolvedFact,
   makeUsageInlineStyleFact,

package/src/facts/types.ts

@@ -364,6 +364,20 @@ export interface UsageTextChildFact extends BaseFact {
   index: number;
 }
 
+/**
+ * Framework-neutral summary of the rendered child content for one usage node.
+ *
+ * An adapter that supports semantic child analysis preserves its existing prop
+ * facts and additionally emits exactly one summary per usage node, so rules do
+ * not have to interpret React's `children`, Vue slots, or Svelte snippets
+ * themselves. Adapters may add support independently.
+ */
+export interface UsageChildContentFact extends BaseFact {
+  kind: "usage_child_content";
+  nodeId: FactId;
+  content: "static-text" | "runtime" | "structural" | "empty";
+}
+
 // ---------------------------------------------------------------------------
 // Tailwind className facts.
 //
@@ -722,6 +736,7 @@ export type UsageFact =
   | UsagePropResolvedFact
   | UsageInlineStyleFact
   | UsageTextChildFact
+  | UsageChildContentFact
   | StyleDeclarationFact
   | StyleUnsupportedFact
   | ClassNameLiteralFact

package/src/governance-integrity.test.ts

@@ -343,7 +343,10 @@ describe("evaluateGovernanceIntegrity", () => {
       canonicalSources: [{ kind: "directory", path: "ui" }],
     };
     const verdict = evaluate({ policy, policySource: "config", declared: true });
-    expect(verdict.families.find((f) => f.id === "components")?.armed).toBe(true);
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: true,
+      rules: ["components/prefer-library", "components/shadow-component"],
+    });
     expect(verdict.status).toBe("healthy");
     expect(verdict.blockingCapable).toBe(false);
     expect(verdict.armed).toContain("components");
@@ -372,6 +375,83 @@ describe("evaluateGovernanceIntegrity", () => {
     expect(verdict.blockingCapable).toBe(true);
   });
 
+  it("4c. prefer-library disabled + canonical source leaves shadow governance armed", () => {
+    const policy: GovernanceConfig = {
+      severity: "error",
+      canonicalSources: [{ kind: "directory", path: "ui" }],
+      rules: { "components/prefer-library": false },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: true,
+      rules: ["components/shadow-component"],
+    });
+    expect(verdict.families.find((f) => f.id === "blocking-deny")?.rules).toEqual([
+      "components/shadow-component",
+    ]);
+    expect(verdict.status).toBe("healthy");
+    expect(verdict.blockingCapable).toBe(true);
+  });
+
+  it("4d. shadow-component disabled + canonical source leaves prefer-library armed", () => {
+    const policy: GovernanceConfig = {
+      severity: "error",
+      canonicalSources: [{ kind: "directory", path: "ui" }],
+      rules: { "components/shadow-component": false },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: true,
+      rules: ["components/prefer-library"],
+    });
+    expect(verdict.families.find((f) => f.id === "blocking-deny")?.rules).toEqual([
+      "components/prefer-library",
+    ]);
+  });
+
+  it("4e. explicitly disabling both canonical-component rules leaves the policy inert", () => {
+    const policy: GovernanceConfig = {
+      severity: "error",
+      canonicalSources: [{ kind: "directory", path: "ui" }],
+      rules: {
+        "components/prefer-library": false,
+        "components/shadow-component": false,
+      },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: false,
+      rules: [],
+      reason: "canonical-component rules not enabled",
+    });
+    expect(verdict.status).toBe("inert");
+    expect(verdict.blockingCapable).toBe(false);
+  });
+
+  it("4f. vocabulary on a disabled sibling rule cannot arm shadow governance", () => {
+    const policy: GovernanceConfig = {
+      rules: {
+        "components/prefer-library": {
+          enabled: false,
+          options: {
+            canonicalMappings: [
+              { name: "Button", htmlEquivalent: "button", importPath: "@acme/ui" },
+            ],
+          },
+        },
+        "components/shadow-component": { enabled: true, severity: "error" },
+      },
+    };
+    const verdict = evaluate({ policy, policySource: "config", declared: true });
+    expect(verdict.families.find((f) => f.id === "components")).toMatchObject({
+      armed: false,
+      rules: ["components/shadow-component"],
+      reason: "component governance enabled but no effective canonical source",
+    });
+    expect(verdict.status).toBe("inert");
+    expect(verdict.blockingCapable).toBe(false);
+  });
+
   it("5. npm source with NO include → components NOT armed → inert (blocker-#2 lock)", () => {
     const policy: GovernanceConfig = {
       canonicalSources: [{ kind: "npm", specifier: "@acme/ui" }],
@@ -445,6 +525,23 @@ describe("evaluateGovernanceIntegrity", () => {
     expect(tokens?.reason).toBe("no token vocabulary");
   });
 
+  it("7c. error-level token drift with a vocabulary is blocking-capable", () => {
+    const policy: GovernanceConfig = {
+      styles: [{ kind: "style.cssVars.mustBeDefined", severity: "error" }],
+    };
+    const verdict = evaluate({
+      policy,
+      policySource: "config",
+      declared: true,
+      cssVarsActive: true,
+      tokenVocabularySize: 5,
+    });
+    expect(verdict.families.find((family) => family.id === "blocking-deny")?.rules).toContain(
+      "tokens/css-vars-must-be-defined"
+    );
+    expect(verdict.blockingCapable).toBe(true);
+  });
+
   it("8. hygiene-only policy (raw-style rule enabled, no contract) → degraded", () => {
     const policy: GovernanceConfig = {
       rules: { "styles/no-raw-color": { enabled: true, severity: "warn" } },

package/src/governance-integrity.ts

@@ -4,7 +4,7 @@
  *
  * The load-bearing distinction is **enabled ≠ armed**. A rule can be `enabled`
  * in the policy yet inert because it has no vocabulary to measure against:
- * `components/prefer-library` with no effective canonical source enforces
+ * canonical-component rules with no effective canonical source enforce
  * nothing; `tokens/css-vars-must-be-defined` with an empty token vocabulary
  * enforces nothing. This module derives, per rule *family*, whether the family
  * is armed (has both an enabled rule AND the vocabulary/signal it needs), then
@@ -119,7 +119,7 @@ export function isEffectiveCanonicalSource(source: CanonicalSource): boolean {
 }
 
 /**
- * Whether `components/prefer-library`'s effective options carry a real component
+ * Whether a canonical-component rule's effective options carry a real component
  * vocabulary: at least one canonical mapping, or at least one effective
  * canonical source. Accepts the raw fact `options` bag (values are `unknown`).
  */
@@ -138,18 +138,27 @@ export function hasEffectiveComponentVocabulary(
 /**
  * Compile the policy to effective per-rule configs, keyed by rule id. Reuses the
  * fact compiler so the effective enabled/severity/options match exactly what the
- * scan engine sees (including the canonicalSources → prefer-library injection).
+ * scan engine sees (including canonicalSources → component-rule injection).
  */
 function effectiveRuleConfigs(
   policy: GovernanceConfig | undefined
 ): Map<string, EffectiveRuleConfig> {
   const configs = new Map<string, EffectiveRuleConfig>();
-  for (const fact of compileGlobalGovernanceFacts(policy)) {
-    if (fact.kind !== "governance_rule_config") continue;
-    configs.set(fact.ruleId, {
-      enabled: fact.enabled,
-      severity: fact.severity,
-      options: fact.options,
+  const facts = compileGlobalGovernanceFacts(policy);
+  for (const fact of facts) {
+    if (fact.kind === "governance_rule_config") {
+      configs.set(fact.ruleId, {
+        enabled: fact.enabled,
+        severity: fact.severity,
+        options: fact.options,
+      });
+    }
+  }
+  const cssVarsPolicy = facts.find((fact) => fact.kind === "style_css_vars_must_be_defined");
+  if (cssVarsPolicy?.kind === "style_css_vars_must_be_defined") {
+    configs.set("tokens/css-vars-must-be-defined", {
+      enabled: true,
+      severity: cssVarsPolicy.severity,
     });
   }
   return configs;
@@ -768,28 +777,34 @@ export function evaluateGovernanceIntegrity(
   }
 
   // --- components family ----------------------------------------------------
-  const componentsConfig = configs.get("components/prefer-library");
+  const preferLibraryConfig = configs.get("components/prefer-library");
+  const shadowComponentConfig = configs.get("components/shadow-component");
   const confirmedBridges = input.policy?.canonicalBridges ?? [];
-  const componentsArmed =
-    confirmedBridges.length > 0 ||
-    (componentsConfig?.enabled === true &&
-      hasEffectiveComponentVocabulary(componentsConfig.options));
+  const componentRuleEnabled =
+    preferLibraryConfig?.enabled === true || shadowComponentConfig?.enabled === true;
+  const preferLibraryArmed =
+    preferLibraryConfig?.enabled === true &&
+    hasEffectiveComponentVocabulary(preferLibraryConfig.options);
+  const shadowComponentArmed =
+    shadowComponentConfig?.enabled === true &&
+    hasEffectiveComponentVocabulary(shadowComponentConfig.options);
+  const componentsArmed = confirmedBridges.length > 0 || preferLibraryArmed || shadowComponentArmed;
   const componentsFamily: GovernanceIntegrityFamily = {
     id: "components",
     armed: componentsArmed,
     rules: [
       ...(confirmedBridges.length > 0 ? ["imports/preferred-path"] : []),
-      ...(componentsConfig?.enabled === true ? ["components/prefer-library"] : []),
+      ...(preferLibraryConfig?.enabled === true ? ["components/prefer-library"] : []),
+      ...(shadowComponentConfig?.enabled === true ? ["components/shadow-component"] : []),
     ],
   };
   if (!componentsArmed) {
-    if (componentsConfig?.enabled === true) {
-      componentsFamily.reason =
-        "components/prefer-library enabled but no effective canonical source";
+    if (componentRuleEnabled) {
+      componentsFamily.reason = "component governance enabled but no effective canonical source";
       componentsFamily.remediation =
         "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     } else {
-      componentsFamily.reason = "components/prefer-library not enabled";
+      componentsFamily.reason = "canonical-component rules not enabled";
       componentsFamily.remediation =
         "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     }
@@ -841,7 +856,12 @@ export function evaluateGovernanceIntegrity(
   for (const ruleId of BLOCKING_RULE_ALLOWLIST) {
     const config = configs.get(ruleId);
     if (config?.enabled !== true) continue;
-    const familyArmed = ruleId === "components/prefer-library" ? componentsArmed : hygieneArmed;
+    const familyArmed =
+      ruleId === "components/prefer-library" || ruleId === "components/shadow-component"
+        ? componentsArmed
+        : ruleId === "tokens/css-vars-must-be-defined"
+          ? tokensArmed
+          : hygieneArmed;
     if (!familyArmed) continue;
     if (config.severity !== "error" && !failOnWarnings) continue;
     blockingRules.push(ruleId);

package/src/index.ts

@@ -133,6 +133,11 @@ export {
 } from "./config-paths.js";
 
 // Types
+export {
+  CompiledFragmentsFileValidationError,
+  parseCompiledFragmentsFile,
+} from "./compiled-types/index.js";
+
 export type {
   FragmentComponent,
   ComponentRef,
@@ -666,6 +671,7 @@ export {
   ruleTailwindUnknownClass,
   ruleTokensRequireDualFallback,
   ruleA11yRequiredAccessibleName,
+  ruleA11yStandard,
 } from "./rules/index.js";
 export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
@@ -820,6 +826,7 @@ export {
   makeTailwindUnknownClassEnabledFact,
   makeUsageNodeFact,
   makeUsageComponentFact,
+  makeUsageChildContentFact,
   makeUsageImportFact,
   makeUsagePropResolvedFact,
   makeUsageInlineStyleFact,
@@ -963,6 +970,7 @@ export type {
   TailwindUnknownClassEnabledFact,
   UsageNodeFact,
   UsageComponentFact,
+  UsageChildContentFact,
   UsageImportFact,
   UsagePropResolvedFact,
   UsageInlineStyleFact,

package/src/rules/a11y-required-accessible-name.ts

@@ -1,7 +1,7 @@
 /**
- * `a11y/required-accessible-name` — fires for components with an
- * `a11y.requireName` policy whose JSX usage has no discoverable accessible
- * name.
+ * `a11y/required-accessible-name` — fires for a component with an authored
+ * `a11y.requireName` policy, or for a statically proven control when the global
+ * rule is enabled, whose JSX usage has no discoverable accessible name.
  *
  * Accepted name sources (any one is enough):
  *   - non-empty `usage_text_child` content
@@ -9,55 +9,107 @@
  *     dynamic value is empty at scan time)
  *   - `aria-labelledby={...}`
  *   - `title="..."`
+ *   - statically non-empty or conservatively classified runtime child content
+ *     on controls whose accessible-name model permits naming from contents
  *
  * Components that explicitly opt out via `aria-hidden="true"` are skipped —
  * they are not part of the accessibility tree.
  */
 
-import type { FactIndex, UsagePropResolvedFact } from "../facts/index.js";
+import type {
+  ComponentDefinitionFact,
+  FactIndex,
+  UsageComponentFact,
+  UsageChildContentFact,
+  UsageNodeFact,
+  UsagePropResolvedFact,
+} from "../facts/index.js";
 
+import { isAriaHidden } from "./a11y-utils.js";
 import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
-import { indexPropsByNodeId, indexTextChildrenByNodeId, readUsageNode } from "./utils.js";
+import { indexPropsByNodeId, indexTextChildrenByNodeId } from "./utils.js";
 
 export const RULE_ID = "a11y/required-accessible-name";
-export const RULE_VERSION = "1";
+export const RULE_VERSION = "2";
 
 const NAME_SOURCE_PROPS = new Set(["aria-label", "aria-labelledby", "title"]);
+const COMPONENT_NAME_SOURCE_PROPS = new Set([...NAME_SOURCE_PROPS, "label"]);
+const NAME_REQUIRED_TAGS = new Set(["button", "input", "select", "textarea"]);
+const NAME_REQUIRED_ROLES = new Set(["button", "checkbox", "radio", "switch", "tab"]);
+const NAME_FROM_CONTENT_TAGS = new Set(["button"]);
+const NAME_FROM_CONTENT_ROLES = new Set(["button", "checkbox", "radio", "switch", "tab"]);
+const NAME_REQUIRED_COMPONENT_SUFFIXES = [
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "checkbox",
+  "radio",
+  "switch",
+] as const;
 
 export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
   const findings: Finding[] = [];
   const propsByNode = indexPropsByNodeId(ix);
   const textByNode = indexTextChildrenByNodeId(ix);
+  const childContentByNode = new Map(
+    ix.byKind("usage_child_content").map((content) => [content.nodeId, content])
+  );
+  const globalPolicy = ix.policy.ruleConfig(RULE_ID);
+  const usageByNode = new Map(ix.byKind("usage_component").map((usage) => [usage.nodeId, usage]));
+  const definitions = new Map(
+    ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
+  );
 
-  for (const usageComponent of ix.byKind("usage_component")) {
-    const policy = ix.policy.a11yNameRequired(usageComponent.componentId);
-    if (!policy) continue;
-
-    const node = readUsageNode(ix, usageComponent.nodeId);
-    if (!node) continue;
-
+  for (const node of ix.byKind("usage_node")) {
+    const usageComponent = usageByNode.get(node.id);
+    const componentPolicy = usageComponent
+      ? ix.policy.a11yNameRequired(usageComponent.componentId)
+      : undefined;
     const props = propsByNode.get(node.id) ?? [];
-    if (props.some(isAriaHidden)) continue;
+    if (isAriaHidden(props)) continue;
+    const genericControl =
+      globalPolicy?.enabled === true &&
+      requiresAccessibleName(node, usageComponent, definitions, props);
+    if (!componentPolicy && !genericControl) continue;
 
-    if (hasAccessibleName(props, textByNode.get(node.id) ?? [])) continue;
+    if (
+      hasAccessibleName(
+        props,
+        textByNode.get(node.id) ?? [],
+        childContentByNode.get(node.id),
+        usageComponent !== undefined,
+        canNameFromContent(node, usageComponent, definitions)
+      )
+    ) {
+      continue;
+    }
 
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
-        severity: policy.severity,
-        message: `<${node.element}> has no accessible name. ${policy.because}`.trim(),
+        severity: componentPolicy?.severity ?? globalPolicy?.severity ?? "warn",
+        message: `<${node.element}> has no accessible name. ${
+          componentPolicy?.because ??
+          "Add visible text, aria-label, aria-labelledby, or a component label."
+        }`.trim(),
         location: node.location,
-        evidence: ix.evidence([node.id, usageComponent.id, policy.id]),
+        evidence: ix.evidence([
+          node.id,
+          ...(usageComponent ? [usageComponent.id] : []),
+          ...(componentPolicy ? [componentPolicy.id] : []),
+          ...(genericControl && globalPolicy ? [globalPolicy.id] : []),
+        ]),
         fingerprintIdentity: {
           file: node.file,
-          componentId: usageComponent.componentId,
+          componentId: usageComponent?.componentId,
           element: node.element,
           nodePath: node.nodePath,
         },
         attributes: {
-          componentId: usageComponent.componentId,
+          ...(usageComponent ? { componentId: usageComponent.componentId } : {}),
           element: node.element,
         },
       })
@@ -69,13 +121,22 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
 
 function hasAccessibleName(
   props: UsagePropResolvedFact[],
-  textChildren: ReadonlyArray<{ text: string }>
+  textChildren: ReadonlyArray<{ text: string }>,
+  childContent: UsageChildContentFact | undefined,
+  componentControl: boolean,
+  nameFromContent: boolean
 ): boolean {
-  for (const child of textChildren) {
-    if (typeof child.text === "string" && child.text.trim().length > 0) return true;
+  const sourceProps = componentControl ? COMPONENT_NAME_SOURCE_PROPS : NAME_SOURCE_PROPS;
+  if (nameFromContent) {
+    for (const child of textChildren) {
+      if (typeof child.text === "string" && child.text.trim().length > 0) return true;
+    }
+    if (childContent?.content === "static-text" || childContent?.content === "runtime") {
+      return true;
+    }
   }
   for (const prop of props) {
-    if (!NAME_SOURCE_PROPS.has(prop.prop)) continue;
+    if (!sourceProps.has(prop.prop)) continue;
     if (prop.resolution === "spread") continue;
     if (prop.resolution === "dynamic") return true;
     if (prop.resolution === "static") {
@@ -86,8 +147,94 @@ function hasAccessibleName(
   return false;
 }
 
-function isAriaHidden(prop: UsagePropResolvedFact): boolean {
-  if (prop.prop !== "aria-hidden") return false;
-  if (prop.resolution !== "static") return false;
-  return prop.value === true || prop.value === "true";
+function canNameFromContent(
+  node: UsageNodeFact,
+  usage: UsageComponentFact | undefined,
+  definitions: ReadonlyMap<string, ComponentDefinitionFact>
+): boolean {
+  const element = node.element.toLowerCase();
+  if (NAME_REQUIRED_TAGS.has(element)) return NAME_FROM_CONTENT_TAGS.has(element);
+  if (node.role && NAME_FROM_CONTENT_ROLES.has(node.role.toLowerCase())) return true;
+  if (!usage) return false;
+
+  const definition = definitions.get(String(usage.componentId));
+  if (definition) {
+    const root = definition.renderRoot;
+    if (root.resolution === "intrinsic") {
+      return intrinsicCanNameFromContent(root.tag, root.role);
+    }
+    if (root.resolution === "canonical") return isContentNamedControl(root.canonical);
+    if (root.resolution === "mixed") {
+      return (
+        root.intrinsics.some((tag) => intrinsicCanNameFromContent(tag)) ||
+        root.canonicals.some(isContentNamedControl)
+      );
+    }
+  }
+  return isContentNamedControl(String(usage.componentId));
+}
+
+function intrinsicCanNameFromContent(tag: string, role?: string): boolean {
+  const normalizedTag = tag.toLowerCase();
+  if (NAME_REQUIRED_TAGS.has(normalizedTag)) {
+    return NAME_FROM_CONTENT_TAGS.has(normalizedTag);
+  }
+  return role !== undefined && NAME_FROM_CONTENT_ROLES.has(role.toLowerCase());
+}
+
+function requiresAccessibleName(
+  node: UsageNodeFact,
+  usage: UsageComponentFact | undefined,
+  definitions: ReadonlyMap<string, ComponentDefinitionFact>,
+  props: readonly UsagePropResolvedFact[]
+): boolean {
+  if (node.role && NAME_REQUIRED_ROLES.has(node.role.toLowerCase())) return true;
+  if (NAME_REQUIRED_TAGS.has(node.element.toLowerCase())) {
+    if (
+      node.element.toLowerCase() === "input" &&
+      props.some(
+        (prop) =>
+          prop.prop === "type" &&
+          prop.resolution === "static" &&
+          String(prop.value).toLowerCase() === "hidden"
+      )
+    ) {
+      return false;
+    }
+    return true;
+  }
+  if (!usage) return false;
+
+  const definition = definitions.get(String(usage.componentId));
+  if (definition) {
+    const root = definition.renderRoot;
+    if (root.resolution === "intrinsic") {
+      return (
+        NAME_REQUIRED_TAGS.has(root.tag.toLowerCase()) ||
+        (root.role !== undefined && NAME_REQUIRED_ROLES.has(root.role.toLowerCase()))
+      );
+    }
+    if (root.resolution === "canonical") return isNamedControl(root.canonical);
+    if (root.resolution === "mixed") {
+      return (
+        root.intrinsics.some((tag) => NAME_REQUIRED_TAGS.has(tag.toLowerCase())) ||
+        root.canonicals.some(isNamedControl)
+      );
+    }
+  }
+  return isNamedControl(String(usage.componentId));
+}
+
+function isContentNamedControl(identity: string): boolean {
+  return normalizedControlName(identity).endsWith("button");
+}
+
+function isNamedControl(identity: string): boolean {
+  const normalized = normalizedControlName(identity);
+  return NAME_REQUIRED_COMPONENT_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+
+function normalizedControlName(identity: string): string {
+  const exported = identity.split("#").at(-1)?.split(".").at(-1) ?? identity;
+  return exported.replace(/[^a-z0-9]/gi, "").toLowerCase();
 }