Getting Started

Scan your codebase for hardcoded colors, spacing, font sizes, and border-radius values that should use design tokens.

The Problem

74%of React components

3+hardcoded values each

According to analysis of 5,000+ enterprise repositories, 74% of React components contain at least three hardcoded color or spacing values that bypass the design system. ds-lint finds them.

Installation

# Run directly (no install)
npx ds-lint src/

# Or install globally
npm i -g ds-lint

Usage

# Basic scan
ds-lint src/

# With token definitions (enables suggestions)
ds-lint src/ --tokens tokens.css

# Markdown report for PR
ds-lint src/ --format markdown --out report.md

# Strict mode for CI
ds-lint src/ --tokens tokens.css --strict

CLI Options

FlagDefaultDescription

[path].Directory or file to scan

--tokens <file>—Token source (.css, .json, or .md)

--format <type>terminalterminal | markdown | json

--out <file>—Write report to file

--strictfalseExit with code 1 if violations found

--versionPrint version

--helpPrint help

What It Detects

Colors

#hex, rgb(), rgba(), hsl(), hsla(), named CSS colors (red, blue, etc.)

Spacing

padding, margin, gap, top/right/bottom/left, width/height in px/rem

Font Sizes

font-size, line-height, letter-spacing in px/rem

Radius

border-radius in px/rem (skips 0px)

Scans: .js .jsx .ts .tsx .css .scss .vue .svelte

Skips: node_modules, dist, build, .next, .git, CSS variable declarations

Token Sources

Provide a token file with --tokens to get replacement suggestions:

CSS custom properties

:root {
  --color-primary: #3b82f6;
  --space-4: 16px;
  --text-sm: 14px;
  --radius-md: 8px;
}

JSON tokens (DTCG compatible)

{
  "color": {
    "primary": { "$value": "#3b82f6" }
  },
  "space": {
    "sm": { "$value": "8px" },
    "md": { "$value": "16px" }
  }
}

Markdown tables

Works with output from figma-to-design-md — token tables are parsed automatically.

Output Example

src/components/Button.tsx L14:5 #3b82f6 → var(--color-primary) (Color) L22:3 16px → var(--space-4) (Spacing) L31:3 14px → var(--text-sm) (Font Size) L45:3 8px → var(--radius-md) (Radius) src/pages/Home.css L8:5 #ff0000 (Color) L12:3 24px (Spacing) ───────────────────────────────── Total: 6 hardcoded values in 2 files Colors: 2 Spacing: 2 Fonts: 1 Radius: 1 Fixable (token match found): 4 of 6

Inline Ignore

Add a comment on the line above to skip specific values:

/* ds-lint-ignore */
.special-case { color: #ff0000; }

// ds-lint-disable
const borderColor = "#333";

CI Integration

# GitHub Actions
- name: Check design tokens
  run: npx ds-lint src/ --tokens tokens.css --strict

# Generate PR report
- name: DS Lint Report
  run: npx ds-lint src/ --tokens tokens.css --format markdown --out ds-lint.md

--strict exits with code 1 when violations are found, failing the CI step.

Pipeline

ds-lint fits between token definition and adoption tracking:

1. Extract from Figma → figma-to-design-md 2. Generate agent rules → design-system-ai-starter 3. Enforce in code → ds-lint ← you are here 4. Measure adoption → ds-coverage 5. Check live site → ds-health

View onGitHub →