Style Guard CLI

A powerful CLI tool that detects hardcoded CSS values and promotes the use of design tokens in your codebase. Style Guard helps maintain consistent styling by identifying hardcoded colors, pixel values, and other CSS properties that should be replaced with design tokens.

🚀 Features

• Hardcoded Color Detection: Identifies hex color values (#fff, #333333) that should use design tokens
• Pixel Value Detection: Finds hardcoded pixel values (16px, 24px) that should use spacing/size tokens
• Multi-Format Support: Scans CSS, SCSS, JSX, TSX, and HTML files
• Configurable Rules: Enable/disable specific checks via configuration file
• Colorized Output: Clear, readable terminal reports with syntax highlighting
• Zero Dependencies: Lightweight tool with no external dependencies

📦 Installation

Global Installation (Recommended)

npm install -g style-guard-cli

Local Installation

npm install --save-dev style-guard-cli

🛠️ Usage

Basic Usage

Scan the current directory:

style-guard

Scan a specific directory:

style-guard ./src

With npm scripts

Add to your package.json:

{
  "scripts": {
    "lint:styles": "style-guard src",
    "lint:styles:ci": "style-guard src --no-color"
  }
}

Then run:

npm run lint:styles

⚙️ Configuration

Create a styleguard.config.json file in your project root to customize the behavior:

{
  "extensions": [".css", ".scss", ".jsx", ".tsx", ".html"],
  "ignore": ["node_modules", "dist", "build", ".git", "coverage"],
  "rules": {
    "hardcodedColors": true,
    "hardcodedPx": true
  }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | extensions | string[] | [".css", ".scss", ".jsx", ".tsx", ".html"] | File extensions to scan | | ignore | string[] | ["node_modules", "dist", "build", ".git"] | Directories to ignore | | rules.hardcodedColors | boolean | true | Detect hardcoded hex colors | | rules.hardcodedPx | boolean | true | Detect hardcoded pixel values |

📋 Examples

Example Output

🔍 Scanning: /path/to/your/project

ℹ️  No styleguard.config.json found — using defaults

Found 12 file(s). Checking for violations...

──────────────────────────────────────────────────
📁 src/components/Button.jsx
──────────────────────────────────────────────────

Line 15: Hardcoded color "#3498db" — use a design token instead
Line 22: Hardcoded px value "16px" — use a spacing/size token instead

──────────────────────────────────────────────────
📁 src/styles/header.scss  
──────────────────────────────────────────────────

Line 8: Hardcoded color "#ffffff" — use a design token instead
Line 12: Hardcoded px value "24px" — use a spacing/size token instead

──────────────────────────────────────────────────
❌ Found 4 style violations across 2 files
──────────────────────────────────────────────────

Before Style Guard

.button {
  background-color: #3498db;
  padding: 16px 24px;
  border-radius: 8px;
  color: #ffffff;
}

After Style Guard (Recommended)

.button {
  background-color: var(--color-primary);
  padding: var(--space-md) var(--space-lg);
  border-radius: var(--radius-sm);
  color: var(--color-white);
}

🔧 Integration

Pre-commit Hooks

With husky:

npx husky add .husky/pre-commit "npx style-guard src"

CI/CD Integration

# GitHub Actions
- name: Run Style Guard
  run: |
    npm install -g style-guard-cli
    style-guard src

VS Code Integration

Add a task to .vscode/tasks.json:

{
  "type": "shell",
  "label": "Style Guard",
  "command": "style-guard",
  "args": ["src"],
  "group": "test",
  "presentation": {
    "echo": true,
    "reveal": "always",
    "panel": "new"
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Made with ❤️ by Hija Happy