Getting Started

Measure how much of your codebase actually uses your design system. Find unused components, duplicates, and adoption gaps.

Why This Exists

Adoption is the #1 challenge in design systems. Teams build component libraries but can't prove they're being used. Satisfaction can drop from 68% to 31% within a year while "adoption" metrics look healthy.

ds-coverage gives you real numbers: which components are imported, how often, and what's being reimplemented locally instead.

Installation

# Run directly (no install)
npx ds-coverage src/ --ds @acme/ui

# Or install globally
npm i -g ds-coverage

Usage

# Basic scan
ds-coverage src/ --ds @acme/ui

# Multiple packages
ds-coverage . --ds @acme/ui,@acme/icons

# With component inventory (finds unused)
ds-coverage src/ --ds @acme/ui --inventory components.json

# Markdown report
ds-coverage src/ --ds @acme/ui --format markdown --out coverage.md

# CI threshold (fail below 70%)
ds-coverage src/ --ds @acme/ui --inventory components.json --min 70

CLI Options

FlagDefaultDescription

[path].Directory to scan

--ds <packages>—Comma-separated DS package names (required)

--inventory <file>—JSON file listing all DS components

--format <type>terminalterminal | markdown | json

--out <file>—Write report to file

--min <percent>—Fail if coverage below threshold

--versionPrint version

--helpPrint help

What It Measures

Components Used

How many DS components appear in import statements across the codebase

Total Imports

Total number of DS import occurrences — measures adoption depth

Custom Components

Local components imported from relative paths — potential DS candidates

Duplicates

Local components with the same name as DS components — likely reimplementations

Unused Components

DS components never imported anywhere — deprecation candidates (requires --inventory)

Healthy Codebase

A team that actively uses their design system:

DS Components

87%

Coverage

Duplicates

Design System Coverage Report ────────────────────────────── Package: @acme/ui Components used: 34 of 39 (87%) Total imports: 412 Unused components: Alert, Breadcrumb, Stepper, Timeline, Tree ───────────────────────────── Files scanned: 186 DS component uses: 412 Custom components: 12 Top used: Button (142) Text (98) Card (67) Input (45) Badge (38)

Low Adoption

A codebase where teams bypass the design system:

DS Components

31%

Coverage

Duplicates

Package: @acme/ui Components used: 12 of 39 (31%) Total imports: 54 Unused components: 27 components never imported ───────────────────────────── Files scanned: 340 DS component uses: 54 Custom components: 89 ⚠ Possible dupes: Button, Modal, Badge, Card, Input Least used (1-2 imports): Tooltip (2) Accordion (1) Tabs (1)

Inventory File

To detect unused components, provide a JSON file listing all exports from your DS package:

Array format

["Button", "Card", "Modal", "Tooltip", "Badge", "Input", "Select"]

Object format

{
  "components": ["Button", "Card", "Modal", "Tooltip", "Badge"]
}

You can also point to the index file of your DS package — ds-coverage will parse its exports.

CI Integration

# GitHub Actions
- name: Check DS adoption
  run: npx ds-coverage src/ --ds @acme/ui --inventory components.json --min 60

# Generate PR report
- name: DS Coverage Report
  run: npx ds-coverage src/ --ds @acme/ui --format markdown --out coverage.md

--min exits with code 1 when coverage is below the threshold.

Pipeline

ds-coverage is the adoption layer in the design system workflow:

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

View onGitHub →