extract_tokens_from_tailwind

Instructions

Implementation Reference

• src/tools/extract-tailwind.ts:15-76 (handler)

  The main handler function `extractTokensFromTailwind` that parses a Tailwind config file's text content and extracts design tokens for colors, typography, spacing, border radii, and elevation/shadows. It uses regex-based static analysis (no eval) to safely extract the theme object from both CJS and ESM config formats.

  export function extractTokensFromTailwind(configContent: string): DesignTokens {
    const themeObj = extractThemeObject(configContent);
    if (!themeObj) {
      throw new Error(
        "Could not extract theme from Tailwind config. Ensure the config exports a theme or theme.extend object."
      );
    }
  
    const tokens: DesignTokens = {};
  
    // Colors
    const colors = themeObj.extend?.colors ?? themeObj.colors;
    if (colors && typeof colors === "object") {
      tokens.colors = extractColors(colors);
    }
  
    // Typography (fontSize)
    const fontSize = themeObj.extend?.fontSize ?? themeObj.fontSize;
    if (fontSize && typeof fontSize === "object") {
      tokens.typography = extractTypography(fontSize);
    }
  
    // Font family — merge into typography if present
    const fontFamily = themeObj.extend?.fontFamily ?? themeObj.fontFamily;
    if (fontFamily && typeof fontFamily === "object") {
      if (!tokens.typography) tokens.typography = {};
      for (const [name, value] of Object.entries(fontFamily)) {
        const family = Array.isArray(value) ? value[0] : String(value);
        // Create or update a typography entry for this font family
        tokens.typography[`font-${name}`] = {
          fontFamily: family,
          fontSize: 16, // default base size
        };
      }
    }
  
    // Spacing
    const spacing = themeObj.extend?.spacing ?? themeObj.spacing;
    if (spacing && typeof spacing === "object") {
      tokens.spacing = extractNumericMap(spacing);
    }
  
    // Border radius -> radii
    const borderRadius = themeObj.extend?.borderRadius ?? themeObj.borderRadius;
    if (borderRadius && typeof borderRadius === "object") {
      tokens.radii = extractNumericMap(borderRadius);
    }
  
    // Box shadow -> elevation
    const boxShadow = themeObj.extend?.boxShadow ?? themeObj.boxShadow;
    if (boxShadow && typeof boxShadow === "object") {
      tokens.elevation = extractElevation(boxShadow);
    }
  
    // Ensure we have at least one category
    const hasContent = Object.values(tokens).some((v) => v !== undefined);
    if (!hasContent) {
      throw new Error("Tailwind config theme contained no extractable token values.");
    }
  
    return tokens;
  }

• src/index.ts:33-54 (registration)

  Registration of the `extract_tokens_from_tailwind` tool with the MCP server. Defines the input schema (config: string) and the async handler that calls `extractTokensFromTailwind` and returns JSON-formatted tokens.

  server.registerTool(
    "extract_tokens_from_tailwind",
    {
      description:
        "Parse a Tailwind config and extract theme values into universal design tokens",
      inputSchema: {
        config: z
          .string()
          .describe(
            "The contents of a tailwind.config.js or tailwind.config.ts file"
          ),
      },
    },
    async ({ config }) => {
      try {
        const tokens = extractTokensFromTailwind(config);
        return toolResult(JSON.stringify(tokens, null, 2));
      } catch (e) {
        return errorResult(e);
      }
    }
  );

• src/types/tokens.ts:41-48 (schema)

  The `DesignTokens` interface defining the canonical intermediate format that all extractors produce. Includes optional categories for colors, typography, spacing, radii, elevation, and motion.

  export interface DesignTokens {
    colors?: Record<string, ColorToken>;
    typography?: Record<string, TypographyToken>;
    spacing?: Record<string, number>; // px values
    radii?: Record<string, number>; // px values
    elevation?: Record<string, ElevationToken>;
    motion?: Record<string, MotionToken>;
  }

• src/types/tokens.ts:7-27 (schema)

  Type definitions for `ColorToken` and `TypographyToken` interfaces used by the extracted design tokens.

  export interface ColorToken {
    value: string; // hex color, e.g. "#6750A4"
    description?: string;
    category?:
      | "primary"
      | "secondary"
      | "tertiary"
      | "neutral"
      | "error"
      | "surface"
      | "background"
      | "custom";
  }
  
  export interface TypographyToken {
    fontFamily?: string;
    fontSize: number; // px
    lineHeight?: number; // px
    fontWeight?: number; // 100-900
    letterSpacing?: number; // px
  }