Design Token Migrations Definition of "done"

Problem Statement

As a team, we are working on the Design Tokens > Migrate Colors to Use Design Tokens epic (&15844), and are currently finding it difficult to balance competing goals, such as:

• Ensuring ease of review versus Pajamas compliance.
• Deciding when to fix issues immediately, create follow-up tasks, or defer action.

The goal of this issue and discussion is to agree on a shared understanding of what constitutes "done" at each phase in this project.

Definition of Phases of this Migration Project

Phase 1: Mass Migration of Deprecated Colors

Goal:

Replace deprecated color classes (e.g., gl-text-green-500) with generic semantic design tokens (e.g., gl-text-success).

Focus:

Large-scale, 1-to-1 replacements to efficiently reduce deprecated color usage.

What We Will Actually Do:

• Perform mass migrations for "easy" and straightforward replacements.
• If something looks weird or complicated, skip it for now—the priority is tackling low-hanging fruit.
• Use follow-up issues to capture skipped or complex cases for later.

How We Will Achieve This:

• Find-and-Replace:
  Replace deprecated classes with modern classes that have the same value (e.g., gl-text-green-500 → gl-text-success).
  Straightforward 1-to-1 migrations are acceptable.

• Fix Immediately:
  When the deprecated class is used incorrectly.
  Example: Replace gl-text on an icon with gl-fill-icon.

• Create Follow-Up Issues:
  When a broader migration is identified.
  Examples:

  • Migrate all gl-icon components to use variants instead of classes.
  • Update gl-button components to use variants for consistent styling.

• Ignore for Now:
  When the class usage is correct but introduces a minor code smell.
  Example: Text using the color --gl-color-neutral-400 or gray-400 should be migrated to gl-text-disabled, as they have the same value exactly.
  At this phase, we will not evaluate whether the text is truly "disabled" or if a more meaningful semantic token (e.g., "subtle") would be appropriate. This refinement will be addressed in the next phase.

---

Phase 2: Page-by-Page Semantic Compliance

Goal:

Ensure compliance and adoption of Pajamas Design System values, for example, using gl-text-disabled only for disabled fields (instead of as a 'tertiary' color).

Focus:

Page-specific audits for ensuring adoption and compliance.

What We Will Actually Do:

• Conduct page-by-page audits, working team by team with their design or frontend engineers.
• Ensure critical pages are compliant (e.g., for dark mode), but teams are responsible for their own compliance.
• Help teams understand what needs to change in order for their pages to be compliant. For example, create issues for them.

How We Will Achieve This:

• Focus on Bad Code Smells:
  Address issues like incorrect use of colors systematically, page by page, with the team.
  Example: If gl-text-disabled was applied in Phase 1 because it matched the previous color value, we will now evaluate whether this usage is semantically appropriate. For example:

  • If the text represents disabled functionality, keep gl-text-disabled.
  • If the text is meant to indicate a subtle, secondary style, update it to gl-text-subtle or another appropriate semantic token.

• Refine to Meaningful Tokens:
  Align generic tokens (e.g., gl-text-disabled) with meaningful semantics (e.g., status.success.text.color).
  Example: Use contextual understanding to determine whether a token should represent "disabled," "subtle," or another variant. This step ensures that design tokens reflect their intended semantics rather than merely matching colors.

• Collaborate for Granularity:
  Work with teams to clean up their pages while leaving them responsible for overall compliance.
  Example: Provide guidance on token choices and create follow-up issues for cases where a team needs additional support.