Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(updating): change theme to palette in the migration guide to v8 #3590

Merged
merged 2 commits into from
Apr 10, 2024
Merged

docs(updating): change theme to palette in the migration guide to v8 #3590

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f493147
docs(updating): change theme to palette in the migration guide to v8
brandyscarney Apr 10, 2024
d227a1f
copy editing
brandyscarney Apr 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/updating/8-0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ npm install @ionic/core@next

The following changes are not required to update to Ionic 8 as your application will continue to work. However, we recommend making the following changes to ensure you can use the new features in Ionic 8.

### Light Theme
### Light Palette

Previous versions shipped a set of default color variables for the light theme:
Previous versions defined a set of default color variables for the light palette in `theme/variables.scss`:

```css
/** Ionic CSS Variables **/
Expand All @@ -90,15 +90,15 @@ Previous versions shipped a set of default color variables for the light theme:
}
```

In Ionic Framework version 8, the default color palette is included as long as `core.css` is imported. Removing the old color variables ensures that the latest palette is not overwritten.
In Ionic Framework version 8, these color variables are included as long as `core.css` is imported. The color variables defined in `theme/variables.scss` should be removed to avoid overriding the imported default variables and ensure the app is always using the latest palette.

Developers who are customizing this color palette can continue to keep the custom variables values, but any of the variables that use the default values should be removed.

You can read more about the new color palette in the [Ionic v8 announcement](https://ionic.io/blog/announcing-the-ionic-8-beta).

### Dark Theme
### Dark Palette

In previous versions, it was recommended to define the dark theme in the following way:
In previous versions, it was recommended to define the dark palette in the following way:

```css
@media (prefers-color-scheme: dark) {
Expand All @@ -116,25 +116,25 @@ In previous versions, it was recommended to define the dark theme in the followi
}
```

In Ionic Framework version 8, the dark theme is being distributed via css files that can be imported. Below is an example of importing a dark theme file in Angular:
In Ionic Framework version 8, the dark palette is being distributed via css files that can be imported. Below is an example of importing a dark palette file in Angular:

```css
/* @import '@ionic/angular/css/palettes/dark.always.css'; */
/* @import "@ionic/angular/css/palettes/dark.class.css"; */
@import '@ionic/angular/css/palettes/dark.system.css';
```

The dark theme is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `<html>` element and is identical to the selector `html`, except that its specificity is higher.
The dark palette is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `<html>` element and is identical to the selector `html`, except that its specificity is higher.

While migrating to include the new dark theme files is unlikely to cause breaking changes, these new selectors can lead to unexpected overrides if custom CSS variables are being set on the `body` element. We recommend updating any instances where global application variables are set to target the `:root` selector instead.
While migrating to include the new dark palette files is unlikely to cause breaking changes, these new selectors can lead to unexpected overrides if custom CSS variables are being set on the `body` element. We recommend updating any instances where global application variables are set to target the `:root` selector instead.

For more information on the new dark theme files, refer to the [Dark Mode documentation](../theming/dark-mode).
For more information on the new dark palette files, refer to the [Dark Mode documentation](../theming/dark-mode).

### Step Color Tokens

To better support the high contrast theme in Ionic 8, separate step colors tokens have been introduced for text and background color. Previously both text and background color were controlled by a single set of `--ion-color-step-[number]` tokens.
To better support the high contrast palette in Ionic 8, separate step colors tokens have been introduced for text and background color. Previously both text and background color were controlled by a single set of `--ion-color-step-[number]` tokens.

Using the newly imported dark theme mentioned above will also import these new step color tokens. However, developers will need to update any step color tokens that were manually defined in an application.
Using the newly imported dark palette mentioned above will also import these new step color tokens. However, developers will need to update any step color tokens that were manually defined in an application.

`--ion-color-step-[number]` usages for **background color** can be migrated by renaming the token to `--ion-background-color-step-[number]`.

Expand Down Expand Up @@ -172,7 +172,7 @@ For more information on the dynamic font, refer to the [Dynamic Font Scaling doc

### (Angular Only) `angular.json` CSS import order

The `angular.json` file currently imports `src/theme/variables.scss` before importing `src/global.scss`. This may cause the incorrect styles to be applied when customizing the new [Dark Theme](#dark-theme) changes.
The `angular.json` file currently imports `src/theme/variables.scss` before importing `src/global.scss`. This may cause the incorrect styles to be applied when customizing the new [Dark Palette](#dark-palette) changes.

We recommend having the `src/global.scss` file get imported first instead:

Expand Down