It has been quite a while (looking back, Ionic 8 was released in April this year), and I want to revisit the theme color and dark mode changes in Ionic 8. Because these were changes you could skip during an upgrade without anything breaking in particular, if you have been putting them off you may have forgotten to update your settings — please take another look.
AA Color Contrast Theme Colors
Last year I wrote the following article. The default theme colors until then did not meet the contrast requirements of WCAG accessibility standards, and Ionic updated to address that.
https://qiita.com/rdlabo/items/c96278364bcb25b4d2f1
Building on that, the Ionic 8 default starter template now ships with an empty theme/variables.scss.
https://github.com/ionic-team/starters/blob/main/angular-standalone/base/src/theme/variables.scss
If you use the new default theme, the styles are bundled in Ionic core so you do not need to write them yourself. Of course, if you keep the old variables.scss, you can still override those core styles and continue as before. That is how this change stays non-breaking: in v8, simply emptying variables.scss is enough to use the new theme.
At the same time, the Ionic Docs color generator now produces AA color contrast themes, and that approach is recommended. As before, you set your key color there and copy the generated styles — simple and convenient.
https://ionicframework.com/docs/theming/color-generator
By the way, you can check whether your current color theme meets WCAG on this site.
https://webaim.org/resources/contrastchecker/
Dark Mode Settings
Dark mode configuration changed at the same time. The big shift is that until Ionic 7, when you gave users a toggle for dark mode you typically added a class on the body tag, such as body.dark. In Ionic 8, you add the ion-palette-dark class on :root (that is, the html tag). The migration looks like this.
Before:
/* Class Dark Mode */
body.dark {
/* global app variables */
&.ios {
/* global ios app variables */
}
}
After:
:root.ion-palette-dark {
body {
/* global app variables */
}
.ios body {
/* global ios app variables */
}
}
Because :root refers to the root element of the HTML document, this is semantically closer to @media (prefers-color-scheme: dark) and feels cleaner.
Also, basic dark mode settings that used to live in variables.scss are now handled by importing CSS. Three CSS files are provided depending on how you want dark mode to behave:
- Always dark mode
- Dark mode following system settings (depends on the OS default)
- Dark mode following user settings (user toggles it in the app)
So you update dark mode in variables.scss and rely on CSS imports for the baseline dark mode setup. Step color variables were updated as well — do not forget to migrate those.
Before:
button { background: var(--ion-color-step-400); }
After:
button { background: var(--ion-background-color-step-400); }
Summary
Color settings are easy to defer during upgrades when nothing breaks, but accessible theme colors and dark mode matter for app development going forward. Understand what changed in Ionic 8 and revisit your app’s theme colors and dark mode setup.
See you next time.