# How to run a design system audit on any website > A design system audit measures how consistently a product uses its own tokens; with designlang you run `designlang score ` for a 0 to 100 quality score, `designlang debt ` for token coverage and a ranked consolidation plan, and `designlang check` to find off-system values in your code. Updated 2026-11-03. Page: https://designlang.app/guides/design-system-audit ## Steps 1. **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. 2. **Measure design debt.** Run npx designlang debt yoursite.com for token coverage by category, hotspots and a ranked consolidation plan. 3. **Check accessibility.** Open the accessibility section of the design-language report, or run npx designlang robustness yoursite.com for WCAG 2.2 checks. 4. **Lint the codebase.** Run npx designlang check src --tokens tokens.json to find hardcoded and off-scale values in source. 5. **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.com ``` The 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 declarations ``` The 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 +1 ``` This 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 ` 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 github ``` The [GitHub Action](https://designlang.app/docs/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 5` or `designlang site` for 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. ## Questions ### What is a good design system score? There is no universal bar. Use the first score as a baseline and track the direction. The categories matter more than the total: a 100 on spacing and a 60 on colour tells you where to work. ### How is design debt different from the score? The score rates the consistency of the values a page shows. Debt measures how much of the CSS uses tokens instead of hardcoded values, and ranks the fixes by how much they would help. ### Can I audit a site I do not own? Yes. Reading a public page is the same as visiting it. It is a useful way to benchmark against competitors. ## Related - [Design Debt](https://designlang.app/features/design-debt) - [GitHub Action docs](https://designlang.app/docs/github-action) - [Make Cursor and Claude follow your design system](https://designlang.app/guides/cursor-claude-design-system-mcp) - [Stripe design system](https://designlang.app/design-system/stripe)