@mp3wizard/figma-console-mcp 1.14.0

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

@@ -0,0 +1,357 @@
+/**
+ * Component Metadata Scorer (weight: 0.20)
+ *
+ * Checks component quality and completeness within the design system.
+ * Evaluates description presence, description quality, property completeness,
+ * variant structure, and category organization.
+ *
+ * Scores against "scorable units" (component sets + standalone components)
+ * rather than raw variant count to avoid inflated totals.
+ */
+import { clamp, getSeverity } from "./types.js";
+/** Maximum examples to include in a finding. */
+const MAX_EXAMPLES = 5;
+/** Minimum description length to be considered "quality" documentation. */
+const MIN_QUALITY_DESC_LENGTH = 20;
+/**
+ * Build a lookup structure for matching components to variant groups.
+ * Collects component set node IDs for `containing_frame.containingComponentSet`
+ * matching (primary REST API path) and name prefixes as fallback.
+ */
+function buildComponentSetLookup(data) {
+    const nodeIds = new Set();
+    const namePrefixes = new Set();
+    for (const cs of data.componentSets) {
+        if (cs.node_id)
+            nodeIds.add(cs.node_id);
+        if (cs.name)
+            namePrefixes.add(cs.name + "/");
+    }
+    return { nodeIds, namePrefixes };
+}
+/**
+ * Check if a component belongs to a variant set.
+ *
+ * Detection order:
+ * 1. Plugin API: `componentSetId` (set on ComponentNode by Figma plugin runtime)
+ * 2. REST API: `containing_frame.containingComponentSet` (present on variants
+ *    returned by GET /v1/files/:key/components)
+ * 3. File JSON: `component_set_id` (snake_case field on COMPONENT nodes in file tree)
+ * 4. Name prefix: variant names starting with "SetName/" (some API formats)
+ * 5. Frame node ID: containing_frame.nodeId matching a known component set node
+ */
+function isComponentInSet(component, lookup) {
+    // Plugin API: direct componentSetId
+    if (component.componentSetId)
+        return true;
+    // REST API: containing_frame.containingComponentSet is set on variant components
+    if (component.containing_frame?.containingComponentSet)
+        return true;
+    // File JSON: snake_case variant of componentSetId
+    if (component.component_set_id)
+        return true;
+    // Name-based fallback: variant names may start with "SetName/"
+    if (component.name) {
+        for (const prefix of lookup.namePrefixes) {
+            if (component.name.startsWith(prefix))
+                return true;
+        }
+    }
+    // Frame node ID fallback
+    const frameNodeId = component.containing_frame?.nodeId;
+    if (frameNodeId && lookup.nodeIds.has(frameNodeId))
+        return true;
+    return false;
+}
+/**
+ * Classify components into standalone, variants, and component sets.
+ * Scoring evaluates `scorableUnits` (standalone + componentSets)
+ * instead of the raw component list which double-counts variants.
+ */
+export function classifyComponents(data) {
+    const lookup = buildComponentSetLookup(data);
+    const standalone = [];
+    const variants = [];
+    for (const comp of data.components) {
+        if (isComponentInSet(comp, lookup)) {
+            variants.push(comp);
+        }
+        else {
+            standalone.push(comp);
+        }
+    }
+    return {
+        standalone,
+        variants,
+        componentSets: data.componentSets,
+        scorableUnits: [...standalone, ...data.componentSets],
+    };
+}
+// ---------------------------------------------------------------------------
+// Scoring functions (operate on scorable units)
+// ---------------------------------------------------------------------------
+/**
+ * Score description presence across scorable units.
+ * Component sets and standalone components should have non-empty descriptions.
+ */
+function scoreDescriptionPresence(classification) {
+    const { scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-desc-presence",
+            label: "Description presence",
+            score: 100,
+            severity: "info",
+            tooltip: "Components and component sets should have descriptions. Descriptions appear in Figma's asset panel and help designers find the right component.",
+            details: "No components to evaluate.",
+        };
+    }
+    const withDesc = scorableUnits.filter((c) => c.description && c.description.trim().length > 0);
+    const withoutDesc = scorableUnits.filter((c) => !c.description || c.description.trim().length === 0);
+    const ratio = withDesc.length / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-desc-presence",
+        label: "Description presence",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Components and component sets should have descriptions. Descriptions appear in Figma's asset panel and help designers find the right component.",
+        details: `${withDesc.length} of ${scorableUnits.length} components have descriptions (${Math.round(ratio * 100)}%).`,
+        examples: withoutDesc.length > 0
+            ? withoutDesc.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: withoutDesc.length > 0
+            ? withoutDesc.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Score description quality.
+ * Descriptions should be meaningful (>20 chars), not just the component name.
+ */
+function scoreDescriptionQuality(classification) {
+    const { scorableUnits } = classification;
+    const withDesc = scorableUnits.filter((c) => c.description && c.description.trim().length > 0);
+    if (withDesc.length === 0) {
+        return {
+            id: "component-desc-quality",
+            label: "Description quality",
+            score: 0,
+            severity: scorableUnits.length === 0 ? "info" : "fail",
+            tooltip: "Descriptions should be meaningful (20+ characters) and explain usage, not just repeat the name. Good descriptions reduce misuse.",
+            details: scorableUnits.length === 0
+                ? "No components to evaluate."
+                : "No components have descriptions to evaluate quality.",
+        };
+    }
+    const shortDescs = withDesc.filter((c) => c.description.trim().length < MIN_QUALITY_DESC_LENGTH);
+    const qualityCount = withDesc.length - shortDescs.length;
+    const ratio = qualityCount / withDesc.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-desc-quality",
+        label: "Description quality",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Descriptions should be meaningful (20+ characters) and explain usage, not just repeat the name. Good descriptions reduce misuse.",
+        details: shortDescs.length > 0
+            ? `${shortDescs.length} of ${withDesc.length} descriptions are too short (<${MIN_QUALITY_DESC_LENGTH} chars). Provide usage guidance, not just names.`
+            : `All ${withDesc.length} descriptions provide meaningful documentation.`,
+        examples: shortDescs.length > 0
+            ? shortDescs.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+    };
+}
+/**
+ * Score property completeness.
+ * Standalone components should define properties for flexibility.
+ * Component sets inherently have properties via their variants.
+ */
+function scorePropertyCompleteness(classification) {
+    const { standalone, componentSets, scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-property-completeness",
+            label: "Property completeness",
+            score: 100,
+            severity: "info",
+            tooltip: "Components should expose properties or use variant sets. Properties make components flexible and reduce the need for detaching instances.",
+            details: "No components to evaluate.",
+        };
+    }
+    // Component sets always count as having properties (they are variant groups)
+    // For standalone, check if they have any property definitions
+    const standaloneWithProps = standalone.filter((c) => c.componentPropertyDefinitions &&
+        Object.keys(c.componentPropertyDefinitions).length > 0);
+    const standaloneWithoutProps = standalone.filter((c) => !c.componentPropertyDefinitions ||
+        Object.keys(c.componentPropertyDefinitions).length === 0);
+    const withProperties = standaloneWithProps.length + componentSets.length;
+    const ratio = withProperties / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-property-completeness",
+        label: "Property completeness",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Components should expose properties or use variant sets. Properties make components flexible and reduce the need for detaching instances.",
+        details: `${withProperties} of ${scorableUnits.length} components have defined properties or variants (${Math.round(ratio * 100)}%).`,
+        examples: standaloneWithoutProps.length > 0
+            ? standaloneWithoutProps.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: standaloneWithoutProps.length > 0
+            ? standaloneWithoutProps.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Score variant structure.
+ * A higher ratio of component sets to total scorable units indicates
+ * good use of variant organization.
+ */
+function scoreVariantStructure(classification) {
+    const { standalone, componentSets, scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-variant-structure",
+            label: "Variant structure",
+            score: 100,
+            severity: "info",
+            tooltip: "Related component variants should be organized into component sets. Sets make variant switching easy and reduce component sprawl.",
+            details: "No components to evaluate.",
+        };
+    }
+    const setCount = componentSets.length;
+    const ratio = setCount / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-variant-structure",
+        label: "Variant structure",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Related component variants should be organized into component sets. Sets make variant switching easy and reduce component sprawl.",
+        details: setCount > 0
+            ? `${setCount} of ${scorableUnits.length} components use variant sets (${Math.round(ratio * 100)}%). ${standalone.length} standalone component${standalone.length === 1 ? "" : "s"}.`
+            : "No components use variant structures. Consider organizing components into sets with variants.",
+        examples: standalone.length > 0 && setCount > 0
+            ? standalone.slice(0, MAX_EXAMPLES).map((c) => `${c.name} (standalone)`)
+            : undefined,
+    };
+}
+/**
+ * Score category organization.
+ * Components should use path separators (/) for logical grouping.
+ */
+function scoreCategoryOrganization(classification) {
+    const { scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-category-org",
+            label: "Category organization",
+            score: 100,
+            severity: "info",
+            tooltip: 'Component names should use path separators (/) for grouping (e.g. Forms/Input). Organized naming improves asset panel navigation.',
+            details: "No components to evaluate.",
+        };
+    }
+    const withPath = scorableUnits.filter((c) => c.name?.includes("/"));
+    const withoutPath = scorableUnits.filter((c) => !c.name?.includes("/"));
+    const ratio = withPath.length / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-category-org",
+        label: "Category organization",
+        score,
+        severity: getSeverity(score),
+        tooltip: 'Component names should use path separators (/) for grouping (e.g. Forms/Input). Organized naming improves asset panel navigation.',
+        details: withPath.length > 0
+            ? `${withPath.length} of ${scorableUnits.length} components use path-based grouping (${Math.round(ratio * 100)}%).`
+            : 'No components use path separators for grouping. Use "/" in names for organization (e.g., "Forms/Input").',
+        examples: withoutPath.length > 0
+            ? withoutPath.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: withoutPath.length > 0
+            ? withoutPath.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/** Matches Figma auto-generated layer names like "Frame 347", "Group 12", "Rectangle 5". */
+const GENERIC_NAME_RE = /^(Frame|Group|Rectangle|Ellipse|Line|Polygon|Vector|Text|Image|Slice|Component|Instance|Section|Boolean\s*Group)\s*\d*$/i;
+/**
+ * Score generic layer naming.
+ * Published components should have intentional names, not auto-generated ones.
+ */
+function scoreGenericNaming(classification) {
+    const { scorableUnits } = classification;
+    if (scorableUnits.length === 0) {
+        return {
+            id: "component-generic-naming",
+            label: "Layer naming",
+            score: 100,
+            severity: "info",
+            tooltip: "Published components should have intentional names. Auto-generated names like Frame 347 or Group 12 indicate layers that were never renamed.",
+            details: "No components to evaluate.",
+        };
+    }
+    const genericComps = scorableUnits.filter((c) => {
+        const segments = (c.name || "").split("/").map((s) => s.trim());
+        return segments.some((seg) => GENERIC_NAME_RE.test(seg));
+    });
+    const ratio = 1 - genericComps.length / scorableUnits.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "component-generic-naming",
+        label: "Layer naming",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Published components should have intentional names. Auto-generated names like Frame 347 or Group 12 indicate layers that were never renamed.",
+        details: genericComps.length > 0
+            ? `${genericComps.length} of ${scorableUnits.length} components have auto-generated layer names (e.g. Frame, Group, Rectangle).`
+            : "All components have intentional names.",
+        examples: genericComps.length > 0
+            ? genericComps.slice(0, MAX_EXAMPLES).map((c) => c.name)
+            : undefined,
+        locations: genericComps.length > 0
+            ? genericComps.slice(0, MAX_EXAMPLES).map((c) => ({
+                name: c.name,
+                nodeId: c.node_id,
+                type: "component",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Component Metadata category scorer.
+ * Returns the average score across all component metadata checks.
+ */
+export function scoreComponentMetadata(data) {
+    const classification = classifyComponents(data);
+    const findings = [
+        scoreDescriptionPresence(classification),
+        scoreDescriptionQuality(classification),
+        scorePropertyCompleteness(classification),
+        scoreVariantStructure(classification),
+        scoreCategoryOrganization(classification),
+        scoreGenericNaming(classification),
+    ];
+    const score = clamp(findings.reduce((sum, f) => sum + f.score, 0) / findings.length);
+    return {
+        id: "component-metadata",
+        label: "Component Metadata",
+        shortLabel: "Components",
+        score,
+        weight: 0.2,
+        findings,
+    };
+}

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

@@ -0,0 +1,341 @@
+/**
+ * Consistency Scorer (weight: 0.15)
+ *
+ * Checks pattern uniformity across the design system.
+ * Evaluates naming delimiter consistency, casing consistency,
+ * size value consistency, and mode naming consistency.
+ */
+import { buildCollectionNameMap, clamp, getSeverity } from "./types.js";
+/** Maximum examples to include in a finding. */
+const MAX_EXAMPLES = 5;
+const PASCAL_CASE_RE = /^[A-Z][a-zA-Z0-9]*$/;
+const CAMEL_CASE_RE = /^[a-z][a-zA-Z0-9]*$/;
+const KEBAB_CASE_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const SNAKE_CASE_RE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+/** Supported delimiters in variable names. */
+const DELIMITERS = ["/", ".", "-", "_"];
+/**
+ * Count delimiter occurrences across all variable names.
+ * Returns a map of delimiter to count of variables that use it.
+ */
+function countDelimiterUsage(names) {
+    const counts = new Map();
+    for (const delimiter of DELIMITERS) {
+        counts.set(delimiter, 0);
+    }
+    for (const name of names) {
+        for (const delimiter of DELIMITERS) {
+            if (name.includes(delimiter)) {
+                counts.set(delimiter, (counts.get(delimiter) ?? 0) + 1);
+            }
+        }
+    }
+    return counts;
+}
+/**
+ * Score naming delimiter consistency.
+ * Variable names should consistently use the same delimiter (/, ., or -).
+ */
+function scoreDelimiterConsistency(data) {
+    const names = data.variables.map((v) => v.name);
+    if (names.length === 0) {
+        return {
+            id: "consistency-delimiter",
+            label: "Naming delimiter consistency",
+            score: 100,
+            severity: "info",
+            tooltip: "Variable names should use the same delimiter throughout (/ or . or -). Mixed delimiters make tokens harder to find and autocomplete.",
+            details: "No variables to evaluate.",
+        };
+    }
+    const counts = countDelimiterUsage(names);
+    // Find variables that use any delimiter at all
+    const varsWithDelimiter = names.filter((name) => DELIMITERS.some((d) => name.includes(d)));
+    if (varsWithDelimiter.length === 0) {
+        return {
+            id: "consistency-delimiter",
+            label: "Naming delimiter consistency",
+            score: 100,
+            severity: "pass",
+            tooltip: "Variable names should use the same delimiter throughout (/ or . or -). Mixed delimiters make tokens harder to find and autocomplete.",
+            details: "No delimiters used in variable names (single-segment names).",
+        };
+    }
+    // Find the dominant delimiter
+    let dominantDelimiter = "/";
+    let dominantCount = 0;
+    for (const [delimiter, count] of counts.entries()) {
+        if (count > dominantCount) {
+            dominantCount = count;
+            dominantDelimiter = delimiter;
+        }
+    }
+    const ratio = dominantCount / varsWithDelimiter.length;
+    const score = clamp(ratio * 100);
+    const collectionNames = buildCollectionNameMap(data.collections);
+    // Find variables using non-dominant delimiters
+    const nonDominantVars = data.variables.filter((v) => {
+        const name = v.name;
+        const usesDelimiter = DELIMITERS.some((d) => name.includes(d));
+        if (!usesDelimiter)
+            return false;
+        return !name.includes(dominantDelimiter);
+    });
+    return {
+        id: "consistency-delimiter",
+        label: "Naming delimiter consistency",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Variable names should use the same delimiter throughout (/ or . or -). Mixed delimiters make tokens harder to find and autocomplete.",
+        details: `${Math.round(ratio * 100)}% of variables use "${dominantDelimiter}" as delimiter. Consistent delimiter usage improves navigability.`,
+        examples: nonDominantVars.length > 0
+            ? nonDominantVars.slice(0, MAX_EXAMPLES).map((v) => v.name)
+            : undefined,
+        locations: nonDominantVars.length > 0
+            ? nonDominantVars.slice(0, MAX_EXAMPLES).map((v) => ({
+                name: v.name,
+                collection: collectionNames.get(v.variableCollectionId),
+                type: "variable",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Detect the casing pattern of a name segment.
+ */
+function detectCasing(segment) {
+    if (PASCAL_CASE_RE.test(segment))
+        return "PascalCase";
+    if (CAMEL_CASE_RE.test(segment))
+        return "camelCase";
+    if (KEBAB_CASE_RE.test(segment))
+        return "kebab-case";
+    if (SNAKE_CASE_RE.test(segment))
+        return "snake_case";
+    if (segment === segment.toUpperCase() && segment.length > 1)
+        return "UPPERCASE";
+    if (segment === segment.toLowerCase())
+        return "lowercase";
+    return "mixed";
+}
+/**
+ * Score casing consistency across component and variable names.
+ */
+function scoreCasingConsistency(data) {
+    // Check component name casing
+    const componentSegments = [];
+    for (const comp of data.components) {
+        const segments = comp.name.split("/").map((s) => s.trim());
+        componentSegments.push(...segments);
+    }
+    // Check variable name leaf segments
+    const variableLeaves = [];
+    for (const v of data.variables) {
+        const segments = v.name.split(/[/.]/);
+        if (segments.length > 0) {
+            variableLeaves.push(...segments);
+        }
+    }
+    const allSegments = [...componentSegments, ...variableLeaves].filter((s) => s.length > 1);
+    if (allSegments.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.",
+            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;
+        }
+    }
+    const ratio = dominantCount / allSegments.length;
+    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,
+    };
+}
+/**
+ * Check if numeric values follow a consistent scale pattern.
+ * Common patterns: multiples of 4, multiples of 8, powers of 2.
+ */
+function detectScalePattern(values) {
+    if (values.length === 0)
+        return { pattern: "none", matchRatio: 0 };
+    const positiveValues = values.filter((v) => v > 0);
+    if (positiveValues.length === 0)
+        return { pattern: "none", matchRatio: 0 };
+    const scales = [
+        { name: "4px base", divisor: 4 },
+        { name: "8px base", divisor: 8 },
+        { name: "2px base", divisor: 2 },
+    ];
+    let bestPattern = "none";
+    let bestRatio = 0;
+    for (const scale of scales) {
+        const matching = positiveValues.filter((v) => v % scale.divisor === 0).length;
+        const ratio = matching / positiveValues.length;
+        if (ratio > bestRatio) {
+            bestRatio = ratio;
+            bestPattern = scale.name;
+        }
+    }
+    return { pattern: bestPattern, matchRatio: bestRatio };
+}
+/**
+ * Score size value consistency.
+ * Numeric (FLOAT) variables should follow a consistent scale.
+ */
+function scoreSizeValueConsistency(data) {
+    const floatVars = data.variables.filter((v) => v.resolvedType === "FLOAT");
+    if (floatVars.length === 0) {
+        return {
+            id: "consistency-size-values",
+            label: "Size value consistency",
+            score: 100,
+            severity: "info",
+            tooltip: "Numeric token values should follow a consistent scale (e.g. multiples of 4 or 8). Consistent scales create visual rhythm and predictable spacing.",
+            details: "No numeric variables to evaluate.",
+        };
+    }
+    // Extract numeric values (skip aliases)
+    const numericValues = [];
+    for (const v of floatVars) {
+        if (!v.valuesByMode)
+            continue;
+        for (const value of Object.values(v.valuesByMode)) {
+            if (typeof value === "number") {
+                numericValues.push(value);
+            }
+        }
+    }
+    if (numericValues.length === 0) {
+        return {
+            id: "consistency-size-values",
+            label: "Size value consistency",
+            score: 50,
+            severity: "warning",
+            tooltip: "Numeric token values should follow a consistent scale (e.g. multiples of 4 or 8). Consistent scales create visual rhythm and predictable spacing.",
+            details: "No direct numeric values found (all aliases).",
+        };
+    }
+    const { pattern, matchRatio } = detectScalePattern(numericValues);
+    const score = clamp(matchRatio * 100);
+    return {
+        id: "consistency-size-values",
+        label: "Size value consistency",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Numeric token values should follow a consistent scale (e.g. multiples of 4 or 8). Consistent scales create visual rhythm and predictable spacing.",
+        details: pattern !== "none"
+            ? `${Math.round(matchRatio * 100)}% of numeric values follow a ${pattern} scale.`
+            : "No consistent scale pattern detected in numeric values.",
+    };
+}
+/**
+ * Score mode naming consistency.
+ * All collections should use the same mode names.
+ */
+function scoreModeNamingConsistency(data) {
+    const collections = data.collections;
+    if (collections.length <= 1) {
+        return {
+            id: "consistency-mode-naming",
+            label: "Mode naming consistency",
+            score: 100,
+            severity: collections.length === 0 ? "info" : "pass",
+            tooltip: "All collections with multiple modes should use the same mode names (e.g. Light/Dark). Inconsistent mode names cause confusion.",
+            details: collections.length === 0
+                ? "No collections to evaluate."
+                : "Only one collection; mode naming consistency is not applicable.",
+        };
+    }
+    // Collect mode name sets per collection
+    const modeNameSets = [];
+    for (const collection of collections) {
+        if (collection.modes && collection.modes.length > 0) {
+            const modeNames = collection.modes
+                .map((m) => m.name.toLowerCase())
+                .sort();
+            modeNameSets.push(modeNames);
+        }
+    }
+    if (modeNameSets.length <= 1) {
+        return {
+            id: "consistency-mode-naming",
+            label: "Mode naming consistency",
+            score: 100,
+            severity: "pass",
+            tooltip: "All collections with multiple modes should use the same mode names (e.g. Light/Dark). Inconsistent mode names cause confusion.",
+            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;
+        }
+    }
+    const ratio = dominantCount / modeNameSets.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.",
+    };
+}
+/**
+ * Consistency category scorer.
+ * Returns the average score across all consistency checks.
+ */
+export function scoreConsistency(data) {
+    const findings = [
+        scoreDelimiterConsistency(data),
+        scoreCasingConsistency(data),
+        scoreSizeValueConsistency(data),
+        scoreModeNamingConsistency(data),
+    ];
+    const score = clamp(findings.reduce((sum, f) => sum + f.score, 0) / findings.length);
+    return {
+        id: "consistency",
+        label: "Consistency",
+        shortLabel: "Consistency",
+        score,
+        weight: 0.15,
+        findings,
+    };
+}