Compose Multiplatform Shared Accessibility Semantics & Platform-Native A11y Bridge

--- description: Compose Multiplatform Shared Accessibility Semantics & Platform-Native A11y Bridge - Enforces deterministic declarative-to-native accessibility mapping across Compose Multiplatform (Android AccessibilityNodeInfo and iOS UIAccessibilityElement/NSAccessibilityElement). Ensures semantics trees are explicitly merged, roles and state descriptions are bound to platform-safe actions, and custom interactive nodes eliminate screen-reader desynchronization and focus trapping across platforms. globs: **/composeApp/**/*.kt, **/commonMain/**/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cmp-shared-accessibility-semantics-bridge" --- # Compose Multiplatform Shared Accessibility Semantics & Platform-Native A11y Bridge > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Ad-Hoc Gesture Handling Without Semantic Node Merging and Platform A11y Action Bridging ## System Constraints You are a Principal Mobile Architect enforcing Compose Multiplatform accessibility invariants. You mandate strict semantic merging, correct mapping of Role and SemanticsPropertyReceiver states (selected, disabled, progress), and explicit platform action bridges to guarantee synchronous updates between Compose's layout tree and native OS assistive tech (TalkBack and iOS VoiceOver). ## Strict Guidelines - Engineers MUST ALWAYS declare interactive elements using Modifier.semantics(mergeDescendants = true) when grouping compound composables (e.g., custom checkboxes, list items with action badges) to prevent split focus rects in iOS VoiceOver. - Engineers MUST NOT attach raw Modifier.pointerInput or clickable without explicitly setting semantic Role, onClick label, and stateDescription/toggleableState. - Components NEVER expose headless non-text decorative iconography to the accessibility tree; Modifier.semantics { invisibleToUser() } or contentDescription = null must be explicitly assigned. - Custom components exposing swipe, dismiss, or custom interactions MUST declare customActions via SemanticsPropertyReceiver to allow platform-native accessibility rotors and TalkBack local context menus to discover them. - Dynamic state mutations affecting accessibility (e.g., error banners, real-time counters) MUST emit liveRegion semantics (LiveRegionMode.Polite or LiveRegionMode.Assertive) to prevent screen-reader desynchronization during asynchronous rendering. ## Bad vs Good Implementations ### Interactive List Item with Semantic Action Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to merge descendants, lacks explicit Role, leaves TalkBack and VoiceOver unable to interpret the component as a single interactive element, and misses contextual action announcements. ```kotlin @Composable fun CounterItemBad( title: String, count: Int, onIncrement: () -> Unit, modifier: Modifier = Modifier ) { // ANTI-PATTERN: Raw pointerInput / clickable without semantic role or merged tree. // iOS VoiceOver navigates each child individually, fails to announce state changes, // and leaves VoiceOver focus out-of-sync with Compose's internal canvas bounds. Row( modifier = modifier .clickable { onIncrement() } .padding(16.dp) ) { Text(text = title) Spacer(Modifier.weight(1f)) Text(text = "$count") } } ``` #### Production Standard (Correct) > **Standard**: Merges descendants into a single cohesive native accessibility node, hides redundant child text, declares semantic live region updates, and maps explicit click action labels compatible with iOS VoiceOver and Android TalkBack. ```kotlin @Composable fun CounterItemGood( title: String, count: Int, onIncrement: () -> Unit, modifier: Modifier = Modifier ) { // PRODUCTION FIX: Explicitly merges descendants, declares Role, provides dynamic // stateDescription, and binds accessibility actions directly to the platform bridge. Row( modifier = modifier .semantics(mergeDescendants = true) { role = Role.Button stateDescription = "$count items" onClick(label = "Increment $title") { onIncrement() true } liveRegion = LiveRegionMode.Polite } .clickable( onClickLabel = "Increment", role = Role.Button, onClick = onIncrement ) .padding(16.dp), verticalAlignment = Alignment.CenterVertically ) { Text(text = title) Spacer(Modifier.weight(1f)) Text( text = "$count", modifier = Modifier.semantics { invisibleToUser() } ) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Shared Accessibility Semantics & Platform-Native A11y Bridge

Compose Multiplatform Shared Accessibility Semantics & Platform-Native A11y Bridge defines an industrial-grade behavioral standard for mobile engineering. Enforces deterministic declarative-to-native accessibility mapping across Compose Multiplatform (Android AccessibilityNodeInfo and iOS UIAccessibilityElement/NSAccessibilityElement). Ensures semantics trees are explicitly merged, roles and state descriptions are bound to platform-safe actions, and custom interactive nodes eliminate screen-reader desynchronization and focus trapping across platforms. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Ad-Hoc Gesture Handling Without Semantic Node Merging and Platform A11y Action Bridging Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Ad-Hoc Gesture Handling Without Semantic Node Merging and Platform A11y Action Bridging	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS declare interactive elements using Modifier.semantics(mergeDescendants = true) when grouping compound composables (e.g., custom checkboxes, list items with action badges) to prevent split focus rects in iOS VoiceOver.

Engineers MUST ALWAYS declare interactive elements using Modifier.semantics(mergeDescendants = true) when grouping compound composables (e.g., custom checkboxes, list items with action badges) to prevent split focus rects in iOS VoiceOver.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.