Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: add component accessibility guidance (#5713)

rubyycheunga32c01136be2
diff --git a/.changeset/add-component-accessibility-coverage.md b/.changeset/add-component-accessibility-coverage.md
new file mode 100644
index 0000000000..c51d45ee72
--- /dev/null
+++ b/.changeset/add-component-accessibility-coverage.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[feature] Add structured accessibility requirements and theme coverage support to component documentation.
+@rubyycheung
diff --git a/apps/docsite/AGENTS.md b/apps/docsite/AGENTS.md
new file mode 100644
index 0000000000..337781a09c
--- /dev/null
+++ b/apps/docsite/AGENTS.md
@@ -0,0 +1,8 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+
+**Keep this block, including in commits.** It is part of the project's agent setup, maintained by `next dev` for every agent that works here. If it appears as an uncommitted change, that is intentional — commit it as-is. Do not remove it to clean up a diff; it will be regenerated.
+<!-- END:nextjs-agent-rules -->
diff --git a/apps/docsite/CLAUDE.md b/apps/docsite/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/apps/docsite/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 2f292e71d0..072ad19df3 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -726,6 +726,68 @@ export interface BestPractice {
description: string;
}
+export interface AccessibilityRequirement {
+ name: string;
+ description: string;
+ category?: 'Color contrast' | 'Keyboard' | 'Semantics' | 'Content';
+ criterion?: string;
+ requirement?: string;
+ states?: string[];
+}
+
+export type AccessibilityThemeStatus = 'Pass' | 'Fail' | 'Not tested';
+
+export type AccessibilityThemeApplicability =
+ | 'Required'
+ | 'Conditional'
+ | 'Supplemental'
+ | 'Decorative';
+
+export interface AccessibilityThemeMeasurement {
+ label: string;
+ value: string;
+ detail?: string;
+ applicability?: AccessibilityThemeApplicability;
+ colorPair?: {
+ foreground: string;
+ background: string;
+ };
+ breakdown?: Array<{
+ label: string;
+ value: string;
+ detail?: string;
+ colorPair: {
+ foreground: string;
+ background: string;
+ };
+ status?: 'Pass' | 'Fail';
+ }>;
+ status?: 'Pass' | 'Fail';
+}
+
+export interface AccessibilityThemeResult {
+ name: string;
+ measurements: AccessibilityThemeMeasurement[];
+ status: AccessibilityThemeStatus;
+}
+
+export interface AccessibilityThemeMode {
+ mode: 'Light' | 'Dark';
+ results: AccessibilityThemeResult[];
+}
+
+export interface AccessibilityThemeTable {
+ title?: string;
+ description?: string;
+ modes: AccessibilityThemeMode[];
+}
+
+export interface AccessibilityThemeCoverage {
+ theme: string;
+ tables: AccessibilityThemeTable[];
+ notMeasured?: string[];
+}
+
export interface AnatomyElement {
name: string;
required: boolean;
@@ -737,7 +799,8 @@ export interface UsageDoc {
bestPractices?: BestPractice[];
anatomy?: AnatomyElement[];
features?: string[];
- accessibility?: string[];
+ accessibility?: AccessibilityRequirement[];
+ accessibilityThemeCoverage?: AccessibilityThemeCoverage[];
keyboard?: string;
notes?: string[];
}
diff --git a/apps/docsite/src/__tests__/component-detail-wiring.test.ts b/apps/docsite/src/__tests__/component-detail-wiring.test.ts
index dc559e5595..176143a1d9 100644
--- a/apps/docsite/src/__tests__/component-detail-wiring.test.ts
+++ b/apps/docsite/src/__tests__/component-detail-wiring.test.ts
@@ -129,4 +129,76 @@ describe('component detail wiring', () => {
}
}
});
+ it('carries component accessibility requirements into the registry', () => {
+ const button = Object.values(components)
+ .flat()
+ .find(entry => entry.name === 'Button');
+
+ expect(button?.usage?.accessibility?.length).toBeGreaterThan(0);
+ expect(button?.usage?.accessibility?.[0]).toMatchObject({
+ category: 'Color contrast',
+ requirement: '4.5:1',
+ });
+ expect(button?.usage?.accessibility).toContainEqual(
+ expect.objectContaining({
+ name: 'Badge text',
+ requirement: '4.5:1',
+ }),
+ );
+ });
+
+ it('renders accessibility metadata in a dedicated tab', () => {
+ const source = fs.readFileSync(
+ path.join(DETAIL_DIR, 'ComponentDetailClient.tsx'),
+ 'utf8',
+ );
+
+ expect(source).toContain(
+ '<Tab value="accessibility" label="Accessibility" />',
+ );
+ expect(source).toContain('themeCoverage={accessibilityThemeCoverage}');
+ expect(source).toContain('componentName={comp.name}');
+
+ const accessibilitySource = fs.readFileSync(
+ path.join(DETAIL_DIR, 'Accessibility.tsx'),
+ 'utf8',
+ );
+ expect(accessibilitySource).toContain(
+ '`${componentName} ${themeName} theme ${mode.mode} mode contrast results`',
+ );
+ expect(accessibilitySource).not.toContain(
+ 'Neutral Button contrast results',
+ );
+ });
+
+ it('supports accessibility guidance across button-like components', () => {
+ const entries = Object.values(components).flat();
+ for (const name of [
+ 'IconButton',
+ 'ToggleButton',
+ 'ButtonGroup',
+ 'SegmentedControl',
+ ]) {
+ const component = entries.find(entry => entry.name === name);
+ expect(component?.usage?.accessibility?.length).toBeGreaterThan(0);
+ expect(component?.usage?.accessibility).toContainEqual(
+ expect.objectContaining({category: 'Color contrast'}),
+ );
+ }
+ });
+
+ it('uses clear button-family contrast terminology', () => {
+ const entries = Object.values(components).flat();
+ for (const name of [
+ 'Button',
+ 'IconButton',
+ 'ToggleButton',
+ 'ButtonGroup',
+ ]) {
+ const component = entries.find(entry => entry.name === name);
+ expect(component?.usage?.accessibility).toContainEqual(
+ expect.objectContaining({name: 'Essential icon or spinner arc'}),
+ );
+ }
+ });
});
diff --git a/apps/docsite/src/components/component-detail/Accessibility.tsx b/apps/docsite/src/components/component-detail/Accessibility.tsx
new file mode 100644
index 0000000000..41249d5673
--- /dev/null
+++ b/apps/docsite/src/components/component-detail/Accessibility.tsx
@@ -0,0 +1,586 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Accessibility.tsx
+ * @input Structured component accessibility requirements and audited theme coverage
+ * @output Renders the component detail Accessibility tab
+ * @position Component-detail tab content, selected by ComponentDetailClient
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {useState} from 'react';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Card} from '@astryxdesign/core/Card';
+import {Icon} from '@astryxdesign/core/Icon';
+import {IconButton} from '@astryxdesign/core/IconButton';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Link} from '@astryxdesign/core/Link';
+import {List, ListItem} from '@astryxdesign/core/List';
+import {Popover} from '@astryxdesign/core/Popover';
+import {Table, proportional, type TablePlugin} from '@astryxdesign/core/Table';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import type {
+ AccessibilityRequirement,
+ AccessibilityThemeCoverage,
+ AccessibilityThemeMode,
+} from '../../generated/componentRegistry';
+
+const CATEGORY_ORDER = [
+ 'Color contrast',
+ 'Keyboard',
+ 'Semantics',
+ 'Content',
+ 'General',
+] as const;
+
+const styles = stylex.create({
+ measurement: {
+ fontVariantNumeric: 'tabular-nums',
+ },
+ colorPair: {
+ alignItems: 'center',
+ borderColor: 'var(--color-border)',
+ borderRadius: 3,
+ borderStyle: 'solid',
+ borderWidth: 1,
+ display: 'inline-flex',
+ flexShrink: 0,
+ height: 22,
+ justifyContent: 'center',
+ width: 22,
+ },
+ colorPairForeground: {
+ borderColor: 'var(--color-border)',
+ borderRadius: '50%',
+ borderStyle: 'solid',
+ borderWidth: 1,
+ height: 10,
+ width: 10,
+ },
+ breakdownGrid: {
+ display: 'grid',
+ gap: 12,
+ gridTemplateColumns: {
+ default: 'repeat(2, minmax(0, 1fr))',
+ '@media (max-width: 480px)': '1fr',
+ },
+ },
+ breakdownItem: {
+ minWidth: 0,
+ },
+ breakdownTrigger: {
+ backgroundColor: 'transparent',
+ borderStyle: 'none',
+ color: 'var(--color-text-secondary)',
+ cursor: 'pointer',
+ fontFamily: 'inherit',
+ fontSize: 'inherit',
+ lineHeight: 'inherit',
+ padding: 0,
+ textAlign: 'start',
+ textDecoration: 'underline',
+ },
+});
+
+const fitTableStyle = {
+ tableLayout: 'fixed',
+ width: '100%',
+} as const;
+
+const responsiveCoverageTableStyle = {
+ ...fitTableStyle,
+ minWidth: 1100,
+} as const;
+
+function ColorPairPreview({
+ foreground,
+ background,
+}: {
+ foreground: string;
+ background: string;
+}) {
+ const label = `Foreground ${foreground} on background ${background}`;
+ return (
+ <span
+ role="img"
+ aria-label={label}
+ title={label}
+ {...stylex.props(styles.colorPair)}
+ style={{backgroundColor: background}}>
+ <span
+ {...stylex.props(styles.colorPairForeground)}
+ style={{backgroundColor: foreground}}
+ />
+ </span>
+ );
+}
+
+type MeasurementBreakdown = NonNullable<
+ AccessibilityThemeMode['results'][number]['measurements'][number]['breakdown']
+>;
+
+function MeasurementBreakdownPopover({
+ breakdown,
+ measurementLabel,
+ mode,
+ variant,
+}: {
+ breakdown: MeasurementBreakdown;
+ measurementLabel: string;
+ mode: AccessibilityThemeMode['mode'];
+ variant: string;
+}) {
+ const [isOpen, setIsOpen] = useState(false);
+ const isBadgeBreakdown = measurementLabel === 'Badges';
+ const breakdownName = isBadgeBreakdown ? 'Badge' : measurementLabel;
+ const triggerText = isBadgeBreakdown
+ ? `${breakdown.length} badge results`
+ : `${breakdown.length} results`;
+
+ return (
+ <Popover
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ hasCloseButton={false}
+ width="min(560px, calc(100vw - 32px))"
+ label={`${mode} mode ${variant} ${breakdownName} contrast details`}
+ content={
+ <VStack gap={3}>
+ <VStack gap={1}>
+ <HStack hAlign="between" vAlign="center" gap={3}>
+ <Text weight="bold">
+ {mode} mode · {variant} {breakdownName} coverage
+ </Text>
+ <IconButton
+ label="Close Badge coverage"
+ icon={<Icon icon="close" color="inherit" />}
+ variant="ghost"
+ size="sm"
+ onClick={() => setIsOpen(false)}
+ />
+ </HStack>
+ <Text type="supporting" color="secondary">
+ {isBadgeBreakdown
+ ? 'Lowest result for each built-in Badge across Rest, Hover, Pointer down, Page background, and Surface background combinations.'
+ : `Detailed results for ${measurementLabel}.`}
+ </Text>
+ </VStack>
+ <div {...stylex.props(styles.breakdownGrid)}>
+ {breakdown.map(item => {
+ const failed = item.status === 'Fail';
+ return (
+ <HStack
+ key={item.label}
+ gap={2}
+ vAlign="center"
+ xstyle={styles.breakdownItem}>
+ <ColorPairPreview {...item.colorPair} />
+ <VStack gap={0}>
+ <Text weight="bold">{item.label}</Text>
+ <Text
+ type="supporting"
+ style={
+ failed ? {color: 'var(--color-text-red)'} : undefined
+ }>
+ {item.value}
+ {item.detail ? ` · ${item.detail}` : ''}
+ </Text>
+ </VStack>
+ </HStack>
+ );
+ })}
+ </div>
+ </VStack>
+ }>
+ {triggerProps => (
+ <button
+ type="button"
+ {...triggerProps}
+ aria-label={`View all ${triggerText} for ${mode} mode ${variant}`}
+ {...stylex.props(styles.breakdownTrigger)}>
+ View all {triggerText}
+ </button>
+ )}
+ </Popover>
+ );
+}
+
+const WCAG_REFERENCES = {
+ '1.4.3': {
+ label: 'WCAG 1.4.3: Contrast (Minimum)',
+ href: 'https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html',
+ },
+ '1.4.11': {
+ label: 'WCAG 1.4.11: Non-text Contrast',
+ href: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html',
+ },
+} as const;
+
+function referencesFor(criterion: string) {
+ return Object.entries(WCAG_REFERENCES)
+ .filter(([number]) => criterion.includes(number))
+ .map(([, reference]) => reference);
+}
+
+function groupRequirements(requirements: AccessibilityRequirement[]) {
+ const groups = new Map<string, AccessibilityRequirement[]>();
+ for (const requirement of requirements) {
+ const category = requirement.category ?? 'General';
+ const group = groups.get(category) ?? [];
+ group.push(requirement);
+ groups.set(category, group);
+ }
+ return [...groups.entries()].sort(
+ ([a], [b]) =>
+ CATEGORY_ORDER.indexOf(a as (typeof CATEGORY_ORDER)[number]) -
+ CATEGORY_ORDER.indexOf(b as (typeof CATEGORY_ORDER)[number]),
+ );
+}
+
+function RequirementsTable({items}: {items: AccessibilityRequirement[]}) {
+ const data = items.map(item => ({
+ name: item.name as unknown,
+ criterion: (item.criterion ?? '—') as unknown,
+ requirement: (item.requirement ?? '—') as unknown,
+ states: (item.states ?? []) as unknown,
+ description: item.description as unknown,
+ })) as Record<string, unknown>[];
+
+ return (
+ <Card>
+ <Table
+ data={data}
+ columns={[
+ {
+ key: 'name',
+ header: 'Requirement',
+ width: proportional(1.2, {minWidth: 0}),
+ renderCell: (item: Record<string, unknown>) => (
+ <Text weight="bold">{item.name as string}</Text>
+ ),
+ },
+ {
+ key: 'requirement',
+ header: 'Ratio',
+ width: proportional(1, {minWidth: 0}),
+ renderCell: (item: Record<string, unknown>) => (
+ <Text>{item.requirement as string}</Text>
+ ),
+ },
+ {
+ key: 'states',
+ header: 'Applies to',
+ width: proportional(1.1, {minWidth: 0}),
+ renderCell: (item: Record<string, unknown>) => {
+ const states = item.states as string[];
+ return (
+ <Text color="secondary">
+ {states.length > 0 ? states.join(', ') : '—'}
+ </Text>
+ );
+ },
+ },
+ {
+ key: 'description',
+ header: 'Guidance',
+ width: proportional(4.5, {minWidth: 0}),
+ renderCell: (item: Record<string, unknown>) => {
+ const references = referencesFor(item.criterion as string);
+ return (
+ <VStack gap={2}>
+ <Text>{item.description as string}</Text>
+ {references.length > 0 && (
+ <HStack gap={3} wrap="wrap">
+ {references.map(reference => (
+ <Link
+ key={reference.href}
+ href={reference.href}
+ type="supporting"
+ color="secondary"
+ hasUnderline
+ target="_blank">
+ {reference.label}
+ </Link>
+ ))}
+ </HStack>
+ )}
+ </VStack>
+ );
+ },
+ },
+ ]}
+ density="spacious"
+ dividers="rows"
+ style={fitTableStyle}
+ />
+ </Card>
+ );
+}
+
+function ThemeCoverageTable({
+ componentName,
+ mode,
+ themeName,
+}: {
+ componentName: string;
+ mode: AccessibilityThemeMode;
+ themeName: string;
+}) {
+ const accessibleName = `${componentName} ${themeName} theme ${mode.mode} mode contrast results`;
+ const accessibilityLabelPlugin: TablePlugin<Record<string, unknown>> = {
+ transformScrollWrapper: props => ({
+ ...props,
+ htmlProps: {...props.htmlProps, 'aria-label': accessibleName},
+ }),
+ };
+ const measurementLabels = [
+ ...new Set(
+ mode.results.flatMap(result =>
+ result.measurements.map(measurement => measurement.label),
+ ),
+ ),
+ ];
+ const data = mode.results.map(result => ({
+ name: result.name,
+ ...Object.fromEntries(
+ result.measurements.flatMap(measurement => [
+ [measurement.label, measurement.value],
+ [`${measurement.label}Detail`, measurement.detail],
+ [`${measurement.label}Applicability`, measurement.applicability],
+ [`${measurement.label}ColorPair`, measurement.colorPair],
+ [`${measurement.label}Breakdown`, measurement.breakdown],
+ [`${measurement.label}Status`, measurement.status],
+ ]),
+ ),
+ status: result.status,
+ }));
+
+ return (
+ <Card>
+ <VStack gap={3}>
+ <Text weight="bold">{mode.mode} mode</Text>
+ <Table
+ aria-label={accessibleName}
+ data={data}
+ plugins={{accessibilityLabel: accessibilityLabelPlugin}}
+ columns={[
+ {
+ key: 'name',
+ header: 'Variant',
+ width: proportional(1.2, {minWidth: 0}),
+ renderCell: (item: Record<string, unknown>) => (
+ <Text weight="bold">{item.name as string}</Text>
+ ),
+ },
+ {
+ key: 'status',
+ header: 'WCAG AA',
+ width: proportional(1.1, {minWidth: 0}),
+ renderCell: (item: Record<string, unknown>) => {
+ const status = item.status as 'Pass' | 'Fail' | 'Not tested';
+ return (
+ <Badge
+ label={status}
+ variant={
+ status === 'Pass'
+ ? 'success'
+ : status === 'Fail'
+ ? 'error'
+ : 'neutral'
+ }
+ />
+ );
+ },
+ },
+ ...measurementLabels.map(label => ({
+ key: label,
+ header: label,
+ width: proportional(label === 'Badges' ? 1.6 : 1, {minWidth: 0}),
+ renderCell: (item: Record<string, unknown>) => {
+ const failed = item[`${label}Status`] === 'Fail';
+ const detail = item[`${label}Detail`] as string | undefined;
+ const applicability = item[`${label}Applicability`] as
+ | 'Required'
+ | 'Conditional'
+ | 'Supplemental'
+ | 'Decorative'
+ | undefined;
+ const colorPair = item[`${label}ColorPair`] as
+ {foreground: string; background: string} | undefined;
+ const breakdown = item[`${label}Breakdown`] as
+ MeasurementBreakdown | undefined;
+ return (
+ <HStack gap={2} vAlign="center">
+ {colorPair && !breakdown && (
+ <ColorPairPreview {...colorPair} />
+ )}
+ <VStack gap={1}>
+ <Text
+ xstyle={styles.measurement}
+ style={
+ failed ? {color: 'var(--color-text-red)'} : undefined
+ }>
+ {(item[label] as string | undefined) ?? '—'}
+ </Text>
+ {(applicability || detail) && (
+ <Text
+ type="supporting"
+ color={failed ? undefined : 'secondary'}
+ style={
+ failed
+ ? {color: 'var(--color-text-red)'}
+ : undefined
+ }>
+ {[applicability, detail].filter(Boolean).join(' · ')}
+ </Text>
+ )}
+ {breakdown && (
+ <MeasurementBreakdownPopover
+ breakdown={breakdown}
+ measurementLabel={label}
+ mode={mode.mode}
+ variant={item.name as string}
+ />
+ )}
+ </VStack>
+ </HStack>
+ );
+ },
+ })),
+ ]}
+ density="compact"
+ dividers="rows"
+ style={responsiveCoverageTableStyle}
+ />
+ </VStack>
+ </Card>
+ );
+}
+
+function ThemeCoverageSection({
+ componentName,
+ items,
+}: {
+ componentName: string;
+ items: AccessibilityThemeCoverage[];
+}) {
+ return (
+ <VStack gap={5}>
+ {items.map(theme => (
+ <VStack key={theme.theme} gap={4}>
+ <VStack gap={2}>
+ <Heading level={2} accessibilityLevel={3}>
+ {theme.theme} Theme
+ </Heading>
+ <Text color="secondary" weight="normal">
+ These tables show the required contrast checks that were measured.
+ Pass means every measured value meets its WCAG AA ratio. Items
+ under Not measured do not affect Pass or Fail.
+ </Text>
+ </VStack>
+ {theme.tables.map((table, index) => (
+ <VStack key={table.title ?? `${theme.theme}-${index}`} gap={4}>
+ {(table.title || table.description) && (
+ <VStack gap={2}>
+ {table.title && <Heading level={4}>{table.title}</Heading>}
+ {table.description && (
+ <Text color="secondary" weight="normal">
+ {table.description}
+ </Text>
+ )}
+ </VStack>
+ )}
+ {table.modes.map(mode => (
+ <ThemeCoverageTable
+ key={mode.mode}
+ componentName={componentName}
+ mode={mode}
+ themeName={theme.theme}
+ />
+ ))}
+ </VStack>
+ ))}
+ {(theme.notMeasured?.length ?? 0) > 0 && (
+ <VStack gap={2}>
+ <Heading level={4}>Not measured</Heading>
+ <List density="compact" listStyle="disc">
+ {theme.notMeasured?.map(item => (
+ <ListItem
+ key={item}
+ label={
+ <Text color="secondary" weight="normal">
+ {item}
+ </Text>
+ }
+ />
+ ))}
+ </List>
+ </VStack>
+ )}
+ </VStack>
+ ))}
+ </VStack>
+ );
+}
+
+function ColorContrastIntro() {
+ return (
+ <Text color="secondary" weight="normal">
+ Components must meet WCAG 2.2 Level AA across variants, states, and
+ themes. Measure foreground and background colors as they appear together
+ on screen.
+ </Text>
+ );
+}
+
+export function Accessibility({
+ componentName,
+ requirements,
+ themeCoverage,
+}: {
+ componentName: string;
+ requirements: AccessibilityRequirement[];
+ themeCoverage: AccessibilityThemeCoverage[];
+}) {
+ const hasColorContrastRequirements = requirements.some(
+ requirement => requirement.category === 'Color contrast',
+ );
+
+ return (
+ <VStack gap={8} style={{paddingBlockStart: 16}}>
+ {groupRequirements(requirements).map(([category, items]) => (
+ <VStack key={category} gap={8}>
+ <VStack gap={3}>
+ <Heading level={2} type="display-3">
+ {category}
+ </Heading>
+ {category === 'Color contrast' && <ColorContrastIntro />}
+ <RequirementsTable items={items} />
+ </VStack>
+ {category === 'Color contrast' && themeCoverage.length > 0 && (
+ <ThemeCoverageSection
+ componentName={componentName}
+ items={themeCoverage}
+ />
+ )}
+ </VStack>
+ ))}
+ {!hasColorContrastRequirements && themeCoverage.length > 0 && (
+ <VStack gap={8}>
+ <VStack gap={3}>
+ <Heading level={2} type="display-3">
+ Color contrast
+ </Heading>
+ <ColorContrastIntro />
+ </VStack>
+ <ThemeCoverageSection
+ componentName={componentName}
+ items={themeCoverage}
+ />
+ </VStack>
+ )}
+ </VStack>
+ );
+}
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index 300d283bbc..276ed86b23 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -18,6 +18,7 @@ import {ComponentPreviewTheme} from './ComponentPreviewTheme';
import {Anatomy} from './Anatomy';
import {BestPractices} from './BestPractices';
import {Theming} from './Theming';
+import {Accessibility} from './Accessibility';
import {HookSignature} from './HookSignature';
import {ExampleBlock} from './ExampleBlock';
import {MarkdownText} from '../MarkdownText';
@@ -170,14 +171,21 @@ function ComponentDetailInner({
// themeable targets or CSS variables — never an empty tab.
const hasThemingTab =
CURRENT_TARGET === 'canary' && hasThemingContent(comp.theming);
- const hasTabs = hasPlayground || hasThemingTab;
+ const accessibilityRequirements = comp.usage?.accessibility ?? [];
+ const accessibilityThemeCoverage =
+ comp.usage?.accessibilityThemeCoverage ?? [];
+ const hasAccessibilityTab =
+ accessibilityRequirements.length > 0 ||
+ accessibilityThemeCoverage.length > 0;
+ const hasTabs = hasPlayground || hasThemingTab || hasAccessibilityTab;
const requestedTab = searchParams.get('tab') ?? 'overview';
// Clamp to a tab that actually exists for this component so a stale or
// hand-edited `?tab=` never lands on a blank panel.
const tab =
(requestedTab === 'properties' && hasPlayground) ||
- (requestedTab === 'theming' && hasThemingTab)
+ (requestedTab === 'theming' && hasThemingTab) ||
+ (requestedTab === 'accessibility' && hasAccessibilityTab)
? requestedTab
: 'overview';
const setTab = (value: string) => {
@@ -224,6 +232,9 @@ function ComponentDetailInner({
<Tab value="overview" label="Overview" />
{hasPlayground && <Tab value="properties" label="Properties" />}
{hasThemingTab && <Tab value="theming" label="Theming" />}
+ {hasAccessibilityTab && (
+ <Tab value="accessibility" label="Accessibility" />
+ )}
</TabList>
{tab === 'overview' && (
@@ -274,6 +285,14 @@ function ComponentDetailInner({
{tab === 'theming' && comp.theming && (
<Theming theming={comp.theming} props={comp.props} />
)}
+
+ {tab === 'accessibility' && hasAccessibilityTab && (
+ <Accessibility
+ componentName={comp.name}
+ requirements={accessibilityRequirements}
+ themeCoverage={accessibilityThemeCoverage}
+ />
+ )}
</>
) : (
<>
diff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.ts
index 221567c24e..a2ab8d221d 100644
--- a/packages/cli/authoring/doctypes/base/type.ts
+++ b/packages/cli/authoring/doctypes/base/type.ts
@@ -64,8 +64,96 @@ export interface ComponentBestPractice {
export interface ComponentAccessibilityRequirement {
/** Short scannable label, e.g. `"Accessible name"` or `"Loading"`. */
name: string;
- /** The accessibility contract consumers must preserve. */
+ /**
+ * The accessibility contract consumers must preserve. Write at about a
+ * grade-7 reading level with short sentences, common words, and active
+ * voice. For color contrast, put the ratio in `requirement`; name the exact
+ * foreground, background, state, and any overlay in `description`; explain
+ * exceptions in plain language; and include enough detail for a human or
+ * agent to reproduce the check.
+ */
description: string;
+ /** Groups related requirements in the docsite Accessibility tab. */
+ category?: 'Color contrast' | 'Keyboard' | 'Semantics' | 'Content';
+ /** Relevant WCAG success criterion, e.g. `"1.4.3 Contrast (Minimum)"`. */
+ criterion?: string;
+ /** Short threshold or rule, e.g. `"4.5:1"`, `"3:1"`, or `"Exempt"`. */
+ requirement?: string;
+ /** Component states covered by this requirement. */
+ states?: string[];
+}
+
+export type ComponentAccessibilityThemeStatus = 'Pass' | 'Fail' | 'Not tested';
+
+export type ComponentAccessibilityThemeApplicability =
+ 'Required' | 'Conditional' | 'Supplemental' | 'Decorative';
+
+export interface ComponentAccessibilityThemeMeasurement {
+ /** Column heading, e.g. `"Rest"` or `"Spinner"`. */
+ label: string;
+ /** Display value, e.g. `"15.13:1"`. */
+ value: string;
+ /** Optional supporting detail shown below the value, such as a worst case. */
+ detail?: string;
+ /**
+ * Whether this measurement is required for every use, required only in some
+ * contexts, shown as a supplemental cue, or decorative. Each theme declares
+ * this intent, informed by the component contract. Never infer it from the
+ * measured ratio. Non-required measurements do not determine row status.
+ */
+ applicability?: ComponentAccessibilityThemeApplicability;
+ /** Rendered foreground and background colors used for this measurement. */
+ colorPair?: {
+ foreground: string;
+ background: string;
+ };
+ /** Optional per-variant results shown from a compact details trigger. */
+ breakdown?: Array<{
+ label: string;
+ value: string;
+ detail?: string;
+ colorPair: {
+ foreground: string;
+ background: string;
+ };
+ status?: 'Pass' | 'Fail';
+ }>;
+ /** Mark a failed measurement so the docsite can emphasize it. */
+ status?: 'Pass' | 'Fail';
+}
+
+export interface ComponentAccessibilityThemeResult {
+ /** Row heading, usually a component variant. */
+ name: string;
+ /** Measurements shown between the row heading and status. */
+ measurements: ComponentAccessibilityThemeMeasurement[];
+ /** Overall result for the row. */
+ status: ComponentAccessibilityThemeStatus;
+}
+
+export interface ComponentAccessibilityThemeMode {
+ /** Theme mode covered by these results. */
+ mode: 'Light' | 'Dark';
+ /** Detailed results for the component in this mode. */
+ results: ComponentAccessibilityThemeResult[];
+}
+
+export interface ComponentAccessibilityThemeTable {
+ /** Optional heading for one complete group of measurements. */
+ title?: string;
+ /** Explains the scope of this measurement group. */
+ description?: string;
+ /** Detailed results separated by theme mode. */
+ modes: ComponentAccessibilityThemeMode[];
+}
+
+export interface ComponentAccessibilityThemeCoverage {
+ /** Display name of the audited theme. */
+ theme: string;
+ /** Complete groups of measurements for this theme and component. */
+ tables: ComponentAccessibilityThemeTable[];
+ /** Theme visuals intentionally excluded from measurement, with a reason. */
+ notMeasured?: string[];
}
/**
@@ -462,6 +550,8 @@ export interface UsageDoc {
/** Accessibility requirements specific to this component and its supported
* content combinations. Generic audit procedure stays in the wiki rubric. */
accessibility?: ComponentAccessibilityRequirement[];
+ /** Verified color-accessibility coverage for bundled themes. */
+ accessibilityThemeCoverage?: ComponentAccessibilityThemeCoverage[];
/** Structural/visual anatomy of the component. Each entry describes one
* element that makes up the component (icon slot, label, container, etc.).
* Order entries in the visual reading order (leading → trailing, top → bottom). */
diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjs
index 1d11c5755d..ac43516446 100644
--- a/packages/cli/authoring/doctypes/component/component.doc.mjs
+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs
@@ -132,7 +132,13 @@ export const doc = {
name: 'usage.accessibility',
type: 'ComponentAccessibilityRequirement[]',
description:
- 'Component-specific accessibility requirements ({name, description}) rendered as a dedicated Accessibility section. Keep audit procedures in the wiki rubric.',
+ 'Component-specific requirements rendered in the shared Accessibility tab. Write at about a grade-7 reading level with short sentences, common words, and active voice. For color contrast, put the ratio in `requirement`; name the exact foreground, background, state, and any overlay in `description`; explain exceptions in plain language; and give a human or agent enough detail to reproduce the check. Keep repository audit procedures in the wiki rubric.',
+ },
+ {
+ name: 'usage.accessibilityThemeCoverage',
+ type: 'ComponentAccessibilityThemeCoverage[]',
+ description:
+ 'Verified per-theme accessibility measurements rendered in the shared Accessibility tab. Record light and dark mode separately, include rendered color pairs, and mark failed measurements. Put visuals excluded from the audit in `notMeasured` with a short reason; do not add them as table measurements. Each theme declares `applicability` for measured values, informed by the component contract and never inferred from the ratio: `Conditional` is required only in some contexts, `Supplemental` adds another meaningful cue, and `Decorative` has no required meaning. These values do not change row status. Provide a complete breakdown when one cell summarizes multiple combinations, and protect derived values with an automated audit.',
},
{
name: 'usage.anatomy',
diff --git a/packages/cli/authoring/index.d.ts b/packages/cli/authoring/index.d.ts
index de8164261c..ee04969547 100644
--- a/packages/cli/authoring/index.d.ts
+++ b/packages/cli/authoring/index.d.ts
@@ -68,6 +68,13 @@ export type {
ComponentExampleDoc,
ComponentAnatomyElement,
ComponentAccessibilityRequirement,
+ ComponentAccessibilityThemeStatus,
+ ComponentAccessibilityThemeApplicability,
+ ComponentAccessibilityThemeMeasurement,
+ ComponentAccessibilityThemeResult,
+ ComponentAccessibilityThemeMode,
+ ComponentAccessibilityThemeTable,
+ ComponentAccessibilityThemeCoverage,
ComponentBestPractice,
ComponentSlotElement,
ComponentPlaygroundConfig,
diff --git a/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs b/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
index a66a3eca97..39960513eb 100644
--- a/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
+++ b/packages/cli/foundation/discovery/__fixtures__/component-accessibility-overlay.doc.mjs
@@ -18,6 +18,20 @@ export const docs = {
description: 'Provide an accessible name.',
},
],
+ accessibilityThemeCoverage: [
+ {
+ theme: 'Fixture',
+ tables: [
+ {
+ modes: [
+ {mode: 'Light', results: []},
+ {mode: 'Dark', results: []},
+ ],
+ },
+ ],
+ notMeasured: ['Decorative track — Not part of the contrast audit.'],
+ },
+ ],
anatomy: [
{
name: 'Base-only anatomy',
diff --git a/packages/cli/foundation/discovery/component-loader.mjs b/packages/cli/foundation/discovery/component-loader.mjs
index 90fe76f5ea..b3a38c7562 100644
--- a/packages/cli/foundation/discovery/component-loader.mjs
+++ b/packages/cli/foundation/discovery/component-loader.mjs
@@ -194,16 +194,23 @@ function overlayComponentDoc(docs, translation) {
});
};
- /** Preserve the new accessibility field without changing established translated output.
+ /** Preserve structured accessibility data without changing established translated output.
* @param {any} baseUsage
* @param {any} translatedUsage
*/
const mergeUsage = (baseUsage, translatedUsage) => {
if (!translatedUsage) return baseUsage;
- if (!baseUsage?.accessibility || translatedUsage.accessibility !== undefined) {
- return translatedUsage;
- }
- return {...translatedUsage, accessibility: baseUsage.accessibility};
+ return {
+ ...translatedUsage,
+ ...(translatedUsage.accessibility === undefined &&
+ baseUsage?.accessibility !== undefined
+ ? {accessibility: baseUsage.accessibility}
+ : null),
+ ...(translatedUsage.accessibilityThemeCoverage === undefined &&
+ baseUsage?.accessibilityThemeCoverage !== undefined
+ ? {accessibilityThemeCoverage: baseUsage.accessibilityThemeCoverage}
+ : null),
+ };
};
const merged = {...docs, ...translation, usage: mergeUsage(docs.usage, translation.usage)};
diff --git a/packages/cli/foundation/discovery/componentDocOverlay.test.mjs b/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
index 14ef83fd48..7f02de1456 100644
--- a/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
+++ b/packages/cli/foundation/discovery/componentDocOverlay.test.mjs
@@ -120,6 +120,12 @@ describe('the reported symptom', () => {
expect(english.usage.accessibility.length).toBeGreaterThan(0);
expect(dense.usage.accessibility).toEqual(english.usage.accessibility);
+ expect(dense.usage.accessibilityThemeCoverage).toEqual(
+ english.usage.accessibilityThemeCoverage,
+ );
+ expect(dense.usage.accessibilityThemeCoverage[0].notMeasured).toContain(
+ 'Decorative track — Not part of the contrast audit.',
+ );
expect(dense.usage.bestPractices).toBeUndefined();
expect(dense.usage.anatomy).toBeUndefined();
});
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index 856497fd0f..fbb31d7d3b 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -23,6 +23,62 @@ export const docs = {
{guidance: false, description: 'Use the destructive variant without a confirmation step for irreversible actions like deleting data.'},
{guidance: false, description: 'Use a button for navigation. If it only takes the user to another page, use a link instead. Buttons are for actions like saving, deleting, or submitting.'},
],
+ accessibility: [
+ {
+ name: 'Text label',
+ category: 'Color contrast',
+ criterion: '1.4.3 Contrast (Minimum)',
+ requirement: '4.5:1',
+ states: ['Rest', 'Hover', 'Pointer down'],
+ description:
+ 'Button text must have at least 4.5:1 contrast with the button background in every state. For Hover and Pointer down, measure the final background after the overlay is applied.',
+ },
+ {
+ name: 'Essential icon or spinner arc',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Icon only', 'Loading'],
+ description:
+ 'An icon used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+ },
+ {
+ name: 'Badge text',
+ category: 'Color contrast',
+ criterion: '1.4.3 Contrast (Minimum)',
+ requirement: '4.5:1',
+ states: ['Rest', 'Hover', 'Pointer down'],
+ description:
+ 'Badge text inside a button must have at least 4.5:1 contrast with the Badge background. Check all 14 built-in Badge colors in Rest, Hover, and Pointer down on page and surface backgrounds. This covers 336 pairs per mode. Check custom end content separately.',
+ },
+ {
+ name: 'Visible control boundary',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1 if needed',
+ states: ['Rest'],
+ description:
+ 'The button edge needs 3:1 contrast only when users need it to see the control. A text-only button can rely on its label.',
+ },
+ {
+ name: 'Keyboard focus indicator',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Focus visible'],
+ description:
+ 'The focus outline needs at least 3:1 contrast with the area around the button. Check every style. Destructive buttons use a red outline.',
+ },
+ {
+ name: 'Disabled appearance',
+ category: 'Color contrast',
+ criterion: '1.4.3 and 1.4.11 exceptions',
+ requirement: 'Not required',
+ states: ['Disabled'],
+ description:
+ 'Disabled controls do not need to meet these contrast ratios.',
+ },
+ ],
anatomy: [
{name: 'Icon', required: false, description: 'A leading icon that reinforces the label, like a trash icon on a Delete button.'},
{name: 'Label', required: true, description: 'The visible text describing the action. Also used as the accessible name.'},
diff --git a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
index e5701d6d47..08a0f67682 100644
--- a/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
+++ b/packages/core/src/ButtonGroup/ButtonGroup.doc.mjs
@@ -39,6 +39,53 @@ export const docs = {
usage: {
description:
'ButtonGroup joins related actions into a single connected control. Use it when multiple buttons represent related choices or operations that belong together visually, like copy/cut/paste, or undo/redo.',
+ accessibility: [
+ {
+ name: 'Text label',
+ category: 'Color contrast',
+ criterion: '1.4.3 Contrast (Minimum)',
+ requirement: '4.5:1',
+ states: ['Rest', 'Hover', 'Pointer down'],
+ description:
+ 'Text in each button must have at least 4.5:1 contrast with its background in every state. For Hover and Pointer down, measure the final background after the overlay is applied.',
+ },
+ {
+ name: 'Essential icon or spinner arc',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Icon only', 'Loading'],
+ description:
+ 'An icon used instead of text must have at least 3:1 contrast with the button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+ },
+ {
+ name: 'Visible control boundary',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1 if needed',
+ states: ['Rest'],
+ description:
+ 'Some groups need a divider or edge to show each button. That divider or edge must have at least 3:1 contrast.',
+ },
+ {
+ name: 'Keyboard focus indicator',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Focus visible'],
+ description:
+ 'The focus outline must have at least 3:1 contrast with the area around it.',
+ },
+ {
+ name: 'Disabled appearance',
+ category: 'Color contrast',
+ criterion: '1.4.3 and 1.4.11 exceptions',
+ requirement: 'Not required',
+ states: ['Disabled'],
+ description:
+ 'Disabled controls do not need to meet these contrast ratios.',
+ },
+ ],
bestPractices: [
{guidance: true, description: 'Group buttons that perform related actions on the same object, like copy, cut, paste on selected text.'},
{guidance: true, description: 'Use the same variant for all buttons in a group so they look like a single connected unit.'},
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index ccad77a75b..81342e0b1e 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -74,6 +74,44 @@ export const docs = {
usage: {
description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
+ accessibility: [
+ {
+ name: 'Essential icon or spinner arc',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Rest', 'Hover', 'Pointer down', 'Loading'],
+ description:
+ 'IconButton has no visible label. Its icon must have at least 3:1 contrast with the button background in Rest, Hover, and Pointer down. The moving spinner arc must also meet 3:1 while loading.',
+ },
+ {
+ name: 'Visible control boundary',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1 if needed',
+ states: ['Rest'],
+ description:
+ 'The button edge needs 3:1 contrast only when users need it to see the control.',
+ },
+ {
+ name: 'Keyboard focus indicator',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Focus visible'],
+ description:
+ 'The focus outline must have at least 3:1 contrast with the area around the button. Check the red outline on destructive buttons too.',
+ },
+ {
+ name: 'Disabled appearance',
+ category: 'Color contrast',
+ criterion: '1.4.3 and 1.4.11 exceptions',
+ requirement: 'Not required',
+ states: ['Disabled'],
+ description:
+ 'Disabled controls do not need to meet these contrast ratios.',
+ },
+ ],
bestPractices: [
{ guidance: true, description: 'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },
{ guidance: true, description: 'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.' },
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index c7040dad44..7308a445ef 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -98,6 +98,62 @@ export const docs = {
usage: {
description:
'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
+ accessibility: [
+ {
+ name: 'Text label',
+ category: 'Color contrast',
+ criterion: '1.4.3 Contrast (Minimum)',
+ requirement: '4.5:1',
+ states: ['Rest', 'Hover', 'Selected'],
+ description:
+ 'Each label must have at least 4.5:1 contrast with its segment background. Check unselected, Hover, and selected colors as they appear on screen.',
+ },
+ {
+ name: 'Essential icon',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Icon only'],
+ description:
+ 'When a segment has no visible label, its icon must have at least 3:1 contrast with the segment background. An icon beside a visible label does not need its own check.',
+ },
+ {
+ name: 'Selected state indicator',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1 if relied upon',
+ states: ['Selected'],
+ description:
+ 'The selected background must reach 3:1 only when users need it to tell selected from unselected. Label color and weight also show selection.',
+ },
+ {
+ name: 'Visible control boundary',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1 if needed',
+ states: ['Rest'],
+ description:
+ 'The control edge or segment borders need at least 3:1 contrast when users need them to see the choices.',
+ },
+ {
+ name: 'Keyboard focus indicator',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Focus visible'],
+ description:
+ 'The focus outline must have at least 3:1 contrast with the area around the segment. Check it on the track and selected background.',
+ },
+ {
+ name: 'Disabled appearance',
+ category: 'Color contrast',
+ criterion: '1.4.3 and 1.4.11 exceptions',
+ requirement: 'Not required',
+ states: ['Disabled'],
+ description:
+ 'Disabled controls do not need to meet these contrast ratios.',
+ },
+ ],
bestPractices: [
{guidance: true, description: 'Use for switching between 2–5 mutually exclusive views or modes where all options should be visible.'},
{guidance: true, description: 'Provide a descriptive label for the control to ensure the group is accessible to screen readers.'},
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index 34a6fc5357..7661467a6b 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -122,6 +122,62 @@ export const docs = {
usage: {
description:
'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
+ accessibility: [
+ {
+ name: 'Text label',
+ category: 'Color contrast',
+ criterion: '1.4.3 Contrast (Minimum)',
+ requirement: '4.5:1',
+ states: ['Unselected', 'Selected', 'Hover', 'Pointer down'],
+ description:
+ 'The label must have at least 4.5:1 contrast with the button background when selected and unselected. For Hover and Pointer down, measure the final background after the overlay is applied.',
+ },
+ {
+ name: 'Essential icon or spinner arc',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Icon only', 'Loading'],
+ description:
+ 'An icon-only ToggleButton must have at least 3:1 contrast between its icon and button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check.',
+ },
+ {
+ name: 'Selected state indicator',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1 if relied upon',
+ states: ['Selected'],
+ description:
+ 'The selected background must reach 3:1 only when users need it to tell selected from unselected. Label weight or a changed icon can also show selection.',
+ },
+ {
+ name: 'Visible control boundary',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1 if needed',
+ states: ['Rest'],
+ description:
+ 'The button edge needs 3:1 contrast only when users need it to see the control. A visible label or icon can show the control instead.',
+ },
+ {
+ name: 'Keyboard focus indicator',
+ category: 'Color contrast',
+ criterion: '1.4.11 Non-text Contrast',
+ requirement: '3:1',
+ states: ['Focus visible'],
+ description:
+ 'The focus outline must have at least 3:1 contrast with the area around the button. Check both selected and unselected states.',
+ },
+ {
+ name: 'Disabled appearance',
+ category: 'Color contrast',
+ criterion: '1.4.3 and 1.4.11 exceptions',
+ requirement: 'Not required',
+ states: ['Disabled'],
+ description:
+ 'Disabled controls do not need to meet these contrast ratios.',
+ },
+ ],
bestPractices: [
{guidance: true, description: 'Use a filled or colored icon for the pressed state so users can see the current state at a glance: an outline star vs a solid star, for example.'},
{guidance: true, description: 'Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.'},