@usefragments/core 1.6.0 → 1.7.0

package/dist/index.js

@@ -105,6 +105,7 @@ import {
   makeTailwindUnknownClassEnabledFact,
   makeThemeDeclarationFact,
   makeTokenDefinitionFact,
+  makeUsageChildContentFact,
   makeUsageComponentFact,
   makeUsageImportFact,
   makeUsageInlineStyleFact,
@@ -126,7 +127,7 @@ import {
   resolveComponentGovernance,
   ruleFamilyMembers,
   scaleGovernanceRecordSchema
-} from "./chunk-WVFNDPM4.js";
+} from "./chunk-WNMWKUYG.js";
 import {
   AGENT_FORMAT_SCHEMA_VERSION,
   agentErrorEnvelopeSchema,
@@ -181,6 +182,10 @@ import {
   severitySchema,
   sortBySeverity
 } from "./chunk-V4VQB57N.js";
+import {
+  CompiledFragmentsFileValidationError,
+  parseCompiledFragmentsFile
+} from "./chunk-RANPUC6C.js";
 
 // src/constants.ts
 var BRAND = {
@@ -420,6 +425,7 @@ function buildAgentFormat(input) {
   const zeroRulesLoaded = input.integrity.rulesLoaded === 0;
   const integrityFailed = !input.integrity.healthy || input.integrity.inert;
   const score = integrityFailed ? 0 : scoreFindings(input.findings);
+  const filesAffected = new Set(input.findings.map((finding) => finding.location.file)).size;
   const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
   const agentFindings = visibleFindings.map((finding) => ({
     code: finding.code,
@@ -437,7 +443,7 @@ function buildAgentFormat(input) {
   const hasErrors = input.findings.some((finding) => severityLevel(finding.severity) === "error");
   const shared = {
     schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
-    summary: zeroRulesLoaded ? "indeterminate; zero_rules_loaded" : integrityFailed ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}` : agentSummary(input.findings.length, input.filesScanned, score),
+    summary: zeroRulesLoaded ? "indeterminate; zero_rules_loaded" : integrityFailed ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}` : agentSummary(input.findings.length, filesAffected, input.filesScanned, score),
     integrity: input.integrity,
     fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
     remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
@@ -498,9 +504,9 @@ function scoreFindings(findings) {
   }
   return Math.max(1, Math.round(100 / (1 + penalty / 40)));
 }
-function agentSummary(count, filesScanned, score) {
+function agentSummary(count, filesAffected, filesScanned, score) {
   if (count === 0) return `passed with score ${score}; no findings`;
-  return `${count} finding${count === 1 ? "" : "s"} across ${filesScanned} file${filesScanned === 1 ? "" : "s"}; score ${score}`;
+  return `${count} finding${count === 1 ? "" : "s"} in ${filesAffected} file${filesAffected === 1 ? "" : "s"}; ${filesScanned} scanned; score ${score}`;
 }
 function planForFinding(finding) {
   if (finding.fix?.deterministic === true) {
@@ -3302,7 +3308,7 @@ function buildToken(name, rawValue, lineNumber, source) {
 }
 
 // src/tokens/design-token-parser.ts
-var TOKEN_DECLARATION_PATTERN = /--([a-zA-Z0-9_-]+)\s*:\s*([^;{}]+?)\s*(?:;|(?=\})|$)/g;
+var CSS_CUSTOM_PROPERTY_NAME_CHARACTER = /[a-zA-Z0-9_-]/u;
 var VAR_REFERENCE_PATTERN = /var\(\s*--([a-zA-Z0-9_-]+)(?:\s*,\s*([^)]+))?\s*\)/;
 function parseDesignTokenContent(content, options = {}) {
   const startTime = performance.now();
@@ -3354,19 +3360,48 @@ function parseDesignTokenContent(content, options = {}) {
       errors.push({ message: err, file: filePath });
     }
   }
-  const tokensByName = /* @__PURE__ */ new Map();
-  for (const match of content.matchAll(TOKEN_DECLARATION_PATTERN)) {
-    const [, name, rawValue] = match;
-    const fullName = `--${name}`;
-    const lineNumber = countNewlines(content, match.index ?? 0) + 1;
-    tokensByName.set(fullName, {
-      rawValue: rawValue.trim().replace(/\s+/g, " "),
-      line: lineNumber
+  const declarationsByThemeAndName = /* @__PURE__ */ new Map();
+  const declarationMatches = scanCssCustomPropertyDeclarations(content);
+  for (const match of declarationMatches) {
+    const fullName = match.name;
+    const lineNumber = match.line;
+    const selector = match.selector;
+    const theme = themeSelectors[selector] || "default";
+    declarationsByThemeAndName.set(`${theme}\0${fullName}`, {
+      name: fullName,
+      rawValue: normalizeCssCustomPropertyValue(match.rawValue),
+      line: lineNumber,
+      selector,
+      theme
     });
   }
-  for (const [name, { rawValue, line }] of tokensByName) {
-    const selector = findSelectorForLine(content, line ?? 1);
-    const theme = themeSelectors[selector] || "default";
+  const declarations = [...declarationsByThemeAndName.values()];
+  const defaults = /* @__PURE__ */ new Map();
+  const declarationsByTheme = /* @__PURE__ */ new Map();
+  for (const declaration of declarations) {
+    if (declaration.theme === "default") defaults.set(declaration.name, declaration);
+    let themeDeclarations = declarationsByTheme.get(declaration.theme);
+    if (!themeDeclarations) {
+      themeDeclarations = /* @__PURE__ */ new Map();
+      declarationsByTheme.set(declaration.theme, themeDeclarations);
+    }
+    themeDeclarations.set(declaration.name, declaration);
+  }
+  const tokensByTheme = /* @__PURE__ */ new Map();
+  for (const [theme, themeDeclarations] of declarationsByTheme) {
+    if (theme === "default") {
+      tokensByTheme.set(theme, defaults);
+      continue;
+    }
+    const tokensByName = new Map(defaults);
+    for (const [name, declaration] of themeDeclarations) {
+      tokensByName.set(name, declaration);
+    }
+    tokensByTheme.set(theme, tokensByName);
+  }
+  const contentLines = content.split("\n");
+  for (const { name, rawValue, line, selector, theme } of declarations) {
+    const tokensByName = tokensByTheme.get(theme) ?? defaults;
     const { resolvedValue, chain, hasCircular, unresolvedRef } = resolveDesignTokenValue(
       rawValue,
       tokensByName
@@ -3388,7 +3423,7 @@ function parseDesignTokenContent(content, options = {}) {
       lineNumber: line,
       theme,
       selector,
-      description: extractDescription(content, line ?? 1)
+      description: extractDescription(contentLines, line ?? 1)
     });
   }
   if (tokens.length === 0 && trimmed.length > 0) {
@@ -3403,13 +3438,6 @@ function parseDesignTokenContent(content, options = {}) {
     parseTimeMs: performance.now() - startTime
   };
 }
-function countNewlines(content, index) {
-  let count = 0;
-  for (let i = 0; i < index && i < content.length; i++) {
-    if (content.charCodeAt(i) === 10) count++;
-  }
-  return count;
-}
 function parsedOutputToDesignTokens(output, filePath) {
   const tokens = [];
   for (const cat of Object.values(output.categories)) {
@@ -3564,29 +3592,284 @@ function inferTokenLevel(name, rawValue, referenceChain) {
   }
   return 2;
 }
-function findSelectorForLine(content, targetLine) {
-  const lines = content.split("\n");
+function scanCssCustomPropertyDeclarations(content) {
+  const declarations = [];
+  const parentSelectors = [];
   let currentSelector = ":root";
-  let braceDepth = 0;
-  for (let i = 0; i < Math.min(targetLine, lines.length); i++) {
-    const line = lines[i];
-    const selectorMatch = line.match(/^\s*([^{]+)\s*\{/);
-    if (selectorMatch) {
-      const selector = selectorMatch[1].trim();
-      if ((line.match(/\{/g) || []).length > (line.match(/\}/g) || []).length) {
-        currentSelector = selector;
+  let boundary = 0;
+  let statementHasContent = false;
+  let line = 1;
+  let quote = null;
+  let escaped = false;
+  let inComment = false;
+  let parentheses = 0;
+  let brackets = 0;
+  for (let index = 0; index < content.length; index++) {
+    const character = content[index];
+    const next = content[index + 1];
+    if (character === "\n") line++;
+    if (inComment) {
+      if (character === "*" && next === "/") {
+        inComment = false;
+        index++;
+      }
+      continue;
+    }
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      inComment = true;
+      index++;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      statementHasContent = true;
+      continue;
+    }
+    if (character === "\\") {
+      statementHasContent = true;
+      if (next === "\n") line++;
+      index++;
+      continue;
+    }
+    if (character === "(") {
+      parentheses++;
+      statementHasContent = true;
+      continue;
+    }
+    if (character === ")") {
+      parentheses = Math.max(0, parentheses - 1);
+      statementHasContent = true;
+      continue;
+    }
+    if (character === "[") {
+      brackets++;
+      statementHasContent = true;
+      continue;
+    }
+    if (character === "]") {
+      brackets = Math.max(0, brackets - 1);
+      statementHasContent = true;
+      continue;
+    }
+    if (parentheses > 0 || brackets > 0) {
+      if (!/\s/u.test(character)) statementHasContent = true;
+      continue;
+    }
+    if (character === "{") {
+      const header = stripCssComments(content.slice(boundary, index)).trim();
+      parentSelectors.push(currentSelector);
+      if (header && !header.startsWith("@")) currentSelector = header;
+      boundary = index + 1;
+      statementHasContent = false;
+    } else if (character === "}") {
+      currentSelector = parentSelectors.pop() ?? ":root";
+      boundary = index + 1;
+      statementHasContent = false;
+    } else if (character === ";") {
+      boundary = index + 1;
+      statementHasContent = false;
+    } else if (character === "-" && next === "-" && !statementHasContent) {
+      const declaration = scanCssCustomPropertyAt(content, index);
+      if (!declaration) {
+        statementHasContent = true;
+        continue;
+      }
+      const rawValue = content.slice(declaration.valueStart, declaration.end).trim();
+      if (rawValue) {
+        declarations.push({
+          name: declaration.name,
+          rawValue,
+          line,
+          selector: currentSelector
+        });
+      }
+      line += countNewlinesInRange(content, index + 1, declaration.end);
+      statementHasContent = true;
+      index = declaration.end - 1;
+    } else if (!/\s/u.test(character)) {
+      statementHasContent = true;
+    }
+  }
+  return declarations;
+}
+function scanCssCustomPropertyAt(content, start) {
+  let cursor = start + 2;
+  while (cursor < content.length && CSS_CUSTOM_PROPERTY_NAME_CHARACTER.test(content[cursor] ?? "")) {
+    cursor++;
+  }
+  if (cursor === start + 2) return null;
+  const nameEnd = cursor;
+  cursor = skipCssWhitespaceAndComments(content, cursor);
+  if (content[cursor] !== ":") return null;
+  const valueStart = cursor + 1;
+  return {
+    name: content.slice(start, nameEnd),
+    valueStart,
+    end: findCssCustomPropertyValueEnd(content, valueStart)
+  };
+}
+function findCssCustomPropertyValueEnd(content, start) {
+  let quote = null;
+  let escaped = false;
+  let inComment = false;
+  let parentheses = 0;
+  let brackets = 0;
+  let braces = 0;
+  for (let index = start; index < content.length; index++) {
+    const character = content[index];
+    const next = content[index + 1];
+    if (inComment) {
+      if (character === "*" && next === "/") {
+        inComment = false;
+        index++;
+      }
+      continue;
+    }
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      inComment = true;
+      index++;
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quote = character;
+      continue;
+    }
+    if (character === "\\") {
+      index++;
+      continue;
+    }
+    if (character === "(") {
+      parentheses++;
+    } else if (character === ")") {
+      parentheses = Math.max(0, parentheses - 1);
+    } else if (character === "[") {
+      brackets++;
+    } else if (character === "]") {
+      brackets = Math.max(0, brackets - 1);
+    } else if (character === "{") {
+      braces++;
+    } else if (character === "}") {
+      if (braces > 0) {
+        braces--;
+      } else if (parentheses === 0 && brackets === 0) {
+        return index;
+      }
+    } else if (character === ";" && parentheses === 0 && brackets === 0 && braces === 0) {
+      return index;
+    }
+  }
+  return content.length;
+}
+function skipCssWhitespaceAndComments(content, start) {
+  let cursor = start;
+  while (cursor < content.length) {
+    if (/\s/u.test(content[cursor] ?? "")) {
+      cursor++;
+      continue;
+    }
+    if (content[cursor] !== "/" || content[cursor + 1] !== "*") break;
+    const commentEnd = content.indexOf("*/", cursor + 2);
+    if (commentEnd < 0) return content.length;
+    cursor = commentEnd + 2;
+  }
+  return cursor;
+}
+function stripCssComments(content) {
+  let output = "";
+  let quote = null;
+  let escaped = false;
+  let inComment = false;
+  for (let index = 0; index < content.length; index++) {
+    const character = content[index];
+    const next = content[index + 1];
+    if (inComment) {
+      if (character === "*" && next === "/") {
+        inComment = false;
+        index++;
       }
+      continue;
     }
-    braceDepth += (line.match(/\{/g) || []).length;
-    braceDepth -= (line.match(/\}/g) || []).length;
-    if (braceDepth === 0) {
-      currentSelector = ":root";
+    if (quote) {
+      output += character;
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      inComment = true;
+      index++;
+      continue;
     }
+    output += character;
+    if (character === "'" || character === '"') quote = character;
   }
-  return currentSelector;
+  return output;
 }
-function extractDescription(content, line) {
-  const lines = content.split("\n");
+function countNewlinesInRange(content, start, end) {
+  let count = 0;
+  for (let index = start; index < end; index++) {
+    if (content.charCodeAt(index) === 10) count++;
+  }
+  return count;
+}
+function normalizeCssCustomPropertyValue(value) {
+  let output = "";
+  let quote = null;
+  let escaped = false;
+  let pendingWhitespace = false;
+  for (const character of value.trim()) {
+    if (quote) {
+      output += character;
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      if (pendingWhitespace && output) output += " ";
+      pendingWhitespace = false;
+      quote = character;
+      output += character;
+    } else if (/\s/u.test(character)) {
+      pendingWhitespace = true;
+    } else {
+      if (pendingWhitespace && output) output += " ";
+      pendingWhitespace = false;
+      output += character;
+    }
+  }
+  return output;
+}
+function extractDescription(lines, line) {
   if (line <= 1) return void 0;
   const prevLine = lines[line - 2]?.trim();
   const singleLineMatch = prevLine?.match(/\/\/\s*(.+)$/);
@@ -4382,6 +4665,13 @@ function discoverComponents(moduleExports, options) {
   return names.sort();
 }
 
+// src/rules/a11y-utils.ts
+function isAriaHidden(props) {
+  const prop = props.find((candidate) => candidate.prop === "aria-hidden");
+  if (!prop || prop.resolution !== "static") return false;
+  return prop.value === true || prop.value === "true";
+}
+
 // src/rules/finding.ts
 function makeFinding(input) {
   if (input.evidence.length === 0) {
@@ -4840,36 +5130,71 @@ function isApplicableTokenReference(referenceFormat) {
 
 // src/rules/a11y-required-accessible-name.ts
 var RULE_ID = "a11y/required-accessible-name";
-var RULE_VERSION = "1";
+var RULE_VERSION = "2";
 var NAME_SOURCE_PROPS = /* @__PURE__ */ new Set(["aria-label", "aria-labelledby", "title"]);
+var COMPONENT_NAME_SOURCE_PROPS = /* @__PURE__ */ new Set([...NAME_SOURCE_PROPS, "label"]);
+var NAME_REQUIRED_TAGS = /* @__PURE__ */ new Set(["button", "input", "select", "textarea"]);
+var NAME_REQUIRED_ROLES = /* @__PURE__ */ new Set(["button", "checkbox", "radio", "switch", "tab"]);
+var NAME_FROM_CONTENT_TAGS = /* @__PURE__ */ new Set(["button"]);
+var NAME_FROM_CONTENT_ROLES = /* @__PURE__ */ new Set(["button", "checkbox", "radio", "switch", "tab"]);
+var NAME_REQUIRED_COMPONENT_SUFFIXES = [
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "checkbox",
+  "radio",
+  "switch"
+];
 function ruleA11yRequiredAccessibleName(ix) {
   const findings = [];
   const propsByNode = indexPropsByNodeId(ix);
   const textByNode = indexTextChildrenByNodeId(ix);
-  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;
+  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 node of ix.byKind("usage_node")) {
+    const usageComponent = usageByNode.get(node.id);
+    const componentPolicy = usageComponent ? ix.policy.a11yNameRequired(usageComponent.componentId) : void 0;
     const props = propsByNode.get(node.id) ?? [];
-    if (props.some(isAriaHidden)) continue;
-    if (hasAccessibleName(props, textByNode.get(node.id) ?? [])) 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) ?? [],
+      childContentByNode.get(node.id),
+      usageComponent !== void 0,
+      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
         }
       })
@@ -4877,12 +5202,18 @@ function ruleA11yRequiredAccessibleName(ix) {
   }
   return findings;
 }
-function hasAccessibleName(props, textChildren) {
-  for (const child of textChildren) {
-    if (typeof child.text === "string" && child.text.trim().length > 0) return true;
+function hasAccessibleName(props, textChildren, childContent, componentControl, nameFromContent) {
+  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") {
@@ -4892,10 +5223,137 @@ function hasAccessibleName(props, textChildren) {
   }
   return false;
 }
-function isAriaHidden(prop) {
-  if (prop.prop !== "aria-hidden") return false;
-  if (prop.resolution !== "static") return false;
-  return prop.value === true || prop.value === "true";
+function canNameFromContent(node, usage, definitions) {
+  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, role) {
+  const normalizedTag = tag.toLowerCase();
+  if (NAME_REQUIRED_TAGS.has(normalizedTag)) {
+    return NAME_FROM_CONTENT_TAGS.has(normalizedTag);
+  }
+  return role !== void 0 && NAME_FROM_CONTENT_ROLES.has(role.toLowerCase());
+}
+function requiresAccessibleName(node, usage, definitions, props) {
+  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 !== void 0 && 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) {
+  return normalizedControlName(identity).endsWith("button");
+}
+function isNamedControl(identity) {
+  const normalized = normalizedControlName(identity);
+  return NAME_REQUIRED_COMPONENT_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+function normalizedControlName(identity) {
+  const exported = identity.split("#").at(-1)?.split(".").at(-1) ?? identity;
+  return exported.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+
+// src/rules/a11y-standard.ts
+var RULE_ID2 = "a11y/standard";
+var RULE_VERSION2 = "1";
+var KEY_HANDLERS = /* @__PURE__ */ new Set(["onKeyDown", "onKeyUp", "onKeyPress"]);
+function ruleA11yStandard(ix) {
+  const policy = ix.policy.ruleConfig(RULE_ID2);
+  if (!policy?.enabled) return [];
+  const propsByNode = indexPropsByNodeId(ix);
+  const findings = [];
+  for (const node of ix.byKind("usage_node")) {
+    if (node.role?.trim().toLowerCase() !== "button") continue;
+    const props = propsByNode.get(node.id) ?? [];
+    if (isAriaHidden(props) || isNativeButton(node.element, props)) continue;
+    const missing = [
+      ...hasFocusableTabIndex(props) ? [] : ["tabIndex"],
+      ...hasKeyHandler(props) ? [] : ["keyboard handler"]
+    ];
+    if (missing.length === 0) continue;
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID2,
+        ruleVersion: RULE_VERSION2,
+        severity: policy.severity ?? "warn",
+        message: `<${node.element} role="button"> is missing ${missing.join(
+          " and "
+        )}. Non-native buttons need tabIndex plus keyboard activation handling.`,
+        location: node.location,
+        evidence: ix.evidence([
+          node.id,
+          policy.id,
+          ...props.filter(
+            (prop) => prop.prop === "tabIndex" || prop.prop === "tabindex" || KEY_HANDLERS.has(prop.prop)
+          ).map((prop) => prop.id)
+        ]),
+        fingerprintIdentity: {
+          file: node.file,
+          element: node.element,
+          nodePath: node.nodePath,
+          standard: "keyboard-role-button"
+        },
+        attributes: {
+          standard: "keyboard-role-button",
+          role: "button",
+          missing
+        }
+      })
+    );
+  }
+  return findings;
+}
+function isNativeButton(element, props) {
+  if (element.toLowerCase() === "button") return true;
+  if (element.toLowerCase() !== "input") return false;
+  return props.some(
+    (prop) => prop.prop === "type" && prop.resolution === "static" && ["button", "submit", "reset"].includes(String(prop.value).toLowerCase())
+  );
+}
+function hasFocusableTabIndex(props) {
+  return props.some((prop) => {
+    if (prop.prop !== "tabIndex" && prop.prop !== "tabindex") return false;
+    if (prop.resolution === "dynamic") return true;
+    if (prop.resolution !== "static") return false;
+    const value = typeof prop.value === "number" ? prop.value : Number(prop.value);
+    return Number.isFinite(value) && value >= 0;
+  });
+}
+function hasKeyHandler(props) {
+  return props.some(
+    (prop) => KEY_HANDLERS.has(prop.prop) && prop.resolution !== "spread" && prop.value !== null && prop.value !== false
+  );
 }
 
 // src/raw-html-canonical.ts
@@ -5080,8 +5538,8 @@ function decisionTargetsExport(target, exportName) {
 }
 
 // src/rules/components-prefer-library.ts
-var RULE_ID2 = "components/prefer-library";
-var RULE_VERSION2 = "1";
+var RULE_ID3 = "components/prefer-library";
+var RULE_VERSION3 = "1";
 function isExplicitTagDeclaration(mapping) {
   return mapping.declaredHtmlEquivalent === true;
 }
@@ -5220,7 +5678,7 @@ function findClassNameReimpl(node, classTokensByNode, targets) {
   return null;
 }
 function ruleComponentsPreferLibrary(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID2);
+  const policy = ix.policy.ruleConfig(RULE_ID3);
   if (!policy?.enabled) return [];
   const configuredSources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
   const conflicts = projectCanonicalDirectionConflicts(ix, configuredSources);
@@ -5235,7 +5693,7 @@ function ruleComponentsPreferLibrary(ix) {
   const classTokensByNode = indexClassTokensByNode(ix);
   const reimplTargets = canonicalReimplTargets(sources, mappings);
   const canonicalDirectoryResolvedNodes = indexCanonicalDirectoryResolvedNodes(ix, sources);
-  const shadowRenderRootNodeIds = indexShadowRenderRootNodeIds(ix);
+  const shadowRenderRootNodeIds = ix.policy.ruleConfig("components/shadow-component")?.enabled === true ? indexShadowRenderRootNodeIds(ix) : /* @__PURE__ */ new Set();
   const findings = [];
   const seenImportFixes = /* @__PURE__ */ new Set();
   for (const node of ix.byKind("usage_node")) {
@@ -5267,8 +5725,8 @@ function ruleComponentsPreferLibrary(ix) {
         seenImportFixes.add(key);
         findings.push(
           makeFinding({
-            ruleId: RULE_ID2,
-            ruleVersion: RULE_VERSION2,
+            ruleId: RULE_ID3,
+            ruleVersion: RULE_VERSION3,
             severity: capAdvisorySeverity(policy.severity),
             message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
             location: imported.location,
@@ -5302,8 +5760,8 @@ function ruleComponentsPreferLibrary(ix) {
       if (node.element === suggestedComponent2) continue;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID2,
-          ruleVersion: RULE_VERSION2,
+          ruleId: RULE_ID3,
+          ruleVersion: RULE_VERSION3,
           severity: severityForTier(policy.severity, precisionTier2),
           message: node.element === "button" ? `Bespoke <button> has a library equivalent. Swap to <${suggestedComponent2}> from ${suggestedImport2}.` : roleMatch ? `Custom <${node.element} role="${node.role}"> reimplements a primitive. Use <${suggestedComponent2}> from ${suggestedImport2}.` : `Bespoke <${node.element}> should use <${suggestedComponent2}> from ${suggestedImport2}.`,
           location: node.location,
@@ -5354,8 +5812,8 @@ function ruleComponentsPreferLibrary(ix) {
         const suggestedImport2 = reimpl.import ?? "the canonical library";
         findings.push(
           makeFinding({
-            ruleId: RULE_ID2,
-            ruleVersion: RULE_VERSION2,
+            ruleId: RULE_ID3,
+            ruleVersion: RULE_VERSION3,
             severity: capAdvisorySeverity(policy.severity),
             message: `<${node.element} class="${reimpl.matchedClass}"> looks like a hand-rolled <${reimpl.canonical}>. Use <${reimpl.canonical}> from ${suggestedImport2} instead of restyling a <${node.element}>.`,
             location: node.location,
@@ -5395,8 +5853,8 @@ function ruleComponentsPreferLibrary(ix) {
       seenImportFixes.add(key);
       findings.push(
         makeFinding({
-          ruleId: RULE_ID2,
-          ruleVersion: RULE_VERSION2,
+          ruleId: RULE_ID3,
+          ruleVersion: RULE_VERSION3,
           severity: capAdvisorySeverity(policy.severity),
           message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
           location: imported.location,
@@ -5438,14 +5896,15 @@ function ruleComponentsPreferLibrary(ix) {
         continue;
       }
     }
-    const suggestedImport = sourceLabel(suggestion);
+    const importReady = suggestion.kind !== "directory";
+    const suggestedImport = importReady ? sourceLabel(suggestion) : "the canonical component directory (resolve its configured import alias)";
     const precisionTier = builtIn?.tier ?? "exact-html";
     const rawElement = formatRawElement(node, props);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID2,
-        ruleVersion: RULE_VERSION2,
-        severity: severityForTier(policy.severity, precisionTier),
+        ruleId: RULE_ID3,
+        ruleVersion: RULE_VERSION3,
+        severity: importReady ? severityForTier(policy.severity, precisionTier) : capAdvisorySeverity(policy.severity),
         message: messageForBuiltInMatch({
           node,
           rawElement,
@@ -5462,7 +5921,7 @@ function ruleComponentsPreferLibrary(ix) {
           suggestedComponent,
           suggestedImport
         },
-        ...!isRawHtmlAdvisoryTier(precisionTier) && isIdentifier(node.element) && isIdentifier(suggestedComponent) ? {
+        ...importReady && !isRawHtmlAdvisoryTier(precisionTier) && isIdentifier(node.element) && isIdentifier(suggestedComponent) ? {
           fix: {
             kind: "replaceComponent",
             title: `Replace ${rawElement} with <${suggestedComponent}>`,
@@ -5477,13 +5936,13 @@ function ruleComponentsPreferLibrary(ix) {
         attributes: {
           rawValue: node.element,
           suggestedComponent,
-          suggestedImport,
           suggestedImportSourceKind: suggestion.kind,
+          ...importReady ? { suggestedImport } : { canonicalDirectory: suggestion.path, importReady: false },
           precisionTier,
           propCompatibility: "unknown",
           ...builtIn?.matchedRole ? { matchedRole: builtIn.matchedRole } : {},
           ...builtIn?.inputType ? { matchedInputType: builtIn.inputType } : {},
-          ...isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}
+          ...isRawHtmlAdvisoryTier(precisionTier) || !importReady ? { advisory: true } : {}
         }
       })
     );
@@ -5503,11 +5962,19 @@ function suppressConflictedExports(source, conflicts) {
 function indexShadowRenderRootNodeIds(ix) {
   const identities = ix.byKind("component_identity");
   if (identities.length === 0) return /* @__PURE__ */ new Set();
+  const definitions = new Map(
+    ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
+  );
   const nodeIds = /* @__PURE__ */ new Set();
   for (const identity of identities) {
     if (identity.state !== "shadow") continue;
+    const definition = definitions.get(identity.componentKey);
+    if (!definition) continue;
     for (const evidenceId of identity.evidence) {
-      if (ix.get(evidenceId)?.kind === "usage_node") nodeIds.add(evidenceId);
+      const evidence = ix.get(evidenceId);
+      if (evidence?.kind === "usage_node" && evidence.file === definition.file) {
+        nodeIds.add(evidenceId);
+      }
     }
   }
   return nodeIds;
@@ -5790,7 +6257,7 @@ function sourceLabel(source) {
 function canonicalImportPath(source) {
   if (source.kind === "npm") return source.specifier;
   if (source.kind === "registry") return source.importPath;
-  return source.include?.length ? source.path : void 0;
+  return void 0;
 }
 function indexCanonicalDirectoryResolvedNodes(ix, sources) {
   const out = /* @__PURE__ */ new Set();
@@ -5866,10 +6333,10 @@ function indexComponentIdentityUsage(ix) {
 }
 
 // src/rules/components-shadow-component.ts
-var RULE_ID3 = "components/shadow-component";
-var RULE_VERSION3 = "1";
+var RULE_ID4 = "components/shadow-component";
+var RULE_VERSION4 = "1";
 function ruleComponentsShadowComponent(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID3);
+  const policy = ix.policy.ruleConfig(RULE_ID4);
   if (!policy?.enabled) return [];
   const definitions = new Map(
     ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
@@ -5886,8 +6353,8 @@ function ruleComponentsShadowComponent(ix) {
     const blastRadius = usage?.blastRadius ?? 0;
     findings.push(
       makeFinding({
-        ruleId: RULE_ID3,
-        ruleVersion: RULE_VERSION3,
+        ruleId: RULE_ID4,
+        ruleVersion: RULE_VERSION4,
         severity: reviewVariant ? "info" : policy.severity ?? "warn",
         message: reviewVariant ? `${definition.exportName} wraps ${identity.canonicalTarget ?? "a canonical component"}; sanction it as a variant or consolidate its usages.` : `${definition.exportName} shadows ${identity.canonicalTarget ?? "a canonical component"} across ${usageCount} usage${usageCount === 1 ? "" : "s"}.`,
         location: definitionLocation(ix, definition, identity),
@@ -5925,8 +6392,8 @@ function definitionLocation(ix, definition, identity) {
 }
 
 // src/rules/components-forbidden-prop-value.ts
-var RULE_ID4 = "components/forbidden-prop-value";
-var RULE_VERSION4 = "1";
+var RULE_ID5 = "components/forbidden-prop-value";
+var RULE_VERSION5 = "1";
 function ruleComponentsForbiddenPropValue(ix) {
   const findings = [];
   const componentByNode = indexComponentByNodeId(ix);
@@ -5956,8 +6423,8 @@ function ruleComponentsForbiddenPropValue(ix) {
       } : void 0;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID4,
-          ruleVersion: RULE_VERSION4,
+          ruleId: RULE_ID5,
+          ruleVersion: RULE_VERSION5,
           severity: policy.severity,
           message: buildMessage(
             node.element,
@@ -6001,8 +6468,8 @@ function buildMessage(element, prop, value, because, replacement) {
 }
 
 // src/rules/components-unknown-prop.ts
-var RULE_ID5 = "components/unknown-prop";
-var RULE_VERSION5 = "1";
+var RULE_ID6 = "components/unknown-prop";
+var RULE_VERSION6 = "1";
 function ruleComponentsUnknownProp(ix) {
   const policy = ix.policy.jsxUnknownPropsForbidden();
   if (!policy) return [];
@@ -6023,8 +6490,8 @@ function ruleComponentsUnknownProp(ix) {
       if (knownNames.has(propUsage.prop)) continue;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID5,
-          ruleVersion: RULE_VERSION5,
+          ruleId: RULE_ID6,
+          ruleVersion: RULE_VERSION6,
           severity: policy.severity,
           message: `Unknown prop "${propUsage.prop}" on <${node.element}>. Allowed props: ${formatPropList(knownNames)}.`,
           location: node.location,
@@ -6056,7 +6523,7 @@ function formatPropList(names) {
 // src/rules/composition-pattern.ts
 var CARDINALITY_RULE_ID = "composition/cardinality";
 var CO_OCCURRENCE_RULE_ID = "composition/co-occurrence";
-var RULE_VERSION6 = "1";
+var RULE_VERSION7 = "1";
 function ruleCompositionCardinality(ix) {
   return evaluate(ix, CARDINALITY_RULE_ID, "cardinality");
 }
@@ -6124,7 +6591,7 @@ function checkCardinality(ctx, region, pattern, constraint, selected) {
     const extras = selected.slice(constraint.max);
     return makeFinding({
       ruleId: ctx.ruleId,
-      ruleVersion: RULE_VERSION6,
+      ruleVersion: RULE_VERSION7,
       severity: ctx.severity,
       message: cardinalityMaxMessage(pattern, constraint.max, count),
       location: extras[0].location,
@@ -6135,7 +6602,7 @@ function checkCardinality(ctx, region, pattern, constraint, selected) {
   if (constraint.min !== void 0 && count < constraint.min) {
     return makeFinding({
       ruleId: ctx.ruleId,
-      ruleVersion: RULE_VERSION6,
+      ruleVersion: RULE_VERSION7,
       severity: ctx.severity,
       message: cardinalityMinMessage(pattern, constraint.min, count),
       location: region.container.location,
@@ -6156,7 +6623,7 @@ function checkCoOccurrence(ctx, region, pattern, constraint, selected) {
   if (satisfied) return null;
   return makeFinding({
     ruleId: ctx.ruleId,
-    ruleVersion: RULE_VERSION6,
+    ruleVersion: RULE_VERSION7,
     severity: ctx.severity,
     message: coOccurrenceMessage(pattern, constraint),
     location: region.container.location,
@@ -6208,8 +6675,8 @@ function coOccurrenceMessage(pattern, constraint) {
 }
 
 // src/rules/jsx-preferred-component.ts
-var RULE_ID6 = "components/preferred-component";
-var RULE_VERSION7 = "1";
+var RULE_ID7 = "components/preferred-component";
+var RULE_VERSION8 = "1";
 function ruleJsxPreferredComponent(ix) {
   const policies = ix.policy.jsxComponentPreferred();
   if (policies.length === 0) return [];
@@ -6225,8 +6692,8 @@ function ruleJsxPreferredComponent(ix) {
       if (!replacement) continue;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID6,
-          ruleVersion: RULE_VERSION7,
+          ruleId: RULE_ID7,
+          ruleVersion: RULE_VERSION8,
           severity: policy.severity,
           message: `<${node.element}> should use <${replacement}>.`,
           location: node.location,
@@ -6263,8 +6730,8 @@ function componentNameFromId(componentId2) {
 }
 
 // src/rules/jsx-preferred-import-path.ts
-var RULE_ID7 = "imports/preferred-path";
-var RULE_VERSION8 = "1";
+var RULE_ID8 = "imports/preferred-path";
+var RULE_VERSION9 = "1";
 function ruleJsxPreferredImportPath(ix) {
   const policies = ix.policy.jsxImportPathPreferred();
   if (policies.length === 0) return [];
@@ -6292,8 +6759,8 @@ function ruleJsxPreferredImportPath(ix) {
       seen.add(key);
       findings.push(
         makeFinding({
-          ruleId: RULE_ID7,
-          ruleVersion: RULE_VERSION8,
+          ruleId: RULE_ID8,
+          ruleVersion: RULE_VERSION9,
           severity: policy.severity,
           message: policy.bridge ? `Import ${policy.bridge.underlyingExportName} through the confirmed local ${policy.bridge.localExportName} wrapper from "${policy.to}".` : `Import from "${usage.source}" should use "${policy.to}".`,
           location: usage.location,
@@ -6352,10 +6819,10 @@ function normalizeRepoPath(path) {
 }
 
 // src/rules/props-invalid-value.ts
-var RULE_ID8 = "props/invalid-value";
-var RULE_VERSION9 = "1";
+var RULE_ID9 = "props/invalid-value";
+var RULE_VERSION10 = "1";
 function rulePropsInvalidValue(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID8);
+  const policy = ix.policy.ruleConfig(RULE_ID9);
   if (!policy?.enabled) return [];
   const findings = [];
   const componentByNode = indexComponentByNodeId(ix);
@@ -6384,8 +6851,8 @@ function rulePropsInvalidValue(ix) {
       } : void 0;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID8,
-          ruleVersion: RULE_VERSION9,
+          ruleId: RULE_ID9,
+          ruleVersion: RULE_VERSION10,
           severity: policy.severity ?? "warn",
           message: buildMessage2(node.element, propUsage.prop, propUsage.value, allowedValues),
           location: propUsage.location ?? node.location,
@@ -6584,8 +7051,8 @@ function localTokenCandidates(ix, category) {
 }
 
 // src/rules/styles-no-raw-color.ts
-var RULE_ID9 = "styles/no-raw-color";
-var RULE_VERSION10 = "1";
+var RULE_ID10 = "styles/no-raw-color";
+var RULE_VERSION11 = "1";
 function ruleStylesNoRawColor(ix) {
   const policy = ix.policy.rawColorPolicy();
   if (!policy) return [];
@@ -6604,8 +7071,8 @@ function ruleStylesNoRawColor(ix) {
     const evidenceIds = resolution ? [decl.id, policy.id, resolution.token.id] : [decl.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID9,
-        ruleVersion: RULE_VERSION10,
+        ruleId: RULE_ID10,
+        ruleVersion: RULE_VERSION11,
         severity: policy.severity,
         message: colorMessage(color, `\`${decl.property}\``, resolution, preferLabel) + (hopped?.suffix ?? ""),
         location: decl.location,
@@ -6641,8 +7108,8 @@ function ruleStylesNoRawColor(ix) {
       const evidenceIds2 = componentEvidenceId2 ? [node2.id, componentEvidenceId2, inline.id, policy.id] : [node2.id, inline.id, policy.id];
       findings.push(
         makeFinding({
-          ruleId: RULE_ID9,
-          ruleVersion: RULE_VERSION10,
+          ruleId: RULE_ID10,
+          ruleVersion: RULE_VERSION11,
           severity: advisorySeverity,
           message: `Runtime-constructed raw color \`${inline.value}\` on inline \`${inline.property}\`. Use a ${preferLabel} instead.`,
           location: node2.location,
@@ -6679,8 +7146,8 @@ function ruleStylesNoRawColor(ix) {
     const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
     findings.push(
       makeFinding({
-        ruleId: RULE_ID9,
-        ruleVersion: RULE_VERSION10,
+        ruleId: RULE_ID10,
+        ruleVersion: RULE_VERSION11,
         severity: policy.severity,
         message: colorMessage(color, `inline \`${inline.property}\``, resolution, preferLabel) + (hopped?.suffix ?? ""),
         location: node.location,
@@ -6724,8 +7191,8 @@ function ruleStylesNoRawColor(ix) {
     const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
     findings.push(
       makeFinding({
-        ruleId: RULE_ID9,
-        ruleVersion: RULE_VERSION10,
+        ruleId: RULE_ID10,
+        ruleVersion: RULE_VERSION11,
         severity: advisorySeverity,
         message: colorMessage(color, `\`${prop.prop}\``, resolution, preferLabel),
         location: prop.location ?? node.location,
@@ -6876,8 +7343,8 @@ function escapeRegExp(value) {
 }
 
 // src/rules/styles-no-raw-dimensions.ts
-var RULE_ID10 = "styles/no-raw-dimensions";
-var RULE_VERSION11 = "1";
+var RULE_ID11 = "styles/no-raw-dimensions";
+var RULE_VERSION12 = "1";
 function ruleStylesNoRawDimensions(ix) {
   const policy = ix.policy.rawDimensionPolicy();
   if (!policy) return [];
@@ -6898,8 +7365,8 @@ function ruleStylesNoRawDimensions(ix) {
     const fixEmission = hopped ? void 0 : dimensionFix(decl.property, resolution, ix);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID10,
-        ruleVersion: RULE_VERSION11,
+        ruleId: RULE_ID11,
+        ruleVersion: RULE_VERSION12,
         severity: policy.severity,
         message: dimensionMessage(decl.value, decl.property, preferLabel, resolution, false) + (hopped?.suffix ?? ""),
         location: decl.location,
@@ -6942,8 +7409,8 @@ function ruleStylesNoRawDimensions(ix) {
     const fixEmission = hopped ? void 0 : dimensionFix(inline.property, resolution, ix);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID10,
-        ruleVersion: RULE_VERSION11,
+        ruleId: RULE_ID11,
+        ruleVersion: RULE_VERSION12,
         severity: policy.severity,
         message: dimensionMessage(inline.value, inline.property, preferLabel, resolution, true) + (hopped?.suffix ?? ""),
         location: node.location,
@@ -7212,8 +7679,8 @@ function parseLengthParts(raw) {
 }
 
 // src/rules/styles-no-raw-spacing.ts
-var RULE_ID11 = "styles/no-raw-spacing";
-var RULE_VERSION12 = "1";
+var RULE_ID12 = "styles/no-raw-spacing";
+var RULE_VERSION13 = "1";
 function ruleStylesNoRawSpacing(ix) {
   const findings = [];
   const lookupCache = /* @__PURE__ */ new Map();
@@ -7256,8 +7723,8 @@ function checkDeclaration(ix, decl, lookupFor) {
   const hopped = hoppedValue(decl);
   const fixEmission = hopped ? void 0 : buildSpacingFix(decl.property, checked, ix);
   return makeFinding({
-    ruleId: RULE_ID11,
-    ruleVersion: RULE_VERSION12,
+    ruleId: RULE_ID12,
+    ruleVersion: RULE_VERSION13,
     severity: policy.severity,
     message: spacingMessage(decl.property, decl.value, allowed, scale, checked) + (hopped?.suffix ?? ""),
     location: decl.location,
@@ -7313,8 +7780,8 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
   const componentEvidenceId = componentByNode.get(node.id)?.id;
   const evidenceIds = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id, scale.id] : [node.id, inline.id, policy.id, scale.id];
   return makeFinding({
-    ruleId: RULE_ID11,
-    ruleVersion: RULE_VERSION12,
+    ruleId: RULE_ID12,
+    ruleVersion: RULE_VERSION13,
     severity: policy.severity,
     message: spacingMessage(inline.property, inline.value, allowed, scale, checked) + (hopped?.suffix ?? ""),
     location: node.location,
@@ -7376,8 +7843,8 @@ function spacingMessage(property, value, allowed, scale, checked) {
 }
 
 // src/rules/styles-no-raw-typography.ts
-var RULE_ID12 = "styles/no-raw-typography";
-var RULE_VERSION13 = "1";
+var RULE_ID13 = "styles/no-raw-typography";
+var RULE_VERSION14 = "1";
 var FONT_SIZE_PROPERTIES = /* @__PURE__ */ new Set(["font-size", "fontsize"]);
 function ruleStylesNoRawTypography(ix) {
   const policy = ix.policy.fontSizeScale();
@@ -7396,8 +7863,8 @@ function ruleStylesNoRawTypography(ix) {
     const fixEmission = hopped ? void 0 : buildFix(decl.property, checked, ix);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID12,
-        ruleVersion: RULE_VERSION13,
+        ruleId: RULE_ID13,
+        ruleVersion: RULE_VERSION14,
         severity: policy.severity,
         message: typographyMessage(decl.property, decl.value, allowed, scale.unit, checked) + (hopped?.suffix ?? ""),
         location: decl.location,
@@ -7445,8 +7912,8 @@ function ruleStylesNoRawTypography(ix) {
     const evidenceIds = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id, scale.id] : [node.id, inline.id, policy.id, scale.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID12,
-        ruleVersion: RULE_VERSION13,
+        ruleId: RULE_ID13,
+        ruleVersion: RULE_VERSION14,
         severity: policy.severity,
         message: typographyMessage(inline.property, inline.value, allowed, scale.unit, checked) + (hopped?.suffix ?? ""),
         location: node.location,
@@ -7549,15 +8016,15 @@ function typographyMessage(property, value, allowed, unit, checked) {
 }
 
 // src/rules/theme-no-theme-coupled-literal.ts
-var RULE_ID13 = "theme/no-theme-coupled-literal";
-var RULE_VERSION14 = "1";
+var RULE_ID14 = "theme/no-theme-coupled-literal";
+var RULE_VERSION15 = "1";
 var COLOR_LITERAL_GLOBAL = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?|oklab|oklch|lab|lch)\(\s*[\d.%\s,\/]+\s*\)/g;
 var WHITE_RGBA = /^rgba?\(\s*255\s*,\s*255\s*,\s*255/i;
 var BLACK_RGBA = /^rgba?\(\s*0\s*,\s*0\s*,\s*0/i;
 var BOX_SHADOW_PROP = /^(?:-webkit-|-moz-)?box-shadow$/i;
 var NEUTRAL_SHADOW = /^(?:none|inherit|initial|unset|revert|revert-layer)\s*$/i;
 function ruleThemeNoThemeCoupledLiteral(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID13);
+  const policy = ix.policy.ruleConfig(RULE_ID14);
   if (!policy?.enabled) return [];
   const findings = [];
   for (const decl of ix.byKind("style_declaration")) {
@@ -7566,8 +8033,8 @@ function ruleThemeNoThemeCoupledLiteral(ix) {
     if (!hit) continue;
     findings.push(
       makeFinding({
-        ruleId: RULE_ID13,
-        ruleVersion: RULE_VERSION14,
+        ruleId: RULE_ID14,
+        ruleVersion: RULE_VERSION15,
         severity: policy.severity ?? "warn",
         message: hit.message,
         location: decl.location,
@@ -7657,8 +8124,8 @@ function isTokenFile(filePath) {
 }
 
 // src/rules/tailwind-arbitrary-color.ts
-var RULE_ID14 = "tailwind/arbitrary-color";
-var RULE_VERSION15 = "1";
+var RULE_ID15 = "tailwind/arbitrary-color";
+var RULE_VERSION16 = "1";
 var COLOR_UTILITIES = /* @__PURE__ */ new Set([
   "accent",
   "bg",
@@ -7700,8 +8167,8 @@ function ruleTailwindArbitraryColor(ix) {
     const evidenceIds = node ? [node.id, klass.id, policy.id] : [klass.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID14,
-        ruleVersion: RULE_VERSION15,
+        ruleId: RULE_ID15,
+        ruleVersion: RULE_VERSION16,
         severity: policy.severity,
         message: `\`${klass.raw}\` uses arbitrary raw color ${color}. Use a ${policy.prefer === "token" ? "design token" : "CSS variable"} instead.`,
         location: klass.location,
@@ -7732,8 +8199,8 @@ function fingerprintIdentity(klass, color) {
 }
 
 // src/rules/tailwind-arbitrary-spacing.ts
-var RULE_ID15 = "tailwind/arbitrary-spacing";
-var RULE_VERSION16 = "1";
+var RULE_ID16 = "tailwind/arbitrary-spacing";
+var RULE_VERSION17 = "1";
 var SPACING_UTILITY_TO_PROPERTY = /* @__PURE__ */ new Map([
   ["m", "margin"],
   ["mt", "margin"],
@@ -7779,8 +8246,8 @@ function ruleTailwindArbitrarySpacing(ix) {
     const fix = buildFix2(klass);
     findings.push(
       makeFinding({
-        ruleId: RULE_ID15,
-        ruleVersion: RULE_VERSION16,
+        ruleId: RULE_ID16,
+        ruleVersion: RULE_VERSION17,
         severity: policy.severity,
         message: `\`${klass.raw}\` is an arbitrary spacing value not on the project's spacing scale.`,
         location: klass.location,
@@ -7911,8 +8378,8 @@ function matchesTokenGlob(value, pattern) {
 }
 
 // src/rules/tailwind-forbidden-palette.ts
-var RULE_ID16 = "tailwind/forbidden-palette";
-var RULE_VERSION17 = "1";
+var RULE_ID17 = "tailwind/forbidden-palette";
+var RULE_VERSION18 = "1";
 function ruleTailwindForbiddenPalette(ix) {
   const deny = ix.policy.tailwindPaletteDeny();
   const allow = ix.policy.tailwindPaletteAllow();
@@ -7937,8 +8404,8 @@ function ruleTailwindForbiddenPalette(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, policy.id] : [klass.id, resolved.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID16,
-        ruleVersion: RULE_VERSION17,
+        ruleId: RULE_ID17,
+        ruleVersion: RULE_VERSION18,
         severity: policy.severity,
         message: messageFor(klass, token, deniedPattern, allow?.patterns ?? []),
         location: klass.location,
@@ -7985,8 +8452,8 @@ function buildFix3(klass) {
 }
 
 // src/rules/tailwind-off-scale-spacing-token.ts
-var RULE_ID17 = "tailwind/off-scale-spacing-token";
-var RULE_VERSION18 = "1";
+var RULE_ID18 = "tailwind/off-scale-spacing-token";
+var RULE_VERSION19 = "1";
 function ruleTailwindOffScaleSpacingToken(ix) {
   const resolvedByKey = indexResolvedTailwindTokens(ix);
   const findings = [];
@@ -8012,8 +8479,8 @@ function ruleTailwindOffScaleSpacingToken(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, policy.id, scale.id] : [klass.id, resolved.id, policy.id, scale.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID17,
-        ruleVersion: RULE_VERSION18,
+        ruleId: RULE_ID18,
+        ruleVersion: RULE_VERSION19,
         severity: policy.severity,
         message: `\`${klass.raw}\` resolves to ${formatResolvedValue(signedValue, scale.unit)}, which is not on the project's spacing scale [${allowed.join(", ")}].`,
         location: klass.location,
@@ -8062,8 +8529,8 @@ function buildFix4(raw, utility) {
 }
 
 // src/rules/tailwind-raw-color-via-token.ts
-var RULE_ID18 = "tailwind/raw-color-via-token";
-var RULE_VERSION19 = "1";
+var RULE_ID19 = "tailwind/raw-color-via-token";
+var RULE_VERSION20 = "1";
 function ruleTailwindRawColorViaToken(ix) {
   const allow = ix.policy.tailwindPaletteAllow();
   if (!allow || allow.patterns.length === 0) return [];
@@ -8083,8 +8550,8 @@ function ruleTailwindRawColorViaToken(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, allow.id] : [klass.id, resolved.id, allow.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID18,
-        ruleVersion: RULE_VERSION19,
+        ruleId: RULE_ID19,
+        ruleVersion: RULE_VERSION20,
         severity: allow.severity,
         message: `\`${klass.raw}\` resolves to raw color \`${color}\` (${sourceLabel2(resolved.resolved.source)}). Project policy requires \`${allow.patterns.join("`, `")}\` palette tokens.`,
         location: klass.location,
@@ -8117,8 +8584,8 @@ function sourceLabel2(source) {
 }
 
 // src/rules/tailwind-unknown-class.ts
-var RULE_ID19 = "tailwind/unknown-class";
-var RULE_VERSION20 = "1";
+var RULE_ID20 = "tailwind/unknown-class";
+var RULE_VERSION21 = "1";
 var UNIVERSAL_COLOR_KEYWORDS = /* @__PURE__ */ new Set([
   "white",
   "black",
@@ -8139,8 +8606,8 @@ function ruleTailwindUnknownClass(ix) {
       const evidenceIds2 = node2 ? [node2.id, klass.id, policy.id] : [klass.id, policy.id];
       findings.push(
         makeFinding({
-          ruleId: RULE_ID19,
-          ruleVersion: RULE_VERSION20,
+          ruleId: RULE_ID20,
+          ruleVersion: RULE_VERSION21,
           severity: policy.severity,
           message: `\`${klass.raw}\` could not be parsed as a known Tailwind utility.`,
           location: klass.location,
@@ -8174,8 +8641,8 @@ function ruleTailwindUnknownClass(ix) {
     const evidenceIds = node ? [node.id, klass.id, resolved.id, policy.id] : [klass.id, resolved.id, policy.id];
     findings.push(
       makeFinding({
-        ruleId: RULE_ID19,
-        ruleVersion: RULE_VERSION20,
+        ruleId: RULE_ID20,
+        ruleVersion: RULE_VERSION21,
         severity: policy.severity,
         message: `\`${klass.raw}\` did not resolve to any known palette token.`,
         location: klass.location,
@@ -8203,12 +8670,12 @@ function ruleTailwindUnknownClass(ix) {
 }
 
 // src/rules/tokens-require-dual-fallback.ts
-var RULE_ID20 = "tokens/require-dual-fallback";
-var RULE_VERSION21 = "1";
+var RULE_ID21 = "tokens/require-dual-fallback";
+var RULE_VERSION22 = "1";
 var CSS_VAR_WITH_OPTIONAL_FALLBACK = /var\(\s*(--[A-Za-z0-9_-]+)(\s*,\s*[^)]*)?\)/g;
 var SASS_FILE = /\.(scss|sass)$/i;
 function ruleTokensRequireDualFallback(ix) {
-  const policy = ix.policy.ruleConfig(RULE_ID20);
+  const policy = ix.policy.ruleConfig(RULE_ID21);
   if (!policy?.enabled) return [];
   const tokensByCssVariable = indexTokensByCssVariable(localTokenCandidates(ix));
   const findings = [];
@@ -8243,8 +8710,8 @@ function ruleTokensRequireDualFallback(ix) {
       ) : void 0;
       findings.push(
         makeFinding({
-          ruleId: RULE_ID20,
-          ruleVersion: RULE_VERSION21,
+          ruleId: RULE_ID21,
+          ruleVersion: RULE_VERSION22,
           severity: policy.severity ?? "warn",
           message: hasScssVariable ? `var(${tokenName}) is missing an SCSS fallback. Use var(${tokenName}, ${scssVar}).` : `var(${tokenName}) is missing a fallback. No matching SCSS variable was found in the token source; add a fallback manually or define ${scssVar}.`,
           location: decl.location,
@@ -8284,8 +8751,8 @@ function indexTokensByCssVariable(tokens) {
 }
 
 // src/rules/tokens-css-vars-must-be-defined.ts
-var RULE_ID21 = "tokens/css-vars-must-be-defined";
-var RULE_VERSION22 = "1";
+var RULE_ID22 = "tokens/css-vars-must-be-defined";
+var RULE_VERSION23 = "1";
 var CSS_VAR_REFERENCE = /var\(\s*(--[A-Za-z0-9_-]+)/gi;
 function ruleTokensCssVarsMustBeDefined(ix) {
   const policy = ix.policy.cssVarsMustBeDefined();
@@ -8312,8 +8779,8 @@ function ruleTokensCssVarsMustBeDefined(ix) {
       seen.add(tokenName);
       findings.push(
         makeFinding({
-          ruleId: RULE_ID21,
-          ruleVersion: RULE_VERSION22,
+          ruleId: RULE_ID22,
+          ruleVersion: RULE_VERSION23,
           severity: policy.severity,
           message: `var(${tokenName}) is not in the contract token vocabulary. Use a token defined in your contract's token source files.`,
           location: decl.location,
@@ -8360,8 +8827,8 @@ function skipToCloseParen(value, openParenIndex) {
 }
 
 // src/rules/tokens-upstream-drift.ts
-var RULE_ID22 = "tokens/upstream-drift";
-var RULE_VERSION23 = "1";
+var RULE_ID23 = "tokens/upstream-drift";
+var RULE_VERSION24 = "1";
 function ruleTokensUpstreamDrift(ix) {
   const local = ix.tokens.list().filter((token) => token.role !== "upstream");
   const upstream = ix.tokens.list().filter((token) => token.role === "upstream");
@@ -8387,8 +8854,8 @@ function ruleTokensUpstreamDrift(ix) {
     };
     findings.push(
       makeFinding({
-        ruleId: RULE_ID22,
-        ruleVersion: RULE_VERSION23,
+        ruleId: RULE_ID23,
+        ruleVersion: RULE_VERSION24,
         severity: "warn",
         message: `Local token ${token.name} is ${token.value}, but upstream ${upstreamName} is ${expected.value}.`,
         location,
@@ -8420,8 +8887,12 @@ var BLOCKING_RULE_ALLOWLIST = /* @__PURE__ */ new Set([
   // off-scale Tailwind spacing utility
   "components/prefer-library",
   // raw element bypasses a canonical component
-  "components/preferred-component"
+  "components/shadow-component",
+  // confirmed local semantic control shadows a canonical
+  "components/preferred-component",
   // imported component bypasses its canonical
+  "tokens/css-vars-must-be-defined"
+  // off-contract custom property reference
 ]);
 function gatesCi(finding, failOnWarnings) {
   if (!canBlock(finding.evidenceGrade ?? "source_backed")) return false;
@@ -8432,9 +8903,13 @@ function gatesCi(finding, failOnWarnings) {
 function isDenyEligible(finding, failOnWarnings) {
   if (!BLOCKING_RULE_ALLOWLIST.has(finding.ruleId)) return false;
   if (finding.attributes?.advisory === true) return false;
+  if (finding.ruleId === "components/shadow-component" && (finding.attributes?.state !== "shadow" || finding.attributes?.confidence !== "confirmed" || typeof finding.attributes?.canonicalTarget !== "string")) {
+    return false;
+  }
   if (!gatesCi(finding, failOnWarnings)) return false;
   if (finding.fix?.deterministic === false) {
-    if (finding.ruleId !== "components/prefer-library" || finding.attributes?.propCompatibility !== "observed-complete") {
+    const exactCanonicalBypass = finding.ruleId === "components/prefer-library" && finding.attributes?.precisionTier === "exact-html" && typeof finding.attributes?.suggestedComponent === "string";
+    if (!exactCanonicalBypass) {
       return false;
     }
   }
@@ -8471,6 +8946,7 @@ var RULE_TIER = {
   "tokens/require-dual-fallback": "hygiene",
   "theme/no-theme-coupled-literal": "hygiene",
   "a11y/required-accessible-name": "hygiene",
+  "a11y/standard": "hygiene",
   // Composition constraints are authored contracts, but not part of the
   // two-choice headline contract; they self-activate when patterns are declared
   // (the compiler injects their configs), so off-by-default here is harmless.
@@ -8632,9 +9108,14 @@ var RULES = [
   },
   {
     id: "a11y/required-accessible-name",
-    version: "1",
+    version: RULE_VERSION,
     run: ruleA11yRequiredAccessibleName
   },
+  {
+    id: "a11y/standard",
+    version: "1",
+    run: ruleA11yStandard
+  },
   {
     id: "composition/cardinality",
     version: "1",
@@ -8673,12 +9154,21 @@ function hasEffectiveComponentVocabulary(options) {
 }
 function effectiveRuleConfigs(policy) {
   const configs = /* @__PURE__ */ new Map();
-  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;
@@ -9082,23 +9572,28 @@ function evaluateGovernanceIntegrity(input) {
   if (!policyArmed) {
     policyFamily.reason = "no governance policy resolved";
   }
-  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 = {
     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";
     }
   }
@@ -9141,7 +9636,7 @@ function evaluateGovernanceIntegrity(input) {
   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);
@@ -9772,6 +10267,7 @@ export {
   CONTRACT_DOMAINS,
   CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
+  CompiledFragmentsFileValidationError,
   DEFAULTS,
   DEFAULT_ENHANCED_STYLE_PROPERTIES,
   DEFAULT_STYLE_PROPERTIES,
@@ -10010,6 +10506,7 @@ export {
   makeTailwindUnknownClassEnabledFact,
   makeThemeDeclarationFact,
   makeTokenDefinitionFact,
+  makeUsageChildContentFact,
   makeUsageComponentFact,
   makeUsageImportFact,
   makeUsageInlineStyleFact,
@@ -10058,6 +10555,7 @@ export {
   ownedImportEquivalents,
   parseColor,
   parseColorToRgb,
+  parseCompiledFragmentsFile,
   parseComponentContract,
   parseContractStamp,
   parseCssTokens,
@@ -10115,6 +10613,7 @@ export {
   resolveTokenValue,
   rgbToHex,
   ruleA11yRequiredAccessibleName,
+  ruleA11yStandard,
   ruleComponentsForbiddenPropValue,
   ruleComponentsPreferLibrary,
   ruleComponentsShadowComponent,