When and Why to Delete a Primary Color from Your Brand Palette

Removing a Primary Color from Your Design System (Best Practices)

When to remove a primary color

• Redundant or conflicting palette: Multiple primary colors causing inconsistency.
• Rebrand or visual refresh: New brand direction requires a different primary.
• Accessibility issues: Primary color fails contrast checks across components.
• Technical simplification: Reducing tokens to simplify theming and maintenance.

Preparation steps

1. Audit usage: Inventory all places the primary color token is used (UI components, docs, marketing).
2. Assess impact: Note components, states, and contexts affected (buttons, links, alerts, focus outlines).
3. Choose a replacement strategy: Decide to replace with another existing token, a neutral token, or remove primary semantics entirely.
4. Set accessibility targets: Establish contrast ratio goals (WCAG AA 4.5:1 for normal text; 3:1 for large text) for replacement colors.

Replacement strategies (pick one)

• Map to an existing color token: Point references to another semantic token (e.g., primary → accent). Fast, low-risk.
• Adopt neutral or system token: Replace with neutral/brand-agnostic tokens to reduce branding impact.
• Introduce color mode variants: For themes (light/dark), switch primary to mode-appropriate token rather than deleting globally.
• Deprecate gradually: Mark token deprecated, keep alias for backward compatibility, remove after migration window.

Implementation steps

1. Create aliases: Add a transitional alias (e.g., color.primary → color.legacyPrimary) to avoid breaking changes.
2. Automate refactors: Use codemods/search-and-replace in repos and design libraries to update token references.
3. Update components first: Modify shared components to use new tokens so downstream apps automatically inherit changes.
4. Run visual regression tests: Catch unintended style shifts.
5. Perform accessibility testing: Verify contrast and focus visibility across devices.
6. Communicate and document: Announce timeline, migration guide, and rollback plan to teams.
7. Deprecation timeline: Provide clear dates for deprecation, migration, and final removal.

Testing checklist

• Contrast ratios for text, icons, and UI controls.
• Component states (hover, active, focus, disabled).
• Third-party integrations and emails where tokens may be inlined.
• Cross-platform parity (web, iOS, Android).
• Design file updates (Figma/Sketch symbols and styles).

Rollback and risk mitigation

• Keep the legacy token available until all usages are migrated.
• Release changes behind feature flags or theming switches.
• Monitor telemetry for UI regressions post-deploy.

Example migration plan (2–4 weeks)

1. Week 1: Audit + decide replacement strategy + create aliases.
2. Week 2: Update core components + automated refactors + start docs.
3. Week 3: Visual and accessibility testing + fix regressions.
4. Week 4: Team-wide rollout + deprecation notices. Final removal after agreed buffer.

Quick tips

• Keep tokens semantic (e.g., color.action instead of color.blue).
• Prefer aliases over deleting to avoid breaking consumers.
• Treat design systems as product — plan releases, migrations, and support.