design-system-metrics

Design system migration reporting for MetaMask.

Primary outputs:

• Dashboard (historical trends and latest status)
• Slack report (weekly update summary)

This repository is an internal reporting pipeline.

Getting Started

• Primary Product Features
• Project Architecture
• Maintainer Workflow
• Dashboard
• Slack Report
• Data Outputs
• Configuration
• Requirements

---

Primary Product Features

1) Dashboard

A React dashboard (dashboard/) that visualizes migration progress over time for Mobile and Extension using generated JSON in metrics/.

Current dashboard scope includes:

• Latest migration KPIs
• 6-month trend charts
• MMDS vs deprecated instance trends
• MMDS component availability and new-component deltas
• Code owner adoption charts

2) Slack Report

A generated weekly markdown report used for stakeholder updates.

It summarizes:

• MMDS component availability
• Migration progress by project
• Week-over-week changes
• Links to detailed artifacts

---

Project Architecture

This repository tracks migration from legacy components to MMDS across:

• repos/metamask-extension
• repos/metamask-mobile

With MMDS component definitions sourced from:

• repos/metamask-design-system

Core implementation files:

• index.js: canonical scanner + generator (.xlsx, -summary.json, -data.json)
• config.json: tracked component mappings
• scripts/sync-config.js: updates config.json from submodules
• scripts/update-timeline.js: rebuilds metrics/timeline.json + metrics/index.json
• scripts/validate-metrics-consistency.js: consistency checks across generated artifacts
• scripts/generate-slack-report.js: weekly Slack markdown output

---

Maintainer Workflow

Use this sequence locally to match CI behavior:

yarn install
yarn setup-repos

yarn sync-config
yarn start
yarn start:mobile

yarn update-timeline
yarn validate-metrics

yarn slack-report --output metrics/slack-report-YYYY-MM-DD.md

cp metrics/*.json dashboard/public/metrics/
cd dashboard && npm ci && npm run build

Historical date override (backfills):

METRICS_DATE=2026-03-04 yarn start
METRICS_DATE=2026-03-04 yarn start:mobile

CI workflows:

• .github/workflows/weekly-metrics.yml
  • runs Fridays 16:00 UTC (~8am Pacific standard / ~9am Pacific daylight) and manually; opens a PR to main (org rules require changes via PR)
  • updates submodules/config, regenerates metrics, updates timeline/index, validates data, generates Slack output, and rebuilds dashboard assets
• .github/workflows/deploy-dashboard.yml
  • deploys dashboard to GitHub Pages when dashboard or metrics JSON changes on main (merge the weekly metrics PR to publish)

---

Dashboard

Location:

• Source: dashboard/src/*
• Data input: dashboard/public/metrics/*

Run locally:

cp metrics/*.json dashboard/public/metrics/
cd dashboard
npm ci
npm run dev

Production build:

cd dashboard
npm run build

---

Slack Report

Generate:

yarn slack-report
yarn slack-report --output metrics/slack-report-YYYY-MM-DD.md

The script reads the latest files via metrics/index.json and related *-summary.json data.

---

Data Outputs

Generated in metrics/:

• extension-component-metrics-YYYY-MM-DD.xlsx
• mobile-component-metrics-YYYY-MM-DD.xlsx
• extension-component-metrics-YYYY-MM-DD-summary.json
• mobile-component-metrics-YYYY-MM-DD-summary.json
• extension-component-metrics-YYYY-MM-DD-data.json
• mobile-component-metrics-YYYY-MM-DD-data.json
• timeline.json
• index.json
• slack-report-YYYY-MM-DD.md

Notes:

• index.js is the canonical generator for XLSX + summary/data JSON.
• scripts/xlsx-to-json.js is retained mainly for repair/backfill workflows.

---

Configuration

The tool uses config.json project entries with:

• filePattern, ignoreFolders, outputFile
• currentPackages, currentComponents
• codeOwnerMetricIgnoreGlobs (optional): array of globs to exclude from code owner adoption metrics only (does not affect overall component counts). Useful for ignoring legacy or soon-to-be-deprecated areas from team adoption charts.
• deprecatedComponents mappings:
  • paths: import paths to match
  • replacement: MMDS target or null

Keep config in sync with codebases:

yarn sync-config
yarn sync-config:dry-run
yarn sync-config:skip-update

Manual overrides are preserved when _autoGenerated: false is set on a component entry.

---

Requirements

• Node.js 20+ recommended (CI uses Node 20)
• Yarn 4.x for root scripts
• npm for dashboard scripts (dashboard/package.json)

---

Contributing

If you change generation logic or data contracts:

1. Regenerate outputs (yarn start, yarn start:mobile)
2. Rebuild timeline/index (yarn update-timeline)
3. Validate consistency (yarn validate-metrics)
4. Rebuild dashboard (cd dashboard && npm run build)

---

License

This project is licensed under the MIT License.