Styling & Options
Relevant source files
The following files were used as context for generating this wiki page:
Styling and Options in SwiftDitherKit provide the primary interface for customizing the visual appearance, interaction behavior, and accessibility of dithered charts. The system is built around two main configuration structures: DitherCartesianOptions for area, line, and bar charts, and DitherPolarOptions for pie and radar charts. These options allow developers to control everything from data stacking and bloom effects to locale-aware value formatting and semantic labels for assistive technologies.
The library uses a unique ordered-dithering approach where visual elements like fills and strokes are rendered as pixel patterns rather than solid vectors. Styling options such as DitherVariant and DitherBloom directly influence how these patterns are generated and post-processed to create glows or specific textures.
Core Configuration Structures
The library separates configuration based on the coordinate system of the chart. Both structures implement Hashable and Sendable to support efficient SwiftUI updates and background rendering.
Cartesian Options
DitherCartesianOptions manages the presentation of charts that utilize X and Y axes. It includes settings for how series interact (stacking) and how the "chrome" (axes, legends, tooltips) is displayed.
| Option | Type | Default | Description |
|---|---|---|---|
stacking | DitherStacking | .overlaid | How multiple series share the value axis. |
margins | DitherMargins | .cartesian | Insets reserved for labels and axes. |
bloom | DitherBloom | .off | Intensity of the glow effect. |
animate | Bool | true | Enables/disables entrance and data animations. |
showsAxes | Bool | true | Toggles visibility of grid lines and labels. |
valueFormat | DitherValueFormat | .automatic | Locale-aware number formatting. |
Sources: Sources/SwiftDitherKit/DitherCartesianCharts.swift:4-48
Polar Options
DitherPolarOptions is tailored for radial charts, focusing on legend and tooltip visibility within circular layouts.
| Option | Type | Default | Description |
|---|---|---|---|
margins | DitherMargins | .polar | Space reserved around the radial raster. |
bloom | DitherBloom | .off | Radial glow effect intensity. |
interactive | Bool | true | Enables touch/pointer scrubbing. |
showsLegend | Bool | true | Toggles the selectable legend. |
Sources: Sources/SwiftDitherKit/DitherPolarCharts.swift:4-38
Visual Styling Components
Visual styling is defined through colors, textures, and post-processing effects.
Dither Colors and Variants
DitherColor is a portable RGB structure. While it provides seven static presets (green, blue, purple, pink, orange, red, grey), it accepts custom hex values or RGB components. DitherVariant determines the specific dither pattern used to fill shapes.
Bloom Effects
DitherBloom defines the intensity of a glow effect created by blurring a low-resolution copy of the raster. Each case maps to a DitherBloomStyle containing specific blur, brightness, and saturation values.
| Bloom Level | Blur | Brightness | Saturation |
|---|---|---|---|
.low | 3 | 0.08 | 1.4 |
.high | 5 | 0.14 | 1.5 |
.aura | 15 | 0.35 | 3.0 |
Sources: Sources/SwiftDitherKit/DitherTypes.swift:130-143
Data Formatting & Accessibility
SwiftDitherKit emphasizes localized and accessible data presentation through DitherValueFormat and DitherAccessibility.
Value Formatting
The DitherValueFormat enum provides presets that respect the user's Locale. This ensures that axes, tooltips, and VoiceOver descriptions remain consistent.
.automatic: Uses compact notation (e.g., "1.2K") for values $\ge 1,000$..percent: Formats values where1.0is 100%..currency: Formats values using ISO 4217 codes (e.g., "USD").
Sources: Sources/SwiftDitherKit/DitherFormatting.swift:4-55
Accessibility
DitherAccessibility allows developers to provide localized semantic labels that are exposed via Apple's chart accessibility descriptor APIs.
public struct DitherAccessibility: Hashable, Sendable {
public var title: String?
public var summary: String?
public var categoryAxisLabel: String?
public var valueAxisLabel: String?
}
Sources: Sources/SwiftDitherKit/DitherAccessibility.swift:2-22
Layout and Chrome
The "Chrome" refers to the non-dithered SwiftUI elements surrounding the chart, such as legends and axes.
Margins
DitherMargins defines the insets where chrome elements are placed.
- Cartesian: Default
(top: 10, trailing: 12, bottom: 24, leading: 38)to accommodate axis labels. - Sparkline: Zero insets
(0, 0, 0, 0)for compact display. - Polar: Uniform insets
(14, 14, 14, 14).
Sources: Sources/SwiftDitherKit/DitherTypes.swift:73-90
Legend Styling
The DitherLegend uses a DitherLegendSwatch to represent series colors. Interestingly, the swatch itself is rendered using a 4x4 dither kernel threshold to maintain visual consistency with the chart marks.
Styling and Options in SwiftDitherKit provide a robust framework for balancing the aesthetic of low-fidelity dithered graphics with high-fidelity SwiftUI interaction and accessibility standards. By centralizing these configurations in DitherCartesianOptions and DitherPolarOptions, the library ensures that complex visual behaviors like bloom and patterns remain synchronized across different chart types.