Accessibility Integration
Relevant source files
The following files were used as context for generating this wiki page:
- Sources/SwiftDitherKit/DitherAccessibility.swift
- Sources/SwiftDitherKit/DitherCartesianAccessibility.swift
- Sources/SwiftDitherKit/DitherPieAccessibility.swift
- Sources/SwiftDitherKit/DitherRadarAccessibility.swift
- Sources/SwiftDitherKit/SwiftDitherKit.docc/InteractionAndAccessibility.md
- Sources/SwiftDitherKit/DitherCartesianCharts.swift
- Sources/SwiftDitherKit/DitherMotion.swift
SwiftDitherKit integrates comprehensive accessibility support by bridging dithered pixel-based renderings with Apple's AXChartDescriptor APIs. This ensures that while the visual representation is a low-resolution dithered raster, assistive technologies like VoiceOver can programmatically navigate categories, series, and specific data points.
The system relies on localized semantic labels provided through the DitherAccessibility structure and handles interaction states (such as active selections) to provide context-aware summaries to the user. Additionally, the kit respects system-level "Reduce Motion" settings to ensure a comfortable experience for users with motion sensitivities.
Sources: InteractionAndAccessibility.md:16-23, DitherAccessibility.swift:2-23
Accessibility Data Structures
The core of the accessibility implementation is the DitherAccessibility struct, which acts as a container for localized strings that describe various chart components.
| Property | Type | Description |
|---|---|---|
title | String? | A concise, localized name for the chart. |
summary | String? | A localized sentence describing the chart's takeaway. |
categoryAxisLabel | String? | Label for categories, slices, or radar axes. |
valueAxisLabel | String? | Label for the numeric value axis. |
Sources: DitherAccessibility.swift:2-12
Chart Descriptor Architecture
SwiftDitherKit uses AXChartDescriptorRepresentable to transform internal chart data into accessible descriptors. This process involves defining axes (categorical and numeric) and data points so that VoiceOver can "read" the chart content.
Descriptor Generation Flow
The following diagram illustrates how raw data and accessibility options are transformed into a system-level accessibility descriptor.
Cartesian Accessibility
For Area, Line, and Bar charts, DitherCartesianChartDescriptor maps categories to the X-axis and numeric values to the Y-axis. The content direction is strictly leftToRight.
- Continuous Data: Line and Area charts mark their series as continuous, while Bar charts do not.
- Summary: Automatically generates a string such as "X categories across Y series" and appends selection status if a specific series is active.
Sources: DitherCartesianAccessibility.swift:29-57
Polar Accessibility (Pie and Radar)
Pie and Radar charts utilize a radialClockwise content direction.
- Pie Charts: Map slices to categorical descriptors. The summary identifies the number of wedges and the currently selected wedge.
- Radar Charts: Map data labels to axes (spokes). The upper bound for the numeric axis is dynamically calculated based on the maximum value across all series.
Sources: DitherPieAccessibility.swift:44-53, DitherRadarAccessibility.swift:51-60
Interaction and Selection State
Accessibility descriptors are kept in sync with the chart's selection state. When a user interacts with a chart, the selectedSeriesID or selectedSliceID is passed to the descriptor generator to update the accessible summary.
Motion and Sensory Support
SwiftDitherKit monitors the system environment for motion preferences. This affects both the visual rendering and the background "sparkle" effects used in certain chart types.
- Reduced Motion Transitions: When
accessibilityReduceMotionis enabled, the library replaces standard entrance animations and crossfades with a simple opacity fade. - Sparkle Suppression: Sparkles in line and area charts stop blinking and remain steady when motion is reduced to avoid distracting high-frequency changes.
- Visual Feedback: Transition blurs are entirely removed in reduced motion mode.
| Feature | Standard Mode | Reduce Motion Mode |
|---|---|---|
| Data Changes | Animated crossfade | Opacity fade |
| Idle Sparkles | Blinking/Flare alpha | Steady (non-flaring) |
| Transitions | Blur + Motion | Zero blur / Settle immediately |
Sources: InteractionAndAccessibility.md:37-41, DitherMotion.swift:35-42, DitherSparkleTests.swift:68-80
Implementation Example: Cartesian Accessibility
let descriptor = DitherCartesianChartDescriptor(
kind: .line,
data: data,
series: series,
stacking: .overlaid,
selectedSeriesID: "sales",
valueFormat: .number(maximumFractionDigits: 0),
accessibility: DitherAccessibility(
title: "Monthly sales",
categoryAxisLabel: "Month",
valueAxisLabel: "Orders"
),
locale: Locale(identifier: "en_US")
).makeChartDescriptor()
Sources: DitherValueAndAccessibilityTests.swift:61-76
Summary
Accessibility in SwiftDitherKit is a first-class citizen that transforms decorative dithered pixels into meaningful semantic data. By implementing AXChartDescriptorRepresentable across all chart families and respecting system motion preferences, the library ensures that dithered visualizations are usable by all users, regardless of their reliance on assistive technologies or sensory requirements.