figma-console-mcp 1.37.1 → 1.38.2

package/README.md

@@ -8,7 +8,7 @@
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, **debugging**, and **bidirectional token sync**.
 
-> **🆕 Design-System Health Audit for Every Client (v1.37.0, scoring calibrated in v1.37.1):** new `figma_audit_design_system_report` tool runs the Design System Dashboard's deterministic scoring engine — naming, tokens, component metadata, accessibility, consistency, coverage — and returns the scored report as data, so **any** MCP client (Claude Code, headless agents, CI) can audit without MCP Apps support or `ENABLE_MCP_APPS`. Live-first data (fileKey-verified per-page bridge crawl, REST published fallback — the source is disclosed), 5-minute cache, chunked per-category drill-down, and every finding states whether this MCP can auto-fix it. Server-only release — **no plugin re-import needed**. [See what's new →](CHANGELOG.md#1371---2026-07-22)
+> **🔌 Connection Stability Fix (v1.38.2):** If your MCP client kept showing **"Server disconnected"**, this release fixes it. The server's own orphan reaper was terminating *healthy* servers: its `/health` liveness probe requested `127.0.0.1` while the server binds `localhost`, which resolves to the **IPv6 loopback** on dual-stack macOS — so the probe returned "nothing responding" for every healthy instance and inverted every kill-safety gate into a rubber stamp. Also fixes non-atomic port-file writes, deletion of files on a transient read error, and an orphan path that killed without probing. Affected all MCP clients equally (server-side, unrelated to the Desktop Bridge plugin). **Fully restart your MCP clients after upgrading** — a server still running an older build keeps the broken probe and will terminate healthy siblings. Server-only — **no plugin re-import needed**. [See what's new →](CHANGELOG.md#1382---2026-07-29)
 
 ## What is this?
 
@@ -19,7 +19,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 - **📸 Visual debugging** - Take screenshots for context
 - **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma — including one-call component-set creation from a variant axes matrix
 - **🔧 Variable management** - Create, update, rename, and delete design tokens
-- **🕰 Version history & time-series awareness** - List versions, diff snapshots, generate markdown changelogs, trace property/variant introduction via binary-search blame
+- **🕰 Version history & time-series awareness** - List versions, diff snapshots, generate markdown changelogs, trace property/variant introduction via binary-search blame, and fold per-component design + git history into generated component docs
 - **⚡ Real-time monitoring** - Watch console logs from the Desktop Bridge plugin
 - **📌 FigJam boards** - Create stickies, flowcharts, tables, and code blocks on collaborative boards
 - **🎞️ Slides presentations** - Build and manage Figma Slides decks programmatically
@@ -823,9 +823,12 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.37.1 (Stable) - Production-ready. Latest: Design-system health audit for every client — `figma_audit_design_system_report` runs the dashboard's deterministic six-category scoring engine and returns the report as data with per-finding remediation, live-first fileKey-verified data (source disclosed), chunked per-category drill-down, and a 5-minute cache (server-only, no plugin re-import). On top of v1.36.0's target lock for multi-file parallel work — — `figma_navigate` takes a `lock: true` flag that pins the active file so an AI agent can work in one file while you work in another without commands routing to the wrong file. On top of v1.35.0's Figma Slots write support — create, inspect, populate, and reset Slots (GA at Config 2026) via 5 new tools (`figma_create_slot`, `figma_get_slots`, `figma_append_to_slot`, `figma_reset_slot`, `figma_add_slot_property`), live-validated against the GA Plugin API and based on community PR #77. On top of v1.34.0's Bidirectional Token Sync v2 + DTCG 2025.10 — `figma_import_tokens` applies the complete diff plan (creates missing collections/variables, applies renames, writes real `VARIABLE_ALIAS` references, and deletes only under explicit `replace`), `figma_export_tokens` speaks the DTCG 2025.10 dialect on request (legacy default byte-identical), variable scopes/codeSyntax round-trip via `$extensions`, `figma_setup_design_tokens` accepts alias values via DTCG brace references, and `figma_create_component_set` builds a full variant set from an axes matrix in one call. On top of the v1.33.x line: version-handshake fix (re-import banner only fires when plugin files actually changed), security dependency sweep, and the v1.33.0 connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect) + a 33-fix full-codebase audit (lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes, bridge-first screenshots). Built on WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **113 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.38.2 (Stable) - Production-ready. Latest: a connection-stability fix — the server's own orphan reaper was terminating healthy MCP servers because its liveness probe used an IPv4 literal while the server binds the IPv6 loopback, which turned every kill-safety gate into a rubber stamp; this was the cause of recurring "Server disconnected" errors across all MCP clients. Alongside v1.38.1's fix for the shared-library variable tools, which had silently reported zero collections since v1.29.0 and reported failed imports as successes. On top of v1.38.0's ongoing component changelogs in generated docs — `figma_generate_component_doc` takes an opt-in `history` parameter that pulls per-component **design history** from Figma version history (each version diffed and scoped to that component, so renames, added properties, and token bindings show up as rows) alongside **code history** from `git log` on the component's source files, rendered as a `## History` section with design, code, and release-note tables. Prefers labeled versions, falls back to auto-saves when a file has none, and is off by default so existing calls are unchanged (server-only, no plugin re-import). On top of v1.37.x's design-system health audit for every client — `figma_audit_design_system_report` runs the dashboard's deterministic six-category scoring engine and returns the report as data with per-finding remediation, live-first fileKey-verified data (source disclosed), chunked per-category drill-down, and a 5-minute cache (server-only, no plugin re-import). On top of v1.36.0's target lock for multi-file parallel work — — `figma_navigate` takes a `lock: true` flag that pins the active file so an AI agent can work in one file while you work in another without commands routing to the wrong file. On top of v1.35.0's Figma Slots write support — create, inspect, populate, and reset Slots (GA at Config 2026) via 5 new tools (`figma_create_slot`, `figma_get_slots`, `figma_append_to_slot`, `figma_reset_slot`, `figma_add_slot_property`), live-validated against the GA Plugin API and based on community PR #77. On top of v1.34.0's Bidirectional Token Sync v2 + DTCG 2025.10 — `figma_import_tokens` applies the complete diff plan (creates missing collections/variables, applies renames, writes real `VARIABLE_ALIAS` references, and deletes only under explicit `replace`), `figma_export_tokens` speaks the DTCG 2025.10 dialect on request (legacy default byte-identical), variable scopes/codeSyntax round-trip via `$extensions`, `figma_setup_design_tokens` accepts alias values via DTCG brace references, and `figma_create_component_set` builds a full variant set from an axes matrix in one call. On top of the v1.33.x line: version-handshake fix (re-import banner only fires when plugin files actually changed), security dependency sweep, and the v1.33.0 connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect) + a 33-fix full-codebase audit (lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes, bridge-first screenshots). Built on WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **113 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.38.2** - Connection stability: the orphan reaper was terminating healthy MCP servers, the cause of recurring "Server disconnected" errors across every MCP client (reproduced in both Claude Code and Claude Desktop; unrelated to the Desktop Bridge plugin). The reaper probes a sibling's `/health` before deciding it is dead, but requested `127.0.0.1` while the WebSocket server binds `localhost` — resolved to the IPv6 loopback on dual-stack macOS, with nothing on IPv4 — so the probe reported "nothing responding" for healthy servers and every kill-safety gate built on it became a rubber stamp, including the one written to spare siblings after the machine sleeps. Three supporting defects: port files written non-atomically (a reader landing mid-rewrite got a parse error that both cleanup paths treated as "corrupt, delete it", stranding a healthy server), an orphan path that terminated fileless port-holders without probing at all, and a heartbeat that gave up permanently once its own file went missing. Fixes: probe `localhost`, atomic temp+rename writes, never delete on a parse failure, health-probe before the orphan kill in both paths, and self-healing re-advertisement guarded by in-process port ownership. **Fully restart MCP clients after upgrading** — older running builds keep the broken probe and still terminate healthy siblings. Server-only, no plugin re-import. 1422 tests (7 new regressions, each verified to fail pre-fix).
+- [x] **v1.38.1** - Shared-library variable tools fixed. `figma_get_library_variables` returned `totalCollections: 0` for every file, on every plan, since it shipped in v1.29.0, and `figma_import_library_variable` reported failed imports as successes with `id: undefined`. Both read the Desktop Bridge's `{ success, result }` envelope as if it were the injected script's bare return value, so `Array.isArray()` was always false, the `__error` guard was dead code, and `.id` was always undefined. The failure presented as a *success* with a plausible hint attached ("subscribe a library via the Assets panel"), which is why it survived two months unreported. Both tools now unwrap through a shared helper that also maps a bridge-level `success: false` onto the error path, so a plugin timeout surfaces as a real error instead of being swallowed as "0 collections"; an import yielding no `id` is now an explicit error. All 26 `executeCodeViaUI` call sites audited — only these two were affected. Test mocks had encoded a wire contract that does not exist, which is why CI stayed green; they now reproduce the real envelope, plus six regression tests verified to fail against the pre-fix source. Reported by Isabella Minzly. Server-only — no plugin re-import needed.
+- [x] **v1.38.0** - Ongoing component changelogs in generated docs. `figma_generate_component_doc` gained an opt-in `history` parameter that produces a real changelog instead of only echoing hand-written `codeInfo.changelog` rows: `history.figma` walks Figma version history and diffs each consecutive pair scoped to the component (reusing the same engine as `figma_diff_versions`, so a rename, a newly added component property, or a token binding each become a row), while `history.git` runs `git log` over the component's source files auto-derived from `codeInfo.filePath` / `sourceFiles[]`. Labeled versions are preferred but auto-saves are used automatically when a file has none — verified against a mature system with 72 auto-saves and 0 labeled versions, where a labeled-only walk yields nothing. Detailed-mode bindings group by property (binding one token across a 24-variant set otherwise produced 44 near-identical bullets in a single table cell). Both sources default off, so existing callers get byte-identical output. No new tools; server-only, no plugin re-import.
 - [x] **v1.37.0** - Design-system health audit for every MCP client. New `figma_audit_design_system_report` runs the Design System Dashboard's deterministic scoring engine (naming, token architecture, component metadata, accessibility, consistency, coverage) and returns the scored report as data — no MCP Apps support or `ENABLE_MCP_APPS` needed (the previous registration gated everything, making the audit unreachable outside Claude Desktop). Component data is now live-first: a fileKey-verified per-page bridge crawl (30s/page, failures isolated per page) with REST published-library fallback, and the chosen source is disclosed in the report (`bridge-live` / `rest-published` / `none`) so stale-publish scores can't masquerade as live ones. Output is token-safe by design: bounded summary, per-category chunked drill-down, clamped full JSON, 5-minute raw-data cache. Every finding carries a remediation verdict — auto-fixable by this MCP's write tools, fixable after a design decision, or manual — with the exact tools named. Scoring accuracy pass: variant components no longer poison PascalCase/casing checks, Title Case accepted, component-set names count toward core-component coverage, `color/content/*` recognized in contrast pairing, state synonyms (`active`≈`pressed` etc.), and `.`/`_`-prefixed internals excluded. Server-only — no plugin re-import needed.
 - [x] **v1.36.0** - Target lock for multi-file parallel work. `figma_navigate` gains a `lock: true` flag that pins the active file — new connections, reconnects, and the user's own selection/page changes in other files no longer move the command target, so an agent can safely write to one file while the user works in another. Auto-releases when the pinned file disconnects or navigates away; `figma_list_open_files` reports a `targetLocked` flag for pre-write guards. Server-only — no plugin re-import needed.
 - [x] **v1.35.0** - Figma Slots write support, closing [#29](https://github.com/southleft/figma-console-mcp/issues/29) (the tracker's most-requested feature) via community PR [#77](https://github.com/southleft/figma-console-mcp/pull/77) by @simonesalvucci, updated to the GA API. Five new tools: `figma_create_slot` (slot + auto-linked SLOT property; variants inside component sets supported — the beta restriction was lifted at GA), `figma_get_slots`, `figma_append_to_slot` (clone or create content into instance slots; snaps clones to the slot origin), `figma_reset_slot`, and `figma_add_slot_property` (retrofit an existing frame as a slot). Hardened by live validation: VARIANT `defaultValue` passthrough restored (Figma requires non-empty), destructive-path reorder in the append handler (content validated before `clearExisting` empties anything), relay whitelist fix for `slot` payloads. **Plugin re-import required** (`code.js` + `ui.html` changed).

package/dist/cloudflare/apps/design-system-dashboard/scoring/accessibility.js

@@ -65,28 +65,59 @@ function isDirectColor(value) {
         v.type !== "VARIABLE_ALIAS");
 }
 /**
- * Extract resolved color values from variables.
- * Returns an array of { name, r, g, b } objects for direct color values.
+ * Extract resolved color values from variables, following alias chains.
+ * Semantic tokens are usually ALIASES of primitives — skipping them (the old
+ * behavior) dropped exactly the tokens whose names drive fg/bg pairing, so
+ * alias-heavy systems fell back to noisy scale-vs-scale pairing.
+ * Returns an array of { name, r, g, b } objects.
  */
 function extractColorValues(variables) {
-    const colors = [];
+    const byId = new Map();
     for (const variable of variables) {
-        if (variable.resolvedType !== "COLOR" || !variable.valuesByMode)
-            continue;
+        if (variable.id)
+            byId.set(variable.id, variable);
+    }
+    const resolve = (variable, depth = 0) => {
+        if (!variable?.valuesByMode || depth > 8)
+            return null;
         for (const value of Object.values(variable.valuesByMode)) {
-            if (isDirectColor(value)) {
-                colors.push({
-                    name: variable.name,
-                    r: value.r,
-                    g: value.g,
-                    b: value.b,
-                });
-                break; // Use the first direct color value per variable
+            if (isDirectColor(value))
+                return value;
+            const v = value;
+            if (v?.type === "VARIABLE_ALIAS" && typeof v.id === "string") {
+                const target = byId.get(v.id);
+                const resolved = target ? resolve(target, depth + 1) : null;
+                if (resolved)
+                    return resolved;
             }
         }
+        return null;
+    };
+    const colors = [];
+    for (const variable of variables) {
+        if (variable.resolvedType !== "COLOR")
+            continue;
+        const value = resolve(variable);
+        // Skip translucent colors: they composite over whatever is beneath
+        // them, so a standalone contrast ratio is meaningless (a 5%-alpha
+        // "background/subtle" wash is not a 1.0:1 background).
+        if (value && (value.a === undefined || value.a >= 0.99)) {
+            colors.push({ name: variable.name, r: value.r, g: value.g, b: value.b });
+        }
     }
     return colors;
 }
+/**
+ * Component-scoped tokens (comp/button/..., component/card/...) only ever
+ * co-occur with tokens of the SAME component scope — pairing a button label
+ * against a card background measures a combination that never renders.
+ * Returns the scope prefix for component-scoped names, or null for global
+ * semantic tokens (which may pair freely).
+ */
+function componentScope(name) {
+    const m = name.match(/^(comp|component|components)\/([^/]+)/i);
+    return m ? `${m[1].toLowerCase()}/${m[2].toLowerCase()}` : null;
+}
 /**
  * Identify likely foreground/background color pairs and check contrast.
  *
@@ -115,13 +146,107 @@ function scoreColorContrast(data) {
     // "annotation-gray" don't false-match.
     const fgPattern = /text|foreground|fg|content|(?:^|\/)on-|on\.|label|title|body|heading/i;
     const backgrounds = colors.filter((c) => bgPattern.test(c.name));
-    const foregrounds = colors.filter((c) => fgPattern.test(c.name));
+    // A token whose name also matches the background pattern is a surface, not
+    // a foreground — "body/background" must not be treated as body text.
+    const foregrounds = colors.filter((c) => fgPattern.test(c.name) && !bgPattern.test(c.name));
     // If naming conventions are not used, use luminance-based heuristic
     let pairs = [];
     if (backgrounds.length > 0 && foregrounds.length > 0) {
-        // Pair foregrounds with backgrounds by naming proximity
+        // Pair foregrounds with backgrounds where the token names DECLARE the
+        // relationship, instead of a full cross-product (which measures
+        // combinations that never render — a primary button label on a
+        // knockout background, default text on an inverted surface):
+        //   1. inverse-content tokens pair with inverted backgrounds only;
+        //   2. utility-family content (danger/warning/…) pairs with the same
+        //      utility family's backgrounds;
+        //   3. other GLOBAL content tokens pair with the default background
+        //      (the canvas every non-inverse text token must survive on);
+        //   4. component-scoped tokens pair by path mirror within the same
+        //      component and variant family (content ↔ background).
+        // Interaction/emphasis modifiers (-hover, -active, -strong, …) are
+        // stripped when matching so state variants inherit their base pair.
+        const stripModifiers = (leaf) => leaf.replace(/-(hover|active|pressed|focus|strong|subtle|weak)$/i, "");
+        const leafOf = (name) => stripModifiers(name.split("/").pop()?.toLowerCase() ?? "");
+        const utilityFamily = (name) => name.match(/utility\/([a-z]+)/i)?.[1]?.toLowerCase() ?? null;
+        // Family of a background token: first path segment after "background"
+        // when one exists ("background/danger/weak" → danger), else null
+        // (canvas-level backgrounds like "background/default").
+        const bgFamilyOf = (name) => {
+            const segs = name.toLowerCase().split("/");
+            const i = segs.findIndex((s) => /^(background|bg|surface)$/.test(s));
+            if (i < 0)
+                return null;
+            const rest = segs.slice(i + 1).filter((s) => s !== "utility");
+            return rest.length >= 2 ? rest[0] : null;
+        };
+        // Is a background the canvas (the default app surface)?
+        const bgIsCanvas = (name) => {
+            const segs = name.toLowerCase().split("/");
+            const i = segs.findIndex((s) => /^(background|bg|surface)$/.test(s));
+            if (i < 0)
+                return false;
+            const rest = segs.slice(i + 1);
+            return rest.length === 1 && stripModifiers(rest[0]) === "default";
+        };
+        // On-surface declaration for a content token: either an explicit
+        // "/on/<family>" path segment (content/on/primary) or an "on-<family>"
+        // / "<family>-strong" leaf — both dialects declare "this text sits ON
+        // that family's surface". Returns the target family, or null.
+        const onSurfaceFamilyOf = (name) => {
+            const lower = name.toLowerCase();
+            const pathMatch = lower.match(/\/on\/([a-z][a-z0-9-]*)/);
+            if (pathMatch)
+                return stripModifiers(pathMatch[1]);
+            const leaf = lower.split("/").pop() ?? "";
+            const onLeaf = leaf.match(/^on-([a-z0-9-]+)$/);
+            if (onLeaf)
+                return stripModifiers(onLeaf[1]);
+            const strongLeaf = leaf.match(/^([a-z0-9]+)-strong$/);
+            if (strongLeaf)
+                return strongLeaf[1];
+            return null;
+        };
         for (const fg of foregrounds) {
+            const fgScope = componentScope(fg.name);
+            const fgOnFamily = onSurfaceFamilyOf(fg.name);
+            const fgIsInverse = fgOnFamily === "inverse" || /inverse/i.test(leafOf(fg.name));
             for (const bg of backgrounds) {
+                const bgScope = componentScope(bg.name);
+                if (fgScope !== bgScope)
+                    continue;
+                const bgIsInverted = /invert|inverse/i.test(leafOf(bg.name)) ||
+                    bgFamilyOf(bg.name) === "inverse";
+                if (fgScope !== null) {
+                    // Component scope: mirror the path with content→background
+                    // swapped and modifiers stripped.
+                    const mirror = fg.name
+                        .toLowerCase()
+                        .replace(/(^|\/)(content|text|foreground|fg)(\/|$)/, "$1background$3");
+                    const bgNorm = bg.name.toLowerCase();
+                    const strip = (s) => s
+                        .split("/")
+                        .map((seg, i, arr) => (i === arr.length - 1 ? stripModifiers(seg) : seg))
+                        .join("/");
+                    if (strip(bgNorm) !== strip(mirror))
+                        continue;
+                }
+                else if (fgIsInverse || bgIsInverted) {
+                    // inverse content ↔ inverted/inverse surfaces only
+                    if (!(fgIsInverse && bgIsInverted))
+                        continue;
+                }
+                else if (fgOnFamily) {
+                    // declared on-surface text → its family's surface only
+                    if (bgFamilyOf(bg.name) !== fgOnFamily)
+                        continue;
+                }
+                else {
+                    // everything else (plain content, family-COLORED canvas text
+                    // like content/brand or content/danger/default) must survive
+                    // on the canvas — and only the canvas is a declared pair.
+                    if (!bgIsCanvas(bg.name))
+                        continue;
+                }
                 pairs.push({ fg, bg });
             }
         }

package/dist/cloudflare/apps/design-system-dashboard/scoring/consistency.js

@@ -134,7 +134,9 @@ function scoreCasingConsistency(data) {
         const segments = comp.name.split("/").map((s) => s.trim());
         componentSegments.push(...segments);
     }
-    // Check variable name leaf segments
+    // Check variable name segments. Pure-numeric segments (scale steps like
+    // "100", "3.5", "12") carry no casing signal and are skipped.
+    const NUMERIC_SEGMENT_RE = /^\d+([.·․․]?\d+)?$/;
     const variableLeaves = [];
     for (const v of data.variables) {
         const segments = v.name.split(/[/.]/);
@@ -142,46 +144,90 @@ function scoreCasingConsistency(data) {
             variableLeaves.push(...segments);
         }
     }
-    const allSegments = [...componentSegments, ...variableLeaves].filter((s) => s.length > 1);
-    if (allSegments.length === 0) {
+    // Calibration: components and variables legitimately follow DIFFERENT
+    // conventions (TitleCase components + lowercase/kebab token paths is the
+    // dominant real-world pattern). Pooling them and demanding one dominant
+    // casing structurally fails every such system, so consistency is measured
+    // WITHIN each pool and combined as a segment-weighted average.
+    const pools = [
+        {
+            label: "component",
+            segments: componentSegments.filter((s) => s.length > 1 && !NUMERIC_SEGMENT_RE.test(s)),
+        },
+        {
+            label: "variable",
+            segments: variableLeaves.filter((s) => s.length > 1 && !NUMERIC_SEGMENT_RE.test(s)),
+        },
+    ].filter((p) => p.segments.length > 0);
+    if (pools.length === 0) {
         return {
             id: "consistency-casing",
             label: "Casing consistency",
             score: 100,
             severity: "info",
-            tooltip: "Name segments should use a consistent casing convention (PascalCase, camelCase, etc.) across all components and variables.",
+            tooltip: "Name segments should follow a consistent casing convention within components and within variables (the two may differ — e.g. TitleCase components with kebab-case token paths).",
             details: "No name segments to evaluate.",
         };
     }
-    // Count casing patterns
-    const casingCounts = new Map();
-    for (const segment of allSegments) {
-        const casing = detectCasing(segment);
-        casingCounts.set(casing, (casingCounts.get(casing) ?? 0) + 1);
-    }
-    // Find dominant casing
-    let dominantCasing = "mixed";
-    let dominantCount = 0;
-    for (const [casing, count] of casingCounts.entries()) {
-        if (count > dominantCount) {
-            dominantCount = count;
-            dominantCasing = casing;
+    // A segment can be AMBIGUOUS between conventions: a single lowercase word
+    // ("default", "brand") is simultaneously valid camelCase, kebab-case, and
+    // snake_case — only multi-word segments reveal the convention. Score each
+    // segment against the set of conventions it is compatible with, and pick
+    // the convention that the most segments are compatible with.
+    const compatibleCasings = (segment) => {
+        const out = [];
+        if (PASCAL_CASE_RE.test(segment))
+            out.push("PascalCase");
+        if (CAMEL_CASE_RE.test(segment))
+            out.push("camelCase");
+        if (KEBAB_CASE_RE.test(segment))
+            out.push("kebab-case");
+        if (SNAKE_CASE_RE.test(segment))
+            out.push("snake_case");
+        if (out.length === 0)
+            out.push(detectCasing(segment));
+        return out;
+    };
+    let weightedConsistent = 0;
+    let totalSegments = 0;
+    const poolSummaries = [];
+    const nonDominantSegments = [];
+    for (const pool of pools) {
+        const casingCounts = new Map();
+        const compat = pool.segments.map((s) => compatibleCasings(s));
+        for (const casings of compat) {
+            for (const casing of casings) {
+                casingCounts.set(casing, (casingCounts.get(casing) ?? 0) + 1);
+            }
+        }
+        let dominantCasing = "mixed";
+        let dominantCount = 0;
+        for (const [casing, count] of casingCounts.entries()) {
+            if (count > dominantCount) {
+                dominantCount = count;
+                dominantCasing = casing;
+            }
+        }
+        weightedConsistent += dominantCount;
+        totalSegments += pool.segments.length;
+        poolSummaries.push(`${pool.label} names ${Math.round((dominantCount / pool.segments.length) * 100)}% ${dominantCasing}`);
+        for (let i = 0; i < pool.segments.length; i++) {
+            if (!compat[i].includes(dominantCasing) &&
+                nonDominantSegments.length < MAX_EXAMPLES) {
+                nonDominantSegments.push(`${pool.segments[i]} (${pool.label})`);
+            }
         }
     }
-    const ratio = dominantCount / allSegments.length;
+    const ratio = weightedConsistent / totalSegments;
     const score = clamp(ratio * 100);
-    // Find segments using non-dominant casing
-    const nonDominantSegments = allSegments.filter((seg) => detectCasing(seg) !== dominantCasing);
     return {
         id: "consistency-casing",
         label: "Casing consistency",
         score,
         severity: getSeverity(score),
-        tooltip: "Name segments should use a consistent casing convention (PascalCase, camelCase, etc.) across all components and variables.",
-        details: `${Math.round(ratio * 100)}% of name segments use ${dominantCasing}. Consistent casing improves readability.`,
-        examples: nonDominantSegments.length > 0
-            ? nonDominantSegments.slice(0, MAX_EXAMPLES)
-            : undefined,
+        tooltip: "Name segments should follow a consistent casing convention within components and within variables (the two may differ — e.g. TitleCase components with kebab-case token paths).",
+        details: `${Math.round(ratio * 100)}% of name segments follow their pool's dominant casing (${poolSummaries.join("; ")}).`,
+        examples: nonDominantSegments.length > 0 ? nonDominantSegments : undefined,
     };
 }
 /**
@@ -299,29 +345,43 @@ function scoreModeNamingConsistency(data) {
             details: "Only one collection has modes; consistency is not applicable.",
         };
     }
-    // Compare mode name sets - check how many match the most common pattern
-    const serialized = modeNameSets.map((s) => s.join(","));
-    const patternCounts = new Map();
-    for (const s of serialized) {
-        patternCounts.set(s, (patternCounts.get(s) ?? 0) + 1);
-    }
-    let dominantCount = 0;
-    for (const count of patternCounts.values()) {
-        if (count > dominantCount) {
-            dominantCount = count;
+    // Calibration: collections legitimately serve DIFFERENT mode axes — a
+    // theme collection's Light/Dark, a density collection's Compact/
+    // Comfortable, a shape collection's Pill/Sharp. Demanding identical mode
+    // SETS across them penalizes correct architecture. What actually causes
+    // confusion is the same mode CONCEPT spelled differently across
+    // collections ("light" vs "Light" vs "light-mode"), so measure spelling
+    // consistency per mode concept instead.
+    const spellingsByConcept = new Map();
+    for (const collection of collections) {
+        for (const mode of collection.modes || []) {
+            const concept = mode.name.toLowerCase().replace(/[\s_-]+/g, "");
+            if (!spellingsByConcept.has(concept)) {
+                spellingsByConcept.set(concept, new Set());
+            }
+            spellingsByConcept.get(concept)?.add(mode.name);
         }
     }
-    const ratio = dominantCount / modeNameSets.length;
+    const concepts = [...spellingsByConcept.entries()];
+    const inconsistent = concepts.filter(([, spellings]) => spellings.size > 1);
+    const ratio = concepts.length === 0
+        ? 1
+        : (concepts.length - inconsistent.length) / concepts.length;
     const score = clamp(ratio * 100);
     return {
         id: "consistency-mode-naming",
         label: "Mode naming consistency",
         score,
         severity: getSeverity(score),
-        tooltip: "All collections with multiple modes should use the same mode names (e.g. Light/Dark). Inconsistent mode names cause confusion.",
-        details: ratio < 1
-            ? `${Math.round(ratio * 100)}% of collections share the same mode names. Align mode names across collections.`
-            : "All collections use consistent mode names.",
+        tooltip: "The same mode concept should be spelled identically across collections (e.g. always \"Light\", never a mix of \"Light\" and \"light\"). Collections may have different mode sets — that's architecture, not inconsistency.",
+        details: inconsistent.length > 0
+            ? `${inconsistent.length} mode name${inconsistent.length === 1 ? "" : "s"} spelled inconsistently across collections.`
+            : "Mode names are spelled consistently across collections.",
+        examples: inconsistent.length > 0
+            ? inconsistent
+                .slice(0, MAX_EXAMPLES)
+                .map(([, spellings]) => [...spellings].join(" vs "))
+            : undefined,
     };
 }
 /**

package/dist/cloudflare/apps/design-system-dashboard/scoring/naming-semantics.js

@@ -98,7 +98,32 @@ function containsVisualColorWord(name) {
  * visual names (color.blue.500).
  */
 function scoreVariableNaming(data) {
-    const colorVars = data.variables.filter((v) => v.resolvedType === "COLOR");
+    // Only judge tokens OUTSIDE the primitive tier: primitives are SUPPOSED to
+    // describe appearance (color/blue/500, color/neutral/black — they're the
+    // palette), and the tooltip's own contract ("semantic names survive theme
+    // changes") only applies to the tokens a theme swap re-points. The
+    // primitive tier is detected the same way the alias-usage check detects
+    // it: the collection contributing the most raw (non-alias) values.
+    const rawByCollection = new Map();
+    for (const v of data.variables) {
+        for (const value of Object.values(v.valuesByMode ?? {})) {
+            const val = value;
+            if (val?.type !== "VARIABLE_ALIAS") {
+                const key = v.variableCollectionId ?? "?";
+                rawByCollection.set(key, (rawByCollection.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    let primitiveCollectionId = null;
+    let maxRaw = -1;
+    for (const [key, count] of rawByCollection) {
+        if (count > maxRaw) {
+            maxRaw = count;
+            primitiveCollectionId = key;
+        }
+    }
+    const colorVars = data.variables.filter((v) => v.resolvedType === "COLOR" &&
+        (v.variableCollectionId ?? "?") !== primitiveCollectionId);
     if (colorVars.length === 0) {
         return {
             id: "naming-variable-semantic",

package/dist/cloudflare/apps/design-system-dashboard/scoring/token-architecture.js

@@ -154,7 +154,70 @@ function scoreAliasUsage(data) {
         };
     }
     const ratio = aliasCount / totalValues;
-    const score = clamp(ratio * 100);
+    // Calibration: primitives hold raw values BY DEFINITION — they are the
+    // alias TARGETS — so a raw all-values ratio punishes systems for having a
+    // primitive tier at all. What layering actually demands is that values
+    // OUTSIDE the primitive tier alias into it instead of duplicating raw
+    // values. Treat the collection contributing the most raw values as the
+    // primitive tier and measure alias density over the remaining values.
+    const rawByCollection = new Map();
+    for (const variable of data.variables) {
+        if (!variable.valuesByMode)
+            continue;
+        for (const value of Object.values(variable.valuesByMode)) {
+            if (!isAlias(value)) {
+                const key = variable.variableCollectionId ?? "?";
+                rawByCollection.set(key, (rawByCollection.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    // The primitive tier = the collection contributing the most raw values.
+    // Additionally, any collection containing ZERO aliases is an alias SOURCE
+    // (a self-contained primitive set, e.g. a motion-timing collection) — it
+    // cannot be expected to alias into anything, so its raw values are also
+    // excluded from the layering denominator.
+    const aliasByCollection = new Map();
+    for (const variable of data.variables) {
+        if (!variable.valuesByMode)
+            continue;
+        for (const value of Object.values(variable.valuesByMode)) {
+            if (isAlias(value)) {
+                const key = variable.variableCollectionId ?? "?";
+                aliasByCollection.set(key, (aliasByCollection.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    let primitiveKey = null;
+    let primitiveRaw = 0;
+    for (const [key, count] of rawByCollection) {
+        if (count > primitiveRaw) {
+            primitiveRaw = count;
+            primitiveKey = key;
+        }
+    }
+    // A system can have MULTIPLE primitive roots (e.g. a Brand tier plus a
+    // Primitive tier that aliases brand colors but roots its own neutrals) —
+    // recognize primitive tiers by the strongest signals available: zero
+    // aliases (pure source), the largest raw contributor, or a tier-naming
+    // convention (primitive/core/base/palette/brand/foundation).
+    const tierNames = new Map();
+    for (const col of data.collections) {
+        if (col.id)
+            tierNames.set(col.id, col.name ?? "");
+    }
+    const PRIMITIVE_NAME_RE = /primitive|core|base|palette|brand|foundation/i;
+    let excludedRaw = 0;
+    for (const [key, count] of rawByCollection) {
+        const isZeroAlias = !(aliasByCollection.get(key) ?? 0);
+        const isMaxRaw = key === primitiveKey;
+        const isPrimitiveNamed = PRIMITIVE_NAME_RE.test(tierNames.get(key) ?? "");
+        if (isZeroAlias || isMaxRaw || isPrimitiveNamed) {
+            excludedRaw += count;
+        }
+    }
+    const nonPrimitiveValues = Math.max(1, totalValues - excludedRaw);
+    const layeredRatio = aliasCount / nonPrimitiveValues;
+    const score = clamp(layeredRatio * 100);
     return {
         id: "token-alias-usage",
         label: "Alias usage",