ThemeTracker

🎨 Real-time theme auditing tool with comprehensive analytics for design system migration

ThemeTracker is a sophisticated code analysis tool designed to help teams migrate from legacy styling approaches (hardcoded values, styled-components themes) to modern CSS custom properties and design systems like design token-based systems.

✨ Features

🚀 Quick Start

• Zero Configuration - Works out of the box with auto-detection
• Universal Compatibility - Works with any React/JS project structure
• Like Majestic for Jest - Install globally and run anywhere

🎯 Core Functionality

• ✅ Zero External Dependencies - Uses only Node.js built-in modules
• ✅ Real-time Analysis - Custom WebSocket implementation for live updates
• ✅ Interactive Dashboard - GitHub-inspired dark UI with responsive design
• ✅ File-by-File Auditing - Click any file to audit instantly
• ✅ Batch Processing - Audit entire directories or codebase
• ✅ CSS/SCSS Support - Analyze stylesheets in addition to JS/TS files

🎨 Design System Integration

• ✅ Design System Ready - Built-in support for design tokens
• ✅ Configurable Patterns - Customize violation detection
• ✅ CSS Custom Properties - Promotes var(--*) usage patterns
• ✅ Smart Auto-Detection - Finds config files automatically

📊 Advanced Analytics

• ✅ Contextual File Classification - UI components, pages, utilities
• ✅ Coverage Metrics Engine - Comprehensive coverage analysis with trends
• ✅ Components Metrics - Page-by-page component hierarchy analysis
• ✅ Violation Categorization - Separates themeable vs non-themeable violations
• ✅ Priority Scoring - Identifies critical files and quick wins

🤖 AI Integration (NEW!)

• ✅ MCP Server Support - Model Context Protocol for AI assistants
• ✅ Cursor Integration - Real-time violation detection in Cursor IDE
• ✅ Automated Fix Suggestions - AI-powered theme compliance fixes
• ✅ Design System Context - AI understands your specific design tokens

🚀 Installation & Usage

Global Installation (Recommended)

# Install globally
npm install -g themetracker

# Run in any project
cd /your-react-project
themetracker start

npx Usage (No Installation Required)

# Run directly without installing
cd /your-react-project
npx themetracker start

AI Integration with MCP (NEW!)

# Start MCP server for AI integration
cd /your-react-project
themetracker mcp

# Then configure in Cursor settings:
{
  "mcpServers": {
    "themetracker": {
      "command": "npx",
      "args": ["themetracker", "mcp"]
    }
  }
}

Local Development Dependency

# Install as dev dependency
npm install --save-dev themetracker

# Add to package.json scripts
{
  "scripts": {
    "theme-audit": "themetracker start"
  }
}

# Run via npm
npm run theme-audit

🎯 Quick Start Guide

1. Start ThemeTracker

themetracker start

What happens:

• 🔍 Auto-detects your project structure (src/, components/, etc.)
• 🎨 Looks for design system configuration
• 🌐 Starts server on http://localhost:3001
• 🚀 Opens interactive dashboard in your browser
• ⚡ Begins real-time file monitoring

2. Initialize Configuration (Optional)

themetracker init

Creates a themetracker.config.js file with all available options:

module.exports = {
  designTokens: {
    tokensPath: "src/styles/tokens/colors.json",
  },
  sourceDirectories: {
    include: ["src", "components"],
  },
  // ... many more options
};

3. Check Project Status

themetracker info

Shows:

• 📂 Project structure detected
• 🎨 Design system configuration status
• 📊 Quick file scan preview
• 🔧 Current configuration

📊 Dashboard Features

Main Dashboard (http://localhost:3001)

📁 Project Structure (Sidebar)     |  📋 Analysis Panel (Main)
├── 📂 components/                 |
│   ├── Button.js        🟢 92%    |  File: components/UserCard.js
│   ├── Card.js          🟡 67%    |  Coverage: 67% | Type: UI Component
│   └── Modal.js         🔴 23%    |
├── 📂 pages/                      |  🚨 Violations Found: 5
│   └── Dashboard.js     🟢 88%    |  ━━━━━━━━━━━━━━━━━━━━━━━━━━━
└── 📂 utils/                      |
    └── helpers.js       ⚫ 12%    |  🔴 HIGH PRIORITY (Line 45)
                                   |  Found: background: #ffffff;
[🔍 Audit All] [📊 Report] [🔄]   |  💡 Use var(--color-fill-surface)

Color Coding:

• 🟢 Green (90%+): Excellent theme coverage
• 🟡 Yellow (40-89%): Needs improvement
• 🔴 Red (<40%): Critical issues
• ⚫ Gray: Appropriately styled (utility files)

Summary Dashboard (/src/summary.html)

📈 Theme Coverage Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Coverage: 73.2%  |  Total Files: 127  |  Violations: 234

📊 File Type Breakdown:
┌─────────────────┬─────────┬──────────┬─────────────┐
│ File Type       │ Count   │ Coverage │ Status      │
├─────────────────┼─────────┼──────────┼─────────────┤
│ UI Components   │ 45      │ 81.2%    │ 🟢 Excellent │
│ Page Components │ 12      │ 67.8%    │ 🟡 Fair      │
│ CSS/SCSS Files  │ 8       │ 74.5%    │ 🟢 Good      │
│ Utility Files   │ 34      │ 15.3%    │ ⚫ Expected  │
└─────────────────┴─────────┴──────────┴─────────────┘

🎨 Violation Detection

JavaScript/TypeScript Files

// ❌ Detected Violations
const Button = styled.button`
  background: #ffffff;                    // → var(--color-fill-surface)
  margin: 16px;                          // → var(--spacing-200)
  ${({ theme }) => theme.colors.primary} // → var(--color-fill-brand)
`;

// Tailwind violations
className="bg-blue-500 text-gray-700 p-4"  // → Use design token classes

// ✅ Approved Patterns
background: var(--color-fill-surface);
className="bg-color-brand-primary text-color-text-primary"

CSS/SCSS Files (New!)

/* ❌ CSS Violations */
.component {
  background-color: #ffffff; /* → var(--color-fill-surface) */
  margin: 16px; /* → var(--spacing-200) */
  font-size: 14px; /* → var(--text-sm) */
  box-shadow: 0 2px 4px #ccc; /* → var(--shadow-sm) */
}

/* ❌ SCSS Violations */
/* → Use design token CSS variables */
color: darken($primary-color, 10%); /* → Use design token color tokens */

/* ✅ Approved Patterns */
.component {
  background: var(--color-fill-surface);
  margin: var(--spacing-200);
}

🔧 Configuration

Auto-Detection (Zero Config)

ThemeTracker automatically detects:

• 📂 Source directories: src/, app/, components/
• 🎨 Design token config files: src/styles/tokens/colors.json
• 📄 File types: .js, .jsx, .ts, .tsx, .css, .scss
• 🚫 Files to ignore: tests, mocks, node_modules, etc.

Custom Configuration

Create themetracker.config.js for custom settings:

module.exports = {
  // Design System
  designTokens: {
    tokensPath: "src/styles/tokens/colors.json",
    cssVariablePrefix: "--",
  },

  // Source scanning
  sourceDirectories: {
    include: ["src", "components", "pages"],
    focus: ["src/components"], // Only scan specific dirs
  },

  // File types
  fileTypes: {
    javascript: { extensions: ["js", "jsx", "ts", "tsx"], enabled: true },
    styles: { extensions: ["css", "scss", "sass"], enabled: true },
  },

  // Enhanced ignore patterns
  ignore: {
    directories: ["node_modules", "dist", "__tests__"],
    filePatterns: ["*.test.*", "*.mock.*", "*.d.ts"],
    pathPatterns: ["/test/", "/mocks/", "/utils/"],
  },

  // Analysis settings
  analysis: {
    includeCssFiles: true,
    violations: {
      hardcodedColors: true,
      cssHardcodedValues: true,
      scssVariables: true,
    },
  },

  // Server settings
  server: {
    port: 3001,
    autoOpen: true,
  },
};

🎯 CLI Commands

# Start interactive dashboard
themetracker start
themetracker start --port 3002 --no-open

# Start MCP server for AI integration
themetracker mcp

# Initialize configuration
themetracker init

# Show project information
themetracker info

# Show help
themetracker help

📋 Supported File Types

| File Type | Extensions | Analysis | | ---------- | ---------------- | ------------------------------------------------- | | JavaScript | .js, .jsx | ✅ Styled-components, className, hardcoded values | | TypeScript | .ts, .tsx | ✅ Same as JavaScript + type definitions | | CSS | .css | ✅ Hardcoded colors, spacing, typography | | SCSS/Sass | .scss, .sass | ✅ CSS + SCSS variables, functions | | Less | .less | ✅ CSS + Less variables |

🎨 Design Token Integration

Token Detection

ThemeTracker automatically loads your design token definitions:

// src/styles/tokens/colors.json
{
  "color-brand-primary": "#0066cc",
  "color-text-primary": "#1a1a1a",
  "color-surface": "#ffffff",
  "spacing-md": "1rem",
  "radius-sm": "0.25rem"
}

Approved vs Violation Patterns

// ✅ Approved
className="bg-color-brand-primary"  // From design token
var(--color-fill-surface)           // CSS custom properties

// ❌ Violations
className="bg-blue-500"            // Hardcoded Tailwind
background: #ffffff                // Hardcoded hex

📊 Migration Strategy

Recommended Workflow

Phase 1: Assessment

themetracker start
# → Click "Coverage Report"
# → Review critical files (red indicators)
# → Export baseline metrics

Phase 2: Quick Wins

Focus on files with 80%+ potential:

• Badge, Tooltip, Icon components
• Simple layout components

Phase 3: Core Components

Tackle complex, high-impact components:

• Form components, navigation, data display

Phase 4: Pages & Integration

Complete migration at page level

🛠 Advanced Features

Real-time Updates

• 🔌 WebSocket-based live communication
• ⚡ Instant feedback as you make changes
• 📊 Live progress tracking during batch operations

Smart File Classification

// Automatically categorized by content analysis
"ui-component"    → 80-95% coverage expected
"page-component"  → 60-80% coverage expected
"style-file"      → 70-90% coverage expected
"utility"         → 10-30% coverage expected (appropriate)

Contextual Analysis

• Different expectations for different file types
• Intelligent violation prioritization
• Contextual recommendations

Performance Optimized

• Processes large codebases efficiently
• Memory usage controls
• Concurrent file processing

🔧 Troubleshooting

Common Issues

No files found:

themetracker info  # Check detected directories
themetracker init  # Create config file

Design tokens not found:

# Check these paths exist:
src/styles/tokens/colors.json
styles/tokens/colors.json
theme/tokens.json

Port already in use:

themetracker start --port 3002

WebSocket connection fails:

• Check firewall settings
• Restart: Ctrl+C then themetracker start
• Clear browser cache

📖 Examples

Example 1: React Component Migration

cd my-react-app
themetracker start
# → Click components/Button.js
# → See violations: hardcoded colors, spacing
# → Follow suggestions to use var(--*)
# → Watch coverage improve in real-time

Example 2: CSS File Analysis

# ThemeTracker now analyzes CSS/SCSS too!
# → Detects hardcoded values in stylesheets
# → Suggests CSS custom property replacements
# → Tracks SCSS variable usage

Example 3: Large Codebase Audit

cd enterprise-app
themetracker start
# → Click "Audit All Files"
# → Watch real-time progress (1000+ files)
# → Review summary dashboard
# → Export coverage report

🚀 Development

Package Structure

themetracker/
├── bin/themetracker          # CLI executable
├── lib/
│   ├── index.js             # Main API
│   ├── cli.js               # CLI implementation
│   ├── server.js            # HTTP + WebSocket server
│   ├── engines/             # Analysis engines
│   ├── config/              # Configuration management
│   └── utils/               # Utilities
├── assets/ui/               # Dashboard UI (preserved exactly)
└── templates/               # Config templates

API Usage

const { ThemeTracker } = require("themetracker");

const tracker = new ThemeTracker({ projectRoot: "/path/to/project" });
await tracker.init();

const files = await tracker.scanFiles();
const server = await tracker.startServer({ port: 3001 });

📋 Migration from Embedded Version

If you're currently using ThemeTracker embedded in your project:

Before (Embedded)

npm run theme-tracker:start

After (Package)

npm install -g themetracker
themetracker start

Benefits:

• ✅ Use in any project without copying files
• ✅ Automatic updates via npm
• ✅ Consistent experience across projects
• ✅ Enhanced features and better performance

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• 📦 npm package
• 🐛 Report Issues
• 📖 Documentation

Ready to improve your theme coverage?

npx themetracker start

Watch your design system migration progress in real-time! 🚀