Getting Started

This page is the complete happy path: six steps take you from zero to a design system that's enforced on every AI-generated diff. Every step below shows the exact output you should see so you can tell you're on track. Everything runs locally — no code ever leaves your machine.

Step 1 — Install the MCP server

The MCP server is how Deslint talks to Claude Code, Cursor, Codex, and Windsurf. It lets the agent call deterministic design checks before it ships a diff, so drift is caught in the generation loop, not after.

npx @deslint/mcp install

The installer auto-detects your agent's config file, writes the MCP server entry, and prints the next restart step. Vendor-specific guides if you want to confirm the config by hand:

• Claude Code
• Cursor
• OpenAI Codex
• Windsurf

Step 2 — Install the CLI

The CLI is how you import tokens, run scans from your terminal, and gate PRs in CI. It's the same deterministic rule set the MCP server uses.

npm install --save-dev @deslint/cli

Or run it directly with npx deslint … — no install step required for a quick try.

Step 3 — Import your design tokens

Deslint enforces rules against the design system you already have. Point import-tokens at wherever your tokens live — Figma Variables, a Style Dictionary file or directory, or a Google Stitch / Material 3 export — and it emits a .deslintrc.json fragment you can merge in.

# Figma Variables (read-only API)
npx deslint import-tokens --figma <file-id> --format deslintrc

# Style Dictionary (single file or directory)
npx deslint import-tokens --style-dictionary ./tokens --format deslintrc

# Google Stitch / Material 3
npx deslint import-tokens --stitch ./stitch-tokens.json --format deslintrc

Expected output:

  ✓ Imported 25 token(s) from 1 file(s)
  ✓ Wrote tokens.json

  Your design system is ready:
    19 colors       → no-arbitrary-colors, no-legacy-color, consistent-color-semantics
     4 radii        → no-arbitrary-border-radius, consistent-border-radius
     2 fonts        → no-arbitrary-font-family

  Next:
    1. Merge tokens.json into your .deslintrc.json
    2. Run `npx deslint scan` to see drift

The summary tells you exactly which rules each bucket unlocks. Merge the fragment into your project's .deslintrc.json (or run npx deslint init first to scaffold one) before moving on.

Step 4 — Run your first scan

With tokens in place, scan reports a Design Health Score out of 100 and a per-category breakdown for colors, spacing, typography, responsive behaviour, and consistency.

npx deslint scan

Expected output (abridged):

  Deslint Design Health Report
  ────────────────────────

  Design Health Score: 88/100

  Colors       ████████████████████ 100
  Spacing      █████████████████░░░  86
  Typography   ████████████████████  99
  Responsive   ███████████░░░░░░░░░  59
  Consistency  ████████████████████  97

  Files scanned: 94
  Files with issues: 43
  Total violations: 0 errors, 110 warnings

  Full report: .deslint/report.html

  Next:
    14 auto-fixable. Review with `npx deslint fix --interactive`
    Or apply every safe fix: `npx deslint fix --all`

The CLI also writes a standalone HTML report at .deslint/report.html. Open it with npx deslint report.

For a design-system-focused view — how much of your UI is on-token vs. drifting into arbitrary values — run the Token Drift Score report alongside scan:

npx deslint coverage

This writes a shareable HTML report to .deslint/coverage.html breaking every class usage into three buckets: design-system tokens, default Tailwind scale, and arbitrary prefix-[value] drift. It's the artifact to send your design-system lead — no violations list, just the adoption curve.

Step 5 — Fix what's auto-fixable

Two common ways to work through the violations:

# Walk each violation with a y/n/skip prompt
npx deslint fix --interactive

# Apply every safe auto-fix at once
npx deslint fix --all

# Preview what would change, without touching files
npx deslint fix --dry-run

Auto-fixes are surgical. Only rules with a safe, deterministic fix (JSX-only, bailing on dynamic class expressions) participate — drift that requires human judgment stays in the report for you to address deliberately.

Step 6 — Gate it in CI

Once your repo is clean, the last step is locking the gate so the next AI-generated PR can't silently regress it.

GitHub Action (recommended)

The Action posts a Design Health Score summary, drops inline review comments on the changed lines that introduced violations, and renders one-click autofixes as GitHub suggestion blocks when the replacement is provably visually lossless.

# .github/workflows/deslint.yml
name: Deslint design review
on:
  pull_request:
    branches: [main]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0              # required for agent-scorecard + token-drift
      - uses: jaydrao215/deslint/action@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          min-score: 85
          suggest-fixes: true         # one-click PR suggestions (safe fixes only)
          agent-scorecard: true       # attribute violations to Claude/Cursor/Codex/…
          token-drift: true           # diff designSystem tokens base vs head
          strict-trailer: false       # flip to true once attestations are rolling

One-click autofixes — when the fix is byte-identical (e.g. bg-[#1A5276] → bg-primary where primary resolves to #1A5276) or additive-safe (a motion-safe: wrap that adds a modifier without removing anything), the Action renders it as a GitHub suggestion block a reviewer can commit in one click. Opinionated closest-match fixes render as read-only code blocks with a "run deslint fix locally" nudge — so nobody one-click-ships a pixel change they never saw. Disable with suggest-fixes: false.

CLI-only (non-GitHub, or local pre-commit)

- name: Design Quality Gate
  run: npx deslint scan --min-score 85 --format sarif

Exit code 1 if the Design Health Score drops below your threshold. SARIF output integrates with GitHub Advanced Security so violations show inline in the PR diff. Use --fail-on warning to fail on warnings too, or --fail-on never to report without blocking.

Troubleshooting

• "No files found to scan" — you're running scan from outside the source root, or your ignore pattern is too broad. Pass the directory explicitly: npx deslint scan ./apps/web.
• "Score unavailable — fix N parser errors first" — your files contain TypeScript/JSX the ESLint parser can't read. Run tsc --noEmit first, fix the errors, then re-scan.
• Too many warnings to address at once? — use --diff origin/main to only report on lines changed since a ref, which is the right gate for legacy codebases.

Alternative: ESLint plugin

If you prefer to run Deslint directly in your ESLint pipeline, skip the CLI and add the plugin to your eslint.config.js (v10+ flat config):

import deslint from '@deslint/eslint-plugin';

export default [
  deslint.configs.recommended,
  // … your other config
];

Framework support

• React / Next.js — JSX className
• Vue — class and :class
• Svelte — class attributes and class: directives
• Angular — templates, [ngClass], [class] bindings
• Plain HTML — standard class

Tailwind v3 + v4

All rules support both Tailwind v3 and v4 class naming conventions. Deslint auto-detects your Tailwind version from your config file.