From 0d336796f0d78e74f5e922bb802c2fa81ded992a Mon Sep 17 00:00:00 2001 From: desig9stein Date: Wed, 26 Aug 2026 13:58:10 +0300 Subject: [PATCH 01/11] docs(accessibility): update accessibility compliance documentation structure and content --- .../en/components/themes/accessibility.mdx | 205 +++++++++ .../src/content/en/components/toc.json | 5 + .../accessibility-compliance.mdx | 428 ++++++++++-------- .../en/components/themes/accessibility.mdx | 199 ++++++++ docs/xplat/src/content/en/toc.json | 8 + 5 files changed, 665 insertions(+), 180 deletions(-) create mode 100644 docs/angular/src/content/en/components/themes/accessibility.mdx create mode 100644 docs/xplat/src/content/en/components/themes/accessibility.mdx 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..aee1e86437 --- /dev/null +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -0,0 +1,205 @@ +--- +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-26 +llms: + description: "The Ignite UI for Angular theming engine calculates readable text colors at runtime, expresses every type scale in relative units, and ships an opt-in color-vision-deficiency palette for charts." +--- + +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 or zooms the page | 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. + +## Available Tools + +| Tool | Signature | What it does | +|---|---|---| +| `contrast-color()` | `contrast-color($palette, $color, $variant, $opacity)` | Returns a readable foreground color for a palette color. | +| `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)` | 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); +} +``` + +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)); +} +``` + +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. + + +### 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: + +```scss +--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](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html) (Level AA) at the styling layer. + +### 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, following the Okabe–Ito approach. + +The palette is **off by default**. Turn it on with `configure-colors()`: + +```scss +.enhanced-accessibility { + @include configure-colors($enhanced-accessibility: true); +} +``` + +Every chart theme then draws from the accessible set. 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. + +### 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 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](https://www.w3.org/WAI/WCAG21/quickref/) — the success criteria referenced on this page. +- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) — 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/toc.json b/docs/angular/src/content/en/components/toc.json index 056691d8fc..660eefa967 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/interactivity/accessibility-compliance.mdx b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx index 90b08074cf..fcc6f404a0 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,267 @@ --- -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-26 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'; - +This page records the accessibility standards {ProductName} targets, what each component's own documentation covers today, and how to report an accessibility problem. -# 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. -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** - -|||| + +**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. For a formal Accessibility Conformance Report, see ‹VERIFY: VPAT / ACR link›. + + +## Standards We Target + +| 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](https://www.w3.org/WAI/WCAG21/quickref/) | International | The success criteria listed below. The baseline referenced by the other two. | +| [Section 508 (Revised)](https://www.section508.gov/) | United States | Federal procurement. Since the 2018 Revised Standards it incorporates WCAG 2.0 Level AA by reference, so it is satisfied by the same work. | +| [EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/) | European Union | The harmonised standard behind the European Accessibility Act, enforceable since 28 June 2025. Also built on WCAG. | - -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](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) | A | Icons and images carry a text alternative. | +| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) | A | Structure conveyed visually is also conveyed in markup. | +| [1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence.html) | A | Reading order matches visual order. | +| [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) | AA | Text meets 4.5:1 against its background. | +| [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html) | AA | Text scales to 200% without loss of content. | +| [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) | AA | Control boundaries and states meet 3:1. | +| [1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html) | AA | Tooltips and popovers are dismissible and persistent. | +| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) | A | All functionality is reachable by keyboard. | +| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) | A | Focus can always move back out. | +| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html) | A | Tab order follows a meaningful sequence. | +| [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html) | AA | The focused control is visibly indicated. | +| [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html) | A | The accessible name contains the visible label. | +| [3.2.1 On Focus](https://www.w3.org/WAI/WCAG21/Understanding/on-focus.html) | A | Focus alone does not trigger a change of context. | +| [3.2.2 On Input](https://www.w3.org/WAI/WCAG21/Understanding/on-input.html) | A | Changing a value alone does not trigger a change of context. | +| [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html) | A | Inputs carry labels or instructions. | +| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | 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 yet verified** means the behavior has not been assessed in the current review cycle — it is not a statement that the component fails. + +| 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 yet verified** | Not assessed in the current review cycle. | + + + +| Component | Keyboard interaction | Screen reader / ARIA | Reference | +|---|---|---|---| +| [Grid](../grid/grid.mdx#keyboard-navigation) | Documented | Not yet verified | [Keyboard navigation](../grid/keyboard-navigation.mdx) | +| [Hierarchical Grid](../hierarchicalgrid/hierarchical-grid.mdx) | Documented | Not yet verified | [Keyboard navigation](../hierarchicalgrid/keyboard-navigation.mdx) | +| [Tree Grid](../treegrid/tree-grid.mdx) | Documented | Not yet verified | [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 yet verified | Not yet verified | — | +| [Bottom Navigation](../tabs.mdx) | Not yet verified | Not yet verified | — | +| [Button](../button.mdx) | Not yet verified | Not yet verified | — | +| [Button Group](../button-group.mdx) | Not yet verified | Not yet verified | — | +| [Calendar](../calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Card](../card.mdx) | Not yet verified | Not yet verified | — | +| [Carousel](../carousel.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Checkbox](../checkbox.mdx) | Not yet verified | Not yet verified | — | +| [Chip](../chip.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Circular Progress](../circular-progress.mdx) | Not yet verified | Not yet verified | — | +| [Combo](../combo.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Date Time Editor](../date-time-editor.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Date Picker](../date-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Dialog](../dialog.mdx) | Not yet verified | Not yet verified | — | +| [Divider](../divider.mdx) | Not yet verified | Not yet verified | — | +| [Drop Down](../drop-down.mdx) | Not yet verified | Not yet verified | — | +| [Expansion Panel](../expansion-panel.mdx) | Not yet verified | Not yet verified | — | +| [Icon](../icon.mdx) | Not yet verified | Not yet verified | — | +| [Input Group](../input-group.mdx) | Not yet verified | Not yet verified | — | +| [Label](../label-input.mdx) | Not yet verified | Not yet verified | — | +| [Linear Progress](../linear-progress.mdx) | Not yet verified | Not yet verified | — | +| [List](../list.mdx) | Not yet verified | Not yet verified | — | +| [Month Picker](../month-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Navbar](../navbar.mdx) | Not yet verified | Not yet verified | — | +| [Navigation Drawer](../navdrawer.mdx) | Not yet verified | Not yet verified | — | +| [Radio](../radio-button.mdx) | Not yet verified | Not yet verified | — | +| [Select](../select.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Slider](../slider/slider.mdx) | Not yet verified | Not yet verified | — | +| [Snackbar](../snackbar.mdx) | Not yet verified | Not yet verified | — | +| [Switch](../switch.mdx) | Not yet verified | Not yet verified | — | +| [Tabs](../tabs.mdx) | Not yet verified | Not yet verified | — | +| [Time Picker](../time-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Toast](../toast.mdx) | Not yet verified | Not yet verified | — | +| [Tooltip](../tooltip.mdx#accessibility) | Documented | Not yet verified | See the topic's Accessibility section | + + + + + +| Component | Keyboard interaction | Screen reader / ARIA | Reference | +|---|---|---|---| +| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | [Keyboard navigation](../grids/grid/keyboard-navigation.mdx) | +| [Hierarchical Grid](../grids/hierarchical-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Tree Grid](../grids/tree-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Tree](../grids/tree.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [List](../grids/list.mdx) | Not yet verified | Not yet verified | — | +| [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 yet verified | Not yet verified | — | +| [Button](../inputs/button.mdx) | Not yet verified | Not yet verified | — | +| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | +| [Calendar](../scheduling/calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Card](../layouts/card.mdx) | Not yet verified | Not yet verified | — | +| [Carousel](../layouts/carousel.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | +| [Checkbox](../inputs/checkbox.mdx) | Not yet verified | Not yet verified | — | +| [Chip](../inputs/chip.mdx) | Not yet verified | Not yet verified | — | +| [Circular Progress](../inputs/circular-progress.mdx) | Not yet verified | Not yet verified | — | +| [Combo](../inputs/combo/overview.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Date Time Input](../inputs/date-time-input.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Date Picker](../scheduling/date-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Dialog](../notifications/dialog.mdx) | Not yet verified | Not yet verified | — | +| [Divider](../layouts/divider.mdx) | Not yet verified | Not yet verified | — | +| [Dock Manager](../layouts/dock-manager.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Dropdown](../inputs/dropdown.mdx) | Not yet verified | Not yet verified | — | +| [Expansion Panel](../layouts/expansion-panel.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| File Input | Documented | Documented | Available on Web Components; see the component topic | +| [Icon](../layouts/icon.mdx) | Not yet verified | Not yet verified | — | +| [Icon Button](../inputs/icon-button.mdx) | Not yet verified | Not yet verified | — | +| [Input](../inputs/input.mdx) | Not yet verified | Not yet verified | — | +| [Linear Progress](../inputs/linear-progress.mdx) | Not yet verified | Not yet verified | — | +| [Navbar](../menus/navbar.mdx) | Not yet verified | Not yet verified | — | +| [Navigation Drawer](../menus/navigation-drawer.mdx) | Not yet verified | Not yet verified | — | +| [Radio](../inputs/radio.mdx) | Not yet verified | Not yet verified | — | +| [Rating](../inputs/rating.mdx) | Not yet verified | Not yet verified | — | +| [Select](../inputs/select.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Slider](../inputs/slider.mdx) | Not yet verified | Not yet verified | — | +| [Snackbar](../notifications/snackbar.mdx) | Not yet verified | Not yet verified | — | +| [Stepper](../layouts/stepper.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Switch](../inputs/switch.mdx) | Not yet verified | Not yet verified | — | +| [Tabs](../layouts/tabs.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Text Area](../inputs/text-area.mdx) | Not yet verified | Not yet verified | — | +| [Toast](../notifications/toast.mdx) | Not yet verified | Not yet verified | — | +| [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 yet verified** 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. -### 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. +## 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](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) | 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](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) | Components that animate on open, close, and selection expose animation settings per component. Review them where a user may have set a reduced-motion preference. ‹VERIFY: global animation opt-out› | + + + +The remaining items apply to every platform. + +| Concern | Criterion | What to configure | +|---|---|---| +| Time limits on transient messages | [2.2.1 Timing Adjustable](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html) | 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)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) | 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](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | Supply an accessible name in your own markup. A control showing only an icon has no name until you give it one. | + +## 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](https://github.com/IgniteUI/igniteui-angular/issues) + + + + + +[github.com/IgniteUI/igniteui-react/issues](https://github.com/IgniteUI/igniteui-react/issues) + + + + + +[github.com/IgniteUI/igniteui-webcomponents/issues](https://github.com/IgniteUI/igniteui-webcomponents/issues) + + + + + +[github.com/IgniteUI/igniteui-blazor/issues](https://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. + +For procurement or conformance enquiries, contact ‹VERIFY: accessibility contact address›. + +## Additional Resources + +- [Theming Accessibility](../themes/accessibility.mdx) — contrast, text scaling, and chart palettes. +- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) — all success criteria with techniques. +- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) — expected keyboard and ARIA behavior per interaction pattern. +- [Section 508](https://www.section508.gov/) — United States federal procurement requirements. + +## 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. For a formal report, request the Accessibility Conformance Report. + + + + That status means the behavior has not been assessed in the current review cycle. It is not a statement that the component fails a criterion. It is recorded honestly so you can tell the difference between a verified result and an unreviewed one. + + + + No. The 2018 Revised Standards 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..2faf31a6f2 --- /dev/null +++ b/docs/xplat/src/content/en/components/themes/accessibility.mdx @@ -0,0 +1,199 @@ +--- +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-26 +mentionedTypes: [] +llms: + description: "The {ProductName} theming engine calculates readable text colors at runtime, expresses every type scale in relative units, and ships an opt-in color-vision-deficiency palette for charts." +--- + +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 or zooms the page | 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. + +## Available Tools + +| Tool | Signature | What it does | +|---|---|---| +| `contrast-color()` | `contrast-color($palette, $color, $variant, $opacity)` | Returns a readable foreground color for a palette color. | +| `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)` | 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); +} +``` + +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)); +} +``` + +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. + + +### 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: + +```scss +--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](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html) (Level AA) at the styling layer. + +### 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, following the Okabe–Ito approach. + +The palette is **off by default**. Turn it on with `configure-colors()`: + +```scss +.enhanced-accessibility { + @include configure-colors($enhanced-accessibility: true); +} +``` + +Every chart theme then draws from the accessible set. + + +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. + +### 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 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](https://www.w3.org/WAI/WCAG21/quickref/) — the success criteria referenced on this page. +- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) — 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/toc.json b/docs/xplat/src/content/en/toc.json index 2d3207de85..c5a9c6efac 100644 --- a/docs/xplat/src/content/en/toc.json +++ b/docs/xplat/src/content/en/toc.json @@ -2765,6 +2765,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", From 952ac4ce5a5d6c63c4c8282d2a6c12bdbc08956a Mon Sep 17 00:00:00 2001 From: RadoMirchev Date: Wed, 26 Aug 2026 18:56:13 +0300 Subject: [PATCH 02/11] review: rado-agent-review --- .../content/en/components/themes/accessibility.mdx | 13 ++++++++----- .../content/en/components/themes/accessibility.mdx | 13 ++++++++----- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/angular/src/content/en/components/themes/accessibility.mdx b/docs/angular/src/content/en/components/themes/accessibility.mdx index aee1e86437..5fdc89e234 100644 --- a/docs/angular/src/content/en/components/themes/accessibility.mdx +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -5,7 +5,7 @@ keywords: accessibility, contrast, WCAG, theming, color, typography, Ignite UI f license: MIT last_updated: 2026-08-26 llms: - description: "The Ignite UI for Angular theming engine calculates readable text colors at runtime, expresses every type scale in relative units, and ships an opt-in color-vision-deficiency palette for charts." + 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." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; @@ -35,7 +35,7 @@ The table below summarizes what the theming engine does for the person ultimatel | 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 or zooms the page | Every type scale is expressed in relative units, and the library never pins the page font size. | +| 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. | @@ -60,6 +60,8 @@ The capabilities on this page describe the theming engine's behavior. They are n ## 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, $color, $variant, $opacity)` | Returns a readable foreground color for a palette color. | @@ -117,12 +119,13 @@ This addresses WCAG 2.1 [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG21/Unders 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, following the Okabe–Ito approach. +{/* TODO: verify the Okabe-Ito attribution above before the next release. A code search for "Okabe" across the IgniteUI GitHub org returns no hits, and packages/theming/sass/color/_charts.scss documents the palette only as "color-blind brushes"; the shipped values are also only partly Okabe-Ito. Either cite a source or drop "following the Okabe-Ito approach". */} + The palette is **off by default**. Turn it on with `configure-colors()`: ```scss -.enhanced-accessibility { - @include configure-colors($enhanced-accessibility: true); -} +// Include at the top level, before your theme includes. +@include configure-colors($enhanced-accessibility: true); ``` Every chart theme then draws from the accessible set. In Ignite UI for Angular the same switch is available at setup: diff --git a/docs/xplat/src/content/en/components/themes/accessibility.mdx b/docs/xplat/src/content/en/components/themes/accessibility.mdx index 2faf31a6f2..a1a869b32b 100644 --- a/docs/xplat/src/content/en/components/themes/accessibility.mdx +++ b/docs/xplat/src/content/en/components/themes/accessibility.mdx @@ -6,7 +6,7 @@ license: MIT last_updated: 2026-08-26 mentionedTypes: [] llms: - description: "The {ProductName} theming engine calculates readable text colors at runtime, expresses every type scale in relative units, and ships an opt-in color-vision-deficiency palette for charts." + description: "{ProductName} calculates readable text colors at runtime, keeps every type scale relative, and ships an opt-in color-vision-deficiency chart palette." --- import DocsAside from 'igniteui-astro-components/components/mdx/DocsAside.astro'; @@ -33,7 +33,7 @@ The table below summarizes what the theming engine does for the person ultimatel | 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 or zooms the page | Every type scale is expressed in relative units, and the library never pins the page font size. | +| 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. | @@ -58,6 +58,8 @@ The capabilities on this page describe the theming engine's behavior. They are n ## 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, $color, $variant, $opacity)` | Returns a readable foreground color for a palette color. | @@ -115,12 +117,13 @@ This addresses WCAG 2.1 [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG21/Unders 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, following the Okabe–Ito approach. +{/* TODO: verify the Okabe-Ito attribution above before the next release. A code search for "Okabe" across the IgniteUI GitHub org returns no hits, and packages/theming/sass/color/_charts.scss documents the palette only as "color-blind brushes"; the shipped values are also only partly Okabe-Ito. Either cite a source or drop "following the Okabe-Ito approach". */} + The palette is **off by default**. Turn it on with `configure-colors()`: ```scss -.enhanced-accessibility { - @include configure-colors($enhanced-accessibility: true); -} +// Include at the top level, before your theme includes. +@include configure-colors($enhanced-accessibility: true); ``` Every chart theme then draws from the accessible set. From 16fb0670778aca5488e16bff80f541a4f18fe885 Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 27 Aug 2026 11:09:19 +0300 Subject: [PATCH 03/11] docs(palettes): correct xplat contrast color mechanism to runtime Contrast colors have been CSS runtime relative colors since igniteui-theming 1a22e1a; the xplat palettes topic still described the superseded build-time behavior and called runtime calculation an "upcoming release". - replace the build-time info aside and the stale "upcoming release" warning with the runtime behavior, plus how to change --ig-contrast-level - update the palette excerpt to the values igniteui-webcomponents actually ships, including the --ig-wcag-*, --y and --y-contrast machinery - label the excerpt as the Light Material Palette; the values shown are Material's, not Bootstrap's - fix "it's staturation" typo in the surrounding paragraph Co-Authored-By: Claude Opus 5 (1M context) --- .../content/en/components/themes/palettes.mdx | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/xplat/src/content/en/components/themes/palettes.mdx b/docs/xplat/src/content/en/components/themes/palettes.mdx index 438f3bcd08..808fc3e28e 100644 --- a/docs/xplat/src/content/en/components/themes/palettes.mdx +++ b/docs/xplat/src/content/en/components/themes/palettes.mdx @@ -58,34 +58,42 @@ 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-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. +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 From 077b68adc239f6feb8600ab5847d4a89d04ddffa Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 27 Aug 2026 11:11:53 +0300 Subject: [PATCH 04/11] docs(accessibility): update links to WCAG standards for improved accessibility reference --- .../en/components/themes/accessibility.mdx | 6 +- .../accessibility-compliance.mdx | 68 +++++++++---------- .../en/components/themes/accessibility.mdx | 6 +- 3 files changed, 39 insertions(+), 41 deletions(-) diff --git a/docs/angular/src/content/en/components/themes/accessibility.mdx b/docs/angular/src/content/en/components/themes/accessibility.mdx index 5fdc89e234..99857ea6a5 100644 --- a/docs/angular/src/content/en/components/themes/accessibility.mdx +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -113,7 +113,7 @@ The library records the base size as a value you can read: 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](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html) (Level AA) at the styling layer. +This addresses WCAG 2.1 1.4.4 Resize Text (Level AA) at the styling layer. ### Enable the color-vision-deficiency chart palette @@ -180,8 +180,8 @@ Each of the four shipped themes — Material, Bootstrap, Fluent, and Indigo — - [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](https://www.w3.org/WAI/WCAG21/quickref/) — the success criteria referenced on this page. -- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) — expected keyboard and ARIA behavior per interaction pattern. +- 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 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 fcc6f404a0..d718e29179 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -21,16 +21,16 @@ This page records the accessibility standards {ProductName} targets, what each c 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. -**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. For a formal Accessibility Conformance Report, see ‹VERIFY: VPAT / ACR link›. +**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 | Standard | Region | What it requires | |---|---|---| -| [WCAG 2.1 Level AA](https://www.w3.org/WAI/WCAG21/quickref/) | International | The success criteria listed below. The baseline referenced by the other two. | -| [Section 508 (Revised)](https://www.section508.gov/) | United States | Federal procurement. Since the 2018 Revised Standards it incorporates WCAG 2.0 Level AA by reference, so it is satisfied by the same work. | -| [EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/) | European Union | The harmonised standard behind the European Accessibility Act, enforceable since 28 June 2025. Also built on WCAG. | +| 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 2018 Revised Standards it incorporates WCAG 2.0 Level AA by reference, so it is satisfied by the same work. | +| EN 301 549 | European Union | The harmonised standard behind the European Accessibility Act, enforceable since 28 June 2025. Also built on WCAG. | 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. @@ -42,22 +42,22 @@ WCAG conformance is claimed against individual **success criteria**, not against | Criterion | Level | What it means for a component | |---|:--:|---| -| [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) | A | Icons and images carry a text alternative. | -| [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) | A | Structure conveyed visually is also conveyed in markup. | -| [1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence.html) | A | Reading order matches visual order. | -| [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) | AA | Text meets 4.5:1 against its background. | -| [1.4.4 Resize Text](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html) | AA | Text scales to 200% without loss of content. | -| [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) | AA | Control boundaries and states meet 3:1. | -| [1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html) | AA | Tooltips and popovers are dismissible and persistent. | -| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) | A | All functionality is reachable by keyboard. | -| [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html) | A | Focus can always move back out. | -| [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html) | A | Tab order follows a meaningful sequence. | -| [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html) | AA | The focused control is visibly indicated. | -| [2.5.3 Label in Name](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html) | A | The accessible name contains the visible label. | -| [3.2.1 On Focus](https://www.w3.org/WAI/WCAG21/Understanding/on-focus.html) | A | Focus alone does not trigger a change of context. | -| [3.2.2 On Input](https://www.w3.org/WAI/WCAG21/Understanding/on-input.html) | A | Changing a value alone does not trigger a change of context. | -| [3.3.2 Labels or Instructions](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html) | A | Inputs carry labels or instructions. | -| [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | A | Every control exposes a name, a role, and its current state. | +| 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 @@ -183,7 +183,7 @@ Some accessibility outcomes depend on how you configure the application rather t | Concern | Criterion | What to configure | |---|---|---| -| Animation and motion | [2.3.1 Three Flashes or Below](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) | Provide `NoopAnimationsModule` from `@angular/platform-browser/animations` instead of `BrowserAnimationsModule` to disable Angular animations application-wide. | +| 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. | @@ -191,7 +191,7 @@ Some accessibility outcomes depend on how you configure the application rather t | Concern | Criterion | What to configure | |---|---|---| -| Animation and motion | [2.3.1 Three Flashes or Below](https://www.w3.org/WAI/WCAG21/Understanding/three-flashes-or-below-threshold.html) | Components that animate on open, close, and selection expose animation settings per component. Review them where a user may have set a reduced-motion preference. ‹VERIFY: global animation opt-out› | +| 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. | @@ -199,9 +199,9 @@ The remaining items apply to every platform. | Concern | Criterion | What to configure | |---|---|---| -| Time limits on transient messages | [2.2.1 Timing Adjustable](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html) | 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)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) | 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](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) | Supply an accessible name in your own markup. A control showing only an icon has no name until you give it one. | +| 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. | ## Reporting an Accessibility Issue @@ -209,44 +209,42 @@ If you find an accessibility problem in a component, report it on the product is -[github.com/IgniteUI/igniteui-angular/issues](https://github.com/IgniteUI/igniteui-angular/issues) +github.com/IgniteUI/igniteui-angular/issues -[github.com/IgniteUI/igniteui-react/issues](https://github.com/IgniteUI/igniteui-react/issues) +github.com/IgniteUI/igniteui-react/issues -[github.com/IgniteUI/igniteui-webcomponents/issues](https://github.com/IgniteUI/igniteui-webcomponents/issues) +github.com/IgniteUI/igniteui-webcomponents/issues -[github.com/IgniteUI/igniteui-blazor/issues](https://github.com/IgniteUI/igniteui-blazor/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. -For procurement or conformance enquiries, contact ‹VERIFY: accessibility contact address›. - ## Additional Resources - [Theming Accessibility](../themes/accessibility.mdx) — contrast, text scaling, and chart palettes. -- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) — all success criteria with techniques. -- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) — expected keyboard and ARIA behavior per interaction pattern. -- [Section 508](https://www.section508.gov/) — United States federal procurement requirements. +- 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. ## 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. For a formal report, request the Accessibility Conformance Report. + 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. diff --git a/docs/xplat/src/content/en/components/themes/accessibility.mdx b/docs/xplat/src/content/en/components/themes/accessibility.mdx index a1a869b32b..9832324137 100644 --- a/docs/xplat/src/content/en/components/themes/accessibility.mdx +++ b/docs/xplat/src/content/en/components/themes/accessibility.mdx @@ -111,7 +111,7 @@ The library records the base size as a value you can read: 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](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html) (Level AA) at the styling layer. +This addresses WCAG 2.1 1.4.4 Resize Text (Level AA) at the styling layer. ### Enable the color-vision-deficiency chart palette @@ -174,8 +174,8 @@ Each of the four shipped themes — Material, Bootstrap, Fluent, and Indigo — - [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](https://www.w3.org/WAI/WCAG21/quickref/) — the success criteria referenced on this page. -- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) — expected keyboard and ARIA behavior per interaction pattern. +- 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 From 049d39da7bb5bece7162f9ee5eaa78308a6e11b5 Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 27 Aug 2026 11:19:49 +0300 Subject: [PATCH 05/11] docs(accessibility): remove unverified Okabe-Ito reference from chart palette description --- .../src/content/en/components/themes/accessibility.mdx | 4 +--- docs/xplat/src/content/en/components/themes/accessibility.mdx | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/angular/src/content/en/components/themes/accessibility.mdx b/docs/angular/src/content/en/components/themes/accessibility.mdx index 99857ea6a5..702d3456b8 100644 --- a/docs/angular/src/content/en/components/themes/accessibility.mdx +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -117,9 +117,7 @@ This addresses WCAG 2.1 Date: Thu, 27 Aug 2026 11:42:33 +0300 Subject: [PATCH 06/11] docs(accessibility): fix broken links in compliance documentation --- .../en/components/interactivity/accessibility-compliance.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 d718e29179..48680e8de4 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -88,7 +88,7 @@ This index records what each component's documentation covers today. **Not yet v | [Banner](../banner.mdx) | Not yet verified | Not yet verified | — | | [Bottom Navigation](../tabs.mdx) | Not yet verified | Not yet verified | — | | [Button](../button.mdx) | Not yet verified | Not yet verified | — | -| [Button Group](../button-group.mdx) | Not yet verified | Not yet verified | — | +| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | | [Calendar](../calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Card](../card.mdx) | Not yet verified | Not yet verified | — | | [Carousel](../carousel.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | @@ -126,7 +126,7 @@ This index records what each component's documentation covers today. **Not yet v | Component | Keyboard interaction | Screen reader / ARIA | Reference | |---|---|---|---| -| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | [Keyboard navigation](../grids/grid/keyboard-navigation.mdx) | +| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | [Keyboard navigation](../grids/_shared/keyboard-navigation.mdx) | | [Hierarchical Grid](../grids/hierarchical-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Tree Grid](../grids/tree-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Tree](../grids/tree.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | From 07b52115b04c5494098bec1b0fb4090fd4dbc916 Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 27 Aug 2026 12:04:04 +0300 Subject: [PATCH 07/11] docs(accessibility): clarify keyboard navigation reference in compliance table --- .../en/components/interactivity/accessibility-compliance.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 48680e8de4..2fd524afd4 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -126,7 +126,7 @@ This index records what each component's documentation covers today. **Not yet v | Component | Keyboard interaction | Screen reader / ARIA | Reference | |---|---|---|---| -| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | [Keyboard navigation](../grids/_shared/keyboard-navigation.mdx) | +| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Hierarchical Grid](../grids/hierarchical-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Tree Grid](../grids/tree-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Tree](../grids/tree.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | From 86b57b413b04674fad911e71cbdcab59005dedc8 Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 27 Aug 2026 12:06:11 +0300 Subject: [PATCH 08/11] lint(cspell): allow "harmonised" and "unreviewed" Both appear in the accessibility compliance topic and are correct as written: "harmonised" is the spelling used in the official EN 301 549 text, and "unreviewed" is a normal English word missing from the dictionary. Co-Authored-By: Claude Opus 5 (1M context) --- cspell.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/cspell.json b/cspell.json index d4117e45dd..b9d3a86fec 100644 --- a/cspell.json +++ b/cspell.json @@ -397,6 +397,8 @@ "agentic", "wireframes", "opensource", - "unlayered" + "unlayered", + "harmonised", + "unreviewed" ] } From 0c5a5e7b2cf4ba264360c31d0ffd69dd26a0db71 Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 27 Aug 2026 12:26:42 +0300 Subject: [PATCH 09/11] docs(accessibility): update last_updated date and clarify documentation status for components --- cspell.json | 3 +- .../en/components/themes/accessibility.mdx | 8 +- .../accessibility-compliance.mdx | 167 ++++++++++-------- .../en/components/themes/accessibility.mdx | 8 +- 4 files changed, 101 insertions(+), 85 deletions(-) diff --git a/cspell.json b/cspell.json index b9d3a86fec..b1c7c0b974 100644 --- a/cspell.json +++ b/cspell.json @@ -399,6 +399,7 @@ "opensource", "unlayered", "harmonised", - "unreviewed" + "unreviewed", + "VPAT" ] } diff --git a/docs/angular/src/content/en/components/themes/accessibility.mdx b/docs/angular/src/content/en/components/themes/accessibility.mdx index 702d3456b8..4b2578b6fb 100644 --- a/docs/angular/src/content/en/components/themes/accessibility.mdx +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -3,11 +3,13 @@ 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-26 +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'; @@ -64,11 +66,11 @@ The theming engine exposes these Sass functions and mixins for the accessibility | Tool | Signature | What it does | |---|---|---| -| `contrast-color()` | `contrast-color($palette, $color, $variant, $opacity)` | Returns a readable foreground color for a palette color. | +| `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)` | Switches chart themes to the color-vision-deficiency palette. | +| `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 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 2fd524afd4..97e190b03e 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -3,7 +3,7 @@ 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-26 +last_updated: "2026-08-27" mentionedTypes: [] llms: 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." @@ -68,57 +68,57 @@ WCAG conformance is claimed against individual **success criteria**, not against ## Component Support -This index records what each component's documentation covers today. **Not yet verified** means the behavior has not been assessed in the current review cycle — it is not a statement that the component fails. +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 yet verified** | Not assessed in the current review cycle. | +| **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 yet verified | [Keyboard navigation](../grid/keyboard-navigation.mdx) | -| [Hierarchical Grid](../hierarchicalgrid/hierarchical-grid.mdx) | Documented | Not yet verified | [Keyboard navigation](../hierarchicalgrid/keyboard-navigation.mdx) | -| [Tree Grid](../treegrid/tree-grid.mdx) | Documented | Not yet verified | [Keyboard navigation](../treegrid/keyboard-navigation.mdx) | +| [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 yet verified | Not yet verified | — | -| [Bottom Navigation](../tabs.mdx) | Not yet verified | Not yet verified | — | -| [Button](../button.mdx) | Not yet verified | Not yet verified | — | -| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | -| [Calendar](../calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Card](../card.mdx) | Not yet verified | Not yet verified | — | +| [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 yet verified | Not yet verified | — | -| [Chip](../chip.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Circular Progress](../circular-progress.mdx) | Not yet verified | Not yet verified | — | -| [Combo](../combo.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Date Time Editor](../date-time-editor.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Date Picker](../date-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Dialog](../dialog.mdx) | Not yet verified | Not yet verified | — | -| [Divider](../divider.mdx) | Not yet verified | Not yet verified | — | -| [Drop Down](../drop-down.mdx) | Not yet verified | Not yet verified | — | -| [Expansion Panel](../expansion-panel.mdx) | Not yet verified | Not yet verified | — | -| [Icon](../icon.mdx) | Not yet verified | Not yet verified | — | -| [Input Group](../input-group.mdx) | Not yet verified | Not yet verified | — | -| [Label](../label-input.mdx) | Not yet verified | Not yet verified | — | -| [Linear Progress](../linear-progress.mdx) | Not yet verified | Not yet verified | — | -| [List](../list.mdx) | Not yet verified | Not yet verified | — | -| [Month Picker](../month-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Navbar](../navbar.mdx) | Not yet verified | Not yet verified | — | -| [Navigation Drawer](../navdrawer.mdx) | Not yet verified | Not yet verified | — | -| [Radio](../radio-button.mdx) | Not yet verified | Not yet verified | — | -| [Select](../select.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Slider](../slider/slider.mdx) | Not yet verified | Not yet verified | — | -| [Snackbar](../snackbar.mdx) | Not yet verified | Not yet verified | — | -| [Switch](../switch.mdx) | Not yet verified | Not yet verified | — | -| [Tabs](../tabs.mdx) | Not yet verified | Not yet verified | — | -| [Time Picker](../time-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Toast](../toast.mdx) | Not yet verified | Not yet verified | — | -| [Tooltip](../tooltip.mdx#accessibility) | Documented | Not yet verified | 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 | @@ -126,53 +126,53 @@ This index records what each component's documentation covers today. **Not yet v | Component | Keyboard interaction | Screen reader / ARIA | Reference | |---|---|---|---| -| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Hierarchical Grid](../grids/hierarchical-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Tree Grid](../grids/tree-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Tree](../grids/tree.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [List](../grids/list.mdx) | Not yet verified | Not yet verified | — | +| [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 yet verified | Not yet verified | — | -| [Button](../inputs/button.mdx) | Not yet verified | Not yet verified | — | -| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | -| [Calendar](../scheduling/calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Card](../layouts/card.mdx) | Not yet verified | Not yet verified | — | +| [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 yet verified | Not yet verified | — | -| [Chip](../inputs/chip.mdx) | Not yet verified | Not yet verified | — | -| [Circular Progress](../inputs/circular-progress.mdx) | Not yet verified | Not yet verified | — | -| [Combo](../inputs/combo/overview.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Date Time Input](../inputs/date-time-input.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Date Picker](../scheduling/date-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Dialog](../notifications/dialog.mdx) | Not yet verified | Not yet verified | — | -| [Divider](../layouts/divider.mdx) | Not yet verified | Not yet verified | — | -| [Dock Manager](../layouts/dock-manager.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Dropdown](../inputs/dropdown.mdx) | Not yet verified | Not yet verified | — | -| [Expansion Panel](../layouts/expansion-panel.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation 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 yet verified | Not yet verified | — | -| [Icon Button](../inputs/icon-button.mdx) | Not yet verified | Not yet verified | — | -| [Input](../inputs/input.mdx) | Not yet verified | Not yet verified | — | -| [Linear Progress](../inputs/linear-progress.mdx) | Not yet verified | Not yet verified | — | -| [Navbar](../menus/navbar.mdx) | Not yet verified | Not yet verified | — | -| [Navigation Drawer](../menus/navigation-drawer.mdx) | Not yet verified | Not yet verified | — | -| [Radio](../inputs/radio.mdx) | Not yet verified | Not yet verified | — | -| [Rating](../inputs/rating.mdx) | Not yet verified | Not yet verified | — | -| [Select](../inputs/select.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Slider](../inputs/slider.mdx) | Not yet verified | Not yet verified | — | -| [Snackbar](../notifications/snackbar.mdx) | Not yet verified | Not yet verified | — | -| [Stepper](../layouts/stepper.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Switch](../inputs/switch.mdx) | Not yet verified | Not yet verified | — | -| [Tabs](../layouts/tabs.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Text Area](../inputs/text-area.mdx) | Not yet verified | Not yet verified | — | -| [Toast](../notifications/toast.mdx) | Not yet verified | Not yet verified | — | +| [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 | -Rows marked **Not yet verified** 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. +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 @@ -203,6 +203,16 @@ The remaining items apply to every platform. | 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. + + ## Reporting an Accessibility Issue If you find an accessibility problem in a component, report it on the product issue tracker. @@ -239,6 +249,7 @@ Include the component, the assistive technology and browser you used, the expect - 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 @@ -247,7 +258,7 @@ Include the component, the assistive technology and browser you used, the expect 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 behavior has not been assessed in the current review cycle. It is not a statement that the component fails a criterion. It is recorded honestly so you can tell the difference between a verified result and an unreviewed one. diff --git a/docs/xplat/src/content/en/components/themes/accessibility.mdx b/docs/xplat/src/content/en/components/themes/accessibility.mdx index ac9b8e8301..a68a2e3d47 100644 --- a/docs/xplat/src/content/en/components/themes/accessibility.mdx +++ b/docs/xplat/src/content/en/components/themes/accessibility.mdx @@ -3,12 +3,14 @@ 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-26 +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'; @@ -62,11 +64,11 @@ The theming engine exposes these Sass functions and mixins for the accessibility | Tool | Signature | What it does | |---|---|---| -| `contrast-color()` | `contrast-color($palette, $color, $variant, $opacity)` | Returns a readable foreground color for a palette color. | +| `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)` | Switches chart themes to the color-vision-deficiency palette. | +| `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 From 9b63d11a13a9a5bfa11748f951ce486bad13195a Mon Sep 17 00:00:00 2001 From: RadoMirchev Date: Thu, 27 Aug 2026 12:33:46 +0300 Subject: [PATCH 10/11] review(*): proposed-fixes --- cspell.json | 4 +--- .../en/components/themes/accessibility.mdx | 20 ++++++++++++++++++ .../content/en/components/themes/palettes.mdx | 10 ++++----- .../accessibility-compliance.mdx | 21 ++++++++++++------- .../en/components/themes/accessibility.mdx | 20 ++++++++++++++++++ 5 files changed, 59 insertions(+), 16 deletions(-) diff --git a/cspell.json b/cspell.json index b9d3a86fec..d4117e45dd 100644 --- a/cspell.json +++ b/cspell.json @@ -397,8 +397,6 @@ "agentic", "wireframes", "opensource", - "unlayered", - "harmonised", - "unreviewed" + "unlayered" ] } diff --git a/docs/angular/src/content/en/components/themes/accessibility.mdx b/docs/angular/src/content/en/components/themes/accessibility.mdx index 702d3456b8..c54c939863 100644 --- a/docs/angular/src/content/en/components/themes/accessibility.mdx +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -101,6 +101,26 @@ The calculation happens in the browser rather than at build time. If the backgro `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. 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/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx index 2fd524afd4..875d2d5be9 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -29,8 +29,8 @@ Accessibility support is delivered by two layers — the components themselves a | Standard | Region | What it requires | |---|---|---| | 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 2018 Revised Standards it incorporates WCAG 2.0 Level AA by reference, so it is satisfied by the same work. | -| EN 301 549 | European Union | The harmonised standard behind the European Accessibility Act, enforceable since 28 June 2025. Also built on WCAG. | +| 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. | 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. @@ -86,9 +86,9 @@ This index records what each component's documentation covers today. **Not yet v | [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 yet verified | Not yet verified | — | -| [Bottom Navigation](../tabs.mdx) | Not yet verified | Not yet verified | — | +| [Bottom Navigation](../tabbar.mdx) | Not yet verified | Not yet verified | — | | [Button](../button.mdx) | Not yet verified | Not yet verified | — | -| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | +| [Button Group](../inputs/button-group.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | | [Calendar](../calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Card](../card.mdx) | Not yet verified | Not yet verified | — | | [Carousel](../carousel.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | @@ -100,9 +100,11 @@ This index records what each component's documentation covers today. **Not yet v | [Date Picker](../date-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Dialog](../dialog.mdx) | Not yet verified | Not yet verified | — | | [Divider](../divider.mdx) | Not yet verified | Not yet verified | — | +| [Dock Manager](../dock-manager.mdx) | Not yet verified | Not yet verified | — | | [Drop Down](../drop-down.mdx) | Not yet verified | Not yet verified | — | | [Expansion Panel](../expansion-panel.mdx) | Not yet verified | Not yet verified | — | | [Icon](../icon.mdx) | Not yet verified | Not yet verified | — | +| [Icon Button](../icon-button.mdx) | Not yet verified | Not yet verified | — | | [Input Group](../input-group.mdx) | Not yet verified | Not yet verified | — | | [Label](../label-input.mdx) | Not yet verified | Not yet verified | — | | [Linear Progress](../linear-progress.mdx) | Not yet verified | Not yet verified | — | @@ -111,14 +113,17 @@ This index records what each component's documentation covers today. **Not yet v | [Navbar](../navbar.mdx) | Not yet verified | Not yet verified | — | | [Navigation Drawer](../navdrawer.mdx) | Not yet verified | Not yet verified | — | | [Radio](../radio-button.mdx) | Not yet verified | Not yet verified | — | +| [Rating](../rating.mdx) | Not yet verified | Not yet verified | — | | [Select](../select.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Slider](../slider/slider.mdx) | Not yet verified | Not yet verified | — | | [Snackbar](../snackbar.mdx) | Not yet verified | Not yet verified | — | +| [Stepper](../stepper.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Switch](../switch.mdx) | Not yet verified | Not yet verified | — | | [Tabs](../tabs.mdx) | Not yet verified | Not yet verified | — | | [Time Picker](../time-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Toast](../toast.mdx) | Not yet verified | Not yet verified | — | | [Tooltip](../tooltip.mdx#accessibility) | Documented | Not yet verified | See the topic's Accessibility section | +| [Tree](../tree.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | @@ -126,7 +131,7 @@ This index records what each component's documentation covers today. **Not yet v | Component | Keyboard interaction | Screen reader / ARIA | Reference | |---|---|---|---| -| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | +| [Grid](../grids/data-grid.mdx) | Documented | Not yet verified | [Keyboard navigation](../grids/data-grid.mdx#keyboard-navigation) | | [Hierarchical Grid](../grids/hierarchical-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Tree Grid](../grids/tree-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Tree](../grids/tree.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | @@ -135,7 +140,7 @@ This index records what each component's documentation covers today. **Not yet v | [Badge](../inputs/badge.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | | [Banner](../notifications/banner.mdx) | Not yet verified | Not yet verified | — | | [Button](../inputs/button.mdx) | Not yet verified | Not yet verified | — | -| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | +| [Button Group](../inputs/button-group.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | | [Calendar](../scheduling/calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | | [Card](../layouts/card.mdx) | Not yet verified | Not yet verified | — | | [Carousel](../layouts/carousel.mdx#accessibility) | Documented | Documented | See the topic's Accessibility section | @@ -248,11 +253,11 @@ Include the component, the assistive technology and browser you used, the expect - That status means the behavior has not been assessed in the current review cycle. It is not a statement that the component fails a criterion. It is recorded honestly so you can tell the difference between a verified result and an unreviewed one. + That status means the behavior has not been assessed in the current review cycle. It is not a statement that the component fails a criterion. It is recorded honestly so you can tell the difference between a verified result and one that has not been reviewed. - No. The 2018 Revised Standards replaced the earlier §1194.22 rules and adopt WCAG Level AA by reference, so meeting WCAG also addresses Section 508. + 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. diff --git a/docs/xplat/src/content/en/components/themes/accessibility.mdx b/docs/xplat/src/content/en/components/themes/accessibility.mdx index ac9b8e8301..f663cee3b0 100644 --- a/docs/xplat/src/content/en/components/themes/accessibility.mdx +++ b/docs/xplat/src/content/en/components/themes/accessibility.mdx @@ -99,6 +99,26 @@ The calculation happens in the browser rather than at build time. If the backgro `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. From e302453c2c18a0eb685aa13c509096cdc7e02d3c Mon Sep 17 00:00:00 2001 From: desig9stein Date: Thu, 27 Aug 2026 14:46:31 +0300 Subject: [PATCH 11/11] docs(accessibility): enhance documentation with additional contrast and theming details --- cspell.json | 3 +- .../content/en/components/ai/theming-mcp.mdx | 4 + .../en/components/themes/accessibility.mdx | 56 +++++++++++- .../content/en/components/ai/theming-mcp.mdx | 4 + .../accessibility-compliance.mdx | 90 +++++++++---------- .../en/components/themes/accessibility.mdx | 60 ++++++++++++- .../content/en/components/themes/overview.mdx | 25 +++++- .../content/en/components/themes/palettes.mdx | 3 + 8 files changed, 192 insertions(+), 53 deletions(-) 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 index 4c0350d47e..e0be1dbeba 100644 --- a/docs/angular/src/content/en/components/themes/accessibility.mdx +++ b/docs/angular/src/content/en/components/themes/accessibility.mdx @@ -59,6 +59,7 @@ The capabilities on this page describe the theming engine's behavior. They are n - 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 @@ -86,6 +87,15 @@ Pair every background drawn from the palette with `contrast-color()` rather than } ``` +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 @@ -97,6 +107,17 @@ For a color that does not come from the palette — a tenant color, a user prefe } ``` +`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. @@ -129,7 +150,7 @@ No configuration is required. Every type scale in the four shipped themes expres The library records the base size as a value you can read: -```scss +```css --ig-base-font-size: 16px; ``` @@ -137,6 +158,18 @@ It never emits a `html { font-size: … }` rule. This matters because writing th 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. @@ -148,7 +181,7 @@ The palette is **off by default**. Turn it on with `configure-colors()`: @include configure-colors($enhanced-accessibility: true); ``` -Every chart theme then draws from the accessible set. In Ignite UI for Angular the same switch is available at setup: +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); @@ -167,7 +200,7 @@ $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. +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 @@ -179,6 +212,23 @@ Custom-styled checkboxes, radios, and switches usually keep a native input under } ``` +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 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 b944bb3d1d..6b23904f17 100644 --- a/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx +++ b/docs/xplat/src/content/en/components/interactivity/accessibility-compliance.mdx @@ -85,40 +85,40 @@ This index records what each component's documentation covers today. **Not docum | [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 yet verified | Not yet verified | — | -| [Bottom Navigation](../tabs.mdx) | Not yet verified | Not yet verified | — | -| [Button](../button.mdx) | Not yet verified | Not yet verified | — | -| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | -| [Calendar](../calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Card](../card.mdx) | Not yet verified | Not yet verified | — | +| [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 yet verified | Not yet verified | — | -| [Chip](../chip.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Circular Progress](../circular-progress.mdx) | Not yet verified | Not yet verified | — | -| [Combo](../combo.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Date Time Editor](../date-time-editor.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Date Picker](../date-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Dialog](../dialog.mdx) | Not yet verified | Not yet verified | — | -| [Divider](../divider.mdx) | Not yet verified | Not yet verified | — | -| [Drop Down](../drop-down.mdx) | Not yet verified | Not yet verified | — | -| [Expansion Panel](../expansion-panel.mdx) | Not yet verified | Not yet verified | — | -| [Icon](../icon.mdx) | Not yet verified | Not yet verified | — | -| [Input Group](../input-group.mdx) | Not yet verified | Not yet verified | — | -| [Label](../label-input.mdx) | Not yet verified | Not yet verified | — | -| [Linear Progress](../linear-progress.mdx) | Not yet verified | Not yet verified | — | -| [List](../list.mdx) | Not yet verified | Not yet verified | — | -| [Month Picker](../month-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Navbar](../navbar.mdx) | Not yet verified | Not yet verified | — | -| [Navigation Drawer](../navdrawer.mdx) | Not yet verified | Not yet verified | — | -| [Radio](../radio-button.mdx) | Not yet verified | Not yet verified | — | -| [Select](../select.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Slider](../slider/slider.mdx) | Not yet verified | Not yet verified | — | -| [Snackbar](../snackbar.mdx) | Not yet verified | Not yet verified | — | -| [Switch](../switch.mdx) | Not yet verified | Not yet verified | — | -| [Tabs](../tabs.mdx) | Not yet verified | Not yet verified | — | -| [Time Picker](../time-picker.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Toast](../toast.mdx) | Not yet verified | Not yet verified | — | -| [Tooltip](../tooltip.mdx#accessibility) | Documented | Not yet verified | 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 | @@ -126,18 +126,18 @@ This index records what each component's documentation covers today. **Not docum | Component | Keyboard interaction | Screen reader / ARIA | Reference | |---|---|---|---| -| [Grid](../grids/data-grid.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Hierarchical Grid](../grids/hierarchical-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Tree Grid](../grids/tree-grid/overview.mdx) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Tree](../grids/tree.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [List](../grids/list.mdx) | Not yet verified | Not yet verified | — | +| [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 yet verified | Not yet verified | — | -| [Button](../inputs/button.mdx) | Not yet verified | Not yet verified | — | -| [Button Group](../inputs/button-group.mdx) | Not yet verified | Not yet verified | — | -| [Calendar](../scheduling/calendar.mdx#keyboard-navigation) | Documented | Not yet verified | See the topic's Keyboard Navigation section | -| [Card](../layouts/card.mdx) | Not yet verified | Not yet verified | — | +| [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 | — | @@ -258,8 +258,8 @@ Include the component, the assistive technology and browser you used, the expect 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 behavior has not been assessed in the current review cycle. It is not a statement that the component fails a criterion. It is recorded honestly so you can tell the difference between a verified result and an unreviewed one. + + 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. diff --git a/docs/xplat/src/content/en/components/themes/accessibility.mdx b/docs/xplat/src/content/en/components/themes/accessibility.mdx index 9aea15b412..815137259c 100644 --- a/docs/xplat/src/content/en/components/themes/accessibility.mdx +++ b/docs/xplat/src/content/en/components/themes/accessibility.mdx @@ -57,11 +57,16 @@ The capabilities on this page describe the theming engine's behavior. They are n - 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. | @@ -84,6 +89,15 @@ Pair every background drawn from the palette with `contrast-color()` rather than } ``` +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 @@ -95,6 +109,17 @@ For a color that does not come from the palette — a tenant color, a user prefe } ``` +`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. @@ -127,7 +152,7 @@ No configuration is required. Every type scale in the four shipped themes expres The library records the base size as a value you can read: -```scss +```css --ig-base-font-size: 16px; ``` @@ -135,6 +160,18 @@ It never emits a `html { font-size: … }` rule. This matters because writing th 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. @@ -146,7 +183,7 @@ The palette is **off by default**. Turn it on with `configure-colors()`: @include configure-colors($enhanced-accessibility: true); ``` -Every chart theme then draws from the accessible set. +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. @@ -161,7 +198,7 @@ $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. +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 @@ -173,6 +210,23 @@ Custom-styled checkboxes, radios, and switches usually keep a native input under } ``` +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 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 808fc3e28e..52b731da0b 100644 --- a/docs/xplat/src/content/en/components/themes/palettes.mdx +++ b/docs/xplat/src/content/en/components/themes/palettes.mdx @@ -68,6 +68,7 @@ Here's an excerpt of the `primary` color as declared in the Light Material Palet //... --ig-primary-500: #09f; --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: 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)); @@ -90,6 +91,8 @@ Here's an excerpt of the `primary` color as declared in the Light Material Palet 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. +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.