Getting Started
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
Colors
How many text and background colors exist. Rewards fewer unique values and CSS variable usage.
Typography
Font families, sizes, and weights in visible text. Fewer means more controlled.
Spacing
How many distinct padding and gap values appear. Converging to a scale is ideal.
Radius
Distinct 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 start
Open http://localhost:3000. If the port is busy:
If Playwright can't find a browser:
npx playwright install chromium
How 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 + recommendations
API
POST /api/analyze
curl -X POST http://localhost:3000/api/analyze \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'Request
FieldTypeDescription
urlstringPublic HTTP/HTTPS URL to analyze
Response
FieldTypeDescription
health.overallnumber0–100 average score
health.colornumberColor consistency score
health.typographynumberTypography consistency score
health.spacingnumberSpacing consistency score
health.radiusnumberRadius consistency score
health.labelstring"Healthy", "Mostly consistent", etc.
executiveSummarystringPlain-English interpretation
prioritiesarrayWhat to fix first
recommendationsarrayActionable next steps
signalsarrayIndividual observations
topValuesobjectMost 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:
{
"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:
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 tokens
Reading Reports
The most useful pattern: score first, then summary, then priorities, then supporting values.
SectionWhat it tells you
Overall healthAverage of 4 category scores — quick pass/fail signal
Executive summaryPlain-English conclusion for stakeholders
Priority issuesWhat's worth fixing first — biggest impact items
RecommendationsPractical cleanup steps you can assign to a sprint
SignalsIndividual observations — raw evidence behind the score
Top valuesMost common colors/sizes/spacing — where consolidation helps most
Normalized groupsNear-identical values collapsed into cleaner buckets
Score Guide
RangeLabelMeaning
90–100HealthyTightly controlled — few colors, restrained typography, small spacing set
70–89Mostly consistentSome fragmentation or a few one-off values
50–69Needs attentionVisual system may be drifting — needs a closer look
0–49FragmentedToo many competing values — likely no token layer
Pipeline
Use ds-health as the verification step in your design system workflow: