Design Token Analyzer ⬡

A production-grade, extensible static analysis developer tool to measure, audit, and enforce Design System compliance across modern frontend codebases.

🎯 The Motto & Vision

"Bridging the gap between design specifications and implementation code via automated static analysis."

In modern software development, design systems quickly drift. While designers publish tokens (colors, spacing, typography) in tools like Figma, developers often introduce:

1. Hardcoded styling values (e.g., #FF5733 or padding: 17px) directly inside React code.
2. Registry Bloat (tokens registered in CSS but never used in any component).
3. Duplicate Variable Values (declaring different names for identical design primitives).

How it Differs from Other Tools

• VS Code Linters (ESLint, Stylelint): These tools analyze files in isolation (e.g., checking syntax errors within a single .tsx or .css file). They cannot perform cross-file correlation (e.g., verifying if a hex code in Card.tsx has a corresponding token variable in variables.css).
• Design Token Managers (Style Dictionary): Style Dictionary converts design tokens from JSON to platform-specific variables (CSS, iOS, Android). It does not scan your source code to see if developers are actually using those variables or bypassing them.
• This Analyzer: Acts as a cross-file correlation engine. It parses the stylesheets to build a Token Registry, parses the JavaScript/TypeScript React tree to build a Usage Registry, and validates compliance across the boundary between the two.

🛠️ Phase-by-Phase Architecture

Here is the breakdown of the engineering pipeline built across the 8 phases of this project:

graph TD
  Scanner[Phase 2: File Scanner] --> Parser[Phase 3: Token Registry Parser]
  Parser --> Analyzer[Phase 4: Token Usage Analyzer]
  Analyzer --> Engine[Phase 5: Validation Engine]
  Engine --> CLI[Phase 7: Professional CLI]
  CLI --> Dashboard[Phase 6: Local Dashboard]
  CLI --> Exporter[Phase 8: Export & Reporting System]

Phase 1: Project Foundation

• Purpose: Establish a production-quality, type-safe development environment with continuous code quality checks.
• What was done: Configured TypeScript workspace compilations, established modern ESLint flat configurations, Prettier styling, and integrated the Vitest testing runner. Implemented a centralized logger class with log levels.
• Libraries Used:
  • typescript (For compilation and type safety).
  • vitest (Fast, ESM-native testing runner. Chosen over Jest for performance).
  • eslint & prettier (Code formatting & style alignment).

Phase 2: File Scanner

• Purpose: Recursively crawl target folders in parallel to locate stylesheets and React codebase files.
• What was done: Built ScannerService using recursive directory walker patterns. Handled OS permission exceptions, ignored build directories (node_modules, dist, .next), and returned details like file sizes and extensions.
• Libraries Used:
  • fast-glob (Industrial-grade glob matcher. Used because it utilizes non-blocking native worker threads to walk file trees exponentially faster than basic Node recursive FS scripts).

Phase 3: Token Registry

• Purpose: Parse CSS/SCSS stylesheets to extract registered CSS variables and detect duplicates.
• What was done: Developed CssParser and TokenRegistry. It extracts CSS variable names (e.g. --primary-color), values, line/column numbers, and maps overrides. It groups variables to detect duplicate color/sizing definitions.
• Libraries Used:
  • postcss (State-of-the-art CSS parser. Chosen over regular expressions because it builds a formal CSS AST, ensuring accurate parse locations even inside complex media queries, nested rules, or calc functions).

Phase 4: Token Usage Analyzer

• Purpose: Scan React component files (.jsx, .tsx) to trace variable usages.
• What was done: Programmed AnalyzerService which parses React codebase files. By traversing AST trees, it detects design token uses in inline styles, CSS classes (var(--token)), and Tailwind token classes (e.g. bg-primary, p-4).
• Libraries Used:
  • @babel/parser & @babel/traverse (Industry-standard JavaScript/TypeScript compiler parsing libraries. Used because regular expressions fail to understand React JS/TS contexts, whereas Babel AST traversal tracks variables, string literals, and imports reliably).

Phase 5: Validation Engine

• Purpose: Inspect collected registries to flags violations of design compliance rules.
• What was done: Created ValidationEngine implementing the Strategy Pattern for rules. Created rules like unused-token, duplicate-value, and category-scoped hardcoded check rules (hardcoded-color, hardcoded-spacing, etc.) which search for hardcoded values and automatically suggest the closest design token alternative.

Phase 6: Local Dashboard

• Purpose: Render a beautiful graphical user interface to visualize scan results.
• What was done: Created a client-only single page React app in dashboard/. Renders overview stats, compliance health ratings, token explorer search lists, components mapping tables, and diagnostics categories. Built with dark-mode support and custom tab navigation.
• Libraries Used:
  • react & vite (Lightweight React development and building pipeline).
  • recharts (Canvas-based data chart library used to display color usage distributions and category bar metrics).
  • lucide-react (Vector graphical icons pack).

Phase 7: Professional CLI

• Purpose: Wrap the analysis logic inside a professional command-line interface resembling ESLint and Prettier.
• What was done: Exposed commands like scan, validate, report, and dashboard. Implemented standard exit codes (0 for success, 1 for violations found, 2 for crashes) so the tool can run in CI pipelines. Configured a debounce file watcher that re-runs scans instantly when files are saved.
• Libraries Used:
  • commander (Robust argument, option, and command parser).
  • chalk (Adds vibrant color outputs to the terminal).
  • ora (Draws animated spinners for visual feedback during long operations).
  • chokidar (File-watcher library. Used because it resolves native Node fs.watch event issues, preventing multiple double-fired scan loops).

Phase 8: Export & Reporting System

• Purpose: Serialize compliance results into multiple archive formats for documentation and QA analysis.
• What was done: Implemented a Strategy Pattern pipeline inside ReportManager. Created exporters for JSON, multi-file CSV (separate spreadsheets for tokens, usages, components, validation details, and run summaries), documentation-ready Markdown, and interactive self-contained HTML.
• Libraries Used:
  • puppeteer (Headless Chromium printing library. Used to load the generated HTML report and print it directly to an A4 PDF document with print stylesheet optimization).

🚀 How to Implement in Another Project

To run this token analyzer on a completely different project (e.g. your UI registry codebase, or a Next.js / Vite web app):

Step 1: Install & Build

In the D:\TokenAnalyser folder, compile the code:

npm run build

Step 2: Configure the Project

Create a configuration file called token-analyzer.config.json in the root of the project you want to scan:

{
  "ignoredFolders": ["node_modules", "dist", ".git", ".next", "build"],
  "ignoredFiles": [],
  "rules": {
    "unused-token": { "enabled": true },
    "duplicate-value": { "enabled": true },
    "hardcoded-color": { "enabled": true },
    "hardcoded-spacing": { "enabled": true },
    "hardcoded-radius": { "enabled": true },
    "hardcoded-typography": { "enabled": true }
  },
  "outputDir": "./reports",
  "tokenPrefixes": ["bg", "text", "border", "p", "m", "rounded"]
}

Step 3: Run the CLI

Use the CLI path to run scans on the target directory:

# 1. Print analysis stats in the console
node D:\TokenAnalyser\dist\cli\bin.js scan "D:\target-project-path"

# 2. Run diagnostic checks (Exits with 1 if violations exist, ideal for CI/CD)
node D:\TokenAnalyser\dist\cli\bin.js validate "D:\target-project-path"

# 3. Export reports (JSON, CSV sheets, HTML, Markdown) to target-project-path/reports/
node D:\TokenAnalyser\dist\cli\bin.js report "D:\target-project-path" --export json,csv,html,md

# 4. Run watch mode (re-scans as you edit files)
node D:\TokenAnalyser\dist\cli\bin.js validate "D:\target-project-path" --watch

Step 4: Open the Interactive Web Dashboard

If you want to view the full interactive dashboard containing charts and diagrams for the new project:

1. Generate the report:

   node D:\TokenAnalyser\dist\cli\bin.js report "D:\target-project-path"

2. Launch the dashboard:

   node D:\TokenAnalyser\dist\cli\bin.js dashboard

3. Open http://localhost:5173 in your web browser. The dashboard will automatically reflect the results of your scanned codebase!