@usefragments/core 1.3.0 → 1.4.0

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

@@ -37,6 +37,12 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings: Finding[] = [];
 
+  // Newly-broadened detections (SVG paint attributes, runtime-constructed
+  // colors) ship advisory this release so CI gates do not harden on findings
+  // teams have not yet had a chance to triage. Existing passes keep the
+  // configured severity.
+  const advisorySeverity = policy.severity === "error" ? "warn" : policy.severity;
+
   for (const decl of ix.byKind("style_declaration")) {
     if (decl.property.startsWith("--") && decl.declaredTokenSource === true) continue;
     const color = detectRawColor(decl.value);
@@ -84,6 +90,43 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
 
   const componentByNode = indexComponentByNodeId(ix);
   for (const inline of ix.byKind("usage_inline_style")) {
+    // #11b — a runtime-constructed color (`` `#${red}` ``, `"rgb(" + r + …`).
+    // The extractor already proved the static fragments begin a color literal,
+    // so surface it detect-only: the value is partly runtime, so it never
+    // carries a deterministic fix and cannot resolve to a token.
+    if (inline.valueKind === "dynamic-raw") {
+      const node = readUsageNode(ix, inline.nodeId);
+      if (!node) continue;
+      const componentEvidenceId = componentByNode.get(node.id)?.id;
+      const evidenceIds = componentEvidenceId
+        ? [node.id, componentEvidenceId, inline.id, policy.id]
+        : [node.id, inline.id, policy.id];
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: advisorySeverity,
+          message: `Runtime-constructed raw color \`${inline.value}\` on inline \`${inline.property}\`. Use a ${preferLabel} instead.`,
+          location: node.location,
+          evidence: ix.evidence(evidenceIds),
+          fingerprintIdentity: {
+            source: "usage_inline_style_dynamic",
+            file: node.file,
+            nodePath: node.nodePath,
+            element: node.element,
+            property: inline.property,
+            value: inline.value,
+          },
+          attributes: {
+            property: inline.property,
+            rawValue: inline.value,
+            source: "jsx",
+            dynamic: true,
+          },
+        })
+      );
+      continue;
+    }
     if (inline.valueKind === "css-variable") continue;
     const color = detectRawColor(inline.value);
     if (!color) continue;
@@ -133,9 +176,91 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
     );
   }
 
+  // #9d — SVG presentation attributes carry color in JSX markup, not CSS, so
+  // they arrive as `usage_prop_resolved` facts the two passes above never read.
+  // Scan a fixed paint-attribute allowlist for static raw colors. Data-URI
+  // colors (hex inside an encoded `url("data:…")`) are intentionally left out.
+  for (const prop of ix.byKind("usage_prop_resolved")) {
+    if (prop.resolution !== "static") continue;
+    if (typeof prop.value !== "string") continue;
+    if (!SVG_PAINT_ATTRS.has(prop.prop)) continue;
+    const color = detectRawColor(prop.value);
+    if (!color) continue;
+    if (isExemptColor(color, policy.except)) continue;
+
+    const node = readUsageNode(ix, prop.nodeId);
+    if (!node) continue;
+
+    const componentEvidenceId = componentByNode.get(node.id)?.id;
+    const cssProperty = SVG_PAINT_CSS_PROPERTY[prop.prop] ?? prop.prop;
+    const resolution = resolveColorToken(cssProperty, color, colorTokens);
+    const fixEmission =
+      resolution?.kind === "exact"
+        ? buildTokenFix(cssProperty, prop.value, color, resolution, ix)
+        : undefined;
+    const baseEvidence = componentEvidenceId
+      ? [node.id, componentEvidenceId, prop.id, policy.id]
+      : [node.id, prop.id, policy.id];
+    const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: advisorySeverity,
+        message: colorMessage(color, `\`${prop.prop}\``, resolution, preferLabel),
+        location: prop.location ?? node.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "usage_prop_resolved",
+          file: node.file,
+          nodePath: node.nodePath,
+          element: node.element,
+          property: prop.prop,
+          value: color,
+        },
+        fix: fixEmission?.fix,
+        attributes: {
+          property: prop.prop,
+          rawValue: prop.value,
+          color,
+          source: "jsx",
+          suggestedToken: resolution?.token.name,
+          ...(resolution ? { tokenMatch: resolution.kind } : {}),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+        },
+      })
+    );
+  }
+
   return findings;
 }
 
+/**
+ * SVG presentation attributes that carry a paint (color) value in JSX markup.
+ * Both the raw-SVG kebab spelling and React's camelCase normalization are
+ * listed so `stop-color` and `stopColor` both resolve.
+ */
+const SVG_PAINT_ATTRS = new Set([
+  "fill",
+  "stroke",
+  "color",
+  "stop-color",
+  "stopColor",
+  "flood-color",
+  "floodColor",
+  "lighting-color",
+  "lightingColor",
+]);
+
+/** Map camelCase paint attributes to their CSS property name so the token
+ *  role-resolver (`colorRoleForProperty`) reasons over a canonical spelling. */
+const SVG_PAINT_CSS_PROPERTY: Record<string, string> = {
+  stopColor: "stop-color",
+  floodColor: "flood-color",
+  lightingColor: "lighting-color",
+};
+
 interface TokenMatch {
   token: TokenDefinitionFact;
   /** True when several tokens share the value and none matches the property's

package/src/schema.ts

@@ -244,6 +244,10 @@ const tokenConfigSchema = z
   .object({
     include: repoRelativePathsSchema.optional(),
     sources: z.array(tokenSourceSchema).min(1).optional(),
+    // Declared design-system packages whose shipped fragments.json token
+    // vocabulary seeds the known-token set (#7c). A packages-only tokens block
+    // is valid — see the superRefine below.
+    packages: z.array(z.string().min(1)).optional(),
     exclude: z.array(repoRelativePathSchema).optional(),
     themeSelectors: z.record(z.string()).optional(),
     enabled: z.boolean().optional(),
@@ -252,10 +256,10 @@ const tokenConfigSchema = z
   })
   .passthrough()
   .superRefine((tokens, ctx) => {
-    if (!tokens.include?.length && !tokens.sources?.length) {
+    if (!tokens.include?.length && !tokens.sources?.length && !tokens.packages?.length) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: "Add tokens.include or tokens.sources",
+        message: "Add tokens.include, tokens.sources, or tokens.packages",
         path: ["sources"],
       });
     }

package/src/token-types.ts

@@ -193,6 +193,18 @@ export interface TokenConfig {
    */
   exclude?: string[];
 
+  /**
+   * npm package names whose SHIPPED `fragments.json` token vocabulary should seed
+   * the known-token set (e.g. `["@usefragments/ui"]`). This is a DECLARED-manifest
+   * ingest — the parser reads each package's published `fragments.json` (via its
+   * `<pkg>/fragments.json` export or its package.json `fragments` field) and
+   * merges the token NAMES into the vocabulary consumed by
+   * `tokens/css-vars-must-be-defined`, so a consumer using those `--fui-*` vars is
+   * not flagged as off-contract drift. node_modules SCSS is NEVER globbed — only
+   * the declared manifest is trusted, keeping the no-inference mandate intact.
+   */
+  packages?: string[];
+
   /**
    * Map CSS selectors to theme names
    * @example { ":root": "default", "[data-theme='dark']": "dark" }

package/src/tokens/categories.ts

@@ -96,7 +96,48 @@ export function inferTokenGroup(name: string): string {
   }
 }
 
-export function normalizeTokenGroupComment(comment: string): string {
+/**
+ * Curated section-comment → category map. ONLY these headings (and short, clean
+ * uncurated headings) become token categories. A prose comment latched as a
+ * category is the #7d smell (`the-@supports-block-below-…` etc.), so anything
+ * that is not curated AND does not read like a heading returns `null`, letting
+ * the caller fall back to name-based `inferTokenGroup`.
+ */
+const TOKEN_GROUP_COMMENT_MAPPINGS: Record<string, string> = {
+  "base configuration": "base",
+  typography: "typography",
+  "spacing (micro)": "spacing",
+  spacing: "spacing",
+  "density padding": "spacing",
+  "border radius": "radius",
+  transitions: "transitions",
+  colors: "colors",
+  surfaces: "surfaces",
+  text: "text",
+  borders: "borders",
+  shadows: "shadows",
+  focus: "focus",
+  scrollbar: "scrollbar",
+  "component heights": "component-sizing",
+  "appshell layout": "layout",
+  codeblock: "code",
+  tooltip: "tooltip",
+  "hero/marketing gradient": "marketing",
+};
+
+/**
+ * A "clean heading" is alphanumerics + spaces + hyphens only (no punctuation,
+ * symbols, em/en dashes, parens, `@`, `/`, etc.) and at most three words. Prose
+ * comments — which carry punctuation and/or run long — fail this and are NOT
+ * treated as categories.
+ */
+function looksLikeCleanHeading(text: string): boolean {
+  if (!/^[a-z0-9][a-z0-9 -]*$/.test(text)) return false;
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  return wordCount > 0 && wordCount <= 3;
+}
+
+export function normalizeTokenGroupComment(comment: string): string | null {
   const text = comment
     .trim()
     .replace(/^\/\/\s*/, "")
@@ -105,27 +146,16 @@ export function normalizeTokenGroupComment(comment: string): string {
     .trim()
     .toLowerCase();
 
-  const mappings: Record<string, string> = {
-    "base configuration": "base",
-    typography: "typography",
-    "spacing (micro)": "spacing",
-    spacing: "spacing",
-    "density padding": "spacing",
-    "border radius": "radius",
-    transitions: "transitions",
-    colors: "colors",
-    surfaces: "surfaces",
-    text: "text",
-    borders: "borders",
-    shadows: "shadows",
-    focus: "focus",
-    scrollbar: "scrollbar",
-    "component heights": "component-sizing",
-    "appshell layout": "layout",
-    codeblock: "code",
-    tooltip: "tooltip",
-    "hero/marketing gradient": "marketing",
-  };
-
-  return mappings[text] ?? text.replace(/\s+/g, "-");
+  if (text in TOKEN_GROUP_COMMENT_MAPPINGS) {
+    return TOKEN_GROUP_COMMENT_MAPPINGS[text];
+  }
+
+  // Uncurated: only accept short, clean headings as categories. Prose comments
+  // (punctuation/symbols or >3 words) return null so the token falls through to
+  // name-based inference instead of minting a garbage category slug (#7d).
+  if (!looksLikeCleanHeading(text)) {
+    return null;
+  }
+
+  return text.replace(/\s+/g, "-");
 }

package/src/tokens/scss.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+
+import { normalizeTokenGroupComment } from "./categories.js";
+import { parseScssTokens } from "./scss.js";
+
+/**
+ * FRICTION #7d — stop prose SCSS comments from being slugified into token
+ * categories (the `the-@supports-block-below-…` / `colors-—-accent-(…)` smell in
+ * ui/fragments.json). Prose comments must fall through to name-based inference;
+ * curated section headings still map.
+ */
+
+describe("normalizeTokenGroupComment (#7d)", () => {
+  it("maps curated section headings", () => {
+    expect(normalizeTokenGroupComment("// Typography")).toBe("typography");
+    expect(normalizeTokenGroupComment("// Spacing")).toBe("spacing");
+    expect(normalizeTokenGroupComment("// Spacing (micro)")).toBe("spacing");
+    expect(normalizeTokenGroupComment("// Component heights")).toBe("component-sizing");
+  });
+
+  it("returns null for prose comments (punctuation / symbols / long)", () => {
+    expect(
+      normalizeTokenGroupComment("// The @supports block below derives accent tokens")
+    ).toBeNull();
+    expect(
+      normalizeTokenGroupComment("// Colors — accent (light/dark for automatic dark mode)")
+    ).toBeNull();
+    expect(normalizeTokenGroupComment("// Shadows (not <color> type)")).toBeNull();
+    expect(
+      normalizeTokenGroupComment("// Touch targets (density-responsive, control floor: 32px)")
+    ).toBeNull();
+  });
+
+  it("slugifies a short, clean uncurated heading", () => {
+    expect(normalizeTokenGroupComment("// Custom Section")).toBe("custom-section");
+  });
+});
+
+describe("parseScssTokens category derivation (#7d)", () => {
+  it("does not create a category from a prose comment; tokens fall to name inference", () => {
+    const scss = `
+:root {
+  // The @supports block below derives accent/semantic tokens from these seeds
+  --fui-color-accent: #39594d;
+  --fui-space-3: 12px;
+}
+`;
+    const out = parseScssTokens(scss);
+    const categoryKeys = Object.keys(out.categories);
+
+    // No garbage slug leaked in.
+    for (const key of categoryKeys) {
+      expect(key).not.toMatch(/[@(<>—/]/);
+    }
+    expect(categoryKeys).not.toContain(
+      "the-@supports-block-below-derives-accent/semantic-tokens-from-these-seeds"
+    );
+
+    // Tokens are categorized by NAME inference instead.
+    const accent = out.categories.colors?.find((t) => t.name === "--fui-color-accent");
+    expect(accent).toBeDefined();
+    const space = out.categories.spacing?.find((t) => t.name === "--fui-space-3");
+    expect(space).toBeDefined();
+  });
+
+  it("still honors curated section headings", () => {
+    const scss = `
+:root {
+  // Typography
+  --fui-font-size-md: 1rem;
+  // Spacing
+  --fui-space-1: 4px;
+}
+`;
+    const out = parseScssTokens(scss);
+    expect(out.categories.typography?.some((t) => t.name === "--fui-font-size-md")).toBe(true);
+    expect(out.categories.spacing?.some((t) => t.name === "--fui-space-1")).toBe(true);
+  });
+
+  it("resets to name inference after a prose comment interrupts a curated section", () => {
+    const scss = `
+:root {
+  // Typography
+  --fui-font-size-md: 1rem;
+  // This is an explanatory note about the following block, not a heading!
+  --fui-color-accent: #39594d;
+}
+`;
+    const out = parseScssTokens(scss);
+    // The prose comment must NOT latch "typography" onto the color token.
+    expect(out.categories.typography?.some((t) => t.name === "--fui-color-accent")).not.toBe(true);
+    expect(out.categories.colors?.some((t) => t.name === "--fui-color-accent")).toBe(true);
+  });
+});

package/src/tokens/scss.ts

@@ -87,7 +87,11 @@ export function parseScssTokens(content: string, filePath = "tokens.scss"): Toke
   const tokens: ParsedToken[] = [];
   const seenNames = new Set<string>();
   let currentCategory = "other";
-  let hasCommentCategories = false;
+  // Tracks whether the CURRENT section comment yielded a curated category. A
+  // prose comment (normalizeTokenGroupComment → null) resets this so subsequent
+  // tokens fall through to name-based inference instead of inheriting a stale or
+  // garbage comment-derived category (#7d).
+  let currentCategoryIsCurated = false;
 
   const scssVars = parseScssVariables(content);
   const varDeclRegex = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;/;
@@ -99,7 +103,10 @@ export function parseScssTokens(content: string, filePath = "tokens.scss"): Toke
       const normalized = normalizeTokenGroupComment(commentMatch[0]);
       if (normalized) {
         currentCategory = normalized;
-        hasCommentCategories = true;
+        currentCategoryIsCurated = true;
+      } else {
+        // Prose comment: not a category. Drop back to per-token name inference.
+        currentCategoryIsCurated = false;
       }
       continue;
     }
@@ -119,7 +126,7 @@ export function parseScssTokens(content: string, filePath = "tokens.scss"): Toke
       tokens.push({
         name,
         value: cleanValue || undefined,
-        category: hasCommentCategories ? currentCategory : inferTokenGroup(name),
+        category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name),
         description,
       });
     }
@@ -131,7 +138,7 @@ export function parseScssTokens(content: string, filePath = "tokens.scss"): Toke
     tokens.push({
       name,
       value,
-      category: hasCommentCategories ? currentCategory : inferTokenGroup(name),
+      category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name),
     });
   }
 

package/src/types.ts

@@ -581,6 +581,17 @@ export interface TokenConfig {
   /** Repo-root-relative token source files/globs for monorepos and Cloud setup. */
   sources?: TokenSourceConfig[];
 
+  /**
+   * npm package names whose shipped `fragments.json` token vocabulary seeds the
+   * known-token set (e.g. `["@usefragments/ui"]`). DECLARED-manifest ingest —
+   * the parser reads each package's published `fragments.json` and merges its
+   * token names into the vocabulary `tokens/css-vars-must-be-defined` consumes,
+   * so a consumer using those `--fui-*` vars is not flagged as drift. Never
+   * globs node_modules SCSS — only the declared manifest is trusted, keeping the
+   * no-inference mandate intact.
+   */
+  packages?: string[];
+
   /**
    * Glob patterns to exclude
    * @example ["node_modules"]