25 days ago•

Dark mode migration playbook with token mapping

Views

6.4K

Copies

960

Likes

1.1K

Comments

Copy rate

15.0%

Prompt

You are a senior design systems engineer leading a migration of a [product_type] from a single-theme design system to full dark and light mode support.

The current codebase uses hardcoded hex values throughout components. We need to migrate to a CSS variable token system that auto-switches based on the [theme_strategy] approach (class-based, media query, or hybrid).

Deliver a complete migration playbook that includes:

1. A semantic token taxonomy (surface, content, border, interactive, status) with naming conventions
2. A hex-to-token mapping table for every common UI color pattern
3. The order of operations for migrating a large codebase without regressions
4. Edge cases: images, shadows, illustrations, brand colors that stay fixed across themes
5. QA strategy including automated contrast checking and visual regression
6. A rollout plan for teams currently shipping to production

Be specific about tradeoffs, pitfalls, and the common mistakes teams make when they first attempt this.

Customise this prompt

Fill in 2 variables to personalise this prompt

Product Type

Theme Strategy

Preview

You are a senior design systems engineer leading a migration of a [product_type] from a single-theme design system to full dark and light mode support. The current codebase uses hardcoded hex values throughout components. We need to migrate to a CSS variable token system that auto-switches based on the [theme_strategy] approach (class-based, media query, or hybrid). Deliver a complete migration playbook that includes: 1. A semantic token taxonomy (surface, content, border, interactive, status) with naming conventions 2. A hex-to-token mapping table for every common UI color pattern 3. The order of operations for migrating a large codebase without regressions 4. Edge cases: images, shadows, illustrations, brand colors that stay fixed across themes 5. QA strategy including automated contrast checking and visual regression 6. A rollout plan for teams currently shipping to production Be specific about tradeoffs, pitfalls, and the common mistakes teams make when they first attempt this.

Example output

# Dark Mode Migration Playbook — B2B Analytics SaaS ## Why Most Migrations Fail Teams almost always make the same mistake: they start by inverting colors. They swap #FFFFFF for #000000 and call it done. Two weeks later the design is inconsistent, accessibility is broken, and the team is re-doing the whole thing. Dark mode is a token problem, not a color problem. Solve the tokens and the themes follow. ## 1. Semantic Token Taxonomy Your tokens should describe **purpose**, not appearance. A token named "gray-900" only works in light mode. A token named "content-primary" works in both. **Surface layer** — backgrounds and elevated planes: - surface-base (page background) - surface-elevated (cards, modals) - surface-overlay (popovers, dropdowns) - surface-inverse (for tooltips that contrast the page) **Content layer** — text and icons: - content-primary (headings, body) - content-secondary (supporting copy) - content-tertiary (hints, timestamps) - content-disabled (greyed-out states) **Border layer**: - border-subtle (dividers, card edges) - border-default (input borders) - border-strong (emphasized separators) - border-focus (focus rings — usually brand-tinted) **Interactive layer** — buttons, links, toggles: - interactive-primary, interactive-primary-hover, interactive-primary-active - interactive-secondary, interactive-ghost **Status layer** — feedback: - status-success, status-warning, status-danger, status-info, each with bg/border/content variants ## 2. Hex-to-Token Mapping Typical light-mode mapping: - #FFFFFF → surface-base - #F9FAFB → surface-elevated - #E5E7EB → border-subtle - #111827 → content-primary - #6B7280 → content-secondary Then the dark mode values for those same tokens become: - surface-base → #0B0B0F - surface-elevated → #15151C - border-subtle → rgba(255,255,255,0.06) - content-primary → #F4F4F5 - content-secondary → #A1A1AA Do the mapping in a spreadsheet first. Every hex in the codebase must land in exactly one bucket. ## 3. Order of Operations 1. Audit every hex in the repo with a regex sweep. Count occurrences. 2. Build the token file and ship it as inert CSS variables nobody uses yet. 3. Convert the design system primitives first: Button, Input, Card, Modal. 4. Convert shared layout: Nav, Sidebar, Footer. 5. Convert feature surfaces one route at a time behind a feature flag. 6. Only then toggle the theme switcher on for internal users. Do not try to migrate the whole app in one sprint. You will regress things. ## 4. Edge Cases **Images and illustrations** — Vector illustrations must be rebuilt with CSS variables or shipped as two assets (light/dark) via `<picture>`. Photos generally need a subtle overlay in dark mode to reduce glare. **Shadows** — Replace with borders plus a very soft translucent shadow in dark mode. Heavy drop shadows look muddy on dark surfaces. **Brand colors** — Logo, brand accents, and category dots stay identical in both themes. These are NOT themed tokens. **Syntax highlighting** — Code blocks need a separate theme-aware highlighter config. Never reuse the light palette for code in dark mode; the contrast will fail. ## 5. QA Strategy - Automate WCAG AA contrast checks on every token pair via CI. - Run Percy or Chromatic visual regression on both themes for every PR. - Add a keyboard shortcut in dev mode to rapidly toggle themes. - Keep an "unthemed hex" lint rule — CI fails if a PR adds a raw hex. ## 6. Rollout Plan Week 1-2: token system and primitives ship silently behind the flag. Week 3-4: internal dogfooding, collect bugs in a dedicated channel. Week 5: opt-in for users via a "Try dark mode (beta)" switch in settings. Week 6-8: iterate on feedback, fix edge cases. Week 9: default dark mode to system preference for new users. Do not announce dark mode on launch day. Announce it a week later when the issue rate has flattened. The first 72 hours will surface bugs only real users can find.

Prompt

Customise this prompt

Example output

Related prompts