Eve library

OSHUN V1 Shared Component Accessibility Standards

Spec

Revision 1

On this page

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.md
  • docs/releases/v1/specs/ergonomic-budgets.md
  • docs/releases/v1/scope/scan-first-content-hierarchy-rules.md
  • docs/releases/v1/scope/motion-hierarchy-rules.md
  • docs/releases/v1/scope/canonical-loading-skeleton-empty-offline-error-state-rules.md
  • docs/releases/v1/scope/interaction-feedback-rules.md
  • docs/adr/ADR-0044-oshun-studio-accessibility-governance.md
  • apps/oshun/web/src/design-system/globals-v2.css
  • apps/oshun/web/src/components/__tests__/accessibility-axe.test.tsx
  • apps/oshun/web/src/components/__tests__/accessibility-keyboard.test.tsx
  • apps/oshun/web/src/components/__tests__/accessibility-screen-reader.test.tsx
  • apps/oshun/web/src/app/legal/accessibility/page.tsx
  • docs/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.css defines a global :focus-visible ring, sr-only utility, skip-link posture, coarse-pointer minimum touch targets, and prefers-reduced-motion collapse behavior.
  • Shared primitives such as Button, IconButton, Tabs, Dropdown, OverlaySheet, FormField, Spinner, Toast, ProgressBar, ProgressRing, MiniChart, and CalendarHeatmap already 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 button for actions, a for navigation, real form controls for data entry, and semantic headings/lists/landmarks whenever possible.
  • div or span with 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 tabIndex values.

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-describedby when 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, or aria-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 tabIndex or 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 44x44 CSS 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" or aria-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-label or an adjacent textual equivalent.

4.7 Error, Validation, And Recovery Contract#

  • Form errors must set aria-invalid and 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-motion and 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-busy and 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.tsx checks landmarks, heading hierarchy, labels, and duplicate-ID posture through manual assertions
  • accessibility-keyboard.test.tsx checks keyboard-only reachability and common interaction patterns
  • accessibility-screen-reader.test.tsx checks ARIA, live regions, and screen reader-facing state

Important implementation note:

  • The repo does not currently have axe-core or vitest-axe installed 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.