diff --git a/cspell.json b/cspell.json index d4117e45dd..42f68b5116 100644 --- a/cspell.json +++ b/cspell.json @@ -397,6 +397,7 @@ "agentic", "wireframes", "opensource", - "unlayered" + "unlayered", + "VPAT" ] } diff --git a/docs/angular/src/content/en/components/ai/theming-mcp.mdx b/docs/angular/src/content/en/components/ai/theming-mcp.mdx index 60cfe03a47..ce7c9970eb 100644 --- a/docs/angular/src/content/en/components/ai/theming-mcp.mdx +++ b/docs/angular/src/content/en/components/ai/theming-mcp.mdx @@ -247,6 +247,10 @@ To see the current full list of tools and their parameters at any time, ask your Here is a brief overview of each tool: + +When it generates a palette, the server checks the contrast ratio between your surface and gray colors against WCAG thresholds and warns you when the pairing falls short. See [Accessibility](../themes/accessibility.mdx) for the contrast behavior built into the theming engine itself. + + | Tool | Description | |------|-------------| | `detect_platform` | Identifies the project framework and selects the correct import paths and selectors. For Angular, React, and Web Components projects, reads `package.json`. For Blazor projects, which do not have a `package.json`, returns `generic` - tell the AI explicitly: _"Use the Blazor platform."_ | diff --git a/docs/angular/src/content/en/components/themes/accessibility.mdx b/docs/angular/src/content/en/components/themes/accessibility.mdx new file mode 100644 index 0000000000..e0be1dbeba --- /dev/null +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -0,0 +1,278 @@ +--- +title: Accessibility +description: How the Ignite UI for Angular theming engine supports accessibility - automatic text contrast, relative text scaling, and a color-vision-deficiency chart palette. +keywords: accessibility, contrast, WCAG, theming, color, typography, Ignite UI for Angular, Angular, Infragistics +license: MIT +last_updated: "2026-08-27" +llms: + description: "Ignite UI for Angular calculates readable text colors at runtime, keeps every type scale relative, and ships an opt-in color-vision-deficiency chart palette." +--- + +{/*Twin topic: docs/xplat/src/content/en/components/themes/accessibility.mdx covers React, Web Components and Blazor. The two are near-identical by design; apply substantive edits to both.*/} + +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; + +# Accessibility + +
+The Ignite UI for Angular theming engine builds accessibility into the styling layer: it calculates a readable text color for any background at runtime, expresses every type scale in relative units so text scales with the user's settings, and ships an opt-in color palette for readers with color-vision deficiency. +
+ + +## Overview + +Accessibility in Ignite UI is delivered by two layers that you configure independently: + +| Layer | What it is responsible for | Where it is documented | +|---|---|---| +| **Theming engine** (`igniteui-theming`) | Color contrast, text sizing, chart color palettes, and the styling utilities that keep custom controls reachable by assistive technology. | This page. | +| **Component library** (`igniteui-angular`) | Keyboard operability, focus movement, ARIA roles and states, and screen-reader announcements. | [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) and each component topic. | + +This page covers the first layer. It describes capabilities that apply to every component you style with the theming engine, including components you build yourself on top of it. + +The table below summarizes what the theming engine does for the person ultimately using your application. + +| A person who… | What the theming engine provides | +|---|---| +| Needs readable text on colored buttons, chips, and badges | A readable foreground color is calculated in the browser for every palette color, including brand colors you supply. | +| Enlarges their default browser font size | Every type scale is expressed in relative units, and the library never pins the page font size. | +| Has a color-vision deficiency and reads charts | An opt-in chart palette chosen to stay distinguishable under common forms of color-vision deficiency. | +| Prefers a dark interface for light sensitivity | A complete dark palette for each of the four shipped themes. | +| Uses a screen reader with a custom-styled form control | A styling utility that hides a native input visually while keeping it in the accessibility tree. | + +## Before You Start + +Two boundaries determine what you can rely on from this page. + +**The theming engine styles; it does not add semantics.** ARIA roles, keyboard handling, and focus management come from the component library, not from the theme. Applying a theme does not make a custom control accessible on its own. + +**The contrast guarantee applies to generated palette colors.** The engine calculates foreground colors for palettes produced by the `palette()` generator. Individual component themes may also pair a specific foreground token with a specific background token by hand; those pairings are set per theme and are not produced by the contrast calculation described below. When you override component tokens directly, verify the result with [`contrast()`](#check-a-contrast-ratio-yourself). + + +The capabilities on this page describe the theming engine's behavior. They are not a conformance statement for Ignite UI for Angular as a product. For per-component conformance information, see [Accessibility Compliance](../interactivity/accessibility-compliance.mdx). + + +## Next Steps + +- Use [`contrast-color()`](#guarantee-readable-text-on-a-brand-color) wherever you place text on a palette color, instead of hard-coding a foreground. +- Turn on the [color-vision-deficiency chart palette](#enable-the-color-vision-deficiency-chart-palette) if your application renders charts. +- Run any custom color pairing you introduce through [`contrast()`](#check-a-contrast-ratio-yourself) before shipping it. +- If you generate palettes with the [Theming MCP server](../ai/theming-mcp.mdx), it checks surface and gray contrast against WCAG thresholds as it builds them. + +## Available Tools + +The theming engine exposes these Sass functions and mixins for the accessibility behavior described on this page. + +| Tool | Signature | What it does | +|---|---|---| +| `contrast-color()` | `contrast-color($palette: null, $color: primary, $variant: 500, $opacity: null)` | Returns a readable foreground color for a palette color. Every argument is optional; omit `$palette` to resolve the shade through its CSS variable. | +| `adaptive-contrast()` | `adaptive-contrast($color)` | Returns a readable foreground color for any color you pass, including one held in a CSS variable. | +| `contrast()` | `contrast($background, $foreground)` | Returns the WCAG contrast ratio between two colors. | +| `luminance()` | `luminance($color)` | Returns a color's relative luminance, from `0` (black) to `1` (white). | +| `configure-colors()` | `configure-colors($enhanced-accessibility: null)` | Switches chart themes to the color-vision-deficiency palette. | +| `hide-default()` | `@include hide-default()` | Hides a native input visually while keeping it in the accessibility tree. | + +## Common Workflows + +### Guarantee readable text on a brand color + +Pair every background drawn from the palette with `contrast-color()` rather than a hard-coded `black` or `white`: + +```scss +.my-component { + background: color($color: 'primary', $variant: 500); + color: contrast-color($color: 'primary', $variant: 500); +} +``` + +The same pairing in plain CSS, using the variables the theme already emits: + +```css +.my-component { + background: var(--ig-primary-500); + color: var(--ig-primary-500-contrast); +} +``` + +For a color that does not come from the palette — a tenant color, a user preference, a value set at runtime — use `adaptive-contrast()`: + +```scss +.my-component { + --bg: #09f; + + background: var(--bg); + color: adaptive-contrast(var(--bg)); +} +``` + +`adaptive-contrast()` is a thin wrapper over a relative-color expression, so the same result is available without Sass. `--y-contrast` is defined by the theme: + +```css +.my-component { + --bg: #09f; + + background: var(--bg); + color: hsla(from color(from var(--bg) var(--y-contrast)) h 0 l / 1); +} +``` + +The calculation happens in the browser rather than at build time. If the background color changes after the stylesheet is compiled, the foreground color is recalculated to match, so the pairing survives runtime theme switching and per-tenant branding. + + +`adaptive-contrast()` selects between black and white. Because those are the two available outcomes, the ratio the mechanism can achieve against a mid-tone background is bounded at roughly 4.6:1. That satisfies the WCAG AA threshold of 4.5:1 for normal text, which is the default the engine is configured for. Do not rely on this mechanism alone to reach the 7:1 AAA threshold; reaching AAA requires choosing background colors that are light or dark enough to allow it. + + +### Set the contrast level + +The calculated foreground is measured against a WCAG threshold held in the `--ig-contrast-level` CSS variable, which defaults to `var(--ig-wcag-aa)`. Three levels are predefined: `a`, `aa`, and `aaa`. + +Set the level for the whole application when you generate the palette: + +```scss +@include palette($palette, $contrast-level: 'aaa'); +``` + +To raise the level for one part of the page only, override the variable on that scope: + +```css +.high-contrast-panel { + --ig-contrast-level: var(--ig-wcag-aaa); +} +``` + +The contrast level moves the luminance threshold at which the calculated foreground switches between black and white; it does not change which two colors can be chosen. See [Palettes](palettes.mdx) for the generated contrast variables. + +### Scale text with the user's browser settings + +No configuration is required. Every type scale in the four shipped themes expresses `font-size`, `line-height`, `letter-spacing`, and margins through the `rem()` function, so all emitted values are relative to the root font size. + +The library records the base size as a value you can read: + +```css +--ig-base-font-size: 16px; +``` + +It never emits a `html { font-size: … }` rule. This matters because writing that rule is the most common way a theming system overrides a user who has enlarged their default text. Because the library only reads the base size, a user who sets a larger default in their browser gets larger Ignite UI text. + +This addresses WCAG 2.1 1.4.4 Resize Text (Level AA) at the styling layer. + +### Raise or lower the contrast threshold + +The level at which the calculated foreground flips from black to white is held in a CSS variable, so it can be changed without Sass. It defaults to AA: + +```css +:root { + --ig-contrast-level: var(--ig-wcag-aaa); +} +``` + +From Sass, the `palette()` and `adaptive-contrast()` mixins take `a`, `aa`, or `aaa` directly. + +### Enable the color-vision-deficiency chart palette + +Charts commonly distinguish series by hue alone, which does not work for readers with a color-vision deficiency. The theming engine ships a second chart palette whose colors stay distinguishable under the common forms of that condition. + +The palette is **off by default**. Turn it on with `configure-colors()`: + +```scss +// Include at the top level, before your theme includes. +@include configure-colors($enhanced-accessibility: true); +``` + +Every chart theme then draws from the accessible set. The chart brushes are set when the theme is generated, so this one requires Sass; the prebuilt theme CSS exposes no variables for them. In Ignite UI for Angular the same switch is available at setup: + +```scss +@include core($enhanced-accessibility: true); +``` + + +Color alone should not be the only way a chart conveys meaning. Pair this palette with direct labels, distinct markers, or dash patterns so the chart also works in grayscale. + + +### Check a contrast ratio yourself + +The engine implements the WCAG relative-luminance formula and exposes it, so you can check your own color choices against the same implementation the library uses: + +```scss +$ratio: contrast(#09f, #000); // 7 +$lum: luminance(#09f); // 0.3 +``` + +Use this whenever you override a component token directly, or introduce a color pairing the palette generator did not produce. These two run at compile time and have no CSS equivalent - a stylesheet cannot compute a ratio. + +### Hide an input without hiding it from screen readers + +Custom-styled checkboxes, radios, and switches usually keep a native input underneath for semantics and keyboard behavior. Hide it with `hide-default()`: + +```scss +.my-checkbox input { + @include hide-default(); +} +``` + +The mixin expands to a fixed set of declarations, so it can be written directly in CSS: + +```css +.my-checkbox input { + position: absolute; + width: 1px; + height: 1px; + margin: -1px; + border: none; + clip: rect(0, 0, 0, 0); + outline: 0; + pointer-events: none; + overflow: hidden; + appearance: none; +} +``` + +The mixin moves the input out of view while leaving it in the accessibility tree, so it keeps its role, its keyboard behavior, and its screen-reader announcements. Using `display: none` or `visibility: hidden` instead removes the control from assistive technology entirely and breaks the component for anyone not using their eyes. + +### Use a dark theme + +Each of the four shipped themes — Material, Bootstrap, Fluent, and Indigo — provides a complete dark palette alongside its light one. Dark presentation is an accessibility need for some users, including those with light sensitivity, so treat it as a supported configuration rather than a cosmetic preference. See [Palettes](palettes.mdx) for how to select one. + +## Troubleshooting + +**Text on a component I restyled is hard to read.** You have likely replaced a background token without replacing its paired foreground token. Set the foreground with `contrast-color()` or `adaptive-contrast()` rather than a fixed value, then confirm the result with `contrast()`. + +**I set `$contrast-level: 'aaa'` but my colors did not change much.** The contrast level moves the luminance threshold at which the calculated foreground switches between black and white. It does not tint the foreground, so it cannot raise the achievable ratio past the bound described above. To reach AAA, change the background colors themselves. + +**My chart colors did not change after enabling the accessible palette.** `configure-colors()` must be included before the chart themes are generated. Move the include above your theme includes. + +**Text does not grow when I increase the browser font size.** Check your own application styles for an `html { font-size: … }` rule or `font-size` values in `px`. The theming engine does not emit either. + +## Additional Resources + +- [Palettes](palettes.mdx) — how palette colors and their contrast companions are generated. +- [Typography](typography.mdx) — the type scales and how to customize them. +- [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) — per-component conformance information. +- WCAG 2.1 Quick Reference — the success criteria referenced on this page. +- WAI-ARIA Authoring Practices — expected keyboard and ARIA behavior per interaction pattern. + +## FAQ + + + + No. The theming engine handles color contrast, text sizing, and chart palettes. Keyboard operability, ARIA semantics, and screen-reader support come from the component library and from your own markup. + + + + Yes, for colors used through the palette. The foreground color is calculated in the browser from the background's luminance, so it is recalculated whenever the background changes, including at runtime. + + + + It moves the luminance threshold at which the calculated foreground switches from black to white. It does not change the two colors that can be chosen, so it does not raise the maximum ratio the mechanism can reach. + + + + No. Enable it with configure-colors($enhanced-accessibility: true), or with core($enhanced-accessibility: true) at setup. + + + + No. Every type scale is already relative, and the library never sets the page font size. Check your own application styles if text does not scale. + + diff --git a/docs/angular/src/content/en/components/themes/palettes.mdx b/docs/angular/src/content/en/components/themes/palettes.mdx index 2349cbc1ac..cf00e2a1f0 100644 --- a/docs/angular/src/content/en/components/themes/palettes.mdx +++ b/docs/angular/src/content/en/components/themes/palettes.mdx @@ -60,17 +60,17 @@ Here's an excerpt of the `primary` variable color as declared in the Light Mater :root { //... --ig-primary-500: #09f; - --ig-primary-500-contrast: hsl(from color(from var(--ig-primary-500) var(--y-contrast)) h 0 l); + --ig-primary-500-contrast: hsla(from color(from var(--ig-primary-500) var(--y-contrast)) h 0 l / 1); --ig-primary-600: hsl(from var(--ig-primary-500) h calc(s * 1.26) calc(l * 0.89)); - --ig-primary-600-contrast: hsl(from color(from var(--ig-primary-600) var(--y-contrast)) h 0 l); + --ig-primary-600-contrast: hsla(from color(from var(--ig-primary-600) var(--y-contrast)) h 0 l / 1); --ig-primary-700: hsl(from var(--ig-primary-500) h calc(s * 1.26) calc(l * 0.81)); //... --ig-secondary-400: hsl(from var(--ig-secondary-500) h calc(s * 0.875) calc(l * 1.08)); - --ig-secondary-400-contrast: hsl(from color(from var(--ig-secondary-400) var(--y-contrast)) h 0 l); + --ig-secondary-400-contrast: hsla(from color(from var(--ig-secondary-400) var(--y-contrast)) h 0 l / 1); --ig-secondary-500: #df1b74; - --ig-secondary-500-contrast: hsl(from color(from var(--ig-secondary-500) var(--y-contrast)) h 0 l); + --ig-secondary-500-contrast: hsla(from color(from var(--ig-secondary-500) var(--y-contrast)) h 0 l / 1); --ig-secondary-600: hsl(from var(--ig-secondary-500) h calc(s * 1.26) calc(l * 0.89)); - --ig-secondary-600-contrast: hsl(from color(from var(--ig-secondary-600) var(--y-contrast)) h 0 l); + --ig-secondary-600-contrast: hsla(from color(from var(--ig-secondary-600) var(--y-contrast)) h 0 l / 1); //... --ig-wcag-a: 0.31; --ig-wcag-aa: 0.185; diff --git a/docs/angular/src/content/en/components/toc.json b/docs/angular/src/content/en/components/toc.json index cee884ad7d..3e5212eb1a 100644 --- a/docs/angular/src/content/en/components/toc.json +++ b/docs/angular/src/content/en/components/toc.json @@ -1806,6 +1806,11 @@ "href": "themes/spacing.mdx", "new": false }, + { + "name": "Accessibility", + "href": "themes/accessibility.mdx", + "new": true + }, { "name": "Sass", "new": false, diff --git a/docs/xplat/src/content/en/components/ai/theming-mcp.mdx b/docs/xplat/src/content/en/components/ai/theming-mcp.mdx index 8dd50be3cd..138235752d 100644 --- a/docs/xplat/src/content/en/components/ai/theming-mcp.mdx +++ b/docs/xplat/src/content/en/components/ai/theming-mcp.mdx @@ -275,6 +275,10 @@ To see the current full list of tools and their parameters at any time, ask your Here is a brief overview of each tool: + +When it generates a palette, the server checks the contrast ratio between your surface and gray colors against WCAG thresholds and warns you when the pairing falls short. See [Accessibility](../themes/accessibility.mdx) for the contrast behavior built into the theming engine itself. + + | Tool | Description | |------|-------------| | `detect_platform` | Identifies the project framework and selects the correct import paths and selectors. For Angular, React, and Web Components projects, reads `package.json`. For Blazor projects, which do not have a `package.json`, returns `generic` - tell the AI explicitly: _"Use the Blazor platform."_ | diff --git a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx index 90b08074cf..6b23904f17 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -1,199 +1,276 @@ --- -title: Ignite UI for {Platform} Accessibility Compliance | Ignite UI for {Platform} | Infragistics -description: Ignite UI for {Platform} Accessibility Support and Compliance - Section 508 Compliance, WCAG and ARIA . -keywords: accessibility, {Platform}, ignite ui for {Platform}, infragistics +title: "{Platform} Accessibility Compliance | {ProductName} | Infragistics" +description: "Accessibility support in {ProductName} - the standards we target, per-component keyboard and screen reader status, and how to report an accessibility issue." +keywords: "{ProductName}, Infragistics, Accessibility, WCAG, Section 508, EN 301 549, ARIA, Keyboard" license: MIT +last_updated: "2026-08-27" mentionedTypes: [] llms: - description: "As the leading global provider of UI and UX tools for developers, our {Platform} team at Infragistics is committed to providing components and tools that make it easier for you to create the best possible user experience." + description: "Accessibility support in {ProductName}: the conformance standards targeted, the per-component keyboard and screen-reader documentation index, required configuration, and the channel for reporting accessibility issues." --- + import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import PlatformBlock from 'igniteui-astro-components/components/mdx/PlatformBlock.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; + +# Accessibility Compliance - +Accessibility support is delivered by two layers — the components themselves and the theming engine that styles them. Use this page to find the status of a specific component; use [Theming Accessibility](../themes/accessibility.mdx) for contrast, text scaling, and chart color behavior. -# Accessibility Compliance + +**Scope of this page.** The information below reflects the **Default theme** and the current documented behavior of each component. It is a support summary, not a formal conformance statement. Custom themes, typography changes, and animation or color overrides can change the result. + + +## Standards We Target -As the leading global provider of UI and UX tools for developers, our {Platform} team at Infragistics is committed to providing components and tools that make it easier for you to create the best possible user experience. Our goal is to enable you to focus on crafting the best applications and the best user experience for all users. - -Here you can find specific information regarding the accessibility support and compliance for our {Platform} grids, charts, and UI components and controls within Ignite UI for {Platform}. - -## Section 508 Compliance - -[Section 508](http://www.section508.gov/) of the Rehabilitation Act was amended in 1998 by Congress to require all Federal agencies to make their electronic and information technology accessible to people with disabilities. Since then, Section 508 compliance has not only been a requirement in government agencies, but it's also important when providing software solutions and designing Web pages. - -Section 1194.22 of the Section 508 law specifically targets Web-based intranet and internet information and systems, and contains a set of 16 rules to follow. In order to enable you to keep your Web applications and Web sites compatible with these rules with minimal effort on your part, Infragistics has taken steps to ensure that the Ignite UI for {Platform} controls and components are compliant with the relevant accessibility rules. - -The matrix below provides a high-level outline of the accessibility support provided by our visual controls (and related components). To learn more about an individual control/component's accessibility compliance, click the name of the control/component. - -### Ignite UI for {Platform} Compliance with Section 508 - -|**Component/Principle**| (a)
|(b)
|(c)
|(d)
|(e)
|(f)
|(g)
|(h)
|(i)
|(j)
|(k)
|(l)
|(m)
|(n)
|(o)
|(p)
| -|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--| -|**Grids**||||||||||||||||| -| - Grid||||||||||*||||||| -| - HierarchicalGrid||||||||||*||||||| -| - TreeGrid||||||||||*||||||| -|**Other**||||||||||*||||||| -| - Avatar||||||||||||||||| -| - Badge||||||||||||||||| -| - Bottom navigation||||||||||*||||||| -| - Button||||||||||*||||||| -| - Button group||||||||||*||||||| -| - Calendar||||||||||*||||||| -| - Card||||||||||||||||| -| - Carousel||||||||||*||||||| -| - Checkbox||||||||||||||||| -| - Chip||||||||||*||||||| -| - Circular progress||||||||||*||||||| -| - Combo||||||||||*||||||| -| - Date time input||||||||||*||||||| -| - Date picker||||||||||*||||||| -| - Divider||||||||||||||||| -| - Dialog||||||||||*||||||| -| - Drop down||||||||||*||||||| -| - Expansion panel||||||||||*||||||| -| - Icon||||||||||||||||| -| - Input||||||||||||||||| -| - Input group||||||||||*||||||| -| - Linear progress||||||||||*||||||| -| - List||||||||||||||||| -| - Navbar||||||||||*||||||| -| - Navigation drawer||||||||||*||||||| -| - Radio group||||||||||||||||| -| - Radio||||||||||||||||| -| - Select||||||||||*||||||| -| - Slider||||||||||*||||||| -| - Snackbar||||||||||*||||||| -| - Switch||||||||||*||||||| -| - Tabs||||||||||*||||||| -| - Time picker||||||||||*||||||| -| - Toast||||||||||*||||||| - - -**LEGEND** - -|||| +| Standard | Region | What it requires | |---|---|---| -||The control/component is completely accessible in this particular area.|| -|*|The control/component is accessible in this particular area after implementing certain configurations| Example: Use **NoopAnimationsModule**utility module to allow disabling of animations| -||The control/component is not entirely accessible unless you perform some sort of action.|| -|'white space'|this particular rule does not apply to the control|| +| WCAG 2.1 Level AA | International | The success criteria listed below. The baseline referenced by the other two. | +| Section 508 (Revised) | United States | Federal procurement. Since the Revised Section 508 Standards (published 2017, compliance date January 2018) it incorporates WCAG 2.0 Level AA by reference, so it is satisfied by the same work. | +| EN 301 549 | Europe | The European standard referenced for ICT accessibility, built on WCAG. The European Accessibility Act, which builds on it, applies from 28 June 2025. | - -The table above is relevant only to the **Default theme** of Ignite UI for {Platform} theming library. The checklist compliance might be different when it comes to custom themes, typography and any visual changes related to animations and colors. + +Section 508 previously defined its own 16 rules under §1194.22. Those were superseded by the Revised Standards, which adopt WCAG directly. Targeting WCAG 2.1 Level AA therefore addresses all three frameworks above. -### Compliance Information - -- **a** - A text equivalent for every non-text element shall be provided (e.g., via "alt", "longdesc", or in element content). -- **b** - Equivalent alternatives for any multimedia presentation shall be synchronized with the presentation. -- **c** - Web pages shall be designed so that all information conveyed with color is also available without color, for example from context or markup. -- **d** - Documents shall be organized so they are readable without requiring an associated style sheet. -- **e** - Redundant text links shall be provided for each active region of a server-side image map. -- **f** - Client-side image maps shall be provided instead of server-side image maps except where the regions cannot be defined with an available geometric shape. -- **g** - Row and column headers shall be identified for data tables. -- **h** - Markup shall be used to associate data cells and header cells for data tables that have two or more logical levels of row or column headers. -- **i** - Frames shall be titled with text that facilitates frame identification and navigation. -- **j** - Pages shall be designed to avoid causing the screen to flicker with a frequency greater than 2 Hz and lower than 55 Hz. -- **k** - A text-only page, with equivalent information or functionality, shall be provided to make a web site comply with the provisions of this part, when compliance cannot be accomplished in any other way. The content of the text-only page shall be updated whenever the primary page changes. -- **l** - When pages utilize scripting languages to display content, or to create interface elements, the information provided by the script shall be identified with functional text that can be read by assistive technology. -- **m** - When a web page requires that an applet, plug-in or other application be present on the client system to interpret page content, the page must provide a link to a plug-in or applet that complies with §1194.21(a) through l. -- **n** - When electronic forms are designed to be completed on-line, the form shall allow people using assistive technology to access the information, field elements, and functionality required for completion and submission of the form, including all directions and cues. -- **o** - A method shall be provided that permits users to skip repetitive navigation links. -- **p** - When a timed response is required, the user shall be alerted and given sufficient time to indicate more time is required. - - -## WCAG compliance -[WCAG](https://www.w3.org/WAI/WCAG21/quickref/?showtechniques=111) is simply a set of formal guidelines on how to develop accessible web content. These standards represent a higher level of accessibility than 508 standards, although they are identical or very similar. WCAG focuses primarily on HTML accessibility. - -|**Component/Guideline**|1.1
|1.2
|1.3
|1.4
|2.1
|2.2
|2.3
|2.4
|2.5
|3.1
|3.2
|3.3
|4.1
| -|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--| -|**Grids**|||||||||||||| -| - Grid|||||||*||||*||| -| - HierarchicalGrid|||||||*||||*||| -| - TreeGrid|||||||*||||*||| -|**Other**|||||||*||||||| -| - Avatar|||||||||||*||| -| - Badge|||||||||||*||| -| - Banner||||||*|*||||*||| -| - Bottom navigation|||||||*||||*||| -| - Button|||||||*||||*||| -| - Button group|||||||*||||*||| -| - Calendar||||||*|*||||*||| -| - Card|||||||||||*||| -| - Carousel||||||*|*||||*||| -| - Checkbox|||||||||||*||| -| - Chip|||||||*||||*||| -| - Circular progress||||||*|*||||*||| -| - Combo||||||*|*||||*||| -| - Date time editor||||||*|*||||*||| -| - Date picker||||||*|*||||*||| -| - Divider|||||||||||*||| -| - Dialog||||||*|*||||*||| -| - Drop down||||||*|*||||*||| -| - Expansion panel||||||*|*||||*||| -| - Icon|||||||||||*||| -| - Input|||||||||||*||| -| - Input group|||||||*||||*||| -| - Label|||||||||||*||| -| - Linear progress||||||*|*||||*||| -| - List|||||||||||*||| -| - Month picker||||||*|*||||*||| -| - Navbar|||||||*||||*||| -| - Navigation drawer||||||*|*||||*||| -| - Radio group|||||||||||*||| -| - Radio|||||||||||*||| -| - Select||||||*|*||||*||| -| - Slider|||||||*||||*||| -| - Snackbar||||||*|*||||*||| -| - Switch|||||||*||||*||| -| - Tabs|||||||*||||*||| -| - Time picker||||||*|*||||*||| -| - Toast||||||*|*||||*||| -| - Tooltip||||||*|*||||*||| - - -**Legend** - -|||| +### Success criteria that apply to UI components + +WCAG conformance is claimed against individual **success criteria**, not against the broader guidelines. These are the criteria that a UI component library can affect: + +| Criterion | Level | What it means for a component | +|---|:--:|---| +| 1.1.1 Non-text Content | A | Icons and images carry a text alternative. | +| 1.3.1 Info and Relationships | A | Structure conveyed visually is also conveyed in markup. | +| 1.3.2 Meaningful Sequence | A | Reading order matches visual order. | +| 1.4.3 Contrast (Minimum) | AA | Text meets 4.5:1 against its background. | +| 1.4.4 Resize Text | AA | Text scales to 200% without loss of content. | +| 1.4.11 Non-text Contrast | AA | Control boundaries and states meet 3:1. | +| 1.4.13 Content on Hover or Focus | AA | Tooltips and popovers are dismissible and persistent. | +| 2.1.1 Keyboard | A | All functionality is reachable by keyboard. | +| 2.1.2 No Keyboard Trap | A | Focus can always move back out. | +| 2.4.3 Focus Order | A | Tab order follows a meaningful sequence. | +| 2.4.7 Focus Visible | AA | The focused control is visibly indicated. | +| 2.5.3 Label in Name | A | The accessible name contains the visible label. | +| 3.2.1 On Focus | A | Focus alone does not trigger a change of context. | +| 3.2.2 On Input | A | Changing a value alone does not trigger a change of context. | +| 3.3.2 Labels or Instructions | A | Inputs carry labels or instructions. | +| 4.1.2 Name, Role, Value | A | Every control exposes a name, a role, and its current state. | + +## How Accessibility Is Delivered + +| Layer | Responsible for | Where it is documented | |---|---|---| -||The control/component is completely accessible in this particular area.|| -|*|The control/component is accessible in this particular area after implementing certain configurations|Example 1: Guideline 2.2. For certain components additional actions and time parameters should be set; Example 2: Guideline 2.3. Use **NoopAnimationsModule**utility module to allow disabling of animations;| -||The control/component is not entirely accessible unless you perform some sort of action.|| -|'white space'|this particular rule does not apply to the control|| +| **Component library** (`igniteui-angular` on Angular) | Keyboard operability, focus movement, ARIA roles and states, screen-reader announcements. | The index below, and each component topic. | +| **Theming engine** (`igniteui-theming`) | Color contrast, text sizing, chart color palettes, styling utilities for custom controls. | [Theming Accessibility](../themes/accessibility.mdx) | + +## Component Support + +This index records what each component's documentation covers today. **Not documented yet** means the component's own documentation does not describe this behavior — it is a statement about the documentation, not about the component. + +| Status | Meaning | +|---|---| +| **Documented** | The behavior is described in the component's own documentation, linked in the row. | +| **Requires configuration** | Available once the setting named in [Configuration Required](#configuration-required) is applied. | +| **Not documented yet** | The component's documentation does not yet describe this behavior. | + + + +| Component | Keyboard interaction | Screen reader / ARIA | Reference | +|---|---|---|---| +| [Grid](../grid/grid.mdx#keyboard-navigation) | Documented | Not documented yet | [Keyboard navigation](../grid/keyboard-navigation.mdx) | +| [Hierarchical Grid](../hierarchicalgrid/hierarchical-grid.mdx) | Documented | Not documented yet | [Keyboard navigation](../hierarchicalgrid/keyboard-navigation.mdx) | +| [Tree Grid](../treegrid/tree-grid.mdx) | Documented | Not documented yet | [Keyboard navigation](../treegrid/keyboard-navigation.mdx) | +| [Avatar](../layouts/avatar.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Badge](../inputs/badge.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Banner](../banner.mdx) | Not documented yet | Not documented yet | — | +| [Bottom Navigation](../tabs.mdx) | Not documented yet | Not documented yet | — | +| [Button](../button.mdx) | Not documented yet | Not documented yet | — | +| [Button Group](../inputs/button-group.mdx) | Not documented yet | Not documented yet | — | +| [Calendar](../calendar.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Card](../card.mdx) | Not documented yet | Not documented yet | — | +| [Carousel](../carousel.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Checkbox](../checkbox.mdx) | Not documented yet | Not documented yet | — | +| [Chip](../chip.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Circular Progress](../circular-progress.mdx) | Not documented yet | Not documented yet | — | +| [Combo](../combo.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Date Time Editor](../date-time-editor.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Date Picker](../date-picker.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Dialog](../dialog.mdx) | Not documented yet | Not documented yet | — | +| [Divider](../divider.mdx) | Not documented yet | Not documented yet | — | +| [Drop Down](../drop-down.mdx) | Not documented yet | Not documented yet | — | +| [Expansion Panel](../expansion-panel.mdx) | Not documented yet | Not documented yet | — | +| [Icon](../icon.mdx) | Not documented yet | Not documented yet | — | +| [Input Group](../input-group.mdx) | Not documented yet | Not documented yet | — | +| [Label](../label-input.mdx) | Not documented yet | Not documented yet | — | +| [Linear Progress](../linear-progress.mdx) | Not documented yet | Not documented yet | — | +| [List](../list.mdx) | Not documented yet | Not documented yet | — | +| [Month Picker](../month-picker.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Navbar](../navbar.mdx) | Not documented yet | Not documented yet | — | +| [Navigation Drawer](../navdrawer.mdx) | Not documented yet | Not documented yet | — | +| [Radio](../radio-button.mdx) | Not documented yet | Not documented yet | — | +| [Select](../select.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Slider](../slider/slider.mdx) | Not documented yet | Not documented yet | — | +| [Snackbar](../snackbar.mdx) | Not documented yet | Not documented yet | — | +| [Switch](../switch.mdx) | Not documented yet | Not documented yet | — | +| [Tabs](../tabs.mdx) | Not documented yet | Not documented yet | — | +| [Time Picker](../time-picker.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Toast](../toast.mdx) | Not documented yet | Not documented yet | — | +| [Tooltip](../tooltip.mdx#accessibility) | Documented | Not documented yet | See the topic's Accessibility section | + + + + + +| Component | Keyboard interaction | Screen reader / ARIA | Reference | +|---|---|---|---| +| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Hierarchical Grid](../grids/hierarchical-grid/overview.mdx) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Tree Grid](../grids/tree-grid/overview.mdx) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Tree](../grids/tree.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [List](../grids/list.mdx) | Not documented yet | Not documented yet | — | +| [Avatar](../layouts/avatar.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Badge](../inputs/badge.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Banner](../notifications/banner.mdx) | Not documented yet | Not documented yet | — | +| [Button](../inputs/button.mdx) | Not documented yet | Not documented yet | — | +| [Button Group](../inputs/button-group.mdx) | Not documented yet | Not documented yet | — | +| [Calendar](../scheduling/calendar.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Card](../layouts/card.mdx) | Not documented yet | Not documented yet | — | +| [Carousel](../layouts/carousel.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Checkbox](../inputs/checkbox.mdx) | Not documented yet | Not documented yet | — | +| [Chip](../inputs/chip.mdx) | Not documented yet | Not documented yet | — | +| [Circular Progress](../inputs/circular-progress.mdx) | Not documented yet | Not documented yet | — | +| [Combo](../inputs/combo/overview.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Date Time Input](../inputs/date-time-input.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Date Picker](../scheduling/date-picker.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Dialog](../notifications/dialog.mdx) | Not documented yet | Not documented yet | — | +| [Divider](../layouts/divider.mdx) | Not documented yet | Not documented yet | — | +| [Dock Manager](../layouts/dock-manager.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Dropdown](../inputs/dropdown.mdx) | Not documented yet | Not documented yet | — | +| [Expansion Panel](../layouts/expansion-panel.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| File Input | Documented | Documented | Available on Web Components; see the component topic | +| [Icon](../layouts/icon.mdx) | Not documented yet | Not documented yet | — | +| [Icon Button](../inputs/icon-button.mdx) | Not documented yet | Not documented yet | — | +| [Input](../inputs/input.mdx) | Not documented yet | Not documented yet | — | +| [Linear Progress](../inputs/linear-progress.mdx) | Not documented yet | Not documented yet | — | +| [Navbar](../menus/navbar.mdx) | Not documented yet | Not documented yet | — | +| [Navigation Drawer](../menus/navigation-drawer.mdx) | Not documented yet | Not documented yet | — | +| [Radio](../inputs/radio.mdx) | Not documented yet | Not documented yet | — | +| [Rating](../inputs/rating.mdx) | Not documented yet | Not documented yet | — | +| [Select](../inputs/select.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Slider](../inputs/slider.mdx) | Not documented yet | Not documented yet | — | +| [Snackbar](../notifications/snackbar.mdx) | Not documented yet | Not documented yet | — | +| [Stepper](../layouts/stepper.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Switch](../inputs/switch.mdx) | Not documented yet | Not documented yet | — | +| [Tabs](../layouts/tabs.mdx#keyboard-navigation) | Documented | Not documented yet | See the topic's Keyboard Navigation section | +| [Text Area](../inputs/text-area.mdx) | Not documented yet | Not documented yet | — | +| [Toast](../notifications/toast.mdx) | Not documented yet | Not documented yet | — | +| [Tooltip](../inputs/tooltip.mdx#accessibility--aria-support) | Documented | Documented | See the topic's Accessibility section | + + -The table above is relevant only to the **Default theme** of Ignite UI for {Platform} theming library. The checklist compliance might be different when it comes to custom themes, typography and any visual changes related to animations and colors. +Rows marked **Not documented yet** are a gap in this documentation, not a known defect. If you need a conformance answer for a specific component before the next review cycle, [open an issue](#reporting-an-accessibility-issue) and ask. + + +## Configuration Required + +Some accessibility outcomes depend on how you configure the application rather than on the component alone. + + + +| Concern | Criterion | What to configure | +|---|---|---| +| Animation and motion | 2.3.1 Three Flashes or Below | Provide `NoopAnimationsModule` from `@angular/platform-browser/animations` instead of `BrowserAnimationsModule` to disable Angular animations application-wide. | + + + + + +| Concern | Criterion | What to configure | +|---|---|---| +| Animation and motion | 2.3.1 Three Flashes or Below | No configuration required. The animation player reads the operating system's `prefers-reduced-motion: reduce` setting and plays animations with a duration of `0` when it is set. | + + + +The remaining items apply to every platform. + +| Concern | Criterion | What to configure | +|---|---|---| +| Time limits on transient messages | 2.2.1 Timing Adjustable | Components that auto-dismiss — such as Snackbar and Toast — expose a display-duration setting. Extend it, or disable auto-dismiss, so a user has time to read the message. | +| Color contrast after theming | 1.4.3 Contrast (Minimum) | Set foreground colors with `contrast-color()` or `adaptive-contrast()` rather than fixed values. See [Theming Accessibility](../themes/accessibility.mdx). | +| Accessible names on icon-only controls | 4.1.2 Name, Role, Value | Supply an accessible name in your own markup. A control showing only an icon has no name until you give it one. | + +## Formal Conformance Documentation + +This page is a documentation index, not a conformance claim. It records what our own documentation covers; it does not certify any component against a standard. + +For procurement, contract, or audit purposes — where a traceable, per-criterion conformance statement is required — request the current accessibility conformance report (VPAT) through your account manager or Infragistics support. Cite the product, version, and the standard the report must address (WCAG 2.1 Level AA, Section 508, or EN 301 549). + + +Earlier revisions of this page carried per-component conformance matrices. Those tables asserted a level of conformance that was not backed by a traceable, per-criterion assessment, and have been removed rather than restated. The conformance report is the authoritative source for that information. -### Compliance Information - -- **Principle 1 - Perceivable** - Information and user interface components must be presentable to users in ways they can perceive - - Guideline 1.1 – **Text Alternatives** - Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as large print, braille, speech, symbols or simpler language. - - Guideline 1.2 – **Time-based Media** - Provide alternatives for time-based media. - - Guideline 1.3 – **Adaptable** - Create content that can be presented in different ways (for example simpler layout) without losing information or structure. - - Guideline 1.4 – **Distinguishable** - Make it easier for users to see and hear content including separating foreground from background. -- **Principle 2 – Operable** - User interface components and navigation must be operable. - - Guideline 2.1 – **Keyboard Accessible** - Make all functionality available from a keyboard. - - Guideline 2.2 – **Enough Time** - Provide users enough time to read and use content. - - Guideline 2.3 – **Seizures and Physical Reactions** - Do not design content in a way that is known to cause seizures or physical reactions. - - Guideline 2.4 – **Navigable** - Provide ways to help users navigate, find content, and determine where they are. - - Guideline 2.5 – **Input Modalities** - Make it easier for users to operate functionality through various inputs beyond keyboard. -- **Principle 3 – Understandable** - Information and the operation of the user interface must be understandable. - - Guideline 3.1 – **Readable** - Make text content readable and understandable. - - Guideline 3.2 – **Predictable** - Make Web pages appear and operate in predictable ways. - - Guideline 3.3 – **Input Assistance** - Help users avoid and correct mistakes. -- **Principle 4 – Robust** - Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies. - - Guideline 4.1 – **Compatible** - Maximize compatibility with current and future user agents, including assistive technologies - - -## WAI-ARIA Support -In 2014 the W3C finalized their [WAI-ARIA specification](http://www.w3.org/TR/wai-aria/) which defined how to design Web content and Web applications to be more accessible to users with disabilities. +## Reporting an Accessibility Issue + +If you find an accessibility problem in a component, report it on the product issue tracker. + + + +github.com/IgniteUI/igniteui-angular/issues + + + + + +github.com/IgniteUI/igniteui-react/issues + + + + + +github.com/IgniteUI/igniteui-webcomponents/issues + + + + + +github.com/IgniteUI/igniteui-blazor/issues + + + +Include the component, the assistive technology and browser you used, the expected behavior, and the WCAG success criterion you believe is affected. Accessibility reports are triaged against the criteria listed above. + +## Additional Resources + +- [Theming Accessibility](../themes/accessibility.mdx) — contrast, text scaling, and chart palettes. +- WCAG 2.1 Quick Reference — all success criteria with techniques. +- WAI-ARIA Authoring Practices — expected keyboard and ARIA behavior per interaction pattern. +- Section 508 — United States federal procurement requirements. +- [Formal Conformance Documentation](#formal-conformance-documentation) — how to request a conformance report (VPAT) for procurement. + +## FAQ + + + + Conformance is a property of a finished application, not of a component library on its own. {ProductName} targets WCAG 2.1 Level AA and documents per-component behavior in the index above, but the markup, content, and configuration you add determine the result. Use the index above to check the components you rely on, and report anything that does not behave as documented. + + + + That status means the component's own documentation does not yet describe the behavior. It is not a statement that the component fails a criterion - it records what the documentation covers, so you can tell the difference between a behavior that is documented and one that is not. + + + + No. The Revised Section 508 Standards (published 2017, compliance date January 2018) replaced the earlier §1194.22 rules and adopt WCAG Level AA by reference, so meeting WCAG also addresses Section 508. + + + + Partly. Keyboard and ARIA behavior is unaffected by theming. Color contrast is not — overriding colors can move text below the required ratio. Verify custom palettes as described in Theming Accessibility. + + + + On the component's own topic, linked from the Reference column above. The grid family shares a dedicated keyboard navigation topic. + + diff --git a/docs/xplat/src/content/en/components/themes/accessibility.mdx b/docs/xplat/src/content/en/components/themes/accessibility.mdx new file mode 100644 index 0000000000..815137259c --- /dev/null +++ b/docs/xplat/src/content/en/components/themes/accessibility.mdx @@ -0,0 +1,276 @@ +--- +title: "{Platform} Styling and Themes | {Platform} Accessibility | Infragistics" +description: "How the {ProductName} theming engine supports accessibility - automatic text contrast, relative text scaling, and a color-vision-deficiency chart palette." +keywords: "{ProductName}, Infragistics, Accessibility, Contrast, WCAG, Styling, Themes" +license: MIT +last_updated: "2026-08-27" +mentionedTypes: [] +llms: + description: "{ProductName} calculates readable text colors at runtime, keeps every type scale relative, and ships an opt-in color-vision-deficiency chart palette." +--- + +{/*Twin topic: docs/angular/src/content/en/components/themes/accessibility.mdx covers Angular. The two are near-identical by design; apply substantive edits to both.*/} + +import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; +import Faq from 'igniteui-astro-components/components/mdx/Faq.astro'; +import FaqItem from 'igniteui-astro-components/components/mdx/FaqItem.astro'; + +# Accessibility in {ProductName} + +The {ProductName} theming engine builds accessibility into the styling layer: it calculates a readable text color for any background at runtime, expresses every type scale in relative units so text scales with the user's settings, and ships an opt-in color palette for readers with color-vision deficiency. + +## Overview + +Accessibility in {ProductName} is delivered by two layers that you configure independently: + +| Layer | What it is responsible for | Where it is documented | +|---|---|---| +| **Theming engine** (`igniteui-theming`) | Color contrast, text sizing, chart color palettes, and the styling utilities that keep custom controls reachable by assistive technology. | This page. | +| **Component library** | Keyboard operability, focus movement, ARIA roles and states, and screen-reader announcements. | [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) and each component topic. | + +This page covers the first layer. It describes capabilities that apply to every component you style with the theming engine, including components you build yourself on top of it. + +The table below summarizes what the theming engine does for the person ultimately using your application. + +| A person who… | What the theming engine provides | +|---|---| +| Needs readable text on colored buttons, chips, and badges | A readable foreground color is calculated in the browser for every palette color, including brand colors you supply. | +| Enlarges their default browser font size | Every type scale is expressed in relative units, and the library never pins the page font size. | +| Has a color-vision deficiency and reads charts | An opt-in chart palette chosen to stay distinguishable under common forms of color-vision deficiency. | +| Prefers a dark interface for light sensitivity | A complete dark palette for each of the four shipped themes. | +| Uses a screen reader with a custom-styled form control | A styling utility that hides a native input visually while keeping it in the accessibility tree. | + +## Before You Start + +Two boundaries determine what you can rely on from this page. + +**The theming engine styles; it does not add semantics.** ARIA roles, keyboard handling, and focus management come from the component library, not from the theme. Applying a theme does not make a custom control accessible on its own. + +**The contrast guarantee applies to generated palette colors.** The engine calculates foreground colors for palettes produced by the `palette()` generator. Individual component themes may also pair a specific foreground token with a specific background token by hand; those pairings are set per theme and are not produced by the contrast calculation described below. When you override component tokens directly, verify the result with [`contrast()`](#check-a-contrast-ratio-yourself). + + +The capabilities on this page describe the theming engine's behavior. They are not a conformance statement for {ProductName} as a product. For per-component conformance information, see [Accessibility Compliance](../interactivity/accessibility-compliance.mdx). + + +## Next Steps + +- Use [`contrast-color()`](#guarantee-readable-text-on-a-brand-color) wherever you place text on a palette color, instead of hard-coding a foreground. +- Turn on the [color-vision-deficiency chart palette](#enable-the-color-vision-deficiency-chart-palette) if your application renders charts. +- Run any custom color pairing you introduce through [`contrast()`](#check-a-contrast-ratio-yourself) before shipping it. +- If you generate palettes with the [Theming MCP server](../ai/theming-mcp.mdx), it checks surface and gray contrast against WCAG thresholds as it builds them. + +## Available Tools + +The theming engine exposes these Sass functions and mixins for the accessibility behavior described on this page. + + +These are Sass APIs: they need a Sass build with `igniteui-theming` resolvable from your load paths, as described in [Customizing with Sass](overview.mdx#customizing-with-sass). If you use the prebuilt theme CSS instead, you still get calculated contrast colors - pair each palette color with its `-contrast` variable, for example `var(--ig-primary-500-contrast)`, and set the threshold with `--ig-contrast-level`. The chart palette, `hide-default()`, and the `contrast()` and `luminance()` functions have no CSS-only equivalent. + + +| Tool | Signature | What it does | +|---|---|---| +| `contrast-color()` | `contrast-color($palette: null, $color: primary, $variant: 500, $opacity: null)` | Returns a readable foreground color for a palette color. Every argument is optional; omit `$palette` to resolve the shade through its CSS variable. | +| `adaptive-contrast()` | `adaptive-contrast($color)` | Returns a readable foreground color for any color you pass, including one held in a CSS variable. | +| `contrast()` | `contrast($background, $foreground)` | Returns the WCAG contrast ratio between two colors. | +| `luminance()` | `luminance($color)` | Returns a color's relative luminance, from `0` (black) to `1` (white). | +| `configure-colors()` | `configure-colors($enhanced-accessibility: null)` | Switches chart themes to the color-vision-deficiency palette. | +| `hide-default()` | `@include hide-default()` | Hides a native input visually while keeping it in the accessibility tree. | + +## Common Workflows + +### Guarantee readable text on a brand color + +Pair every background drawn from the palette with `contrast-color()` rather than a hard-coded `black` or `white`: + +```scss +.my-component { + background: color($color: 'primary', $variant: 500); + color: contrast-color($color: 'primary', $variant: 500); +} +``` + +The same pairing in plain CSS, using the variables the theme already emits: + +```css +.my-component { + background: var(--ig-primary-500); + color: var(--ig-primary-500-contrast); +} +``` + +For a color that does not come from the palette — a tenant color, a user preference, a value set at runtime — use `adaptive-contrast()`: + +```scss +.my-component { + --bg: #09f; + + background: var(--bg); + color: adaptive-contrast(var(--bg)); +} +``` + +`adaptive-contrast()` is a thin wrapper over a relative-color expression, so the same result is available without Sass. `--y-contrast` is defined by the theme: + +```css +.my-component { + --bg: #09f; + + background: var(--bg); + color: hsla(from color(from var(--bg) var(--y-contrast)) h 0 l / 1); +} +``` + +The calculation happens in the browser rather than at build time. If the background color changes after the stylesheet is compiled, the foreground color is recalculated to match, so the pairing survives runtime theme switching and per-tenant branding. + + +`adaptive-contrast()` selects between black and white. Because those are the two available outcomes, the ratio the mechanism can achieve against a mid-tone background is bounded at roughly 4.6:1. That satisfies the WCAG AA threshold of 4.5:1 for normal text, which is the default the engine is configured for. Do not rely on this mechanism alone to reach the 7:1 AAA threshold; reaching AAA requires choosing background colors that are light or dark enough to allow it. + + +### Set the contrast level + +The calculated foreground is measured against a WCAG threshold held in the `--ig-contrast-level` CSS variable, which defaults to `var(--ig-wcag-aa)`. Three levels are predefined: `a`, `aa`, and `aaa`. + +Set the level for the whole application when you generate the palette: + +```scss +@include palette($palette, $contrast-level: 'aaa'); +``` + +To raise the level for one part of the page only, override the variable on that scope: + +```css +.high-contrast-panel { + --ig-contrast-level: var(--ig-wcag-aaa); +} +``` + +The contrast level moves the luminance threshold at which the calculated foreground switches between black and white; it does not change which two colors can be chosen. See [Palettes](palettes.mdx) for the generated contrast variables. + +### Scale text with the user's browser settings + +No configuration is required. Every type scale in the four shipped themes expresses `font-size`, `line-height`, `letter-spacing`, and margins through the `rem()` function, so all emitted values are relative to the root font size. + +The library records the base size as a value you can read: + +```css +--ig-base-font-size: 16px; +``` + +It never emits a `html { font-size: … }` rule. This matters because writing that rule is the most common way a theming system overrides a user who has enlarged their default text. Because the library only reads the base size, a user who sets a larger default in their browser gets larger {ProductName} text. + +This addresses WCAG 2.1 1.4.4 Resize Text (Level AA) at the styling layer. + +### Raise or lower the contrast threshold + +The level at which the calculated foreground flips from black to white is held in a CSS variable, so it can be changed without Sass. It defaults to AA: + +```css +:root { + --ig-contrast-level: var(--ig-wcag-aaa); +} +``` + +From Sass, the `palette()` and `adaptive-contrast()` mixins take `a`, `aa`, or `aaa` directly. + +### Enable the color-vision-deficiency chart palette + +Charts commonly distinguish series by hue alone, which does not work for readers with a color-vision deficiency. The theming engine ships a second chart palette whose colors stay distinguishable under the common forms of that condition. + +The palette is **off by default**. Turn it on with `configure-colors()`: + +```scss +// Include at the top level, before your theme includes. +@include configure-colors($enhanced-accessibility: true); +``` + +Every chart theme then draws from the accessible set. The chart brushes are set when the theme is generated, so this one requires Sass; the prebuilt theme CSS exposes no variables for them. + + +Color alone should not be the only way a chart conveys meaning. Pair this palette with direct labels, distinct markers, or dash patterns so the chart also works in grayscale. + + +### Check a contrast ratio yourself + +The engine implements the WCAG relative-luminance formula and exposes it, so you can check your own color choices against the same implementation the library uses: + +```scss +$ratio: contrast(#09f, #000); // 7 +$lum: luminance(#09f); // 0.3 +``` + +Use this whenever you override a component token directly, or introduce a color pairing the palette generator did not produce. These two run at compile time and have no CSS equivalent - a stylesheet cannot compute a ratio. + +### Hide an input without hiding it from screen readers + +Custom-styled checkboxes, radios, and switches usually keep a native input underneath for semantics and keyboard behavior. Hide it with `hide-default()`: + +```scss +.my-checkbox input { + @include hide-default(); +} +``` + +The mixin expands to a fixed set of declarations, so it can be written directly in CSS: + +```css +.my-checkbox input { + position: absolute; + width: 1px; + height: 1px; + margin: -1px; + border: none; + clip: rect(0, 0, 0, 0); + outline: 0; + pointer-events: none; + overflow: hidden; + appearance: none; +} +``` + +The mixin moves the input out of view while leaving it in the accessibility tree, so it keeps its role, its keyboard behavior, and its screen-reader announcements. Using `display: none` or `visibility: hidden` instead removes the control from assistive technology entirely and breaks the component for anyone not using their eyes. + +### Use a dark theme + +Each of the four shipped themes — Material, Bootstrap, Fluent, and Indigo — provides a complete dark palette alongside its light one. Dark presentation is an accessibility need for some users, including those with light sensitivity, so treat it as a supported configuration rather than a cosmetic preference. See [Palettes](palettes.mdx) for how to select one. + +## Troubleshooting + +**Text on a component I restyled is hard to read.** You have likely replaced a background token without replacing its paired foreground token. Set the foreground with `contrast-color()` or `adaptive-contrast()` rather than a fixed value, then confirm the result with `contrast()`. + +**I set `$contrast-level: 'aaa'` but my colors did not change much.** The contrast level moves the luminance threshold at which the calculated foreground switches between black and white. It does not tint the foreground, so it cannot raise the achievable ratio past the bound described above. To reach AAA, change the background colors themselves. + +**My chart colors did not change after enabling the accessible palette.** `configure-colors()` must be included before the chart themes are generated. Move the include above your theme includes. + +**Text does not grow when I increase the browser font size.** Check your own application styles for an `html { font-size: … }` rule or `font-size` values in `px`. The theming engine does not emit either. + +## Additional Resources + +- [Palettes](palettes.mdx) — how palette colors and their contrast companions are generated. +- [Typography](typography.mdx) — the type scales and how to customize them. +- [Accessibility Compliance](../interactivity/accessibility-compliance.mdx) — per-component conformance information. +- WCAG 2.1 Quick Reference — the success criteria referenced on this page. +- WAI-ARIA Authoring Practices — expected keyboard and ARIA behavior per interaction pattern. + +## FAQ + + + + No. The theming engine handles color contrast, text sizing, and chart palettes. Keyboard operability, ARIA semantics, and screen-reader support come from the component library and from your own markup. + + + + Yes, for colors used through the palette. The foreground color is calculated in the browser from the background's luminance, so it is recalculated whenever the background changes, including at runtime. + + + + It moves the luminance threshold at which the calculated foreground switches from black to white. It does not change the two colors that can be chosen, so it does not raise the maximum ratio the mechanism can reach. + + + + No. Enable it with configure-colors($enhanced-accessibility: true). + + + + No. Every type scale is already relative, and the library never sets the page font size. Check your own application styles if text does not scale. + + diff --git a/docs/xplat/src/content/en/components/themes/overview.mdx b/docs/xplat/src/content/en/components/themes/overview.mdx index 10ebc70cbd..5d1219edf8 100644 --- a/docs/xplat/src/content/en/components/themes/overview.mdx +++ b/docs/xplat/src/content/en/components/themes/overview.mdx @@ -72,13 +72,16 @@ Changing the theme at runtime also requires you to replace the global stylesheet {ProductName} allows you to switch the component themes at runtime by using the `ConfigureTheme` function exported by the library. -Calling it and passing one of the four valid themes - `bootstrap`, `material`, `fluent`, or `indigo` as a string will change the loaded component styles; +It takes the theme as its first argument - `bootstrap`, `material`, `fluent`, or `indigo` - and an optional variant as its second, either `light` or `dark`. Omit the variant to keep the one currently active. ```ts import { configureTheme } from "igniteui-webcomponents"; // Sets material as the theme to be used by all components configureTheme("material"); + +// Sets material and switches to its dark variant +configureTheme("material", "dark"); ``` @@ -87,6 +90,26 @@ This only tells components to switch their internal styles to the desired theme, +## Customizing with Sass + +The theme files above are prebuilt CSS, and the topics in this section customize them by overriding CSS variables - see [Palettes](palettes.mdx), [Typography](typography.mdx), [Elevations](elevations.mdx), and [Configuration](configuration.mdx). That path needs no build configuration and covers most customization. + +Some capabilities are only reachable from Sass, because they run at compile time rather than through a variable. The contrast and chart-palette functions on the [Accessibility](accessibility.mdx) topic are the main example. To use them, install `igniteui-theming` and import it: + +```scss +@use 'igniteui-theming' as *; + +// Required for $material-type-scale, $indigo-type-scale, and similar preset variables +@use 'igniteui-theming/sass/typography/presets' as *; + +// Required for $material-elevations and $indigo-elevations +@use 'igniteui-theming/sass/elevations/presets' as *; +``` + + +If `@use 'igniteui-theming' as *;` does not resolve, your Sass compiler is missing `node_modules` in its load paths. Set `css.preprocessorOptions.scss.loadPaths` in Vite, or `sassOptions.loadPaths` in Next.js. + + ## API References diff --git a/docs/xplat/src/content/en/components/themes/palettes.mdx b/docs/xplat/src/content/en/components/themes/palettes.mdx index 438f3bcd08..52b731da0b 100644 --- a/docs/xplat/src/content/en/components/themes/palettes.mdx +++ b/docs/xplat/src/content/en/components/themes/palettes.mdx @@ -58,34 +58,45 @@ As the table above shows, the `gray` color doesn't include the `A100`, `A200`, ` On top of the aforementioned colors, we also include **Level AA** [WCAG](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) compliant `contrast` colors for each color variant. This means that you can safely use the corresponding `contrast` color variants as foreground colors for the base color variant. -Contrast colors are generated at build-time therefore overriding the CSS variables will not update the corresponding contrast colors. +Contrast colors are CSS relative colors calculated at runtime from the corresponding shade color, so overriding a base color variant updates its contrast color along with it. -Here's an excerpt of the `primary` color as declared in the Light Bootstrap Palette: +Here's an excerpt of the `primary` color as declared in the Light Material Palette: ```css :root { //... --ig-primary-500: #09f; - --ig-primary-500-contrast: black; + --ig-primary-500-contrast: hsla(from color(from var(--ig-primary-500) var(--y-contrast)) h 0 l / 1); + --ig-primary-seed: #09f; --ig-primary-600: hsl(from var(--ig-primary-500) h calc(s * 1.26) calc(l * 0.89)); - --ig-primary-600-contrast: black; + --ig-primary-600-contrast: hsla(from color(from var(--ig-primary-600) var(--y-contrast)) h 0 l / 1); --ig-primary-700: hsl(from var(--ig-primary-500) h calc(s * 1.26) calc(l * 0.81)); //... --ig-secondary-400: hsl(from var(--ig-secondary-500) h calc(s * 0.875) calc(l * 1.08)); - --ig-secondary-400-contrast: black; + --ig-secondary-400-contrast: hsla(from color(from var(--ig-secondary-400) var(--y-contrast)) h 0 l / 1); --ig-secondary-500: #df1b74; - --ig-secondary-500-contrast: white; + --ig-secondary-500-contrast: hsla(from color(from var(--ig-secondary-500) var(--y-contrast)) h 0 l / 1); --ig-secondary-600: hsl(from var(--ig-secondary-500) h calc(s * 1.26) calc(l * 0.89)); - --ig-secondary-600-contrast: white; + --ig-secondary-600-contrast: hsla(from color(from var(--ig-secondary-600) var(--y-contrast)) h 0 l / 1); //... + --ig-wcag-a: 0.31; + --ig-wcag-aa: 0.185; + --ig-wcag-aaa: 0.178; + --ig-contrast-level: var(--ig-wcag-aa); + --y: clamp(0, (y / var(--ig-contrast-level) - 1) * -infinity, 1); + --y-contrast: xyz-d65 var(--y) var(--y) var(--y); } ``` -All primary color variants are derived from one base variable color variant `--ig-primary-500`. The same goes for the other color variables `--ig-secondary-500`, `--ig-surface-500`, etc. The other variants are generated through the relative color function `hsl()` which takes the main variable color variant `500` and changes it's `staturation` and `lightness` according to the variable variant which is assigned on (`600`,`700`, etc.). We decided to use this approach as it allows us to modify all variants of the `primary`, `secondary`, `surface` and other colors at runtime. +All primary color variants are derived from one base variable color variant `--ig-primary-500`. The same goes for the other color variables `--ig-secondary-500`, `--ig-surface-500`, etc. The other variants are generated through the relative color function `hsl()` which takes the main variable color variant `500` and changes its `saturation` and `lightness` according to the variable variant which is assigned on (`600`,`700`, etc.). We decided to use this approach as it allows us to modify all variants of the `primary`, `secondary`, `surface` and other colors at runtime. - -Because the contrast colors are not generated at CSS runtime like the rest, if we change the main color variant(`500`), the contrast color would not be updated. We would need to change them manually. This behavior will be improved upon in an upcoming release, where the contrast colors will also be calculated at CSS runtime. +Alongside the numbered variants, each color exposes a `seed` variable that holds the base color the palette was generated from, unchanged. For `primary`, `secondary`, and the other chromatic colors the seed matches the `500` variant. For `gray` it does not: `--ig-gray-seed` records the color the grayscale was derived from - black or white, chosen from the surface color's luminance - while `--ig-gray-500` is a generated mid-tone. + +The contrast colors are calculated at CSS runtime from the base color's luminance and the chosen contrast level, picking the more readable of black or white. Because the calculation is part of the cascade, changing the main color variant (`500`) updates its contrast colors with it - no manual step is required. + + +The threshold is held in `--ig-contrast-level`, which defaults to `var(--ig-wcag-aa)`. Override it on any scope to switch to `var(--ig-wcag-a)` or `var(--ig-wcag-aaa)`. If you compile the themes from Sass instead of using the prebuilt CSS, the `palette` and `adaptive-contrast` mixins accept `a`, `aa`, or `aaa` directly - see [Accessibility](accessibility.mdx). ## Defining Palettes diff --git a/docs/xplat/src/content/en/toc.json b/docs/xplat/src/content/en/toc.json index 5839d7ff38..47a74ba361 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2764,6 +2764,14 @@ "name": "Styles", "href": "themes/styles.mdx" }, + { + "exclude": [ + "Angular" + ], + "name": "Accessibility", + "href": "themes/accessibility.mdx", + "new": true + }, { "name": "Custom Tailwind Classes", "href": "themes/tailwind.mdx",