feat(themes): add ionic theme tokens

[brandyscarney]

Issue number: internal

---

What is the current behavior?

• The ionic theme tokens are undefined.
• The dark palette does not work with the ionic theme.
• The ionic theme uses different colors than md and ios.
• The modular theme tokens are not being used by any tests dependent on URL params.

What is the new behavior?

• Updates the token interface to accept a numeric scale - it is TBD if it will be the way forward but it is needed for the ionic theme currently.
• Updates the base tokens to use the new interface.
• Adds tokens for the ionic theme based on the existing design tokens.
• Excludes certain keys (enabled, rippleEffect, formHighlight) from the generated CSS variables.
• Removes the --background and --ion-background-color from the global ionic theme overrides, allowing it to use the dark palette.
• Removes the different Ionic colors from the ionic theme, ensuring all of the themes use the same named (primary, secondary, etc.) colors.
• Updates the testing script to pull in the tokens based on the theme & palette passed to the URL.
• Adds a new npm script, build.themes, to generate the theme files.

Does this introduce a breaking change?

• Yes
• No

Other information

Preview: Basic
Preview: Color
Preview: Typography

Add the URL parameters ?ionic:palette=dark or ?ionic:theme={ios|md|ionic} to see the palette or theme change and pull in the associated tokens.

Note: most of the theme specific tokens are not applied yet because we haven't updated the components.

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
ionic-framework	Ready	Preview	Comment	Oct 16, 2025 1:49pm

[BenOsodrac]

@brandyscarney I have some doubts about the approach, as I see no relation was kept to the outsystems-design-tokens package in the code.

I was expecting the interfaces and default values would be generated based on the info provided by the outsystems-design-tokens. Even more so, if now we are using the same structure for all themes, but at least keep that connection for the Ionic one.

What happens now if the UX team decides to change the scale or the palette, for example? We would need to manual review all interfaces, values and variables to match that?

The advantage of tokens is the auto sync between design (figma) and code, and its different contexts (for example, the outsystems-design-tokens package is also used on the outsystems side, to make sure everything is synced, regarding css).

If we are loosing that, then there's no use to call these design tokens 😄, just type-safe css structures, like https://vanilla-extract.style/

[brandyscarney]

@BenOsodrac Yeah, this is definitely an open topic.

For now, the plan is to move forward with all themes using the same tokens, and the mobile UI would override those design tokens in the framework on your side. The idea is that if the Outsystems design tokens changed values it would require a breaking change release on our end, which we're trying to avoid.

This work is still in the early stages, and we haven't finalized the naming or process yet. I'll add this to the Confluence doc under open topics so we can discuss it further.

[BenOsodrac]

@BenOsodrac Yeah, this is definitely an open topic.

For now, the plan is to move forward with all themes using the same tokens, and the mobile UI would override those design tokens in the framework on your side. The idea is that if the Outsystems design tokens changed values it would require a breaking change release on our end, which we're trying to avoid.

This work is still in the early stages, and we haven't finalized the naming or process yet. I'll add this to the Confluence doc under open topics so we can discuss it further.

Ok thanks! 👍

But would we keep the css variables with fallbacks from the token ones?
Because if not, that could mean a big shift on how we are preparing the customization documentation for MobileUI

[brandyscarney]

@BenOsodrac I think that decision still needs to be made also. I can send you the link to the open discussion document. It is still a WIP but feel free to add topics to it or add any thoughts to existing ones! 🙂

[ShaneK]

This generally looks fine to me, I just had a few comments/questions that might just need clarity rather than changes. Approving this because I don't really consider them blocking even if you want to change something related to it.

Great work!!

[thetaPC]

1. For dark palette on the basic page, can the text be black on spacing? It's a bit hard to read.
2. When using dark palette with ionic theme, the header doesn't change to a darker shade like the other themes. Is that on purpose? This happens on all the previews.

[thetaPC]

LGTM, my comments aren't blockers. Just make sure to update the path and should be good to merge.

[brandyscarney]

@thetaPC:

1. For dark palette on the basic page, can the text be black on spacing? It's a bit hard to read.

Done: 6f2c0c3

2. When using dark palette with ionic theme, the header doesn't change to a darker shade like the other themes. Is that on purpose? This happens on all the previews.

The ionic theme has never worked with the dark palette. You can see this on next: colors test

My changes enable the global dark palette for the ionic theme, but that doesn't work on components that are not using the global theme variables. The components will be updated to work as they are ported to the new modular system.

[thetaPC]

LGTM, with minor suggestion