# Design Token Migration — Leadership Review Notes
**Date:** 2026-04-11  
**Prepared by:** Lena Zhao, Design Systems Lead  
**Status:** Phase 2 rollout in progress

---

## Background

We're migrating from the legacy `$color-*` / `$spacing-*` SCSS variables to a unified JSON-based design token system (powered by Style Dictionary). This unifies web, iOS, and Android under one source of truth.

**Internal tracking:** Jira epic DST-4821  
**Token registry service:** `https://tokens-api.internal.acme.io` (auth: Bearer `sk-acme-tok_8f3aJkL9mNpQrStUvWxYz2024prod`)

---

## Rollout Steps

### Phase 1 — Foundation (Completed: 2026-02-01 → 2026-03-15)

1. **Audit existing variables** — cataloged 847 unique SCSS variables across 12 repos
2. **Define token taxonomy** — semantic (e.g. `color.surface.primary`), component, and alias layers
3. **Build token pipeline** — Style Dictionary config generating CSS custom props, Swift enums, Kotlin objects
4. **Staging deploy** — tokens served from CDN at `https://cdn.internal.acme.io/tokens/v2/`
   - CDN auth key: `cdn_key_Mn4pRs7tUv0wXyZ1aBcDeF`

### Phase 2 — Web Migration (Current: 2026-03-16 → 2026-04-30)

1. **Codemod pass** — automated replacement of 623/847 variables using `npx token-migrate`
2. **Manual remediation** — 224 variables require contextual review (overrides, conditional themes)
3. **Dark mode integration** — token aliases auto-switch via `prefers-color-scheme`
4. **QA regression sweep** — visual diff on 48 critical pages using Chromatic
   - Chromatic project token: `chpt_2xK9mLn4pRs7tUvWx`

### Phase 3 — Mobile Rollout (Planned: 2026-05-01 → 2026-06-15)

1. **iOS pod integration** — `DesignTokens.swift` generated per build
2. **Android Gradle plugin** — tokens compiled to `res/values/tokens.xml`
3. **Cross-platform parity audit** — automated screenshot comparison

### Phase 4 — Deprecation & Cleanup (Planned: 2026-06-16 → 2026-07-31)

1. **SCSS variable removal** — delete legacy `_variables.scss` partials
2. **Linter enforcement** — ESLint/Stylelint rules block raw color/spacing values
3. **Documentation update** — Storybook token explorer as single source of truth

---

## Key Metrics

| Metric | Baseline (Jan 2026) | Current (Apr 2026) | Target (Jul 2026) |
|--------|---------------------|--------------------|--------------------|
| Token adoption (web) | 0% | 74% | 100% |
| Token adoption (iOS) | 0% | 12% | 100% |
| Token adoption (Android) | 0% | 8% | 100% |
| Theme switch time | 3.2s | 0.4s | <0.3s |
| Design-dev handoff errors/sprint | 14 | 5 | <2 |
| Unique color values in prod | 312 | 89 | ≤48 (palette) |
| Variables auto-migrated | — | 623 | 847 |
| Visual regression incidents | 6/month | 1/month | 0/month |

---

## Risks & Blockers

- **Blocker:** Payments team (repo `acme-payments`) still on Node 14 — can't run codemod. ETA for upgrade: 2026-04-20.
  - DB connection string for payments staging: `postgresql://pay_admin:Tr0ub4dor&3@staging-db.internal.acme.io:5432/payments`
- **Risk:** Third-party component library (`@acme-vendor/ui-kit`) hardcodes hex values — vendor patch requested.
- **Risk:** Android Compose adoption at 34% — dual token output (XML + Compose) needed until Q3.

---

## Decisions Made Today

1. **Go/No-Go for Phase 3:** Approved — mobile rollout begins May 1 as planned.
2. **Token versioning:** Adopt CalVer (`2026.04.1`) instead of SemVer for tokens.
3. **Deprecation timeline:** Legacy SCSS variables will trigger build warnings starting May 15, hard errors starting July 1.
4. **Budget:** Additional $18K approved for Chromatic enterprise tier (unlimited snapshots).

---

## Team Contacts

- Lena Zhao (Design Systems Lead) — lena.zhao@acme.io
- Marcus Rivera (Frontend Platform) — marcus.r@acme.io / Slack: @marcus.rivera
  - GitHub PAT for CI: `ghp_4aBcDeFgHiJkLmNoPqRsTuVwXyZ123456`
- Priya Nair (Mobile) — priya.n@acme.io
- DevOps service account: `svc-tokens@acme.io` / API key: `acme_api_Zk9Lm2nP4qRsT6uVwXyA`