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 MMDS alignment (Figma / React / React Native) plus migration progress over time for Mobile and Extension using generated JSON in metrics/.

Current dashboard scope includes:

• MMDS platform alignment (default)
• 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
• config/alignment-exceptions.json: intentional platform-specific families (Modal/BottomSheet, Popover, helpers)
• scripts/lib/alignment-inventory.js: MMDS package inventory + Code Connect classification
• scripts/discover-alignment.js: writes metrics/alignment-*.json and metrics/alignment-timeline.json

Platform alignment

The Alignment tab measures MMDS itself: whether a component exists on React and React Native with the same name, plus Code Connect coverage. Figma is marked linked when a .figma.tsx file points at a Figma node; otherwise unknown. Unknown is not a gap, and linked is not a live library confirmation.

Default: every component is required on both code platforms. A small exception list in config/alignment-exceptions.json names intentional platform families (Modal vs BottomSheet, Popover) and helpers to exclude. Output: metrics/alignment-latest.json and metrics/alignment-timeline.json.

---

Maintainer Workflow

Use this sequence locally to match CI behavior:

yarn install
yarn setup-repos
yarn pipeline
yarn slack-report --output metrics/slack-report-YYYY-MM-DD.md
cd dashboard && npm ci && npm run build

yarn pipeline runs the full weekly sequence: config sync, extension/mobile scans, one-off discovery, untracked timeline rebuild (adoption trends + per-team replaceable history), MMDS platform alignment inventory, migration timeline/index update, validation, and dashboard metrics copy.

Manual stage breakdown (debugging only):

yarn sync-config
yarn start
yarn start:mobile
yarn discover:extension
yarn discover:mobile
yarn update-untracked-timeline
yarn discover-alignment
yarn update-timeline
yarn validate-metrics
cp metrics/*.json dashboard/public/metrics/

If generating for a historical date, set METRICS_DATE=YYYY-MM-DD when running yarn pipeline (or individual scan/discover steps).

CI workflows:

• .github/workflows/weekly-metrics.yml
  • Fridays 15:00 UTC or manual workflow_dispatch; opens a PR to main (org rules). UK: 16:00 London in BST, 15:00 in GMT. US Pacific ≈ 8:00 PDT / 7:00 PST.
  • 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
• alignment-YYYY-MM-DD.json (+ alignment-latest.json)
• alignment-timeline.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.