Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-034
Related:
docs/releases/v1/design/ux-principles.mddocs/releases/v1/specs/ergonomic-budgets.mddocs/releases/v1/scope/scan-first-content-hierarchy-rules.mddocs/releases/v1/scope/motion-hierarchy-rules.mddocs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.mddocs/releases/v1/scope/interaction-feedback-rules.mddocs/adr/ADR-0044-oshun-studio-accessibility-governance.mdapps/oshun/web/src/design-system/globals-v2.cssapps/oshun/web/src/components/__tests__/accessibility-axe.test.tsxapps/oshun/web/src/components/__tests__/accessibility-keyboard.test.tsxapps/oshun/web/src/components/__tests__/accessibility-screen-reader.test.tsxapps/oshun/web/src/app/legal/accessibility/page.tsxdocs/releases/v1/specs/todos.md
1. Purpose#
This document defines the canonical accessibility standards for OSHUN V1 shared components.
Scope:
- reusable web design-system primitives
- shared shell/navigation building blocks
- reusable interaction containers used across customer, research, and admin surfaces
The standard exists to stop accessibility quality from becoming route-local craft. A component is only truly shared if it carries its accessibility contract with it.
2. Current Repo Signals And Gap#
The repo already has strong implementation signals:
globals-v2.cssdefines a global:focus-visiblering,sr-onlyutility, skip-link posture, coarse-pointer minimum touch targets, andprefers-reduced-motioncollapse behavior.- Shared primitives such as
Button,IconButton,Tabs,Dropdown,OverlaySheet,FormField,Spinner,Toast,ProgressBar,ProgressRing,MiniChart, andCalendarHeatmapalready expose meaningful ARIA roles, labels, and state attributes. - Current automation already checks semantic markup, keyboard behavior, and
screen-reader posture at the shell level via the three accessibility test
suites under
apps/oshun/web/src/components/__tests__. - The public accessibility statement already promises keyboard navigation, reduced motion, focus indicators, color independence, and 44x44 touch targets.
The gap is canonical component-level governance. Today the rules exist across implementation details, tests, and public promises, but not as one shared standard that every new component must satisfy before it is reusable.
3. Core Doctrine#
3.1 Accessibility Is Part Of The Component API#
Accessibility behavior is not optional polish and not an integration concern.
If consumers need to add labels, keyboard parity, focus handling, or live announcements just to make a supposedly shared component usable, then the component is incomplete.
3.2 Native Semantics Win First#
Shared components should begin with the correct HTML element and only add ARIA when native semantics do not already provide the needed behavior.
3.3 Every Interaction Needs Modality Parity#
Anything a pointer user can do must also be possible with keyboard and assistive technology, without hidden timing requirements or gesture-only paths.
3.4 Reduced Motion And Reduced Cognitive Load Matter Together#
Shared components must remain understandable when motion is removed, hover is absent, color is not trusted, or the user is navigating linearly through the screen.
3.5 Shared Components Must Meet WCAG At The Primitive Layer#
OSHUN V1 shared components target WCAG 2.1 AA behavior by default. Domain surfaces may add context, but they must not have to repair the primitive.
4. Universal Accessibility Contract#
4.1 Semantic Element Choice#
- Use
buttonfor actions,afor navigation, real form controls for data entry, and semantic headings/lists/landmarks whenever possible. divorspanwith interactive roles is allowed only when the layout truly cannot be expressed with a native control.- If a non-native interactive wrapper is unavoidable, it must provide the full native contract: keyboard activation, focusability, disabled posture, visible focus, and an accessible name.
- Decorative wrappers must stay non-interactive and must not acquire stray
tabIndexvalues.
4.2 Accessible Name, Description, And State#
- Every interactive component must expose one stable accessible name from
visible text,
aria-label,aria-labelledby, or an associated form label. - Placeholder text is not an acceptable primary label.
- Supporting help text, hint text, and errors must be connected with
aria-describedbywhen they alter interpretation or recovery. - Stateful controls must expose the right state attributes, such as
aria-expanded,aria-selected,aria-checked,aria-pressed,aria-current,aria-invalid,aria-busy, oraria-valuenow. - Decorative icons, flourishes, and non-informational media must be hidden from
assistive technology with
aria-hidden.
4.3 Focus Contract#
- Every interactive variant must be reachable through a logical tab order.
- Shared components must preserve a clearly visible focus indicator. Variant styling may refine the ring but may not suppress it.
- Focus indicators must survive dark surfaces, accent-heavy variants, and high-density operator layouts.
- Composite widgets must manage focus intentionally through roving
tabIndexor an equivalent canonical pattern. - Overlays, menus, dialogs, and sheets must move focus into the active surface, constrain it while the surface is modal, and restore it to the invoker on close.
4.4 Keyboard Contract#
- Pointer activation must have keyboard parity.
- Enter and Space behavior must match the control role.
- Escape closes transient surfaces unless doing so would destroy unsaved work without a confirmation pattern.
- Arrow-key navigation belongs only to true composite widgets such as tablists, menus, radio groups, or similar structured controls.
- Hover-only affordances are non-canonical. Required information and primary actions must also appear on focus or in the normal reading order.
4.5 Touch, Pointer, And Motor Contract#
- Shared interactive components must meet a minimum target size of
44x44CSS pixels when rendered on coarse-pointer surfaces. - Small icon affordances must increase their hit area without visually bloating the interface.
- Drag, swipe, or long-press gestures must never be the only way to complete a task.
- Repeated-action controls must follow the ergonomic budgets defined in
OSHUN_V1_ERGONOMIC_BUDGETS.md, especially on dense admin and mobile flows.
4.6 Screen Reader And Live Region Contract#
- Passive state badges and inline readiness indicators should use polite
semantics such as
role="status"when they convey meaningful state. - Urgent failures should use
role="alert"oraria-live="assertive"only when interruption is justified. - Progress indicators must expose numeric progress when known and an indeterminate posture when not known.
- Pure skeleton blocks must be hidden from assistive technology.
- Charts, sparklines, heatmaps, and other visual summaries must provide a short
textual summary through
aria-labelor an adjacent textual equivalent.
4.7 Error, Validation, And Recovery Contract#
- Form errors must set
aria-invalidand connect the error copy to the field. - Disabled states that block an expected action should expose a visible reason nearby or a documented recovery path.
- Empty, loading, offline, and error variants must follow the canonical state
ladder in
OSHUN_V1_CANONICAL_LOADING_SKELETON_EMPTY_OFFLINE_ERROR_STATE_RULES.md. - Shared components must not create dead ends. Recovery actions, dismiss paths, and return paths must remain available where applicable.
4.8 Motion And Sensory Safety Contract#
- Shared components must respect
prefers-reduced-motionand equivalent product-level motion preferences. - Motion may clarify hierarchy, but the component must remain fully legible and usable when travel, shimmer, or looping animation is removed.
- Focus indication cannot depend on motion alone.
- Ripple, confetti, sheet entrance motion, shimmer, hover translation, and animated tooltips must degrade to still or near-still behavior under reduced motion.
4.9 Contrast, Color Independence, And Reflow#
- Shared components must not rely on color alone to communicate state, priority, validity, or selection.
- Text, iconography, border, and focus treatments must maintain WCAG-compliant contrast for their role, even within minimal-chrome surfaces.
- Components must remain usable at
200%zoom and under narrow viewport reflow. - If a component legitimately needs horizontal overflow, such as a dense data structure, it must preserve keyboard access and provide a textual summary of the hidden structure.
5. Family-Specific Requirements#
| Family | Current shared examples | Required accessibility posture |
|---|---|---|
| action controls | Button, IconButton, SegmentedControl, ReviewDecisionControl |
Use native button or radio semantics, expose loading and pressed state, keep icon-only controls explicitly named, and ensure destructive actions are identifiable without color alone. |
| inputs and filters | SearchInput, FormField, HabitCheckbox, AdminQueueFilter |
Every input needs a programmatic label, error linkage, helper linkage, and keyboard parity for clear/reset/filter actions. |
| navigation and composite controls | Tabs, Sidebar, TopBar, DomainSwitcher, Dropdown |
Use landmark and list semantics where appropriate, expose current location, support roving focus or menu navigation patterns, and keep collapsed navigation discoverable by screen readers. |
| overlays and transient surfaces | OverlaySheet, Tooltip, Toast |
Dialogs trap and restore focus, tooltips never hold required information alone, and live regions use the least disruptive politeness level that still tells the truth. |
| status and progress | Spinner, ProgressBar, ProgressRing, Badge, ConfidenceBadge, VisibilityBadge, ProvenanceBadge |
Status surfaces announce meaning, progress surfaces expose range/value semantics, and decorative dots stay hidden unless paired with accessible text. |
| data visualization and evidence media | MiniChart, CalendarHeatmap, Avatar, AssistantDisclosureStrip |
Visual summaries need text equivalents, avatars need meaningful labeling or decorative hiding, and disclosure/confidence signals must communicate meaning beyond hue. |
| interactive containers | CollectionCard, NotebookCard, EvidenceCard, ClaimListItem, SourceListItem, PassageListItem, AvatarVoicePackCard, RightsSummaryCard, LicenseSummaryCard |
If the container is clickable, it must behave like a real control, not a generic styled box. Large hit areas, stable names, and deterministic focus posture are mandatory. |
| non-interactive layout primitives | Card, Divider, SectionHeader, PageContainer, DomainSurfaceLayout |
Layout helpers must preserve document structure, avoid fake interactivity, and support heading, separator, and landmark semantics where the structure warrants them. |
6. Standard Patterns For Known OSHUN Cases#
6.1 Interactive Cards And Rows#
OSHUN already uses interactive card and list-row primitives in several shared components.
Rules:
- Prefer a real button or anchor when the entire container is actionable.
- If an interactive container remains role-driven, it must support Enter and Space, visible focus, and a stable accessible label that summarizes the row.
- Nested controls inside an actionable container must not create accidental double-focus or conflicting click targets.
6.2 Menus, Tabs, And Segmented Controls#
- Tabs must keep one active tab in the tab order and link tabs to their panels.
- Dropdown and submenu items must support arrow-key movement, Escape dismissal, and disabled-item skipping.
- Segmented controls should use radio-group semantics when the interaction is single-select.
6.3 Dialogs, Sheets, And Tooltips#
- Modal surfaces must announce title and context on entry.
- Dismiss controls must stay reachable and named.
- Tooltip content may reinforce meaning but cannot be the only place a user learns the required instruction, status, or warning.
6.4 Progress, Loading, And Toasts#
- Loading buttons must expose
aria-busyand keep their purpose readable. - Determinate progress must expose value; indeterminate progress must expose the work intent without fake precision.
- Toasts should announce concise changes and offer dismiss affordances without stealing focus unless the event is critical.
7. Verification Standard#
Every shared-component change must map to explicit accessibility evidence.
Minimum required evidence:
- component-level tests for semantics or state attributes when the component introduces or changes ARIA, focus, or validation behavior
- keyboard-path coverage when the component opens, closes, traps, reorders, or nests focus
- screen-reader or live-region coverage when the component communicates async state, status, errors, or non-textual meaning
- route-level regression coverage when the component is consumed in a critical shared shell or workspace flow
Current repo enforcement signals:
accessibility-axe.test.tsxchecks landmarks, heading hierarchy, labels, and duplicate-ID posture through manual assertionsaccessibility-keyboard.test.tsxchecks keyboard-only reachability and common interaction patternsaccessibility-screen-reader.test.tsxchecks ARIA, live regions, and screen reader-facing state
Important implementation note:
- The repo does not currently have
axe-coreorvitest-axeinstalled for these shared suites, even though the public accessibility statement names axe as part of the broader testing strategy. - Until that tooling is added, teams must not claim automated axe coverage from the existing shared-component test files alone.
- A task that introduces or promises axe-backed validation must install and wire that tooling in the same scope.
8. Definition Of Done For A Shared Component#
A shared component meets the OSHUN V1 accessibility standard only when:
- semantics are native-first and role usage is justified
- the accessible name and state contract are stable
- keyboard operation fully matches pointer operation
- focus entry, visibility, trapping, and restoration are correct
- touch-target size and gesture alternatives are acceptable
- screen-reader output conveys the same decision-critical meaning as the visual UI
- reduced-motion behavior preserves usability
- contrast and non-color cues remain sufficient
- component-level and route-level accessibility evidence exist for the changed behavior
If any of those fail, the component is not ready to be treated as shared.