@usefragments/core 1.5.2 → 1.7.0

package/src/rules/jsx-preferred-import-path.ts

@@ -1,4 +1,4 @@
-import type { FactIndex } from "../facts/index.js";
+import type { FactIndex, JsxImportPathPreferredFact, UsageImportFact } from "../facts/index.js";
 import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
 
 import { makeFinding } from "./finding.js";
@@ -15,22 +15,21 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
   const seen = new Set<string>();
 
   for (const usage of ix.byKind("usage_import")) {
+    // A confirmed bridge supersedes any non-bridge preference over the same
+    // underlying import (report #2 B6): without this, both policies emit with
+    // the same fingerprint (corrupting baseline/Cloud dedupe) and the hand
+    // rule flags the wrapper's own implementation file with a self-import fix.
+    // The bridge's domain — not its implementation-file exemption — decides
+    // supersession, so inside an exempt file the duplicate stays silent too.
+    const bridgeGoverned = policies.some((policy) => bridgeGovernsUnderlyingImport(policy, usage));
     const matches = policies.filter((policy) => {
       if (policy.bridge) {
         if (policy.bridge.implementationFiles.some((file) => sameRepoPath(file, usage.file))) {
           return false;
         }
-        if (!ownedImportMatchesRoot(usage.source, policy.from)) return false;
-        if (ownedImportsEqual(usage.source, policy.from)) {
-          return usage.imported === policy.bridge.underlyingExportName;
-        }
-        const subpath = usage.source.slice(policy.from.length + 1);
-        const leaf = subpath.split("/").at(-1);
-        return (
-          leaf === policy.bridge.underlyingExportName &&
-          (usage.imported === "default" || usage.imported === policy.bridge.underlyingExportName)
-        );
+        return bridgeGovernsUnderlyingImport(policy, usage);
       }
+      if (bridgeGoverned) return false;
       if (!ownedImportsEqual(policy.from, usage.source)) return false;
       if (policy.imported !== undefined && policy.imported !== usage.imported) return false;
       return true;
@@ -94,6 +93,25 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
   return findings;
 }
 
+/** Whether the bridge policy's underlying-import domain covers this usage. */
+function bridgeGovernsUnderlyingImport(
+  policy: JsxImportPathPreferredFact,
+  usage: UsageImportFact
+): boolean {
+  const bridge = policy.bridge;
+  if (!bridge) return false;
+  if (!ownedImportMatchesRoot(usage.source, policy.from)) return false;
+  if (ownedImportsEqual(usage.source, policy.from)) {
+    return usage.imported === bridge.underlyingExportName;
+  }
+  const subpath = usage.source.slice(policy.from.length + 1);
+  const leaf = subpath.split("/").at(-1);
+  return (
+    leaf === bridge.underlyingExportName &&
+    (usage.imported === "default" || usage.imported === bridge.underlyingExportName)
+  );
+}
+
 function sameRepoPath(left: string, right: string): boolean {
   return normalizeRepoPath(left) === normalizeRepoPath(right);
 }

package/src/rules/rules.test.ts

@@ -11,12 +11,15 @@ import {
   makeClassNameDynamicFact,
   makeStyleDeclarationFact,
   makeTokenDefinitionFact,
+  makeUsageChildContentFact,
   makeUsageComponentFact,
   makeUsageImportFact,
   makeUsageInlineStyleFact,
   makeUsageNodeFact,
   makeUsagePropResolvedFact,
   makeUsageTextChildFact,
+  projectSupersededImportPathPreferences,
+  RULES,
   ruleA11yRequiredAccessibleName,
   ruleComponentsForbiddenPropValue,
   ruleComponentsPreferLibrary,
@@ -32,7 +35,8 @@ import {
   ruleTokensRequireDualFallback,
   runRules,
 } from "../index.js";
-import type { Fact, FactId } from "../index.js";
+import type { CanonicalBridgeV1, Fact, FactId } from "../index.js";
+import { RULE_VERSION as A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION } from "./a11y-required-accessible-name.js";
 
 type ButtonProps = {
   variant?: "primary" | "secondary" | "ghost" | "link";
@@ -137,6 +141,7 @@ interface ButtonUsageInput {
     value: string;
   }>;
   text?: string;
+  childContent?: "static-text" | "runtime" | "structural" | "empty";
 }
 
 function addButtonUsage(ix: FactIndex, input: ButtonUsageInput): { nodeId: FactId } {
@@ -175,6 +180,14 @@ function addButtonUsage(ix: FactIndex, input: ButtonUsageInput): { nodeId: FactI
   if (input.text !== undefined) {
     ix.add(makeUsageTextChildFact({ nodeId: node.id, text: input.text, index: 0 }));
   }
+  if (input.childContent !== undefined) {
+    ix.add(
+      makeUsageChildContentFact({
+        nodeId: node.id,
+        content: input.childContent,
+      })
+    );
+  }
   return { nodeId: node.id };
 }
 
@@ -625,6 +638,129 @@ describe("preferred JSX imports and components", () => {
     expect(ruleJsxPreferredImportPath(ix)).toHaveLength(0);
   });
 
+  // Report #2 B6 (brownfield-canonical brief 03): a confirmed bridge
+  // supersedes any non-bridge preference over the same underlying import —
+  // otherwise both emit with the same fingerprint and the hand rule flags the
+  // wrapper's own implementation file with a self-import fix.
+  describe("bridge supersession of non-bridge import preferences", () => {
+    const B6_BRIDGE: CanonicalBridgeV1 = {
+      underlying: { packageName: "@mui/material", exportName: "Button" },
+      local: {
+        componentKey: "src/components/Button.tsx#Button",
+        moduleSpecifier: "@/components",
+        exportName: "Button",
+        implementationFiles: ["src/components/Button.tsx"],
+      },
+      decision: { state: "confirmed", source: "authored" },
+    };
+
+    it("emits only the bridge finding when a hand-authored record duplicates it", () => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components", { imported: "Button" })],
+          canonicalBridges: [B6_BRIDGE],
+        })
+      );
+      ix.add(
+        makeUsageImportFact({
+          file: "src/app/page.tsx",
+          local: "MuiButton",
+          imported: "Button",
+          source: "@mui/material",
+          location: { file: "src/app/page.tsx", line: 1, column: 0 },
+        })
+      );
+
+      const findings = ruleJsxPreferredImportPath(ix);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].attributes).toMatchObject({ canonicalBridge: true });
+    });
+
+    it("keeps the hand rule silent inside the wrapper implementation file", () => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components", { imported: "Button" })],
+          canonicalBridges: [B6_BRIDGE],
+        })
+      );
+      ix.add(
+        makeUsageImportFact({
+          file: "src/components/Button.tsx",
+          local: "MuiButton",
+          imported: "Button",
+          source: "@mui/material",
+          location: { file: "src/components/Button.tsx", line: 1, column: 0 },
+        })
+      );
+
+      expect(ruleJsxPreferredImportPath(ix)).toHaveLength(0);
+    });
+
+    it("leaves the hand rule firing on imports the bridge does not govern", () => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components")],
+          canonicalBridges: [B6_BRIDGE],
+        })
+      );
+      ix.add(
+        makeUsageImportFact({
+          file: "src/app/page.tsx",
+          local: "Stepper",
+          imported: "Stepper",
+          source: "@mui/material",
+          location: { file: "src/app/page.tsx", line: 1, column: 0 },
+        })
+      );
+
+      const findings = ruleJsxPreferredImportPath(ix);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].attributes).toMatchObject({ imported: "Stepper" });
+      expect(findings[0].attributes?.canonicalBridge).toBeUndefined();
+    });
+
+    it("names each superseded record through the compile-side projection", () => {
+      const superseded = projectSupersededImportPathPreferences({
+        jsx: [
+          g.jsx.importPath().prefer("@mui/material", "@/components", { imported: "Button" }),
+          g.jsx.importPath().prefer("@mui/material/Button", "@/components"),
+          g.jsx.importPath().prefer("@mui/material", "@/inputs", { imported: "TextField" }),
+          g.jsx.importPath().prefer("@legacy/ui", "@usefragments/ui"),
+        ],
+        canonicalBridges: [B6_BRIDGE],
+      });
+
+      expect(superseded).toEqual([
+        {
+          from: "@mui/material",
+          imported: "Button",
+          to: "@/components",
+          packageName: "@mui/material",
+          underlyingExportName: "Button",
+          localExportName: "Button",
+        },
+        {
+          from: "@mui/material/Button",
+          to: "@/components",
+          packageName: "@mui/material",
+          underlyingExportName: "Button",
+          localExportName: "Button",
+        },
+      ]);
+    });
+
+    it("projects nothing without bridges", () => {
+      expect(
+        projectSupersededImportPathPreferences({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components")],
+        })
+      ).toEqual([]);
+    });
+  });
+
   it("does not exempt sibling helpers, stories, barrels, or consumers", () => {
     const ix = new FactIndex();
     ix.addMany(
@@ -1148,6 +1284,47 @@ describe("a11y/required-accessible-name", () => {
     }
   });
 
+  it("does not fire for conservatively classified runtime child content", () => {
+    const ix = emptyIndexWithGovernance();
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0",
+      line: 1,
+      column: 0,
+      props: [{ prop: "children", resolution: "jsx" }],
+      childContent: "runtime",
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
+  });
+
+  it.each(["structural", "empty"] as const)("still fires for %s child content", (childContent) => {
+    const ix = emptyIndexWithGovernance();
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0",
+      line: 1,
+      column: 0,
+      props: [{ prop: "children", resolution: "jsx" }],
+      childContent,
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(1);
+  });
+
+  it("does not infer a name from the public children prop-resolution fact", () => {
+    const ix = emptyIndexWithGovernance();
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0",
+      line: 1,
+      column: 0,
+      props: [{ prop: "children", resolution: "dynamic" }],
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(1);
+  });
+
   it("fires for an empty Button with no name source", () => {
     const ix = emptyIndexWithGovernance();
     addButtonUsage(ix, {
@@ -1174,6 +1351,11 @@ describe("a11y/required-accessible-name", () => {
 
     expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
   });
+
+  it("keeps the registry version in lockstep with the emitted finding version", () => {
+    const registered = RULES.find((rule) => rule.id === "a11y/required-accessible-name");
+    expect(registered?.version).toBe(A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION);
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -2991,7 +3173,7 @@ describe("components/prefer-library", () => {
       expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
     });
 
-    it("flags raw <button> → Button without advertising it as deterministic when Button is not imported", () => {
+    it("keeps raw <button> → Button advisory without treating the directory as import-ready", () => {
       const ix = new FactIndex();
       ix.addMany(
         compileGlobalGovernanceFacts({
@@ -3027,14 +3209,12 @@ describe("components/prefer-library", () => {
           rawValue: "button",
           suggestedComponent: "Button",
           suggestedImportSourceKind: "directory",
+          canonicalDirectory: "src/fragments/ui/components",
+          importReady: false,
+          advisory: true,
         },
       });
-      expect(findings[0].fix).toMatchObject({
-        kind: "replaceComponent",
-        from: "button",
-        to: "Button",
-        deterministic: false,
-      });
+      expect(findings[0].fix).toBeUndefined();
     });
 
     it("flags a raw element by canonical vocab id when display name diverges (Modal → Dialog)", () => {

package/src/rules/styles-no-raw-color.ts

@@ -20,6 +20,7 @@ import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   detectRawColor,
   emitFix,
+  hoppedValue,
   indexComponentByNodeId,
   isExemptColor,
   readUsageNode,
@@ -51,8 +52,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
     if (isExemptColor(color, policy.except)) continue;
 
     const resolution = resolveColorToken(decl.property, color, colorTokens);
+    const hopped = hoppedValue(decl);
     const fixEmission =
-      resolution?.kind === "exact"
+      resolution?.kind === "exact" && !hopped
         ? buildTokenFix(decl.property, decl.value, color, resolution, ix)
         : undefined;
     const evidenceIds = resolution
@@ -64,7 +66,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: colorMessage(color, `\`${decl.property}\``, resolution, preferLabel),
+        message:
+          colorMessage(color, `\`${decl.property}\``, resolution, preferLabel) +
+          (hopped?.suffix ?? ""),
         location: decl.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -84,6 +88,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );
@@ -138,8 +143,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
 
     const componentEvidenceId = componentByNode.get(node.id)?.id;
     const resolution = resolveColorToken(inline.property, color, colorTokens);
+    const hopped = hoppedValue(inline);
     const fixEmission =
-      resolution?.kind === "exact"
+      resolution?.kind === "exact" && !hopped
         ? buildTokenFix(inline.property, inline.value, color, resolution, ix)
         : undefined;
     const baseEvidence = componentEvidenceId
@@ -152,7 +158,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: colorMessage(color, `inline \`${inline.property}\``, resolution, preferLabel),
+        message:
+          colorMessage(color, `inline \`${inline.property}\``, resolution, preferLabel) +
+          (hopped?.suffix ?? ""),
         location: node.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -172,6 +180,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );

package/src/rules/styles-no-raw-dimensions.ts

@@ -34,6 +34,7 @@ import { localTokenCandidates } from "./token-candidates.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   emitFix,
+  hoppedValue,
   indexComponentByNodeId,
   parseLengthValue,
   readUsageNode,
@@ -83,14 +84,17 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
     if (!resolution) continue;
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [decl.id, policy.id, ...tokenIds] : [decl.id, policy.id];
-    const fixEmission = dimensionFix(decl.property, resolution, ix);
+    const hopped = hoppedValue(decl);
+    const fixEmission = hopped ? undefined : dimensionFix(decl.property, resolution, ix);
 
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: dimensionMessage(decl.value, decl.property, preferLabel, resolution, false),
+        message:
+          dimensionMessage(decl.value, decl.property, preferLabel, resolution, false) +
+          (hopped?.suffix ?? ""),
         location: decl.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -108,6 +112,7 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           source: "css",
           suggestedToken: resolutionSuggestedToken(resolution),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );
@@ -131,14 +136,17 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
       : [node.id, inline.id, policy.id];
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [...baseEvidence, ...tokenIds] : baseEvidence;
-    const fixEmission = dimensionFix(inline.property, resolution, ix);
+    const hopped = hoppedValue(inline);
+    const fixEmission = hopped ? undefined : dimensionFix(inline.property, resolution, ix);
 
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: dimensionMessage(inline.value, inline.property, preferLabel, resolution, true),
+        message:
+          dimensionMessage(inline.value, inline.property, preferLabel, resolution, true) +
+          (hopped?.suffix ?? ""),
         location: node.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -156,6 +164,7 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           source: "jsx",
           suggestedToken: resolutionSuggestedToken(resolution),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );

package/src/rules/styles-no-raw-spacing.ts

@@ -45,6 +45,7 @@ import {
 import type { Finding } from "./types.js";
 import {
   emitFix,
+  hoppedValue,
   indexComponentByNodeId,
   readUsageNode,
   tokenSymbolsInText,
@@ -111,13 +112,15 @@ function checkDeclaration(
     tokens: lookupFor(scale),
   });
   if (!checked) return null;
-  const fixEmission = buildSpacingFix(decl.property, checked, ix);
+  const hopped = hoppedValue(decl);
+  const fixEmission = hopped ? undefined : buildSpacingFix(decl.property, checked, ix);
 
   return makeFinding({
     ruleId: RULE_ID,
     ruleVersion: RULE_VERSION,
     severity: policy.severity,
-    message: spacingMessage(decl.property, decl.value, allowed, scale, checked),
+    message:
+      spacingMessage(decl.property, decl.value, allowed, scale, checked) + (hopped?.suffix ?? ""),
     location: decl.location,
     evidence: ix.evidence([decl.id, policy.id, scale.id]),
     fingerprintIdentity: {
@@ -144,6 +147,7 @@ function checkDeclaration(
       assumedEmBasePx: checked.assumedEmBasePx,
       source: "css",
       ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+      ...(hopped?.attributes ?? {}),
     },
   });
 }
@@ -171,7 +175,8 @@ function checkInlineStyle(
     bareNumberFix: inline.valueKind === "number",
   });
   if (!checked) return null;
-  const fixEmission = buildSpacingFix(inline.property, checked, ix);
+  const hopped = hoppedValue(inline);
+  const fixEmission = hopped ? undefined : buildSpacingFix(inline.property, checked, ix);
 
   const node = readUsageNode(ix, inline.nodeId);
   if (!node) return null;
@@ -185,7 +190,9 @@ function checkInlineStyle(
     ruleId: RULE_ID,
     ruleVersion: RULE_VERSION,
     severity: policy.severity,
-    message: spacingMessage(inline.property, inline.value, allowed, scale, checked),
+    message:
+      spacingMessage(inline.property, inline.value, allowed, scale, checked) +
+      (hopped?.suffix ?? ""),
     location: node.location,
     evidence: ix.evidence(evidenceIds),
     fingerprintIdentity: {
@@ -212,6 +219,7 @@ function checkInlineStyle(
       assumedEmBasePx: checked.assumedEmBasePx,
       source: "jsx",
       ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+      ...(hopped?.attributes ?? {}),
     },
   });
 }

package/src/rules/styles-no-raw-typography.ts

@@ -31,6 +31,7 @@ import type { Finding } from "./types.js";
 import {
   indexComponentByNodeId,
   emitFix,
+  hoppedValue,
   matchesScale,
   nearestSignedScaleValue,
   normalizeLengthForScale,
@@ -61,13 +62,16 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
     if (decl.property.toLowerCase() !== "font-size") continue;
     const checked = checkFontSize(decl.value, allowed, scale, tokens);
     if (!checked) continue;
-    const fixEmission = buildFix(decl.property, checked, ix);
+    const hopped = hoppedValue(decl);
+    const fixEmission = hopped ? undefined : buildFix(decl.property, checked, ix);
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: typographyMessage(decl.property, decl.value, allowed, scale.unit, checked),
+        message:
+          typographyMessage(decl.property, decl.value, allowed, scale.unit, checked) +
+          (hopped?.suffix ?? ""),
         location: decl.location,
         evidence: ix.evidence([decl.id, policy.id, scale.id]),
         fingerprintIdentity: {
@@ -88,6 +92,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           matchedToken: checked.matchedToken,
           source: "css",
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );
@@ -105,7 +110,8 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
       inline.valueKind === "number"
     );
     if (!checked) continue;
-    const fixEmission = buildFix(inline.property, checked, ix);
+    const hopped = hoppedValue(inline);
+    const fixEmission = hopped ? undefined : buildFix(inline.property, checked, ix);
     const node = readUsageNode(ix, inline.nodeId);
     if (!node) continue;
     const componentEvidenceId = componentByNode.get(node.id)?.id;
@@ -117,7 +123,9 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: typographyMessage(inline.property, inline.value, allowed, scale.unit, checked),
+        message:
+          typographyMessage(inline.property, inline.value, allowed, scale.unit, checked) +
+          (hopped?.suffix ?? ""),
         location: node.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -138,6 +146,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           matchedToken: checked.matchedToken,
           source: "jsx",
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );

package/src/rules/tiers.ts

@@ -51,6 +51,7 @@ export const RULE_TIER: Readonly<Record<string, RuleTier>> = {
   "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.

package/src/rules/utils.ts

@@ -232,6 +232,45 @@ export function readStyleDeclaration(ix: FactIndex, id: FactId): StyleDeclaratio
   return fact && fact.kind === "style_declaration" ? fact : undefined;
 }
 
+/** What a raw-value rule needs to report a value that arrived through a hop. */
+export interface HoppedValue {
+  /** Appended to the message so the use site names the declaration a reader
+   *  cannot see from the finding's own line. */
+  suffix: string;
+  /** Merged into the finding's attributes for JSON/SARIF consumers. */
+  attributes: {
+    valueFrom: "const-binding";
+    declaredAs: string;
+    declaredAt: string;
+  };
+}
+
+/**
+ * Shared reading of `valueFrom` provenance for the raw-value style rules
+ * (color, spacing, dimensions, typography). One helper so a const-resolved
+ * value reports identically everywhere instead of becoming a color special
+ * case.
+ *
+ * Callers must also drop their fix when this returns a value: the authored text
+ * at the finding's location is an identifier, so replacing "the value" there
+ * would rewrite code the user never wrote.
+ */
+export function hoppedValue(fact: {
+  valueFrom?: { kind: "const-binding"; name: string; location: { file: string; line: number } };
+}): HoppedValue | undefined {
+  const from = fact.valueFrom;
+  if (!from) return undefined;
+  const declaredAt = `${from.location.file}:${from.location.line}`;
+  return {
+    suffix: ` Value comes from \`${from.name}\`, declared at ${declaredAt}.`,
+    attributes: {
+      valueFrom: "const-binding",
+      declaredAs: from.name,
+      declaredAt,
+    },
+  };
+}
+
 /**
  * The set of CSS custom-property names a token vocabulary defines, normalized to
  * `--`-prefixed form. Shared by the token-vocabulary rules