docs(accessibility): update accessibility compliance documentation stucture and content

cspell.json

@@ -397,6 +397,7 @@
     "agentic",
     "wireframes",
     "opensource",
-    "unlayered"
+    "unlayered",
+    "VPAT"
   ]
 }

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:
 
+<DocsAside type="info">
+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.
+</DocsAside>
+
 | 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."_ |

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;

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,

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:
 
+<DocsAside type="info">
+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.
+</DocsAside>
+
 | 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."_ |

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");
 ```
 
 <DocsAside type="info">
@@ -87,6 +90,26 @@ This only tells components to switch their internal styles to the desired theme,
 
 </PlatformBlock>
 
+## 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 *;
+```
+
+<DocsAside type="note">
+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.
+</DocsAside>
+
 <PlatformBlock for="React, WebComponents">
 
 ## API References

docs/xplat/src/content/en/components/themes/palettes.mdx

@@ -58,34 +58,45 @@ As the table above shows, the `gray` color doesn't include the `A100`, `A200`, `
 On top of the aforementioned colors, we also include **Level AA** [WCAG](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) compliant `contrast` colors for each color variant. This means that you can safely use the corresponding `contrast` color variants as foreground colors for the base color variant.
 
 <DocsAside type="info">
-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.
 </DocsAside>
 
-Here's an excerpt of the `primary` color as declared in the Light Bootstrap Palette:
+Here's an excerpt of the `primary` color as declared in the Light Material Palette:
 
 ```css
 :root {
   //...
   --ig-primary-500: #09f;
-  --ig-primary-500-contrast: black;
+  --ig-primary-500-contrast: hsla(from color(from var(--ig-primary-500) var(--y-contrast)) h 0 l / 1);
+  --ig-primary-seed: #09f;
   --ig-primary-600: hsl(from var(--ig-primary-500) h calc(s * 1.26) calc(l * 0.89));
-  --ig-primary-600-contrast: black;
+  --ig-primary-600-contrast: hsla(from color(from var(--ig-primary-600) var(--y-contrast)) h 0 l / 1);
   --ig-primary-700: hsl(from var(--ig-primary-500) h calc(s * 1.26) calc(l * 0.81));
   //...
   --ig-secondary-400: hsl(from var(--ig-secondary-500) h calc(s * 0.875) calc(l * 1.08));
-  --ig-secondary-400-contrast: black;
+  --ig-secondary-400-contrast: hsla(from color(from var(--ig-secondary-400) var(--y-contrast)) h 0 l / 1);
   --ig-secondary-500: #df1b74;
-  --ig-secondary-500-contrast: white;
+  --ig-secondary-500-contrast: hsla(from color(from var(--ig-secondary-500) var(--y-contrast)) h 0 l / 1);
   --ig-secondary-600: hsl(from var(--ig-secondary-500) h calc(s * 1.26) calc(l * 0.89));
-  --ig-secondary-600-contrast: white;
+  --ig-secondary-600-contrast: hsla(from color(from var(--ig-secondary-600) var(--y-contrast)) h 0 l / 1);
   //...
+  --ig-wcag-a: 0.31;
+  --ig-wcag-aa: 0.185;
+  --ig-wcag-aaa: 0.178;
+  --ig-contrast-level: var(--ig-wcag-aa);
+  --y: clamp(0, (y / var(--ig-contrast-level) - 1) * -infinity, 1);
+  --y-contrast: xyz-d65 var(--y) var(--y) var(--y);
 }
 ```
 
-All primary color variants are derived from one base variable color variant `--ig-primary-500`. The same goes for the other color variables `--ig-secondary-500`, `--ig-surface-500`, etc. The other variants are generated through the relative color function `hsl()` which takes the main variable color variant `500` and changes it's `staturation` and `lightness` according to the variable variant which is assigned on (`600`,`700`, etc.). We decided to use this approach as it allows us to modify all variants of the `primary`, `secondary`, `surface` and other colors at runtime.
+All primary color variants are derived from one base variable color variant `--ig-primary-500`. The same goes for the other color variables `--ig-secondary-500`, `--ig-surface-500`, etc. The other variants are generated through the relative color function `hsl()` which takes the main variable color variant `500` and changes its `saturation` and `lightness` according to the variable variant which is assigned on (`600`,`700`, etc.). We decided to use this approach as it allows us to modify all variants of the `primary`, `secondary`, `surface` and other colors at runtime.
 
-<DocsAside type="warning">
-Because the contrast colors are not generated at CSS runtime like the rest, if we change the main color variant(`500`), the contrast color would not be updated. We would need to change them manually. This behavior will be improved upon in an upcoming release, where the contrast colors will also be calculated at CSS runtime.
+Alongside the numbered variants, each color exposes a `seed` variable that holds the base color the palette was generated from, unchanged. For `primary`, `secondary`, and the other chromatic colors the seed matches the `500` variant. For `gray` it does not: `--ig-gray-seed` records the color the grayscale was derived from - black or white, chosen from the surface color's luminance - while `--ig-gray-500` is a generated mid-tone.
+
+The contrast colors are calculated at CSS runtime from the base color's luminance and the chosen contrast level, picking the more readable of black or white. Because the calculation is part of the cascade, changing the main color variant (`500`) updates its contrast colors with it - no manual step is required.
+
+<DocsAside type="info">
+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).
 </DocsAside>
 
 ## Defining Palettes

docs/xplat/src/content/en/toc.json

@@ -2764,6 +2764,14 @@
     "name": "Styles",
     "href": "themes/styles.mdx"
   },
+  {
+    "exclude": [
+      "Angular"
+    ],
+    "name": "Accessibility",
+    "href": "themes/accessibility.mdx",
+    "new": true
+  },
   {
     "name": "Custom Tailwind Classes",
     "href": "themes/tailwind.mdx",