Disciplines · Decisions (ADRs)

ADR-0044: OSHUN Studio Accessibility Governance

Studio now spans high-density interaction workflows across domains.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Web Engineering, OSHUN Security + Compliance
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio now spans high-density interaction workflows across domains. Accessibility expectations exist in multiple local surfaces, but governance and enforcement remain fragmented. Without a canonical accessibility governance model, teams can ship regressions that degrade keyboard navigation, screen-reader semantics, motion safety, and inclusive operability.

Without unified accessibility governance, OSHUN risks:

  • inconsistent accessibility quality across Studio domains and workflows
  • weak enforcement for ARIA/keyboard/focus contracts in release decisions
  • inaccessible incident and governance operations under production pressure
  • compliance and trust risk for enterprise and regulated deployments

Decision Drivers#

  • Inclusivity: every Studio workflow must remain operable with assistive technologies.
  • Consistency: one accessibility contract vocabulary across domains.
  • Enforcement: deterministic checks in CI, runtime, and release gates.
  • Governance: policy-aware handling for high-risk accessibility regressions.
  • Operability: fast diagnosis and remediation of accessibility incidents.

Considered Options#

Option 1: Team-Local Accessibility Checklists#

Allow each domain to maintain independent accessibility guidance and checks.

Pros:

  • Low central coordination overhead.

Cons:

  • Inconsistent standards and fragmented evidence quality.
  • Hard to enforce release safety for cross-domain Studio flows.

Option 2: End-of-Release Accessibility Audits Only#

Run accessibility checks only near release cutoff.

Pros:

  • Simplified operational process.

Cons:

  • Late discovery of regressions and high remediation cost.
  • Weak ongoing accessibility observability.

Option 3: Canonical Accessibility Governance Control Plane (Chosen)#

Adopt typed accessibility contracts, policy-tier enforcement, telemetry/audit instrumentation, and deterministic release gating.

Pros:

  • Stronger accessibility consistency and release confidence.
  • Continuous enforcement for keyboard/screen-reader/motion semantics.
  • Better compliance and operational accountability.

Cons:

  • Requires disciplined contract governance and ongoing maintenance.

Decision Outcome#

Chosen option: Option 3.

Accessibility-governance requirements:

  1. Canonical accessibility contract model for focus, keyboard, semantics, and motion controls.
  2. Policy-tier release controls for accessibility-impacting changes.
  3. Validation model spanning CI automation, runtime checks, and release gating.
  4. Exception/waiver policy with owner, scope, reason, and expiry metadata.
  5. Incident/remediation model for deterministic closure and audit evidence.

Normative Rules#

Accessibility Contract Model#

  • Governed flows must define accessibility requirements for keyboard, screen-reader semantics, focus order, and reduced-motion behavior.
  • Contract fields must include owner, sourceDomain, workflowRef, severity, and expiresAt.
  • Missing ownership or expiry metadata invalidates contract publication.

Validation and Release Contract#

  • Accessibility checks must run in CI for semantic, keyboard, and focus rules.
  • Runtime validation must emit deterministic pass/fail status events.
  • Production release is blocked on unresolved critical accessibility violations.

Policy and Approval Contract#

  • Sensitive or production accessibility waivers require role + permission-tier authorization.
  • High-impact production waivers require CAB/compliance evidence.
  • Policy denials must emit auditable and queryable reason codes.

Incident and Remediation Contract#

  • Accessibility incidents must include deterministic severity classification and ownership attribution.
  • Closure requires successful post-fix validation evidence.
  • Incident/remediation actions must emit telemetry and governance audit events.

Architecture Implications#

  • Studio accessibility workspace surfaces expose contract posture, violation status, and remediation flow controls.
  • Existing accessibility test suites (axe, keyboard, screen-reader) become first-class release gate dependencies.
  • Metrics/observability systems ingest accessibility governance events.
  • Experimentation and performance governance can correlate rollout decisions with accessibility posture.

Acceptance Criteria (OST-00249)#

OST-00249 is complete only when:

  1. ADR exists at docs/adr/ADR-0050-oshun-studio-accessibility-governance.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines accessibility contracts, policy tiers, validation/release rules, and remediation governance.
  4. ADR aligns with ADR-0007 through ADR-0043, especially ADR-0012, ADR-0018, ADR-0040, ADR-0041, and ADR-0043.
  5. ADR aligns with existing accessibility test surfaces in apps/oshun/web/src/components/__tests__.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Stronger accessibility reliability and cross-domain consistency.
  • Earlier detection and safer remediation of accessibility regressions.
  • Better compliance posture with auditable governance workflows.

Negative#

  • Additional governance and validation maintenance overhead.
  • Requires cross-team coordination for contract and policy evolution.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0024-oshun-studio-component-primitives-and-composition-contracts.md
  • docs/adr/ADR-0046-oshun-studio-metrics-and-analytics-instrumentation.md
  • docs/adr/ADR-0047-oshun-studio-observability-and-operational-dashboards.md
  • docs/adr/ADR-0049-oshun-studio-performance-budgets.md

References#

  • 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/components/__tests__/StudioPerformanceBudgetsWorkspace.validation.test.tsx
  • apps/oshun/web/src/components/__tests__/StudioExperimentationFeatureFlagsWorkspace.validation.test.tsx
  • libs/oshun/domain-registry/src/index.ts
  • docs/releases/v1/design/ux-principles.md
  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/domains/bellona/features.md