feat(tokens): add gray and text colors by thetaPC · Pull Request #30799 · ionic-team/ionic-framework

thetaPC · 2025-11-19T21:07:31Z

Issue number: internal

What is the current behavior?

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.

Does this introduce a breaking change?

Yes
No

You simply need to swap the text of the background stepped variables with the 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-background-color-step-900`

Unlike the migration for background colors, the number suffix for text colors is not a direct swap. Due to the inverse nature required for contrast, the new text variable number is calculated by subtracting the old number from 1000.

Old Variable (Deprecated)	Calculation	New Variable
`--ion-text-color-step-50`	`1000−50`	`--ion-color-text-950`
`--ion-text-color-step-900`	`1000-900`	`--ion-color-text-100`

Other information

vercel · 2025-11-19T21:07:36Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Jan 20, 2026 6:19pm

thetaPC · 2025-11-26T01:00:22Z

core/src/themes/base/dark.tokens.primitives.ts

+// TODO: ADD TYPE
+export const darkPrimitiveColors = {
+  // TODO: Update hex values to use the text color variable and background color variable
+  gray: generateColorSteps('#ffffff', '#000', true),


I decided to use white and black for the base because base should be as simple as possible.

thetaPC · 2025-11-26T01:02:26Z

core/src/themes/base/default.tokens.primitives.ts

+// TODO: ADD TYPE
+export const defaultPrimitiveColors = {
+  // TODO: Update hex values to use the text color variable and background color variable
+  gray: generateColorSteps('#fff', '#000'),


I decided to use white and black for the base because base should be as simple as possible.

… into FW-6751

thetaPC · 2026-01-20T16:10:52Z

core/src/components/radio-group/test/validation/index.html

        font-size: 12px;
        font-weight: normal;

-        color: var(--ion-color-step-600);


This wasn't being used.

thetaPC · 2026-01-20T16:11:12Z

core/src/components/select/test/validation/index.html

        font-size: 12px;
        font-weight: normal;

-        color: var(--ion-color-step-600);


It's not being used.

thetaPC · 2026-01-20T18:04:05Z

core/src/components/breadcrumb/breadcrumb.ios.vars.scss


 /// @prop - Color of the breadcrumb
-$breadcrumb-ios-color: var(--ion-color-step-850, var(--ion-text-color-step-150, #2d4665));
+$breadcrumb-ios-color: var(--ion-components-ion-breadcrumb-color);


Any variable that uses --ion-components-ion-COMPONENT-NAME-* will be updated to be --ion-COMPONENT-NAME- once the chip PR is merged due to the code changes done there to shorten the names.

thetaPC · 2026-01-20T18:06:49Z

core/src/components/textarea/test/validation/index.html

        font-size: 12px;
        font-weight: normal;

-        color: var(--ion-color-step-600);


It's not being used.

thetaPC · 2026-01-20T18:07:08Z

core/src/components/toggle/test/validation/index.html

        font-size: 12px;
        font-weight: normal;

-        color: var(--ion-color-step-600);


It's not being used.

thetaPC · 2026-01-20T18:15:40Z

core/src/utils/theme.ts

+  // Exclude palette from the default tokens
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const { palette, components, ...defaultTokens } = theme;
+  const { palette, ...defaultTokens } = theme;


This change will be undone through chip. Once chip is merged in, I'll come back and update this.

brandyscarney · 2026-02-02T16:51:01Z

Can we convert this back to a draft until it's ready for review?

feat(tokens): add gray colors

3192b29

github-actions bot added the package: core @ionic/core package label Nov 19, 2025

refactor(tokens): remove comment

0cc323a

vercel bot deployed to Preview November 19, 2025 21:08 View deployment

vercel bot deployed to Preview November 19, 2025 21:10 View deployment

thetaPC added 3 commits November 19, 2025 13:59

feat(tokens): add gray colors for dark

d4a05e5

feat(action-sheet): replace stepped variables with gray

444c56a

refactor(action-sheet): revert disabled

0b4b461

vercel bot deployed to Preview November 19, 2025 22:04 View deployment

feat(alert): use gray tokens

6c31996

vercel bot deployed to Preview November 20, 2025 22:21 View deployment

thetaPC added 3 commits November 20, 2025 14:23

feat(card): use gray tokens

15870a9

feat(checkbox): use gray tokens

3902e5d

feat(datetime): use gray tokens

db67416

vercel bot deployed to Preview November 20, 2025 22:42 View deployment

feat(core): update dark tokens

fc40c77

vercel bot deployed to Preview November 21, 2025 01:09 View deployment

feat(tokens): update md and add default primitives

9b0782c

vercel bot deployed to Preview November 21, 2025 19:33 View deployment

thetaPC added 2 commits November 21, 2025 16:45

feat(tokens): use gray on datetime

50998a3

refactor(token): remove comments

44aa9e8

vercel bot deployed to Preview November 22, 2025 00:49 View deployment

chore(themes): update gray tokens

42a1ecd

vercel bot deployed to Preview November 26, 2025 00:26 View deployment

thetaPC added 2 commits November 25, 2025 16:57

fix(dark): use correct hex order

e20c7c0

feat(breadcrumb): use gray tokens

c0b9385

vercel bot deployed to Preview November 26, 2025 01:00 View deployment

thetaPC commented Nov 26, 2025

View reviewed changes

thetaPC marked this pull request as ready for review December 8, 2025 16:32

thetaPC requested a review from a team as a code owner December 8, 2025 16:32

thetaPC requested review from brandyscarney and gnbm and removed request for gnbm December 8, 2025 16:32

test(themes): use correct path to local themes

ccbda68

vercel bot deployed to Preview December 12, 2025 19:00 View deployment

thetaPC mentioned this pull request Jan 16, 2026

feat(themes): enable all palettes #30874

Merged

2 tasks

Merge branch 'ionic-modular' of github.com:ionic-team/ionic-framework…

df0044b

… into FW-6751

vercel bot had a problem deploying to Preview January 19, 2026 21:50 Failure

feat(themes): add gray tokens to high contrast and high contrast dark

077864f

vercel bot deployed to Preview January 19, 2026 22:02 View deployment

fix(theme): revert the dups that were added in merge

c2659e8

vercel bot deployed to Preview January 20, 2026 00:04 View deployment

chore(button): remove test variable

75d05a2

vercel bot deployed to Preview January 20, 2026 01:35 View deployment

chore(modal): revert change to test page

70f08f1

vercel bot deployed to Preview January 20, 2026 01:38 View deployment

thetaPC commented Jan 20, 2026

View reviewed changes

docs(themes): remove comments

d416e6d

vercel bot deployed to Preview January 20, 2026 16:41 View deployment

thetaPC commented Jan 20, 2026

View reviewed changes

docs(themes): remove notes

d3b4545

vercel bot deployed to Preview January 20, 2026 18:19 View deployment

thetaPC marked this pull request as draft February 2, 2026 18:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(tokens): add gray and text colors#30799

feat(tokens): add gray and text colors#30799
thetaPC wants to merge 93 commits intoionic-modularfrom
FW-6751

thetaPC commented Nov 19, 2025 •

edited

Loading

Uh oh!

vercel bot commented Nov 19, 2025 •

edited

Loading

Uh oh!

thetaPC Nov 26, 2025

Uh oh!

thetaPC Nov 26, 2025

Uh oh!

thetaPC Jan 20, 2026

Uh oh!

thetaPC Jan 20, 2026

Uh oh!

thetaPC Jan 20, 2026

Uh oh!

thetaPC Jan 20, 2026

Uh oh!

thetaPC Jan 20, 2026

Uh oh!

thetaPC Jan 20, 2026

Uh oh!

brandyscarney commented Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

thetaPC commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Uh oh!

vercel bot commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brandyscarney commented Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

thetaPC commented Nov 19, 2025 •

edited

Loading

vercel bot commented Nov 19, 2025 •

edited

Loading