docs(high-contrast): add documentation #3431
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,6 +12,7 @@ Swiper | |
| Udemy | ||
| Vetur | ||
| Wistia | ||
| WCAG | ||
|
|
||
| actionsheet | ||
| fabs | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,228 @@ | ||
| --- | ||
| title: Hide Contrast Mode | ||
| initialTab: 'preview' | ||
| inlineHtmlPreviews: true | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| --- | ||
|
|
||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
|
|
||
| <head> | ||
| <title>High Contrast Mode to Increase Color Contrast</title> | ||
| <meta | ||
| name="description" | ||
| content="Developers are adding high contrast mode CSS on native applications to support their user preferences. Read to learn more about high contrast color schemes for Ionic apps." | ||
| /> | ||
| </head> | ||
|
|
||
| Ionic ships with themes for increased contrast for users with low vision. These themes work by increasing the contrast between foreground content, such as text, and background content, such as UI components. Ionic provides light and dark variants for high contrast. | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Overview | ||
|
|
||
| The [Ionic colors](./colors) in the high contrast theme have been updated to meet [Level AAA color contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced.html) as defined by the Web Content Accessibility Guidelines (WCAG) when used with the appropriate contrast color. The theme also seeks to improve the contrast of UI components such as the border on an Item. However, Ionic's high contrast theme prioritizes text. This means that if increasing the contrast of a UI component against the page background would significantly reduce the contrast of the component's text against the component's background, the UI component contrast will not be modified. | ||
|
||
|
|
||
| ## Enabling High Contrast Theme | ||
|
|
||
| There are three provided ways to enable the high contrast theme in an app: **always**, based on **system** settings, or by using a **class**. | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ### Always | ||
|
|
||
| The default theme provided with Ionic Framework also uses the default color contrast levels. The high contrast theme can be enabled by importing the following stylesheet in the appropriate files. This approach will enable the high contrast theme regardless of a user's preference for high contrast. | ||
thetaPC marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| <Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}> | ||
|
|
||
| <TabItem value="angular"> | ||
|
|
||
| ```css | ||
| @import '@ionic/angular/css/themes/high-contrast.always.css'; | ||
| ``` | ||
liamdebeasi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| </TabItem> | ||
| <TabItem value="javascript"> | ||
|
|
||
| ```ts | ||
| import '@ionic/core/css/themes/high-contrast.always.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="react"> | ||
|
|
||
| ```tsx | ||
| import '@ionic/react/css/themes/high-contrast.always.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="vue"> | ||
|
|
||
| ```ts | ||
| import '@ionic/vue/css/themes/high-contrast.always.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| The high contrast dark theme can be applied by importing `high-contrast-dark.always.css` instead of `high-contrast.always.css`. | ||
|
|
||
| The following example will always display the high contrast light theme, regardless of the user's preference for high contrast or dark mode. | ||
|
|
||
| import AlwaysHighContrastMode from '@site/static/usage/v8/theming/always-high-contrast-mode/index.md'; | ||
|
|
||
| <AlwaysHighContrastMode /> | ||
|
|
||
| ### System | ||
liamdebeasi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The system approach to enabling high contrast mode involves checking the system settings for the user's preferred contrast. This is the default when starting a new Ionic Framework app. Importing the following stylesheets in the appropriate file will automatically retrieve the user's preference from the system settings and apply the high contrast theme when high contrast is preferred. | ||
|
|
||
| <Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}> | ||
|
|
||
| <TabItem value="angular"> | ||
|
|
||
| ```css | ||
| @import '@ionic/angular/css/themes/high-contrast.system.css'; | ||
| @import '@ionic/angular/css/themes/high-contrast-dark.system.css'; | ||
liamdebeasi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="javascript"> | ||
|
|
||
| ```ts | ||
| import '@ionic/core/css/themes/high-contrast.system.css'; | ||
| import '@ionic/core/css/themes/high-contrast-dark.system.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="react"> | ||
|
|
||
| ```tsx | ||
| import '@ionic/react/css/themes/high-contrast.system.css'; | ||
| import '@ionic/react/css/themes/high-contrast-dark.system.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="vue"> | ||
|
|
||
| ```ts | ||
| import '@ionic/vue/css/themes/high-contrast.system.css'; | ||
| import '@ionic/vue/css/themes/high-contrast-dark.system.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| This approach activates the high contrast theme when the [CSS media query for `prefers-contrast`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) is `more`. The `prefers-contrast` media query is supported by [all modern browsers](https://caniuse.com/?search=prefers-contrast). If support for an older browser is required, we recommend using the [class](#class) approach. | ||
|
|
||
| The following example uses the system settings to decide when to show high contrast mode. | ||
|
|
||
| :::info | ||
| Not sure how to change the system settings? Here's how to enable high contrast mode on [Windows 11](hhttps://support.microsoft.com/en-us/windows/turn-high-contrast-mode-on-or-off-in-windows-909e9d89-a0f9-a3a9-b993-7a6dcee85025) and on [macOS](https://support.apple.com/guide/mac-help/change-display-settings-for-accessibility-unac089/mac). | ||
| ::: | ||
|
|
||
| import SystemHighContrastMode from '@site/static/usage/v8/theming/system-high-contrast-mode/index.md'; | ||
|
|
||
| <SystemHighContrastMode /> | ||
| :::caution The high contrast light theme must be imported after [core.css](../layout/global-stylesheets#corecss), and the | ||
| high contrast dark theme must be imported after `dark.system.css`. Otherwise, the standard contrast theme will take priority. | ||
| ::: | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ### Class | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| While the previous approaches are excellent for enabling the high contrast theme through file imports alone, there are scenarios where you may need more control over its application. In cases where you need to apply the high contrast theme conditionally, such as through a toggle, or if you want to extend the functionality based on system settings, we provide a high contrast theme class file. This file applies the high contrast theme when a specific class is added to an app. Importing the following stylesheets into the appropriate file will provide the necessary styles for using the high contrast theme with the class: | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| <Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}> | ||
|
|
||
| <TabItem value="angular"> | ||
|
|
||
| ```css | ||
| @import '@ionic/angular/css/themes/high-contrast.class.css'; | ||
| @import '@ionic/angular/css/themes/high-contrast-dark.class.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="javascript"> | ||
|
|
||
| ```ts | ||
| import '@ionic/core/css/themes/high-contrast.class.css'; | ||
| import '@ionic/core/css/themes/high-contrast-dark.class.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="react"> | ||
|
|
||
| ```tsx | ||
| import '@ionic/react/css/themes/high-contrast.class.css'; | ||
| import '@ionic/react/css/themes/high-contrast-dark.class.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="vue"> | ||
|
|
||
| ```ts | ||
| import '@ionic/vue/css/themes/high-contrast.class.css'; | ||
| import '@ionic/vue/css/themes/high-contrast-dark.class.css'; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| This approach activates the high contrast theme when the `.ion-theme-high-contrast` class is set on the `html` element. This class must be applied by the developer. This can be combined with the [`.ion-theme-dark` class](./dark-mode#class) to conditionally apply the high contrast dark theme. | ||
|
|
||
| The following example combines site settings, system settings, and the toggle to decide when to show high contrast mode. The site's theme takes precedence over system settings. If your system settings differ from the site's theme when the demo loads, it will use the site's theme. | ||
|
|
||
| :::info | ||
| Not sure how to change the system settings? Here's how to enable high contrast mode on [Windows 11](hhttps://support.microsoft.com/en-us/windows/turn-high-contrast-mode-on-or-off-in-windows-909e9d89-a0f9-a3a9-b993-7a6dcee85025) and on [macOS](https://support.apple.com/guide/mac-help/change-display-settings-for-accessibility-unac089/mac). | ||
| ::: | ||
|
|
||
| import ClassHighContrastMode from '@site/static/usage/v8/theming/class-high-contrast-mode/index.md'; | ||
|
|
||
| <ClassHighContrastMode /> | ||
| :::caution Important The high contrast light theme must be imported after [core.css](../layout/global-stylesheets#corecss), | ||
| and the high contrast dark theme must be imported after `dark.class.css`. Otherwise, the standard contrast theme will take | ||
| priority. ::: | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| :::caution Important | ||
| The `.ion-theme-high-contrast` class **must** be added to the `html` element in order to work with the imported high contrast theme. | ||
| ::: | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Customizing Ionic High Contrast Theme | ||
brandyscarney marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Ionic has a recommended high contrast theme that can be enabled in three different ways: [always](#always), based on [system](#system) settings, or by using a [class](#class). Each of these methods involves importing the high contrast theme file with the corresponding name. | ||
liamdebeasi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| The theme variables are set by importing the relevant high contrast theme file and do not need to be copied into an app. For more information on the variables being changed, including additional variables for further customization, refer to the [Themes](themes.md) section. | ||
|
|
||
| <Tabs groupId="darkFiles" defaultValue="always" values={[{ value: 'always', label: 'Always (high-contrast.always.css)' }, { value: 'system', label: 'System (high-contrast.system.css)' }, { value: 'class', label: 'Class (high-contrast.class.css)' }]}> | ||
|
|
||
| <TabItem value="always"> | ||
|
|
||
| The **always** high contrast theme behaves in the following ways: | ||
|
|
||
| 1. Sets the [Ionic colors](colors.md) for all [modes](platform-styles.md#ionic-modes) to complement a high contrast theme in the `:root` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector is identical to the selector `html`, except that its [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) is higher. | ||
| 2. Setting variables for the high contrast theme on `ios` devices using the `:root.ios` selector. | ||
| 3. Setting variables for the high contrast theme on `md` devices using the `:root.md` selector. | ||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="system"> | ||
|
|
||
| The **system** high contrast theme behaves in the following ways: | ||
|
|
||
| 1. Sets the [Ionic colors](colors.md) for all [modes](platform-styles.md#ionic-modes) to complement a high contrast theme in the `:root` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector is identical to the selector `html`, except that its [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) is higher. | ||
| 2. Setting variables for the high contrast theme on `ios` devices using the `:root.ios` selector. | ||
| 3. Setting variables for the high contrast theme on `md` devices using the `:root.md` selector. | ||
| 4. Only applies these variables when the [CSS media query for `prefers-contrast`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) is `more`. | ||
|
|
||
| </TabItem> | ||
|
|
||
| <TabItem value="class"> | ||
|
|
||
| The **class** high contrast theme behaves in the following ways: | ||
|
|
||
| 1. Sets the [Ionic colors](colors.md) for all [modes](platform-styles.md#ionic-modes) to complement a high contrast theme in the `.ion-theme-high-contrast` selector. The `.ion-theme-high-contrast` class must be added to the `html` element in an app. | ||
| 2. Setting variables for the high contrast theme on `ios` devices using the `.ion-theme-high-contrast.ios` selector. | ||
| 3. Setting variables for the high contrast theme on `md` devices using the `.ion-theme-high-contrast.md` selector. | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,7 @@ | ||
| { | ||
| "dependencies": { | ||
| "@ionic/angular": "7.6.7-dev.11707162903.1706e75f", | ||
| "@ionic/core": "7.6.7-dev.11707162903.1706e75f", | ||
| "@angular/platform-browser-dynamic": "17.0.4" | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| { | ||
| "dependencies": { | ||
| "@ionic/core": "7.6.7-dev.11707162903.1706e75f" | ||
| } | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.