ds-lint — Andrew Antoshkin

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

The Problem

A design system leaks when a component next to the tokens still writes a raw color or spacing value. ds-lint finds those values and, when a token file is nearby, suggests the system name.

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

Flag	Default	Description
[path]	.	Directory or file to scan
--tokens <file>	—	Token source (.css, .json, or .md)
--format <type>	terminal	terminal \| markdown \| json
--out <file>	—	Write report to file
--strict	false	Exit with code 1 if violations found
--version		Print version
--help		Print help

What It Detects

Colors#hex, rgb(), rgba(), hsl(), hsla(), named CSS colors (red, blue, etc.)
Spacingpadding, margin, gap, top/right/bottom/left, width/height in px/rem
Font Sizesfont-size, line-height, letter-spacing in px/rem
Radiusborder-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 is the gate in code, before a model is allowed to see the system:

figma-to-design-md extracts the spec
ds-lint blocks raw values ← you are here
ds-context packs what the model may see
ds-eval scores the generated UI

Source