Web tool
ds-health
Paste a URL, get a design system health report. Analyzes colors, typography, spacing, and radius on any live website using a real browser.
What It Measures
- ColorsHow many text and background colors exist. Rewards fewer unique values and CSS variable usage.
- TypographyFont families, sizes, and weights in visible text. Fewer means more controlled.
- SpacingHow many distinct padding and gap values appear. Converging to a scale is ideal.
- RadiusDistinct non-zero border-radius values. Fewer = more consistent corners.
Run Locally
git clone https://github.com/AndrewAntoshkin/ds-health.git
cd ds-health
npm install
npm startOpen http://localhost:3000. If the port is busy:
PORT=3002 npm startIf Playwright can't find a browser:
npx playwright install chromiumHow It Works
The tool loads the page in a real Chromium browser (via Playwright), samples visible elements, reads their computed styles, and generates a health report with scores, signals, and recommendations.
URL → Playwright (Chromium) → getComputedStyle() on sampled elements
→ Count unique colors, fonts, spacing, radii
→ Score each category (0–100)
→ Generate executive summary + priorities + recommendationsAPI
POST /api/analyze
curl -X POST http://localhost:3000/api/analyze \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'Request
| Field | Type | Description |
|---|---|---|
| url | string | Public HTTP/HTTPS URL to analyze |
Response
| Field | Type | Description |
|---|---|---|
| health.overall | number | 0–100 average score |
| health.color | number | Color consistency score |
| health.typography | number | Typography consistency score |
| health.spacing | number | Spacing consistency score |
| health.radius | number | Radius consistency score |
| health.label | string | "Healthy", "Mostly consistent", etc. |
| executiveSummary | string | Plain-English interpretation |
| priorities | array | What to fix first |
| recommendations | array | Actionable next steps |
| signals | array | Individual observations |
| topValues | object | Most common values per category |
GET /health
Returns { "ok": true } — use for uptime checks.
Healthy Site Example
Result from analyzing barvian.me — a disciplined, minimalist site:
| Score | Meaning |
|---|---|
| 100 | Color |
| 100 | Typography |
| 100 | Spacing |
| 100 | Radius |
{
"elementsSampled": 69,
"textNodesSampled": 41,
"cssVariables": 4,
"textColors": 3,
"backgroundColors": 3,
"fontFamilies": 1,
"fontSizes": 1,
"fontWeights": 2,
"spacingValues": 4,
"radiusValues": 1
}
Executive summary:
"This page looks healthy. 4 CSS variables were
detected, and no major consistency issues stood
out in the sampled page."Fragmented Site Example
A page with many competing values — typical of legacy UIs or rapid prototyping:
| Score | Meaning |
|---|---|
| 65 | Color |
| 45 | Typography |
| 70 | Spacing |
| 90 | Radius |
Priority issues:
⚠ 14 text colors detected — consider consolidating
⚠ 4 font families in use — reduce to 1–2
⚠ 8 font sizes found — align to a type scale
⚠ No CSS variables detected — consider tokenizing
Recommendations:
→ Audit text colors and create a semantic palette
→ Standardize on 1–2 font families
→ Define a spacing scale (4, 8, 12, 16, 24, 32)
→ Introduce CSS custom properties for tokensReading Reports
The most useful pattern: score first, then summary, then priorities, then supporting values.
| Section | What it tells you |
|---|---|
| Overall health | Average of 4 category scores — quick pass/fail signal |
| Executive summary | Plain-English conclusion for stakeholders |
| Priority issues | What's worth fixing first — biggest impact items |
| Recommendations | Practical cleanup steps you can assign to a sprint |
| Signals | Individual observations — raw evidence behind the score |
| Top values | Most common colors/sizes/spacing — where consolidation helps most |
| Normalized groups | Near-identical values collapsed into cleaner buckets |
Score Guide
| Range | Label | Meaning |
|---|---|---|
| 90–100 | Healthy | Tightly controlled — few colors, restrained typography, small spacing set |
| 70–89 | Mostly consistent | Some fragmentation or a few one-off values |
| 50–69 | Needs attention | Visual system may be drifting — needs a closer look |
| 0–49 | Fragmented | Too many competing values — likely no token layer |
Pipeline
ds-health checks the live page after the model loop, when the UI is already in production:
ds-context prepares the pack
ds-eval scores generated UI
ds-health reads the live page ← you are here