StyleGuard

Validate your code against design system style guides.

Powered by Elastik Teams

What is StyleGuard?

StyleGuard is a CLI tool and Node.js library that automatically validates your HTML/CSS code against your brand's design system or style guide. It helps development teams maintain visual consistency by catching style violations before they reach production.

Why Use StyleGuard?

• Design System Compliance: Ensure your codebase follows your company's design tokens and brand guidelines
• Automated Validation: Catch color, spacing, and typography violations in CI/CD pipelines
• Multiple Input Formats: Import style guides from PDF, Word, Markdown, JSON, or plain text
• Flexible Output: Generate reports in HTML, Markdown, or JSON formats
• Zero Config Start: Interactive wizard guides you through validation with file autocomplete

What Does It Check?

| Category | Validations | |----------|-------------| | Colors | Hex, RGB, RGBA, HSL, HSLA values against approved palette | | Spacing | Margin, padding, gap values against spacing scale | | Typography | Font families, sizes, weights, line heights | | Components | Selector-based style rules for buttons, cards, etc. |

Use Cases

• Validate frontend code during pull request reviews
• Audit existing projects for design system compliance
• Convert legacy style guide documents to structured JSON tokens
• Generate compliance reports for stakeholders

Installation

npm install -g @elastikteams/styleguard

This installs StyleGuard globally. Run it with:

styleguard

Alternative: Local installation

npm install @elastikteams/styleguard --save-dev
npx styleguard --version  # Use npx for local installs

Quick Start

# Interactive mode - guided wizard with file autocomplete
styleguard

# Validate your source code against a style guide
styleguard validate -s ./brand-guide.pdf -p ./src

# Generate an HTML report (auto-opens in browser)
styleguard validate -s ./tokens.json -p ./src -f html

Commands

validate

Validate a target directory against a style guide.

styleguard validate -s <style-guide> -p <target> [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | -s, --styleguide <path> | Path to style guide file | (required) | | -p, --project <path> | Path to project to validate | (required) | | -f, --format <format> | Output format: json, html, md | json | | -o, --output <path> | Write output to file | stdout | | -e, --exclude <folders> | Folders to exclude (comma-separated) | node_modules,dist | | --threshold-errors <n> | Max errors before exit code 1 | 0 | | --threshold-warnings <n> | Max warnings before exit code 1 | Infinity | | --no-open | Do not auto-open HTML reports | - |

Examples:

# Generate HTML report
styleguard validate -s ./brand-guide.pdf -p ./src -f html

# Save report to specific path
styleguard validate -s ./tokens.json -p ./src -f html -o ./report.html

# Fail if more than 5 errors
styleguard validate -s ./tokens.json -p ./src --threshold-errors 5

convert

Convert a style guide document to JSON tokens.

styleguard convert <input> [output]

# Example
styleguard convert ./brand-guide.pdf ./tokens.json

init

Create a configuration file.

styleguard init

Creates styleguard.config.json with default settings.

Supported Formats

| Format | Extensions | |--------|------------| | JSON | .json | | Markdown | .md, .markdown | | PDF | .pdf | | Word | .docx, .doc | | Text | .txt |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success - all checks passed | | 1 | Validation failed - errors exceed threshold | | 2 | Configuration error | | 3 | File not found | | 4 | Parse error |

License

MIT License - see LICENSE for details.

Powered by Elastik Teams