AlignMyDesign

AlignMyDesign is your comprehensive tool for maintaining visual consistency. Detect drift, generate tokens, and automate your design system.

The Problem: Drift

Codebases rot. Hex values multiply. Spacing scales break. Design drift isn't just ugly—it's technical debt that slows you down.

The Solution: Align

We scan every line of code, cluster similar values using perceptual algorithms, and give you the tools/tokens to fix it instantly.

Installation

Global Installation (Recommended for CLI)

npm install -g alignmydesign

Project Dependency

npm install --save-dev alignmydesign

[!NOTE] You can also run commands directly with npx alignmydesign without installing.

Quick Start

01 Scan Your Codebase

Inventory every color, font, and spacing value in your project.

alignmydesign start

Core Concepts

Clustering Engine

We don't just count values. We use CIE Delta-E to group similar colors (e.g. Slate 500 and Gray 500) and normalize spacing to your nearest grid unit.

Design Tokens

Drift happens when values are hardcoded. We replace magic values with semantic tokens like colors.primary.

Supported Frameworks

AlignMyDesign works seamlessly with:

• Next.js - Full support with automatic detection
• Vite (React, Vue) - CSS variables + Vite plugin generation
• React Native / Expo - Native token format with numeric values
• Create React App - TypeScript and JSON tokens
• Remix - Full support

TanStack Integration

Automatically detects and works with:

• TanStack Query (React Query)
• TanStack Router
• TanStack Table
• TanStack Form
• TanStack Virtual

CLI Reference

| Command | Description | Options | | :--- | :--- | :--- | | scan | Inventory design values | --include, --exclude, --format, --verbose | | report | Generate drift analysis | --output, --format, --threshold | | init | Generate design tokens | --format, --output, --vite-plugin, --postcss, --types | | plan | Generate refactoring plan | --output | | rules | Generate linting rules | --cursor, --stylelint, --eslint | | lint | Validate against tokens | --fix, --strict | | watch | Real-time linting | --debounce | | start | Launch dashboard | --port, --cwd <path> | | architecture | Analyze code architecture | --include, --exclude, --output, --format |

Which project is analyzed?

The dashboard analyzes the directory you run the command from. To analyze a specific project:

• Option 1: Run the command from that project's directory:

  cd /path/to/your-project
  alignmydesign start

• Option 2: Use the --cwd option from anywhere:

  alignmydesign start --cwd /path/to/your-project

The dashboard shows the analyzed project path in the footer. If you see the same design results when switching projects, ensure you're running alignmydesign start from (or with --cwd pointing to) the correct project, and that only one server is running on the chosen port.

Token Formats

• json - Universal JSON format
• typescript - TypeScript with type definitions
• css - CSS variables (recommended for Vite)
• tailwind - Tailwind CSS v4 @theme format
• native - React Native StyleSheet format

Vite-Specific Features

When working with Vite projects, use these additional options:

# Generate tokens with Vite plugin and TypeScript types
alignmydesign init --vite-plugin --types

# Generate with PostCSS configuration
alignmydesign init --postcss

# Or let auto-detection handle it
alignmydesign init

Generated files for Vite projects:

• tokens.css - CSS custom properties
• tokens.json - JSON format
• theme.ts - TypeScript with types
• vite-plugin-alignmydesign.js - Auto-import plugin
• tokens.types.ts - Type-safe CSS variables
• VITE_USAGE.md - Usage guide with examples

Visual Dashboard

The CLI is powerful, but seeing is believing. Launch the local dashboard to visualize your design system's health, interact with dependency graphs, and spot outliers.

• Run in terminal: alignmydesign start
• Open active port: localhost:5656

Drift Score

Your Drift Score (0-100) is a weighted calculation of how consistent your codebase is. A lower score means a healthier, more consistent design implementation.

| Score Range | Status | | :--- | :--- | | 0-20 | Excellent | | 21-40 | Good | | 41-60 | Fair | | 61-80 | Poor | | 81+ | Critical |

Scoring Weights

| Metric | Weight | | :--- | :--- | | Color Variance | 25% | | Font Inconsistency | 25% | | Off-Scale Spacing | 20% | | Low Reuse Rate | 15% | | Cluster Similarity | 15% |