accessibility-checklist（无障碍检查表）

Accessibility Review Checklist

How to Use This Checklist

• Review changed components against the relevant sections below
• Not every section applies to every component — form checks only apply to form components, modal checks only apply to modals, etc.
• This codebase uses Radix UI / shadcn/ui extensively. These libraries handle most a11y patterns (keyboard nav, focus management, ARIA) automatically. Your primary job is to catch misuse of the library, not absence of manual implementation.
• When unsure whether a component library handles a pattern, lower confidence rather than asserting

§1 Component Library Misuse (Radix / shadcn/ui)

This is the highest-signal section for this codebase. Radix handles a11y correctly when used correctly — bugs come from misuse.

• Dialog/Sheet without title: Radix Dialog and Sheet require DialogTitle / SheetTitle for screen reader announcement. If DialogTitle is omitted or visually hidden without aria-label on DialogContent, screen readers announce an unlabeled dialog.

- Common violation: <DialogContent> with no <DialogTitle> and no aria-label - Note: Using <VisuallyHidden><DialogTitle>...</DialogTitle></VisuallyHidden> is a valid pattern for dialogs where a visible title doesn't fit the design

• AlertDialog without description: AlertDialogContent should include AlertDialogDescription for screen readers to understand the confirmation context. If omitted, add aria-describedby={undefined} to explicitly opt out (otherwise Radix warns).
• Select/Combobox without accessible trigger label: Radix Select needs aria-label on the trigger when there's no visible label. Custom generic-select.tsx and generic-combo-box.tsx wrappers should propagate labels.

- Common violation: <Select> inside a form field that has a visual label, but the label isn't associated via htmlFor or wrapping

• DropdownMenu items without accessible names: Icon-only menu items need text content or aria-label. Menu items that are just icons (e.g., copy, delete, edit) need text.

- Correct pattern: <DropdownMenuItem><TrashIcon /> Delete</DropdownMenuItem> (icon + text) - Violation: <DropdownMenuItem><TrashIcon /></DropdownMenuItem> (icon only, no text, no aria-label)

• Tooltip as only accessible name: Tooltip text is not reliably announced by all screen readers. If a control's only accessible name is in a tooltip, it needs aria-label as well.

- Common pattern to flag: <Tooltip><TooltipTrigger><Button><Icon /></Button></TooltipTrigger><TooltipContent>Delete</TooltipContent></Tooltip> — Button needs aria-label="Delete"

• Overriding Radix's keyboard handling: If a component wraps a Radix primitive and adds onKeyDown that calls e.preventDefault() or e.stopPropagation(), it may break Radix's built-in keyboard navigation.

§2 Forms & Labels

The codebase uses react-hook-form + Zod with shadcn/ui's Form component, which auto-associates labels via FormItem context. Issues arise when forms bypass this pattern.

• Every form input must have an accessible name: Via <FormLabel>, <label htmlFor={id}>, aria-label, or aria-labelledby. Placeholder text alone is NOT a label.

- Common violation: Custom inputs outside <FormField> / <FormItem> that don't get auto-association - Common violation: <Input placeholder="Enter name" /> used standalone without any label

• Error messages must be associated with their input: shadcn/ui's <FormMessage> auto-associates via aria-describedby when inside <FormItem>. Custom error rendering outside this pattern loses the association.

- Flag: Error text rendered near an input but not using <FormMessage> or manual aria-describedby

• Required fields must be indicated programmatically: Use aria-required="true" or native required, not just a visual asterisk. The Form component doesn't add this automatically — it comes from the Zod schema validation at submit time, not at the HTML level.
• Grouped controls need group semantics: Radio groups and checkbox groups should use <RadioGroup> (Radix) or <fieldset>/<legend>. Loose radio buttons or checkboxes without group context confuse screen readers.

- Scope: Configuration pages, settings forms, multi-option selectors

§3 Accessible Names (Icons & Buttons)

With 48 shadcn/ui components and heavy icon usage (Lucide React), icon-only interactive elements are a primary risk area.

• Icon-only buttons must have aria-label: Buttons containing only an icon (no visible text) need aria-label describing the action.

- Common violation: <Button variant="ghost" size="icon"><TrashIcon /></Button> without aria-label - Very common in: data tables (row actions), toolbars, card headers, dialog close buttons - Note: shadcn/ui's Dialog close button already includes <span className="sr-only">Close</span> — don't flag this

• Icon-only links need accessible names: Same as buttons — <a> or <Link> with only an icon needs aria-label.
• sr-only text is a valid alternative to aria-label: <Button><TrashIcon /><span className="sr-only">Delete item</span></Button> is correct. Don't flag this pattern as missing a label.
• Decorative icons should be hidden: Icons that are purely decorative (next to visible text) should have aria-hidden="true" to avoid redundant announcements.

- Correct: <Button><PlusIcon aria-hidden="true" /> Add item</Button> - Also correct: Lucide icons may set aria-hidden by default — check before flagging

§4 Semantic HTML & Regression Guard

The codebase currently has no <div onClick> anti-patterns. This section guards against regressions.

• Interactive elements must use native interactive HTML: <button> for actions, <a>/<Link> for navigation. NOT <div>, <span>, or <p> with onClick.

- Flag any new <div onClick> or <span onClick> in the diff as CRITICAL - Exception: Components from Radix that render proper elements under the hood are fine

• Tables must use semantic HTML: <table>, <thead>, <tbody>, <th>, <td>. The codebase already does this. Flag any new data display that should be a table but uses <div> grid instead.

- Consider: <th> elements should have scope="col" or scope="row" for complex tables

• Don't disable zoom: Flag user-scalable=no or maximum-scale=1 in viewport meta tags.

§5 Focus Management

Radix Dialog handles focus trap and restore automatically. This section covers what Radix doesn't handle.

• Custom modals/overlays must manage focus: Any modal-like UI NOT built on Radix Dialog (e.g., custom overlays, fullscreen panels, React Flow side panels) must:

- Move focus into the overlay when it opens - Trap focus while open (Tab cycles within the overlay) - Return focus to the trigger when closed - Close on Escape

• Focus visible indicator must not be removed: outline-none / outline: none without a focus-visible:ring-* replacement removes the only visual cue for keyboard users.

- Note: The codebase consistently uses focus-visible:ring-* alongside outline-none — this is correct. Only flag if a new component uses outline-none without the replacement.

• Route change focus (Next.js App Router): After client-side navigation, focus should move to the main content. Next.js App Router may handle this — only flag if a custom route change mechanism bypasses the framework's handling.
• Positive tabIndex is an anti-pattern: tabIndex={0} and tabIndex={-1} are fine. tabIndex={1} or higher overrides natural order and creates unpredictable navigation. Flag any positive tabIndex values.

§6 Dynamic Content & Live Regions

With 287 toast usages (Sonner) and chat streaming interfaces, announcements for screen readers matter.

• Sonner toasts: Sonner uses role="status" with aria-live="polite" by default. This is correct. Only flag if:

- A custom toast/notification bypasses Sonner and doesn't use a live region - An error toast should use role="alert" (assertive) instead of role="status" (polite) for critical errors

• Loading states should be communicated: Skeleton loaders and spinners should be accompanied by screen reader announcements. Options:

- aria-busy="true" on the loading container - <span className="sr-only">Loading...</span> inside the spinner - aria-live="polite" region that announces "Loading..." then announces when content is ready - Note: The codebase's Spinner component already has aria-label — check that new loading patterns follow suit

• Chat streaming messages: For the copilot/playground chat interfaces, new messages should be announced to screen readers. The @inkeep/agents-ui library should handle this — only flag if custom chat rendering bypasses the library's announcements.
• Inline form validation: When validation errors appear dynamically (without page reload), they should either:

- Be associated with the input via aria-describedby (shadcn/ui's <FormMessage> does this) - Or use aria-live="polite" to announce the error - Only flag custom validation rendering outside the <FormMessage> pattern

§7 Specialized Components

These components have unique a11y considerations beyond standard patterns.

• Monaco Editor: Has known a11y limitations for screen reader users. When Monaco is used for required input (not just optional code editing), consider providing an alternative text input fallback. Flag only if a new Monaco instance is introduced without consideration.
• React Flow (node graph editor): Keyboard navigation in visual node editors is inherently difficult. When React Flow is used:

- Ensure all node operations are also accessible via context menus or keyboard shortcuts - Node labels should be readable by screen readers - Flag only if new React Flow interactions are added without keyboard alternatives

• Data tables with actions: Tables with row-level action buttons (common in this codebase) should ensure action buttons have accessible names and the table structure allows screen reader navigation.

- Flag: New table action buttons that are icon-only without aria-label

Severity Calibration