fix(tokens): update tokens version and adjust its usage by BenOsodrac · Pull Request #31680 · ionic-team/ionic-framework

BenOsodrac · 2026-11-02T10:58:28Z

Issue number: internal

What is the new behavior?

This pull request updates the design tokens package and refines the visual styling of several Ionic components to improve consistency and support new elevation/background tokens. The most significant changes are the adoption of new elevation background variables, updates to box-shadow levels, and a dependency bump for design tokens.

Design tokens and dependency updates:

Upgraded outsystems-design-tokens dependency from version 2.5.0 to 2.6.0 in both package.json and package-lock.json, ensuring access to the latest design primitives and variables. [1] [2] [3]

Component visual updates:

Updated the background and box-shadow variables for action-sheet, alert, modal, popover, and toast components to use the new elevation tokens (e.g., --background: #{globals.$ion-bg-surface-elevation-3} and adjusted shadow levels), aligning with the new design system elevations. [1] [2] [3] [4] [5]

Design token variable management:

Moved the definitions for $ion-primitives-base-white, $ion-primitives-base-black, and their RGB variants to a new location in ionic.vars.scss to improve organization and maintainability. [1] [2]
Added new elevation background variables ($ion-bg-surface-elevation-2, $ion-bg-surface-elevation-3, and their RGB variants) to the design token definitions to support the updated component backgrounds.

Does this introduce a breaking change?

Yes
No

vercel · 2026-11-02T10:58:35Z

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

Project	Deployment	Actions	Updated
ionic-framework	Ready	Preview	Nov 2, 2026 4:00pm UTC

BenOsodrac · 2026-11-02T13:42:04Z

@brandyscarney the angular failures are false positives, probably missing next sync from main.

Copilot

🟡 Changes recommended

Opaque child backgrounds hide the elevated modal and popover surfaces, requiring overlay-scoped defaults that preserve explicit consumer background and color overrides.

1 open issue

Apply elevated surface defaults to modal and popover contents · New

1 file not reviewed

core/package-lock.json: Generated file

What changed in this PR

Updates Ionic components to use the latest design tokens, aligning overlay backgrounds and shadows with the new elevation styles.

Changes:

Upgrades outsystems-design-tokens from 2.5.0 to 2.6.0.
Adds elevation background variables and reorganizes base color definitions.
Updates overlay backgrounds and adjusts modal, popover, and toast shadows.

File	Description
core/src/foundations/ionic.vars.scss	Adds elevation surface variables and relocates base color definitions.
core/src/components/toast/toast.ionic.scss	Changes the shadow to elevation 2.
core/src/components/popover/popover.ionic.scss	Uses elevation-3 background and shadow tokens.
core/src/components/modal/modal.ionic.scss	Uses an elevation-3 background and elevation-4 shadow.
core/src/components/alert/alert.ionic.scss	Uses the elevation-3 background token.
core/src/components/action-sheet/action-sheet.ionic.scss	Uses the elevation-3 background token.
core/package.json	Updates the design tokens dependency range.
core/package-lock.json	Locks design tokens to version 2.6.0.

_{Review effort: Balanced}

ShaneK · 2026-11-02T14:47:05Z

Hey @BenOsodrac, working on a sync PR for main into next currently (here)

ShaneK

Looks good to me! I left a couple of questions about the overlay surfaces, but nothing that should hold this up.

ShaneK · 2026-11-02T15:01:39Z


 :host {
-  --background: #{globals.$ion-bg-surface-default};
+  --background: #{globals.$ion-bg-surface-elevation-3};


Should the alert shadow move too? It's still on $ion-elevation-4, while popover now uses elevation-3 for both. That does match the modal, so it might be intentional. Also, the action sheet has no shadow at all in the ionic theme. Are both of these per Figma?

The alert stays on elevation-4 on purpose.

It follows the same mapping OutSystems UI uses (they share the same tokens now, and we still don't have a figma updated for MobileUI on this): dialogs and sheets (popup, bottom sheet, action sheet) use elevation-4, while popovers and dropdowns use elevation-3. That's also why the modal moved from 3 to 4.

The action sheet never had a shadow in the ionic theme, so I left it as it was.

Makes sense, thanks!

ShaneK · 2026-11-02T15:01:40Z

 :host {
-  --background: #{globals.$ion-bg-surface-default};
-  --box-shadow: #{globals.$ion-elevation-3};
+  --background: #{globals.$ion-bg-surface-elevation-3};


The elevated background gets covered by whatever's inside the modal or popover. The ionic theme gives ion-content, ion-toolbar and ion-item a $ion-bg-surface-default background, so with --token-bg-surface-elevation-3 set to a dark gray, the popover wrapper turns gray but the content and items inside it stay white. Both tokens are white right now, so it doesn't show yet. Is that intended, or a follow-up for when they start to differ, like in dark mode?

Good catch. It wasn't intended, and it's now fixed in eaf250b. In the ionic theme, ion-content, ion-toolbar and ion-item inside a modal or popover now default to the same surface-elevation-3 fill as the overlay. That means they'll stay consistent once the tokens differ, as in dark mode.

It's scoped with :where(), so it stays a default that consumers can still override. Let me know if you don't like this approach

I like this approach! I left one comment on the new rule about items inside cards.

…ic theme ion-content, ion-toolbar and ion-item paint their own surface background, which covered the elevated modal/popover fill. Default them to the same elevation-3 surface inside overlays, using :where() so consumer --background overrides still apply. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ShaneK

Thanks for the updates, looks good to me! I left one small suggestion, up to you!

ShaneK · 2026-11-02T17:46:02Z


 :host {
-  --background: #{globals.$ion-bg-surface-default};
+  --background: #{globals.$ion-bg-surface-elevation-3};


Makes sense, thanks!

ShaneK · 2026-11-02T17:46:04Z

 :host {
-  --background: #{globals.$ion-bg-surface-default};
-  --box-shadow: #{globals.$ion-elevation-3};
+  --background: #{globals.$ion-bg-surface-elevation-3};


I like this approach! I left one comment on the new rule about items inside cards.

ShaneK · 2026-11-02T17:46:05Z

+ * surface. `:where()` keeps the specificity at zero so any consumer
+ * `--background` override on these components still applies.
+ */
+:where(html.ionic ion-modal, html.ionic ion-popover) :where(ion-content, ion-toolbar, ion-item) {


Suggested change

:where(html.ionic ion-modal, html.ionic ion-popover) :where(ion-content, ion-toolbar, ion-item) {

:where(html.ionic ion-modal, html.ionic ion-popover) :where(ion-content, ion-toolbar, ion-item:not(ion-card ion-item)) {

Items inside an ion-card pick this up too, but the card itself stays on the default surface, so once the tokens differ you get a dark item inside a white card. Excluding card items fixes that and keeps the specificity at zero. Also, ion-datetime stays on the default surface inside overlays, which is probably worth a follow-up since ion-datetime-button puts it in a popover or modal pretty often.

update tokens version and adjust its usage

1d1954a

github-actions Bot added the package: core @ionic/core package label Nov 2, 2026

BenOsodrac added package: react @ionic/react package dependencies Pull requests that update a dependency file labels Nov 2, 2026

vercel Bot deployed to Preview November 2, 2026 11:03

View deployment

chore(): add updated snapshots

8b04f81

github-actions Bot removed the package: react @ionic/react package label Nov 2, 2026

vercel Bot deployed to Preview November 2, 2026 12:02

View deployment

BenOsodrac marked this pull request as ready for review November 2, 2026 13:41

BenOsodrac requested a review from a team as a code owner November 2, 2026 13:41

BenOsodrac requested review from ShaneK and brandyscarney and a balanced review from Copilot and removed request for ShaneK November 2, 2026 13:41

Copilot started reviewing on behalf of BenOsodrac November 2, 2026 13:41

View session

Copilot AI reviewed Nov 2, 2026

View reviewed changes

Comment thread core/src/components/modal/modal.ionic.scss Resolved

BenOsodrac requested review from ShaneK and removed request for brandyscarney November 2, 2026 14:16

Merge branch 'next' into ROU-13159

31537b2

ShaneK approved these changes Nov 2, 2026

View reviewed changes

vercel Bot deployed to Preview November 2, 2026 15:08

View deployment

vercel Bot deployed to Preview November 2, 2026 16:00

View deployment

BenOsodrac requested a review from ShaneK November 2, 2026 16:20

ShaneK approved these changes Nov 2, 2026

View reviewed changes

	:where(html.ionic ion-modal, html.ionic ion-popover) :where(ion-content, ion-toolbar, ion-item) {
	:where(html.ionic ion-modal, html.ionic ion-popover) :where(ion-content, ion-toolbar, ion-item:not(ion-card ion-item)) {

Conversation

BenOsodrac commented Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the new behavior?

Does this introduce a breaking change?

Uh oh!

vercel Bot commented Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BenOsodrac commented Nov 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

ShaneK commented Nov 2, 2026

Uh oh!

ShaneK left a comment

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!

ShaneK left a comment

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!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

BenOsodrac commented Nov 2, 2026 •

edited

Loading

vercel Bot commented Nov 2, 2026 •

edited

Loading