ds-coverage — Andrew Antoshkin

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

Flag	Default	Description
[path]	.	Directory to scan
--ds <packages>	—	Comma-separated DS package names (required)
--inventory <file>	—	JSON file listing all DS components
--format <type>	terminal	terminal \| markdown \| json
--out <file>	—	Write report to file
--min <percent>	—	Fail if coverage below threshold
--version		Print version
--help		Print help

What It Measures

Components UsedHow many DS components appear in import statements across the codebase
Total ImportsTotal number of DS import occurrences — measures adoption depth
Custom ComponentsLocal components imported from relative paths — potential DS candidates
DuplicatesLocal components with the same name as DS components — likely reimplementations
Unused ComponentsDS components never imported anywhere — deprecation candidates (requires --inventory)

Healthy Codebase

A team that actively uses their design system:

Score	Meaning
34	DS Components
87%	Coverage
0	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:

Score	Meaning
12	DS Components
31%	Coverage
5	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 counts whether the codebase imports the system the model was told to use:

ds-lint blocks raw values
ds-context packs the system
ds-coverage counts real imports ← you are here
ds-health reads the live page

Source