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.mdnew file mode 100644index 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.+@rubyycheungdiff --git a/apps/docsite/AGENTS.md b/apps/docsite/AGENTS.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mjsindex 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.tsindex 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.tsxnew file mode 100644index 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.tsxindex 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.tsindex 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.mjsindex 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.tsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.'},