Skip to content

Commit b863341

Browse files
liamdebeasiliamdebeasi
authored
docs(high-contrast): add documentation (#3431)
1 parent c5d762c commit b863341

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+2285
-79
lines changed

‎cspell-wordlist.txt

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Swiper
1212
Udemy
1313
Vetur
1414
Wistia
15+
WCAG
1516

1617
actionsheet
1718
fabs

‎docs/theming/dark-mode.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Ionic makes it easy to change the themes of your app, including supporting dark
1919

2020
## Enabling Dark Theme
2121

22-
There are three provided ways to enable the dark theme in an app: **always**, based on **system** settings, or by using a **class**.
22+
There are three provided ways to enable the dark theme in an app: **always**, based on **system** settings, or by using a CSS **class**.
2323

2424
### Always
2525

@@ -107,7 +107,7 @@ import '@ionic/vue/css/themes/dark.system.css';
107107

108108
</Tabs>
109109

110-
This sets the [application colors](/docs/theming/themes#application-colors) and [stepped colors](/docs/theming/themes#stepped-colors) when the [CSS media query for `prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) is `dark`. The `prefers-color-scheme` media query is supported by [all modern browsers](https://caniuse.com/#feat=prefers-color-scheme). If support for older browser is required, we recommend using the [class](#class) approach.
110+
This sets the [application colors](/docs/theming/themes#application-colors) and [stepped colors](/docs/theming/themes#stepped-colors) when the [CSS media query for `prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) is `dark`. The `prefers-color-scheme` media query is supported by [all modern browsers](https://caniuse.com/#feat=prefers-color-scheme). If support for older browser is required, we recommend using the [CSS class](#css-class) approach.
111111

112112
The following example uses the system settings to decide when to show dark mode.
113113

@@ -123,7 +123,7 @@ import SystemDarkMode from '@site/static/usage/v8/theming/system-dark-mode/index
123123
Avoid targeting the `.ios` or `.md` selectors to override the Ionic dark theme, as these classes are added to each component and will take priority over globally defined variables. Instead, we can target the mode-specific classes on the `:root` element.
124124
:::
125125

126-
### Class
126+
### CSS Class
127127

128128
While the previous approaches are excellent for enabling the dark 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 dark theme conditionally, such as through a toggle, or if you want to extend the functionality based on system settings, we provide a dark theme class file. This file applies the dark theme when a specific class is added to an app. Importing the following stylesheet into the appropriate file will provide the necessary styles for using the dark theme with the class:
129129

@@ -208,7 +208,7 @@ For developers looking to customize the theme color under the status bar in Safa
208208

209209
## Ionic Dark Theme
210210

211-
Ionic has a recommended dark 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 dark theme file with the corresponding name.
211+
Ionic has a recommended dark theme that can be enabled in three different ways: [always](#always), based on [system](#system) settings, or by using a [CSS class](#css-class). Each of these methods involves importing the dark theme file with the corresponding name.
212212

213213
The contents of each file are included below for reference. These variables are set by importing the relevant dark 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.
214214

‎docs/theming/high-contrast-mode.md

+245
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
title: Hide Contrast Mode
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
<head>
9+
<title>High Contrast Mode to Increase Color Contrast</title>
10+
<meta
11+
name="description"
12+
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."
13+
/>
14+
</head>
15+
16+
Ionic offers themes with increased contrast for users with low vision. These themes work by amplifying the contrast between foreground content, such as text, and background content, such as UI components. Ionic provides both light and dark variants for achieving high contrast.
17+
18+
## Overview
19+
20+
The default theme in Ionic provides [Ionic colors](./colors.md) that meet [Level AA color contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) as defined by Web Content Accessibility Guidelines (WCAG) when used with the appropriate contrast color. The [Ionic colors](./colors.md) in the high contrast theme have been updated to meet [Level AAA color contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced.html) when used with the appropriate contrast color. Notably, improvements have been made to the contrast of UI components, including border, text, and background colors. However, it's important to note that within the high contrast theme, priority is given to text legibility. This means that if adjusting the contrast of a UI component against the page background would significantly compromise the contrast between the component's text and its background, the contrast of the UI component background will remain unchanged.
21+
22+
## Enabling High Contrast Theme
23+
24+
There are three provided ways to enable the high contrast theme in an app: **always**, based on **system** settings, or by using a CSS **class**.
25+
26+
### Always
27+
28+
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 the system settings for contrast preference.
29+
30+
<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
31+
32+
<TabItem value="angular">
33+
34+
```css
35+
@import '@ionic/angular/css/themes/high-contrast.always.css'; // Light theme
36+
// @import '@ionic/angular/css/themes/high-contrast.always.css'; // Dark theme
37+
```
38+
39+
</TabItem>
40+
<TabItem value="javascript">
41+
42+
```typescript
43+
import '@ionic/core/css/themes/high-contrast.always.css'; // Light theme
44+
// import '@ionic/core/css/themes/high-contrast-dark.always.css'; // Dark theme
45+
```
46+
47+
</TabItem>
48+
<TabItem value="react">
49+
50+
```tsx
51+
import '@ionic/react/css/themes/high-contrast.always.css'; // Light theme
52+
// import '@ionic/react/css/themes/high-contrast-dark.always.css'; // Dark theme
53+
```
54+
55+
</TabItem>
56+
<TabItem value="vue">
57+
58+
```typescript
59+
import '@ionic/vue/css/themes/high-contrast.always.css'; // Light theme
60+
// import '@ionic/vue/css/themes/high-contrast-dark.always.css'; // Dark theme
61+
```
62+
63+
</TabItem>
64+
65+
</Tabs>
66+
67+
The high contrast dark theme can be applied by importing `high-contrast-dark.always.css` instead of `high-contrast.always.css`.
68+
69+
The following example will always display the high contrast light theme, regardless of the user's preference for high contrast or dark mode.
70+
71+
import AlwaysHighContrastMode from '@site/static/usage/v8/theming/always-high-contrast-mode/index.md';
72+
73+
<AlwaysHighContrastMode />
74+
75+
### System
76+
77+
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.
78+
79+
The following example shows how to include both the high contrast light theme as well as the high contrast dark theme. The system's dark mode preference will be checked to show either the light or dark variant of the high contrast theme.
80+
81+
<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
82+
83+
<TabItem value="angular">
84+
85+
```css
86+
@import '@ionic/angular/css/themes/high-contrast.system.css';
87+
@import '@ionic/angular/css/themes/high-contrast-dark.system.css';
88+
```
89+
90+
</TabItem>
91+
<TabItem value="javascript">
92+
93+
```ts
94+
import '@ionic/core/css/themes/high-contrast.system.css';
95+
import '@ionic/core/css/themes/high-contrast-dark.system.css';
96+
```
97+
98+
</TabItem>
99+
<TabItem value="react">
100+
101+
```tsx
102+
import '@ionic/react/css/themes/high-contrast.system.css';
103+
import '@ionic/react/css/themes/high-contrast-dark.system.css';
104+
```
105+
106+
</TabItem>
107+
<TabItem value="vue">
108+
109+
```ts
110+
import '@ionic/vue/css/themes/high-contrast.system.css';
111+
import '@ionic/vue/css/themes/high-contrast-dark.system.css';
112+
```
113+
114+
</TabItem>
115+
116+
</Tabs>
117+
118+
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 [CSS class](#css-class) approach.
119+
120+
The following example uses the system settings to decide when to show high contrast mode.
121+
122+
:::info
123+
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).
124+
:::
125+
126+
import SystemHighContrastMode from '@site/static/usage/v8/theming/system-high-contrast-mode/index.md';
127+
128+
<SystemHighContrastMode />
129+
130+
:::caution
131+
The high contrast light theme must be imported after [core.css](../layout/global-stylesheets.md#corecss), and the
132+
high contrast dark theme must be imported after `dark.system.css`. Otherwise, the standard contrast theme will take priority.
133+
:::
134+
135+
### CSS Class
136+
137+
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 where it is applied. 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:
138+
139+
<Tabs groupId="framework" defaultValue="angular" values={[{ value: 'angular', label: 'Angular' }, { value: 'javascript', label: 'Javascript' }, { value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}>
140+
141+
<TabItem value="angular">
142+
143+
```css
144+
@import '@ionic/angular/css/themes/high-contrast.class.css';
145+
@import '@ionic/angular/css/themes/high-contrast-dark.class.css';
146+
```
147+
148+
</TabItem>
149+
<TabItem value="javascript">
150+
151+
```ts
152+
import '@ionic/core/css/themes/high-contrast.class.css';
153+
import '@ionic/core/css/themes/high-contrast-dark.class.css';
154+
```
155+
156+
</TabItem>
157+
<TabItem value="react">
158+
159+
```tsx
160+
import '@ionic/react/css/themes/high-contrast.class.css';
161+
import '@ionic/react/css/themes/high-contrast-dark.class.css';
162+
```
163+
164+
</TabItem>
165+
<TabItem value="vue">
166+
167+
```ts
168+
import '@ionic/vue/css/themes/high-contrast.class.css';
169+
import '@ionic/vue/css/themes/high-contrast-dark.class.css';
170+
```
171+
172+
</TabItem>
173+
174+
</Tabs>
175+
176+
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.md#css-class) to conditionally apply the high contrast dark theme.
177+
178+
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.
179+
180+
:::info
181+
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).
182+
:::
183+
184+
import ClassHighContrastMode from '@site/static/usage/v8/theming/class-high-contrast-mode/index.md';
185+
186+
<ClassHighContrastMode />
187+
188+
:::caution
189+
The high contrast light theme must be imported after [core.css](../layout/global-stylesheets.md#corecss),
190+
and the high contrast dark theme must be imported after `dark.class.css`. Otherwise, the standard contrast theme will take
191+
priority.
192+
:::
193+
194+
:::caution
195+
The `.ion-theme-high-contrast` class **must** be added to the `html` element in order to work with the imported high contrast theme.
196+
:::
197+
198+
## Customizing Ionic High Contrast Theme
199+
200+
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 [CSS class](#css-class). Each of these methods involves importing the high contrast theme file with the corresponding name.
201+
202+
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.
203+
204+
The following provides details on how to customize the high contrast theme depending on how it was applied in an application.
205+
206+
<Tabs groupId="highContrastFile" defaultValue="always" values={[{ value: 'always', label: 'Always' }, { value: 'system', label: 'System' }, { value: 'class', label: 'Class' }]}>
207+
208+
<TabItem value="always">
209+
210+
The **always** high contrast theme can be accessed by importing `high-contrast.always.css` for the light variant and `high-contrast-dark.always.css` for the dark variant.
211+
212+
The **always** high contrast theme behaves in the following ways:
213+
214+
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.
215+
2. Setting variables for the high contrast theme on `ios` devices using the `:root.ios` selector.
216+
3. Setting variables for the high contrast theme on `md` devices using the `:root.md` selector.
217+
218+
</TabItem>
219+
220+
<TabItem value="system">
221+
222+
The **system** high contrast theme can be accessed by importing `high-contrast.system.css` for the light variant and `high-contrast-dark.system.css` for the dark variant.
223+
224+
The **system** high contrast theme behaves in the following ways:
225+
226+
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.
227+
2. Setting variables for the high contrast theme on `ios` devices using the `:root.ios` selector.
228+
3. Setting variables for the high contrast theme on `md` devices using the `:root.md` selector.
229+
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`.
230+
231+
</TabItem>
232+
233+
<TabItem value="class">
234+
235+
The **class** high contrast theme can be accessed by importing `high-contrast.class.css` for the light variant and `high-contrast-dark.class.css` for the dark variant.
236+
237+
The **class** high contrast theme behaves in the following ways:
238+
239+
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.
240+
2. Setting variables for the high contrast theme on `ios` devices using the `.ion-theme-high-contrast.ios` selector.
241+
3. Setting variables for the high contrast theme on `md` devices using the `.ion-theme-high-contrast.md` selector.
242+
243+
</TabItem>
244+
245+
</Tabs>

‎sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ module.exports = {
5757
'theming/colors',
5858
'theming/themes',
5959
'theming/dark-mode',
60+
'theming/high-contrast-mode',
6061
'theming/advanced',
6162
'theming/color-generator',
6263
],

‎static/code/stackblitz/v8/angular/package.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"dependencies": {
3-
"@ionic/angular": "7.6.2-dev.11705355381.14b22962",
4-
"@ionic/core": "7.6.2-dev.11705355381.14b22962",
3+
"@ionic/angular": "7.6.7-dev.11707162903.1706e75f",
4+
"@ionic/core": "7.6.7-dev.11707162903.1706e75f",
55
"@angular/platform-browser-dynamic": "17.0.4"
66
}
77
}

‎static/code/stackblitz/v8/html/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"dependencies": {
3-
"@ionic/core": "7.6.2-dev.11705355381.14b22962"
3+
"@ionic/core": "7.6.7-dev.11707162903.1706e75f"
44
}
55
}

0 commit comments

Comments
 (0)