How to run a design system audit on any website
Updated 3 November 2026. Every command and output on this page is real.
A design system audit measures how consistently a product uses its own tokens; with designlang you run designlang score <url> for a 0 to 100 quality score, designlang debt <url> for token coverage and a ranked consolidation plan, and designlang check to find off-system values in your code.
Steps
- Score the live site. Run npx designlang score yoursite.com for a 0 to 100 score across colour, type, spacing, shadows, radii, accessibility and tokenisation.
- Measure design debt. Run npx designlang debt yoursite.com for token coverage by category, hotspots and a ranked consolidation plan.
- Check accessibility. Open the accessibility section of the design-language report, or run npx designlang robustness yoursite.com for WCAG 2.2 checks.
- Lint the codebase. Run npx designlang check src --tokens tokens.json to find hardcoded and off-scale values in source.
- Gate it in CI. Add designlang debt --fail-under or the Preview Gate GitHub Action so the score cannot slip unnoticed.
A design system audit answers one question: does the product actually use its design system? Most do not, fully. Over time teams add one-off colours, spacing values that are almost on the scale, a third shade of grey, and an !important to win a specificity fight. AI-written code speeds this up, because a model that has not seen your tokens writes new values every time.
A manual audit means screenshots, a spreadsheet and a week. designlang does the counting from the live site in under a minute, so you can spend the time on decisions.
Step 1: score the system
npx designlang score stripe.comThe real result for stripe.com. Captured with designlang 13.3.2 on 3 November 2026.
Design System Score
https://stripe.com
87/100 Grade: B
Color Discipline ████████████████░░░░ 80
Typography ██████████████████░░ 92
Spacing System ████████████████████ 100
Shadows ████████████████████ 100
Border Radii ██████████████████░░ 90
Accessibility ███████████████░░░░░ 75
Tokenization ████████████████████ 100
Strengths:
✓ Consistent typography system
✓ Well-defined spacing scale
✓ Clean elevation system
✓ Consistent border radii
✓ Good CSS variable tokenization
Issues:
! 3 WCAG contrast failures
! 58% of CSS is unused — consider purging
! 7817 duplicate CSS declarationsThe score is a quick read of discipline. Stripe’s spacing and shadows are tight; its weakest area is contrast.
Step 2: measure design debt
The score says how consistent a system looks. designlang debt says how much of the CSS actually uses tokens, and what to fix first:
$ npx designlang debt stripe.com
Design Debt https://stripe.com/ae
Score 72/100 Grade C (97 after the plan)
Breakdown
Token coverage 61
Duplication 72
Specificity 96
Variables 73
Token coverage by category
Colour 71.7% 967/1349 tokenised, 171 distinct hardcoded (129 after merging)
Spacing 62.4% 739/1185 tokenised, 46 distinct hardcoded (29 after merging)
Radius 79.7% 216/271 tokenised, 13 distinct hardcoded (9 after merging)
Type 25.6% 150/585 tokenised, 28 distinct hardcoded (19 after merging)
Hotspots
3 !important, 79 high-specificity selectors (2 with an id), 248 of 915 variables unused
Consolidation plan
1. Use the tokens you already have for 431 hardcoded spacing values +7
2. Use the tokens you already have for 345 hardcoded font sizes +5
3. Use the tokens you already have for 122 hardcoded colours +4
4. Remove 248 unused CSS variables +3
5. Add tokens for 17 repeated colours (96 uses) +1
6. Flatten 79 high-specificity selectors +1This is the useful part of an audit: a ranked list. On stripe.com, type is the least tokenised category at 25.6%, and the top three fixes are all "use the tokens you already have". Nothing new needs designing to gain 16 points.
debt also takes a stylesheet, a folder or a glob, so you can audit your own build output instead of a URL: npx designlang debt dist/**/*.css.
Step 3: check accessibility
Every extraction writes an accessibility section into the design-language report, listing each text and background pair with its contrast ratio. From the stripe.com report:
## Accessibility (WCAG 2.1)
**Overall Score: 75%** — 9 passing, 3 failing color pairs
| Foreground | Background | Ratio | Level | Used On |
|------------|------------|--------|-------|----------|
| #ffffff | #e3ecf7 | 1.19:1 | FAIL | h4 (3x) |
| Foreground | Background | Ratio | Level |
|------------|------------|--------|-------|
| #ffffff | #533afd | 6.19:1 | AA |For a deeper pass, npx designlang robustness <url> simulates colour-vision deficiencies and runs WCAG 2.2 checks for target size, focus visibility and 320px reflow.
Step 4: lint the code
The live site is the result. The cause is in the source. designlang check reads your components and flags hardcoded colours, off-scale spacing and radii, and fonts outside the system, each with the nearest token:
src/Button.tsx
3:73 warn 13px is not on the spacing scale. Nearest is 1px (1px). spacing/off-scale
3:99 warn 6 is not on the radius scale. Nearest is 4px (4px). radius/off-scale
3:115 error "Inter" is not a font in this system. Nearest is "sohne-var". font-family/off-system
1 errors, 3 warnings, 1 info in 1 file(s). 33% on-brand. 2 fixable.Run --fix to apply safe fixes, or --format markdown to paste the findings into an audit document.
Step 5: keep it from slipping
An audit is a snapshot. To hold the line, put a threshold in CI:
# fail the build if design debt drops below 70
npx designlang debt dist --fail-under 70
# fail on hardcoded or off-system values in changed code
npx designlang check src --tokens tokens.json --fail-on error --format githubThe GitHub Action does the same on every preview deploy and comments on the pull request.
Reading the results honestly
- A homepage is a sample. Use
--pages 5ordesignlang sitefor a fuller picture. - Unused CSS figures come from one page load, so CSS used on other pages counts as unused.
- A high score does not mean a good design, only a consistent one.