@mp3wizard/figma-console-mcp 1.14.0

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

@@ -0,0 +1,230 @@
+/**
+ * Coverage Scorer (weight: 0.10)
+ *
+ * Checks completeness of the design system.
+ * Evaluates token type coverage, core component presence,
+ * variable count health, and collection completeness.
+ */
+import { clamp, getSeverity } from "./types.js";
+/** All variable types that a complete token system should include. */
+const ALL_VARIABLE_TYPES = ["COLOR", "FLOAT", "STRING", "BOOLEAN"];
+/** Core component categories that a mature design system should have. */
+const CORE_COMPONENT_PATTERNS = [
+    { name: "button", pattern: /button/i },
+    { name: "input", pattern: /input|text\s*field/i },
+    { name: "card", pattern: /card/i },
+    { name: "modal/dialog", pattern: /modal|dialog/i },
+    { name: "navigation", pattern: /nav|navigation|menu|sidebar/i },
+    { name: "alert/toast", pattern: /alert|toast|notification|snackbar/i },
+];
+/**
+ * Score token type coverage.
+ * A complete system should include COLOR, FLOAT, STRING, and BOOLEAN variables.
+ */
+function variableDataUnavailable(data) {
+    return (data.dataAvailability !== undefined && !data.dataAvailability.variables);
+}
+function variableUnavailableMessage(data) {
+    const reason = data.dataAvailability?.variableError ||
+        "Figma Enterprise plan or Desktop Bridge plugin required";
+    return `Variable data unavailable: ${reason}`;
+}
+function scoreTokenTypeCoverage(data) {
+    if (data.variables.length === 0) {
+        return {
+            id: "coverage-token-types",
+            label: "Token type coverage",
+            score: 0,
+            severity: variableDataUnavailable(data) ? "info" : "fail",
+            tooltip: "A complete design system should include all variable types: COLOR, FLOAT, STRING, and BOOLEAN. Missing types indicate gaps.",
+            details: variableDataUnavailable(data)
+                ? variableUnavailableMessage(data)
+                : "No variables found in the design system.",
+        };
+    }
+    const presentTypes = new Set(data.variables.map((v) => v.resolvedType));
+    const foundTypes = ALL_VARIABLE_TYPES.filter((t) => presentTypes.has(t));
+    let score;
+    switch (foundTypes.length) {
+        case 4:
+            score = 100;
+            break;
+        case 3:
+            score = 75;
+            break;
+        case 2:
+            score = 50;
+            break;
+        case 1:
+            score = 25;
+            break;
+        default:
+            score = 0;
+    }
+    const missingTypes = ALL_VARIABLE_TYPES.filter((t) => !presentTypes.has(t));
+    return {
+        id: "coverage-token-types",
+        label: "Token type coverage",
+        score: clamp(score),
+        severity: getSeverity(score),
+        tooltip: "A complete design system should include all variable types: COLOR, FLOAT, STRING, and BOOLEAN. Missing types indicate gaps.",
+        details: missingTypes.length > 0
+            ? `${foundTypes.length} of ${ALL_VARIABLE_TYPES.length} variable types present. Missing: ${missingTypes.join(", ")}.`
+            : "All variable types (COLOR, FLOAT, STRING, BOOLEAN) are present.",
+    };
+}
+/**
+ * Score core component presence.
+ * A mature design system should include button, input, card, modal, nav, and alert components.
+ */
+function scoreCoreComponentPresence(data) {
+    if (data.components.length === 0) {
+        return {
+            id: "coverage-core-components",
+            label: "Core component presence",
+            score: 0,
+            severity: "fail",
+            tooltip: "A mature design system should include core UI patterns: button, input, card, modal/dialog, navigation, and alert/toast.",
+            details: "No components found in the design system.",
+        };
+    }
+    const foundCategories = [];
+    const missingCategories = [];
+    const matchExamples = [];
+    for (const category of CORE_COMPONENT_PATTERNS) {
+        const matching = data.components.filter((c) => category.pattern.test(c.name));
+        if (matching.length > 0) {
+            foundCategories.push(category.name);
+            matchExamples.push(`${category.name}: ${matching
+                .slice(0, 2)
+                .map((c) => c.name)
+                .join(", ")}`);
+        }
+        else {
+            missingCategories.push(category.name);
+        }
+    }
+    const ratio = foundCategories.length / CORE_COMPONENT_PATTERNS.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "coverage-core-components",
+        label: "Core component presence",
+        score,
+        severity: getSeverity(score),
+        tooltip: "A mature design system should include core UI patterns: button, input, card, modal/dialog, navigation, and alert/toast.",
+        details: missingCategories.length > 0
+            ? `${foundCategories.length} of ${CORE_COMPONENT_PATTERNS.length} core component categories found. Missing: ${missingCategories.join(", ")}.`
+            : "All core component categories are represented.",
+        examples: matchExamples.length > 0 ? matchExamples : undefined,
+    };
+}
+/**
+ * Score variable count health.
+ * A healthy design system should have a meaningful number of tokens.
+ */
+function scoreVariableCountHealth(data) {
+    const count = data.variables.length;
+    let score;
+    let details;
+    if (count === 0 && variableDataUnavailable(data)) {
+        return {
+            id: "coverage-variable-count",
+            label: "Variable count health",
+            score: 0,
+            severity: "info",
+            tooltip: "A healthy token system typically has 50+ variables. Fewer tokens may indicate the system relies on hard-coded values.",
+            details: variableUnavailableMessage(data),
+        };
+    }
+    if (count === 0) {
+        score = 0;
+        details =
+            "No variables found. A design system needs tokens for colors, spacing, and typography.";
+    }
+    else if (count <= 10) {
+        score = 50;
+        details = `${count} variables found. Consider expanding the token set for better coverage.`;
+    }
+    else if (count <= 50) {
+        score = 75;
+        details = `${count} variables found. Good foundation; consider adding more semantic layers.`;
+    }
+    else {
+        score = 100;
+        details = `${count} variables found. Healthy token coverage.`;
+    }
+    return {
+        id: "coverage-variable-count",
+        label: "Variable count health",
+        score: clamp(score),
+        severity: getSeverity(score),
+        tooltip: "A healthy token system typically has 50+ variables. Fewer tokens may indicate the system relies on hard-coded values.",
+        details,
+    };
+}
+/**
+ * Score collection completeness.
+ * Collections should cover different design concerns (color, spacing, typography, etc.).
+ */
+function scoreCollectionCompleteness(data) {
+    const count = data.collections.length;
+    let score;
+    let details;
+    if (count === 0 && variableDataUnavailable(data)) {
+        return {
+            id: "coverage-collection-completeness",
+            label: "Collection completeness",
+            score: 0,
+            severity: "info",
+            tooltip: "Multiple collections (3+) indicate good separation of concerns. Tokens should be organized by domain: colors, spacing, typography, etc.",
+            details: variableUnavailableMessage(data),
+        };
+    }
+    if (count === 0) {
+        score = 0;
+        details =
+            "No variable collections found. Organize tokens into logical collections.";
+    }
+    else if (count === 1) {
+        score = 50;
+        details =
+            "1 collection found. Consider splitting tokens into multiple collections by concern (color, spacing, typography).";
+    }
+    else if (count === 2) {
+        score = 75;
+        details = `${count} collections found. Good separation of concerns.`;
+    }
+    else {
+        score = 100;
+        details = `${count} collections found. Well-organized token architecture.`;
+    }
+    return {
+        id: "coverage-collection-completeness",
+        label: "Collection completeness",
+        score: clamp(score),
+        severity: getSeverity(score),
+        tooltip: "Multiple collections (3+) indicate good separation of concerns. Tokens should be organized by domain: colors, spacing, typography, etc.",
+        details,
+    };
+}
+/**
+ * Coverage category scorer.
+ * Returns the average score across all coverage checks.
+ */
+export function scoreCoverage(data) {
+    const findings = [
+        scoreTokenTypeCoverage(data),
+        scoreCoreComponentPresence(data),
+        scoreVariableCountHealth(data),
+        scoreCollectionCompleteness(data),
+    ];
+    const score = clamp(findings.reduce((sum, f) => sum + f.score, 0) / findings.length);
+    return {
+        id: "coverage",
+        label: "Coverage",
+        shortLabel: "Coverage",
+        score,
+        weight: 0.1,
+        findings,
+    };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Design System Health Dashboard — Scoring Engine
+ *
+ * Main orchestrator that runs all 6 category scorers against raw Figma data
+ * and produces a Lighthouse-style health score.
+ *
+ * Data flow:
+ *   DesignSystemRawData → scoreDesignSystem() → DashboardData (JSON)
+ */
+import { scoreAccessibility } from "./accessibility.js";
+import { classifyComponents, scoreComponentMetadata, } from "./component-metadata.js";
+import { scoreConsistency } from "./consistency.js";
+import { scoreCoverage } from "./coverage.js";
+import { scoreNamingSemantics } from "./naming-semantics.js";
+import { scoreTokenArchitecture } from "./token-architecture.js";
+import { getStatus } from "./types.js";
+/**
+ * Collect actionable findings from scored categories.
+ * Returns up to 5 human-readable strings from the worst findings,
+ * prioritizing "fail" severity, then "warning", sorted by score ascending.
+ */
+function generateSummary(categories) {
+    const actionableFindings = [];
+    for (const category of categories) {
+        for (const finding of category.findings) {
+            if (finding.severity === "fail" || finding.severity === "warning") {
+                actionableFindings.push({
+                    ...finding,
+                    categoryLabel: category.label,
+                });
+            }
+        }
+    }
+    // Sort: fail before warning, then by score ascending (worst first)
+    actionableFindings.sort((a, b) => {
+        const severityOrder = { fail: 0, warning: 1, pass: 2, info: 3 };
+        const aSev = severityOrder[a.severity];
+        const bSev = severityOrder[b.severity];
+        if (aSev !== bSev)
+            return aSev - bSev;
+        return a.score - b.score;
+    });
+    return actionableFindings
+        .slice(0, 5)
+        .map((f) => `[${f.categoryLabel}] ${f.label}: ${f.details ?? "Needs improvement."}`);
+}
+/**
+ * Score a design system's health from raw Figma data.
+ *
+ * Runs all 6 category scorers and produces a weighted overall score.
+ * Category weights sum to 1.0:
+ *   - Naming & Semantics:   0.20
+ *   - Token Architecture:   0.20
+ *   - Component Metadata:   0.20
+ *   - Accessibility:        0.15
+ *   - Consistency:          0.15
+ *   - Coverage:             0.10
+ *
+ * @param data - Raw Figma data (variables, collections, components, styles)
+ * @returns Complete dashboard payload with overall score, categories, and summary
+ */
+export function scoreDesignSystem(data) {
+    const categories = [
+        scoreNamingSemantics(data),
+        scoreTokenArchitecture(data),
+        scoreComponentMetadata(data),
+        scoreAccessibility(data),
+        scoreConsistency(data),
+        scoreCoverage(data),
+    ];
+    const overall = Math.round(categories.reduce((sum, c) => sum + c.score * c.weight, 0));
+    const summary = generateSummary(categories);
+    const classification = classifyComponents(data);
+    return {
+        overall,
+        status: getStatus(overall),
+        categories,
+        summary,
+        meta: {
+            componentCount: data.components.length,
+            variableCount: data.variables.length,
+            collectionCount: data.collections.length,
+            styleCount: data.styles.length,
+            componentSetCount: data.componentSets.length,
+            standaloneCount: classification.standalone.length,
+            variantCount: classification.variants.length,
+            timestamp: Date.now(),
+        },
+        fileInfo: data.fileInfo,
+        dataAvailability: data.dataAvailability,
+    };
+}

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

@@ -0,0 +1,308 @@
+/**
+ * Naming & Semantics Scorer (weight: 0.20)
+ *
+ * Checks whether design system names describe intent rather than appearance.
+ * Evaluates variable naming, component naming, variant naming, and boolean
+ * naming conventions against semantic best practices.
+ */
+import { buildCollectionNameMap, clamp, getSeverity } from "./types.js";
+/** Maximum examples to include in a finding. */
+const MAX_EXAMPLES = 5;
+/** Color words that indicate visual (non-semantic) naming. */
+const VISUAL_COLOR_WORDS = [
+    "red",
+    "blue",
+    "green",
+    "yellow",
+    "orange",
+    "purple",
+    "pink",
+    "black",
+    "white",
+    "gray",
+    "grey",
+    "cyan",
+    "magenta",
+    "teal",
+    "indigo",
+    "violet",
+    "brown",
+    "lime",
+    "amber",
+    "emerald",
+    "rose",
+    "sky",
+    "slate",
+    "zinc",
+    "stone",
+    "neutral",
+];
+/** Visual variant values that should be replaced with semantic ones. */
+const VISUAL_VARIANT_VALUES = [
+    "red",
+    "blue",
+    "green",
+    "yellow",
+    "orange",
+    "purple",
+    "pink",
+    "black",
+    "white",
+    "gray",
+    "grey",
+    "cyan",
+];
+/** Semantic variant values that indicate good naming. */
+const SEMANTIC_VARIANT_VALUES = [
+    "primary",
+    "secondary",
+    "tertiary",
+    "danger",
+    "warning",
+    "success",
+    "info",
+    "error",
+    "disabled",
+    "default",
+    "accent",
+    "muted",
+    "destructive",
+    "outline",
+    "ghost",
+    "link",
+];
+const PASCAL_CASE_RE = /^[A-Z][a-zA-Z0-9]*$/;
+const BOOLEAN_PREFIX_RE = /^(is|has|can|should|will|did|was|with|show|hide|enable|disable)/i;
+/**
+ * Extract the leaf segment from a variable name.
+ * e.g. "color/action/primary" -> "primary", "color.blue.500" -> "500"
+ */
+function getLeafName(name) {
+    const parts = name.split(/[/.]/);
+    return parts[parts.length - 1];
+}
+/**
+ * Check if a name contains visual color words in its leaf segments.
+ */
+function containsVisualColorWord(name) {
+    const leaf = getLeafName(name).toLowerCase();
+    return VISUAL_COLOR_WORDS.some((word) => leaf === word || leaf.startsWith(`${word}-`));
+}
+/**
+ * Score variable naming for semantic quality.
+ * Variables should use semantic names (color.action.primary) rather than
+ * visual names (color.blue.500).
+ */
+function scoreVariableNaming(data) {
+    const colorVars = data.variables.filter((v) => v.resolvedType === "COLOR");
+    if (colorVars.length === 0) {
+        return {
+            id: "naming-variable-semantic",
+            label: "Variable naming",
+            score: 100,
+            severity: "info",
+            tooltip: "Variables should describe intent (e.g. color/action/primary) rather than appearance (e.g. color/blue/500). Semantic names survive theme changes.",
+            details: "No color variables to evaluate.",
+        };
+    }
+    const collectionNames = buildCollectionNameMap(data.collections);
+    const visualVars = colorVars.filter((v) => containsVisualColorWord(v.name));
+    const semanticRatio = 1 - visualVars.length / colorVars.length;
+    const score = clamp(semanticRatio * 100);
+    return {
+        id: "naming-variable-semantic",
+        label: "Variable naming",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Variables should describe intent (e.g. color/action/primary) rather than appearance (e.g. color/blue/500). Semantic names survive theme changes.",
+        details: visualVars.length > 0
+            ? `${visualVars.length} of ${colorVars.length} color variables use visual names instead of semantic names.`
+            : `All ${colorVars.length} color variables use semantic names.`,
+        examples: visualVars.length > 0
+            ? visualVars.slice(0, MAX_EXAMPLES).map((v) => v.name)
+            : undefined,
+        locations: visualVars.length > 0
+            ? visualVars.slice(0, MAX_EXAMPLES).map((v) => ({
+                name: v.name,
+                collection: collectionNames.get(v.variableCollectionId),
+                type: "variable",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Score component naming for consistency.
+ * Components should use PascalCase and avoid mixed abbreviations.
+ */
+function scoreComponentNaming(data) {
+    const components = data.components;
+    if (components.length === 0) {
+        return {
+            id: "naming-component-casing",
+            label: "Component naming",
+            score: 100,
+            severity: "info",
+            tooltip: "Component names should use consistent PascalCase (e.g. Button, IconStar). Consistent casing improves discoverability.",
+            details: "No components to evaluate.",
+        };
+    }
+    let pascalCount = 0;
+    const nonPascalComps = [];
+    for (const comp of components) {
+        // Component names may use path separators; check each segment
+        const segments = comp.name.split("/").map((s) => s.trim());
+        const allPascal = segments.every((seg) => PASCAL_CASE_RE.test(seg));
+        if (allPascal) {
+            pascalCount++;
+        }
+        else {
+            nonPascalComps.push(comp.name);
+        }
+    }
+    const ratio = pascalCount / components.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "naming-component-casing",
+        label: "Component naming",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Component names should use consistent PascalCase (e.g. Button, IconStar). Consistent casing improves discoverability.",
+        details: `${pascalCount} of ${components.length} components use consistent PascalCase naming.`,
+        examples: nonPascalComps.length > 0
+            ? nonPascalComps.slice(0, MAX_EXAMPLES)
+            : undefined,
+    };
+}
+/**
+ * Score variant naming for semantic quality.
+ * Variant values should be semantic (primary, danger) rather than
+ * visual (blue, red). Also checks for consistent size naming.
+ */
+function scoreVariantNaming(data) {
+    // Components with variants have a componentSetId (Plugin API),
+    // containing_frame.containingComponentSet (REST API), or component_set_id (file JSON)
+    const variantComponents = data.components.filter((c) => c.componentSetId ||
+        c.containing_frame?.containingComponentSet ||
+        c.component_set_id);
+    if (variantComponents.length === 0) {
+        return {
+            id: "naming-variant-semantic",
+            label: "Variant naming",
+            score: 100,
+            severity: "info",
+            tooltip: "Variant values should use semantic terms (primary, danger) rather than visual ones (red, blue). This decouples design from implementation.",
+            details: "No variant components to evaluate.",
+        };
+    }
+    // Extract variant info from component names (e.g., "Button/Primary" or "Size=Small, Color=Primary")
+    let semanticCount = 0;
+    let visualCount = 0;
+    const visualVariantComps = [];
+    for (const comp of variantComponents) {
+        const nameLower = comp.name.toLowerCase();
+        const hasVisual = VISUAL_VARIANT_VALUES.some((v) => nameLower === v ||
+            nameLower.includes(`=${v}`) ||
+            nameLower.includes(`, ${v}`));
+        const hasSemantic = SEMANTIC_VARIANT_VALUES.some((v) => nameLower === v ||
+            nameLower.includes(`=${v}`) ||
+            nameLower.includes(`, ${v}`));
+        if (hasSemantic)
+            semanticCount++;
+        if (hasVisual) {
+            visualCount++;
+            visualVariantComps.push(comp.name);
+        }
+    }
+    const totalEvaluated = semanticCount + visualCount;
+    if (totalEvaluated === 0) {
+        return {
+            id: "naming-variant-semantic",
+            label: "Variant naming",
+            score: 75,
+            severity: "warning",
+            tooltip: "Variant values should use semantic terms (primary, danger) rather than visual ones (red, blue). This decouples design from implementation.",
+            details: "Variant values could not be classified as semantic or visual.",
+        };
+    }
+    const ratio = semanticCount / totalEvaluated;
+    const score = clamp(ratio * 100);
+    return {
+        id: "naming-variant-semantic",
+        label: "Variant naming",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Variant values should use semantic terms (primary, danger) rather than visual ones (red, blue). This decouples design from implementation.",
+        details: visualCount > 0
+            ? `${visualCount} variant values use visual names. Prefer semantic names like "primary", "danger".`
+            : "Variant values use semantic naming conventions.",
+        examples: visualVariantComps.length > 0
+            ? visualVariantComps.slice(0, MAX_EXAMPLES)
+            : undefined,
+    };
+}
+/**
+ * Score boolean variable naming.
+ * Boolean variables should follow is-, has-, can- prefix patterns.
+ */
+function scoreBooleanNaming(data) {
+    const boolVars = data.variables.filter((v) => v.resolvedType === "BOOLEAN");
+    if (boolVars.length === 0) {
+        return {
+            id: "naming-boolean-prefix",
+            label: "Boolean naming",
+            score: 100,
+            severity: "info",
+            tooltip: "Boolean variables should start with is, has, can, show, or similar prefixes (e.g. isDisabled). This makes their purpose immediately clear.",
+            details: "No boolean variables to evaluate.",
+        };
+    }
+    const collectionNames = buildCollectionNameMap(data.collections);
+    const missingPrefix = boolVars.filter((v) => {
+        const leaf = getLeafName(v.name);
+        return !BOOLEAN_PREFIX_RE.test(leaf);
+    });
+    const correctCount = boolVars.length - missingPrefix.length;
+    const ratio = correctCount / boolVars.length;
+    const score = clamp(ratio * 100);
+    return {
+        id: "naming-boolean-prefix",
+        label: "Boolean naming",
+        score,
+        severity: getSeverity(score),
+        tooltip: "Boolean variables should start with is, has, can, show, or similar prefixes (e.g. isDisabled). This makes their purpose immediately clear.",
+        details: missingPrefix.length > 0
+            ? `${missingPrefix.length} of ${boolVars.length} boolean variables lack is*/has*/can* prefixes.`
+            : `All ${boolVars.length} boolean variables use proper prefixes.`,
+        examples: missingPrefix.length > 0
+            ? missingPrefix.slice(0, MAX_EXAMPLES).map((v) => v.name)
+            : undefined,
+        locations: missingPrefix.length > 0
+            ? missingPrefix.slice(0, MAX_EXAMPLES).map((v) => ({
+                name: v.name,
+                collection: collectionNames.get(v.variableCollectionId),
+                type: "variable",
+            }))
+            : undefined,
+    };
+}
+/**
+ * Naming & Semantics category scorer.
+ * Returns the average score across all naming checks.
+ */
+export function scoreNamingSemantics(data) {
+    const findings = [
+        scoreVariableNaming(data),
+        scoreComponentNaming(data),
+        scoreVariantNaming(data),
+        scoreBooleanNaming(data),
+    ];
+    const score = clamp(findings.reduce((sum, f) => sum + f.score, 0) / findings.length);
+    return {
+        id: "naming-semantics",
+        label: "Naming & Semantics",
+        shortLabel: "Naming",
+        score,
+        weight: 0.2,
+        findings,
+    };
+}