ds-coverage
Scan imports across your codebase to see which design-system exports are used, which sit unused, and where local components duplicate system names.
Why This Exists
A repository can have a forty-component library while product screens right next to it still build their own Button and Modal.
ds-coverage scans import statements across the codebase and reports what share of the system catalog is imported, which exports sit unused, and where a local component shares a name with a system export.
Installation
# Run directly (no install)
npx @andrewaitken/ds-coverage src/ --ds @acme/ui
# Or install globally
npm i -g @andrewaitken/ds-coverageUsage
# 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 70CLI 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)
Here “coverage” specifically means the share of exported DS components imported at least once (for example, 34 of 39 exports = 87%) plus name-collision detection, not a standalone grade of UI quality.
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 @andrewaitken/ds-coverage src/ --ds @acme/ui --inventory components.json --min 60
# Generate PR report
- name: DS Coverage Report
run: npx @andrewaitken/ds-coverage src/ --ds @acme/ui --format markdown --out coverage.md--min exits with code 1 when coverage is below the threshold.