How is design system health measured?

Buoy scores it from 0 to 100 across four pillars: value discipline (60 points, hardcoded values per component), token health (20, whether a token system exists and its tokens are used), consistency (10, naming conflicts) and critical issues (10, color contrast failures, accessibility conflicts and deprecated patterns).

What is a good design system health score?

80 or more reads as mostly tokenized, 60–79 largely tokenized, 40–59 partly tokenized, 20–39 often hardcoded and under 20 mostly hardcoded. The labels describe the code, not the team. Across 20 well-known open-source codebases the median is 90, and 14 score 80 or more.

What does it take to score 100?

Almost no hardcoded design values per component, a token system whose tokens are used, no naming conflicts, and no critical findings. Every Buoy report lists its path to 100: the points each pillar is missing and the change that earns them back.

Does using Tailwind or a component library raise the score?

Tailwind's theme counts as a token system, and so do your own CSS variables or tokens file, but adding dependencies earns nothing by itself. A plain-CSS codebase with a complete token set can score 100.

Which values does the score ignore?

Icons and logos, email templates, Open Graph images, tests and stories, example and demo apps, layout math such as calc() and 100dvh, 1px hairlines, vendored shadcn/ui templates, and values the code marks as deliberate with a comment, a 2–3px optical nudge or its commit message.

How to measure design system health

Updated 2026-10-26 · Buoy

Short answer

Count how often the code bypasses the design system per component, check that a token system exists and its tokens are used, and add naming conflicts and accessibility failures. Buoy combines these into a 0–100 score where hardcoded values per component carry 60 of the points; the median across 20 well-known open-source codebases is 90.

Design system adoption is usually measured in design tools: how many components are used, how many files are detached. That misses what ships. A code-level health score measures how much of the product's UI actually goes through the system.

The four pillars

Pillar	Points	What it measures
Value discipline	60	Hardcoded colors, spacing, font sizes, radii and shadows per component. Every finding costs a little; about one per three components empties the pillar.
Token health	20	Half for having a token system (your own tokens, full credit at 20, or Tailwind's theme), half for tokens actually being used rather than left stale.
Consistency	10	Naming and semantic conflicts, for example two components named for the same role with different APIs.
Critical issues	10	Color contrast failures between text and background on the same element, accessibility conflicts and deprecated patterns.

Labels: 80–100 mostly tokenized, 60–79 largely tokenized, 40–59 partly tokenized, 20–39 often hardcoded, under 20 mostly hardcoded. They describe how much of the UI goes through tokens, not the quality of the product or the team. (The CLI prints Great, Good, OK, Bad and Terrible for the same bands.)

Why density, not totals

A large product has more code, so it has more literals. Counting findings per component keeps a 4,000-component monorepo comparable with a 300-component app. Earlier versions of the score capped every large codebase at the same number; density fixed that.

What does not count

The score only counts design decisions that should have used a token. It skips icons and logos, email templates, social images, tests, stories, example and demo apps, layout math, hairlines, vendored shadcn/ui templates, and values the code marks as deliberate. In the public reports, 307 values were left alone for that last reason alone.

The path to 100

Every report lists what stands between its score and 100, for example "Replace the hardcoded values in all 15 findings with tokens or scale steps (+8)". Run it on your own code:

npx @buoy-design/cli show health

Real scores

20 well-known open-source codebases, scanned with the same CLI: median 90, range 38–99. The highest right now:

All of them are on the reports page, and any public repository can be scored at buoy.design/scan.

Scan a repository now

Paste a public GitHub URL and get a design health report in under a minute: score, the hardcoded values to fix first, and the path to 100.

Frequently asked questions

How is design system health measured?: Buoy scores it from 0 to 100 across four pillars: value discipline (60 points, hardcoded values per component), token health (20, whether a token system exists and its tokens are used), consistency (10, naming conflicts) and critical issues (10, color contrast failures, accessibility conflicts and deprecated patterns).
What is a good design system health score?: 80 or more reads as mostly tokenized, 60–79 largely tokenized, 40–59 partly tokenized, 20–39 often hardcoded and under 20 mostly hardcoded. The labels describe the code, not the team. Across 20 well-known open-source codebases the median is 90, and 14 score 80 or more.
What does it take to score 100?: Almost no hardcoded design values per component, a token system whose tokens are used, no naming conflicts, and no critical findings. Every Buoy report lists its path to 100: the points each pillar is missing and the change that earns them back.
Does using Tailwind or a component library raise the score?: Tailwind's theme counts as a token system, and so do your own CSS variables or tokens file, but adding dependencies earns nothing by itself. A plain-CSS codebase with a complete token set can score 100.
Which values does the score ignore?: Icons and logos, email templates, Open Graph images, tests and stories, example and demo apps, layout math such as calc() and 100dvh, 1px hairlines, vendored shadcn/ui templates, and values the code marks as deliberate with a comment, a 2–3px optical nudge or its commit message.