Issue number: internal

---

What is the current behavior?

ios and md themes are still using the stepped color variables.

What is the new behavior?

The CSS variable --ion-background-color-step-{number} is no longer recommended for use and has been replaced by a more intuitive and standardized naming convention as part of Ionic's new theming structure. The functionality provided by the old variable has been replaced with a new set of CSS variables that use the same color values but are named: --ion-color-gray-{number}.

This new structure aligns with how other popular design systems and frameworks are setting up their color palettes (e.g., using names like gray, red, blue, followed by a number to denote the shade). Additionally, it follows the proposal agreed upon within the design doc.

• Added gray tokens based on themes and palettes
• Replaced background stepped color variables with gray tokens

The CSS variable --ion-text-color-step-* is being replaced by --ion-color-text-* to adhere to the standardized naming convention for Ionic's new theming structure (--ion-color-*-*). This change aims for greater clarity and consistency within the framework's color palette.

• Added text tokens based on themes and palettes
• Replaced text stepped color variables with text tokens

The original thought was to use only the --ion-color-gray-* variables for all purposes (backgrounds, text, icons, etc.). However, it was quickly determined that text color requirements are not a 1:1 match with the gray steps designed for backgrounds and other elements. Text often requires a different shade to maintain proper contrast and readability across various theme palettes (especially between high contrast and high contrast dark modes). Introducing the dedicated functional variable --ion-color-text-* solves this issue by allowing text color to be defined independently based on the current palette's needs.

Also the --ion-color-step-* variables were removed since they were deprecated in v7.

Does this introduce a breaking change?

• Yes
• No

You simply need to swap the wording of the background stepped variables with the new gray variables. The number suffix remains exactly the same:

Old Variable (Deprecated)	New Variable
--ion-background-color-step-50	--ion-color-gray-50
--ion-background-color-step-900	--ion-color-gray-900

You simply need to swap the wording of the text stepped variables with the new text variables. The number suffix remains exactly the same:

Old Variable (Deprecated)	New Variable
--ion-text-color-step-50	--ion-color-text-50
--ion-text-color-step-900	--ion-color-text-900

Other information

Preview