extract_tokens_from_tailwind

Extract design tokens from Tailwind CSS configuration files to create universal theme values for cross-platform design systems.

Instructions

Parse a Tailwind config and extract theme values into universal design tokens

Input Schema

TableJSON Schema

Name	Required	Description	Default
`config`	Yes	The contents of a tailwind.config.js or tailwind.config.ts file

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
}

design-token-bridge-mcp