Measure design system adoption scientifically — component usage tracking, codebase scanning, ROI calculation, and dashboards that make the design system's value visible to leadership.
Measure design system adoption scientifically — component usage tracking, codebase scanning, ROI calculation, and dashboards that make the design system's value visible to leadership.
Manual adoption tracking is impossible at scale. Automate it with AST-based scanning across all product repositories using the GitHub API:
1// scripts/adoption-scanner.ts
2import { Octokit } from '@octokit/rest';
3import { execSync } from 'child_process';
4import { glob } from 'glob';
5
6const DS_IMPORT = /@acme\/(react|tokens|icons)/;
7
8async function scanRepository(owner: string, repo: string) {
9 const files = await glob('**/*.{tsx,ts}', {
10 cwd: `/tmp/${repo}`,
11 ignore: ['node_modules/**', 'dist/**'],
12 });
13
14 const stats = {
15 totalComponents: 0,
16 dsComponents: 0,
17 customComponents: 0,
18 dsImports: new Set<string>(),
19 };
20
21 for (const file of files) {
22 const content = readFileSync(join(`/tmp/${repo}`, file), 'utf8');
23 if (DS_IMPORT.test(content)) {
24 // Parse imports to count DS component usage
25 const imports = parseImports(content);
26 imports.forEach(imp => stats.dsImports.add(imp));
27 }
28 }
29
30 return {
31 repo,
32 adoptionRate: stats.dsComponents / stats.totalComponents,
33 uniqueComponentsUsed: stats.dsImports.size,
34 };
35}Run this scan weekly via GitHub Actions scheduled workflow. Store results in a database and serve them in a Retool or Grafana dashboard. Track trends over time to identify repos that are improving adoption versus regressing.
Component adoption tells only part of the story — teams can import Button from the design system but override its styles with custom CSS, defeating the purpose. Measure token adoption separately:
1# Count CSS custom property usage vs hardcoded values
2# Run across all product stylesheets
3
4# Script: scripts/token-divergence.sh
5#!/bin/bash
6DIR=${1:-src}
7
8# Count uses of design tokens
9TOKEN_USES=$(grep -r 'var(--color\|var(--space\|var(--radius' $DIR \
10 --include='*.css' --include='*.scss' | wc -l)
11
12# Count hardcoded color values (likely divergences)
13HARDCODED=$(grep -rE '#[0-9a-fA-F]{3,6}|rgb\(|hsl\(' $DIR \
14 --include='*.css' --include='*.scss' | wc -l)
15
16echo "Token usage: $TOKEN_USES"
17echo "Hardcoded values: $HARDCODED"
18echo "Token ratio: $(echo "scale=2; $TOKEN_USES / ($TOKEN_USES + $HARDCODED) * 100" | bc)%"Target 90%+ token usage ratio. Repos below 70% need a dedicated token migration sprint. Track this metric per repository and include it in the quarterly design system health report sent to engineering leads.
Leadership wants to know if design system investment is paying off. Quantify value in engineering time and quality metrics:
Time savings calculation:
Quality savings calculation:
Total quarterly ROI: $137,250 against design system team cost of ~$90,000/quarter = 52% ROI.
Present this in a one-page executive summary with a trend graph. Update quarterly. Even conservative assumptions produce compelling ROI numbers that justify design system investment.
Translate technical metrics into business language for executive visibility. A design system dashboard should show four metrics that non-engineers understand:
Build this in Retool, Observable, or a custom Next.js page that pulls from your scanning database. Schedule a monthly automated report sent to VP Engineering and VP Design. Include a "Design System ROI this quarter" number on the first line — that is the metric that protects headcount during budget seasons.
Optional telemetry in your design system npm package can track real-world component usage patterns — which props are used, which variants are popular — to inform roadmap decisions:
1// packages/react/src/telemetry.ts
2// IMPORTANT: Telemetry is opt-in only, anonymized, and GDPR-compliant
3export function trackComponentUsage(
4 componentName: string,
5 props: Record<string, unknown>
6) {
7 // Check opt-in environment variable
8 if (process.env.DS_TELEMETRY !== 'true') return;
9 if (typeof window === 'undefined') return; // Server-side: skip
10
11 // Send only prop names (no values) to avoid PII leakage
12 const propNames = Object.keys(props).filter(k => props[k] !== undefined);
13
14 // Batch and send to your analytics endpoint
15 requestIdleCallback(() => {
16 navigator.sendBeacon(
17 'https://telemetry.ds.acme.com/usage',
18 JSON.stringify({
19 component: componentName,
20 propsUsed: propNames,
21 // No user identifiers, no prop values, no session tracking
22 })
23 );
24 });
25}Publish a clear telemetry data policy in your design system docs. Consent at the application level (NEXT_PUBLIC_DS_TELEMETRY=true in a team's .env) ensures teams opt in consciously. Never track by default.
Write a script that scans your largest product repository for design system component imports and calculates the current adoption rate. Run it, then set a quarterly target for improvement and share the baseline with your team.
Your progress is saved in this browser, on this device only.