@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-charts/SKILL.md

@@ -1,500 +1,314 @@
 ---
 name: swift-charts
-description: "Implement, review, or improve data visualizations using Swift Charts. Use when building bar, line, area, point, pie, donut, or iOS 26 3D charts; when adding chart selection, scrolling, annotations, axes, scales, legends, or foregroundStyle grouping; when plotting functions with BarPlot, LinePlot, AreaPlot, PointPlot, Chart3D, or SurfacePlot; or when creating heat maps, Gantt charts, grouped bars, sparklines, threshold lines, or spatial visualizations."
+description: "Swift Charts: bar, line, area, point, pie, donut, iOS 26 3D charts (Chart3D, SurfacePlot), axes, scales, legends, annotations, scrolling, selection, foregroundStyle grouping, vectorized BarPlot/LinePlot/AreaPlot/PointPlot function plots, Gantt, heat maps, sparklines, grouped bars, threshold lines, spatial plots. Use when implementing, reviewing or improving a SwiftUI chart. Not for map annotations, navigation, data loading or full VoiceOver audits."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# Swift Charts
-
-Build data visualizations with Swift Charts targeting iOS 26+. Compose marks
-inside `Chart` or `Chart3D`, configure axes and scales with view modifiers, and
-use vectorized plots or 3D plots when the data calls for them.
-
-See [references/charts-patterns.md](references/charts-patterns.md) for extended patterns, 3D charts, accessibility, and theming guidance.
-
-## Contents
-
-- [Workflow](#workflow)
-- [Chart Container](#chart-container)
-- [Mark Types](#mark-types)
-- [Axis Customization](#axis-customization)
-- [Scale Configuration](#scale-configuration)
-- [Foreground Style and Encoding](#foreground-style-and-encoding)
-- [Selection (iOS 17+)](#selection-ios-17)
-- [Scrollable Charts (iOS 17+)](#scrollable-charts-ios-17)
-- [Annotations](#annotations)
-- [Legend](#legend)
-- [Vectorized Plots (iOS 18+)](#vectorized-plots-ios-18)
-- [3D Charts (iOS 26+)](#3d-charts-ios-26)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Workflow
 
-### 1. Build a new chart
-
-1. Define data as an `Identifiable` struct or use `id:` key path.
-2. Choose mark type(s): `BarMark`, `LineMark`, `PointMark`, `AreaMark`,
-   `RuleMark`, `RectangleMark`, `SectorMark`, or `SurfacePlot`.
-3. Wrap 2D marks in `Chart`; use `Chart3D` only for real spatial or surface data.
-4. Encode visual channels: `.foregroundStyle(by:)`, `.symbol(by:)`, `.lineStyle(by:)`.
-5. Configure axes with `.chartXAxis` / `.chartYAxis`.
-6. Set scale domains with `.chartXScale(domain:)` / `.chartYScale(domain:)`.
-7. Add selection, scrolling, or annotations as needed.
-8. For 1000+ 2D data points, use vectorized plots (`BarPlot`, `LinePlot`, etc.).
+# Swift Charts
 
-### 2. Review existing chart code
+Baseline: iOS 26. Marks go inside `Chart` (or `Chart3D`), axes and scales are
+view modifiers, and vectorized or 3D plots are used when the data calls for
+them. Each API below lists its first release.
 
-Run through the Review Checklist at the end of this file.
+Extended recipes: [chart patterns](references/charts-patterns.md).
 
-## Chart Container
+Outside this skill: map annotations and overlays (MapKit guidance), navigation
+and deep links (`swiftui-navigation`), loading data and model ownership
+(networking, concurrency and SwiftUI architecture skills), full VoiceOver
+audits (`ios-accessibility`). Chart-level labels, colour, Dynamic Type and
+audio graphs stay here.
 
-```swift
-// Data-driven init (single-series)
-Chart(sales) { item in
-    BarMark(x: .value("Month", item.month), y: .value("Revenue", item.revenue))
-}
+## Workflow
 
-// Content closure init (multi-series, mixed marks)
-Chart {
-    ForEach(seriesA) { item in
-        LineMark(x: .value("Date", item.date), y: .value("Value", item.value))
-            .foregroundStyle(.blue)
-    }
-    RuleMark(y: .value("Target", 500))
-        .foregroundStyle(.red)
-}
+Building a chart:
 
-// Custom ID key path
-Chart(data, id: \.category) { item in
-    BarMark(x: .value("Category", item.category), y: .value("Count", item.count))
-}
-```
+1. Make each data point an `Identifiable` value, or give the chart an `id:`
+   key path.
+2. Choose marks: `BarMark`, `LineMark`, `PointMark`, `AreaMark`, `RuleMark`,
+   `RectangleMark`, `SectorMark`, or `SurfacePlot` for surfaces.
+3. Flat marks belong in `Chart`. Reserve `Chart3D` for data that truly has
+   three spatial dimensions or describes a surface.
+4. Encode extra dimensions with `.foregroundStyle(by:)`, `.symbol(by:)` and
+   `.lineStyle(by:)`.
+5. Configure axes with `.chartXAxis` and `.chartYAxis`.
+6. Fix domains with `.chartXScale(domain:)` and `.chartYScale(domain:)`.
+7. Add selection, scrolling and annotations where they help.
+8. Above roughly 1,000 points in 2D, switch to vectorized plots (`BarPlot`,
+   `LinePlot` and friends).
 
-## Mark Types
+Reviewing a chart: work down the checklist that closes this file.
 
-### BarMark (iOS 16+)
+## The `Chart` Container
 
 ```swift
-// Vertical bar
-BarMark(x: .value("Month", item.month), y: .value("Sales", item.sales))
-
-// Stacked by category (automatic when same x maps to multiple bars)
-BarMark(x: .value("Month", item.month), y: .value("Sales", item.sales))
-    .foregroundStyle(by: .value("Product", item.product))
-
-// Horizontal bar
-BarMark(x: .value("Sales", item.sales), y: .value("Month", item.month))
-
-// Interval bar (Gantt chart)
-BarMark(
-    xStart: .value("Start", item.start),
-    xEnd: .value("End", item.end),
-    y: .value("Task", item.task)
-)
-```
+import Charts
+import SwiftUI
 
-### LineMark (iOS 16+)
+struct StepsChart: View {
+    let days: [DailySteps]
 
-```swift
-// Single line
-LineMark(x: .value("Date", item.date), y: .value("Price", item.price))
-
-// Multi-series via foregroundStyle encoding
-LineMark(x: .value("Date", item.date), y: .value("Temp", item.temp))
-    .foregroundStyle(by: .value("City", item.city))
-    .interpolationMethod(.catmullRom)
-
-// Multi-series with explicit series parameter
-LineMark(
-    x: .value("Date", item.date),
-    y: .value("Price", item.price),
-    series: .value("Ticker", item.ticker)
-)
+    var body: some View {
+        Chart(days) { entry in
+            BarMark(x: .value("Date", entry.date, unit: .day),
+                    y: .value("Steps", entry.count))
+        }
+    }
+}
 ```
 
-### PointMark (iOS 16+)
+- `Chart(data) { item in ... }` suits a single series.
+- `Chart { ForEach(...) { ... }; RuleMark(...) }` mixes marks and series.
+- `Chart(data, id: \.code) { ... }` uses a custom identifier.
+- Every value is wrapped as `.value("Label", value)`, a `PlottableValue`.
 
-```swift
-PointMark(x: .value("Height", item.height), y: .value("Weight", item.weight))
-    .foregroundStyle(by: .value("Species", item.species))
-    .symbol(by: .value("Species", item.species))
-    .symbolSize(100)
-```
+## Marks
 
-### AreaMark (iOS 16+)
+All of these are iOS 16 unless noted.
 
 ```swift
-// Stacked area
-AreaMark(x: .value("Date", item.date), y: .value("Sales", item.sales))
-    .foregroundStyle(by: .value("Category", item.category))
-
-// Range band
-AreaMark(
-    x: .value("Date", item.date),
-    yStart: .value("Min", item.min),
-    yEnd: .value("Max", item.max)
-)
-.opacity(0.3)
+Chart {
+    ForEach(sales) { sale in
+        BarMark(x: .value("Store", sale.store), y: .value("Units", sale.units))
+            .foregroundStyle(by: .value("Channel", sale.channel))
+    }
+}
 ```
 
-### RuleMark (iOS 16+)
+- **`BarMark`**: vertical with a category on x and a value on y; swap x and y
+  for horizontal bars. Several bars on the same x with `.foregroundStyle(by:)`
+  stack automatically. `BarMark(xStart:xEnd:y:)` draws an interval, the
+  building block of a Gantt chart.
+- **`LineMark`**: separate lines with `.foregroundStyle(by:)` or the
+  `series:` parameter; smooth with `.interpolationMethod(.catmullRom)`.
+- **`PointMark`**: combine with `.foregroundStyle(by:)`, `.symbol(by:)` and
+  `.symbolSize(100)`.
+- **`AreaMark`**: stacks with `.foregroundStyle(by:)`;
+  `AreaMark(x:yStart:yEnd:)` draws a band, usually with `.opacity(0.3)`.
+- **`RuleMark`**: a threshold line.
 
 ```swift
-RuleMark(y: .value("Target", 9000))
-    .foregroundStyle(.red)
-    .lineStyle(StrokeStyle(dash: [5, 3]))
+RuleMark(y: .value("Goal", 10_000))
+    .lineStyle(StrokeStyle(lineWidth: 1.5, dash: [6, 4]))
     .annotation(position: .top, alignment: .leading) {
-        Text("Target").font(.caption).foregroundStyle(.red)
+        Text("Daily goal").font(.caption)
     }
 ```
 
-### RectangleMark (iOS 16+)
+- **`RectangleMark(x:y:)`** with `.foregroundStyle(by:)`: the cells of a heat
+  map.
+- **`SectorMark`** (iOS 17): the slices of pies and donuts. Every value has
+  to be above zero; drop, combine or footnote any zero or negative entries
+  before they reach the chart.
 
 ```swift
-RectangleMark(x: .value("Hour", item.hour), y: .value("Day", item.day))
-    .foregroundStyle(by: .value("Intensity", item.intensity))
-```
-
-### SectorMark (iOS 17+)
-Use `SectorMark` for strictly positive values; filter, aggregate, or explain zero/negative values outside the pie or donut.
-```swift
-// Pie chart
-Chart(data, id: \.name) { item in
-    SectorMark(angle: .value("Sales", item.sales))
-        .foregroundStyle(by: .value("Category", item.name))
-}
-
-// Donut chart
-Chart(data, id: \.name) { item in
-    SectorMark(
-        angle: .value("Sales", item.sales),
-        innerRadius: .ratio(0.618),
-        outerRadius: .inset(10),
-        angularInset: 1
-    )
-    .cornerRadius(4)
-    .foregroundStyle(by: .value("Category", item.name))
+Chart(budget) { item in
+    SectorMark(angle: .value("Amount", item.amount),
+               innerRadius: .ratio(0.618),
+               outerRadius: .inset(10),
+               angularInset: 1)
+        .cornerRadius(4)
+        .foregroundStyle(by: .value("Envelope", item.envelope))
 }
 ```
 
-## Axis Customization
-
-```swift
-// Hide axes
-.chartXAxis(.hidden)
-.chartYAxis(.hidden)
+Drop `innerRadius` and `angularInset` for a plain pie:
+`SectorMark(angle:)` plus `.foregroundStyle(by:)`.
 
-// Custom axis content
-.chartXAxis {
-    AxisMarks(values: .stride(by: .month)) { value in
-        AxisGridLine()
-        AxisTick()
-        AxisValueLabel(format: .dateTime.month(.abbreviated))
-    }
-}
+## Axes
 
-// Multiple AxisMarks compositions (different intervals for grid vs. labels)
+```swift
 .chartXAxis {
     AxisMarks(values: .stride(by: .day)) { _ in AxisGridLine() }
-    AxisMarks(values: .stride(by: .week)) { _ in
+    AxisMarks(values: .stride(by: .weekOfYear)) { _ in
         AxisTick()
         AxisValueLabel(format: .dateTime.week())
     }
 }
-
-// Axis labels (titles)
-.chartXAxisLabel("Time", position: .bottom, alignment: .center)
-.chartYAxisLabel("Revenue ($)", position: .leading, alignment: .center)
+.chartYAxis(.hidden)
+.chartXAxisLabel("Date", position: .bottom, alignment: .center)
 ```
 
-## Scale Configuration
+- `.chartXAxis(.hidden)` and `.chartYAxis(.hidden)` remove an axis.
+- A single `AxisMarks(values: .stride(by: .month))` with `AxisGridLine()`,
+  `AxisTick()` and `AxisValueLabel(format: .dateTime.month(.abbreviated))` is
+  the common monthly axis.
+- Several `AxisMarks` in one builder give grid lines and labels different
+  intervals, as above.
+- Titles: `.chartXAxisLabel(_:position:alignment:)` and
+  `.chartYAxisLabel("Steps", position: .leading, alignment: .center)`.
+
+## Scales
 
 ```swift
-.chartYScale(domain: 0...100)                          // Explicit numeric domain
-.chartYScale(domain: .automatic(includesZero: true))   // Include zero
-.chartYScale(domain: 1...10000, type: .log)            // Logarithmic scale
-.chartXScale(domain: ["Mon", "Tue", "Wed", "Thu"])     // Categorical ordering
+.chartYScale(domain: 0...100)
+.chartYScale(domain: .automatic(includesZero: true))
+.chartYScale(domain: 1...10_000, type: .log)
+.chartXScale(domain: ["Small", "Medium", "Large", "XL"])
 ```
 
-## Foreground Style and Encoding
+A numeric range fixes the domain, `.automatic(includesZero: true)` keeps zero
+in view, `type: .log` gives a log scale, and an array of categories sets their
+order.
+
+## Colour and Encoding
 
 ```swift
-BarMark(...).foregroundStyle(.blue)                                    // Static color
-BarMark(...).foregroundStyle(by: .value("Category", item.category))   // Data encoding
-AreaMark(...).foregroundStyle(                                         // Gradient
-    .linearGradient(colors: [.blue, .cyan], startPoint: .bottom, endPoint: .top)
-)
+.foregroundStyle(.teal)
+.foregroundStyle(by: .value("Region", item.region))
+.foregroundStyle(.linearGradient(colors: [.teal, .blue],
+                                 startPoint: .bottom, endPoint: .top))
 ```
 
-## Selection (iOS 17+)
+A fixed style, a style driven by data, and a gradient.
+
+## Selection (iOS 17)
 
 ```swift
-@State private var selectedDate: Date?
-@State private var selectedRange: ClosedRange<Date>?
-@State private var selectedAngle: Double?
+@State private var pickedDay: Date?
+@State private var pickedWeek: ClosedRange<Date>?
+@State private var pickedAngle: Double?
 
-// Point selection
-Chart(data) { item in
-    LineMark(x: .value("Date", item.date), y: .value("Value", item.value))
-}
-.chartXSelection(value: $selectedDate)
+Chart(days) { BarMark(x: .value("Date", $0.date, unit: .day), y: .value("Steps", $0.count)) }
+    .chartXSelection(value: $pickedDay)
 
-// Range selection
-.chartXSelection(range: $selectedRange)
+Chart(days) { BarMark(x: .value("Date", $0.date, unit: .day), y: .value("Steps", $0.count)) }
+    .chartXSelection(range: $pickedWeek)
 
-// Angular selection binds the plottable angle value; derive the category from ranges.
-.chartAngleSelection(value: $selectedAngle)
+Chart(budget) { SectorMark(angle: .value("Amount", $0.amount)) }
+    .chartAngleSelection(value: $pickedAngle)
 ```
 
-## Scrollable Charts (iOS 17+)
+`chartAngleSelection` hands back a position along the cumulative angle value,
+not a category. Walk the sectors and add up their values to find which one
+contains it; the patterns file has a full example.
+
+## Scrolling (iOS 17)
 
 ```swift
-Chart(dailyData) { item in
-    BarMark(x: .value("Date", item.date, unit: .day), y: .value("Steps", item.steps))
+Chart(readings) { reading in
+    LineMark(x: .value("Time", reading.date, unit: .day),
+             y: .value("Level", reading.level))
 }
 .chartScrollableAxes(.horizontal)
-.chartXVisibleDomain(length: 3600 * 24 * 7) // 7 days visible
-.chartScrollPosition(initialX: latestDate)
+.chartXVisibleDomain(length: 3600 * 24 * 7)
+.chartScrollPosition(initialX: newestDate)
 .chartScrollTargetBehavior(
-    .valueAligned(matching: DateComponents(hour: 0), majorAlignment: .page)
-)
+    .valueAligned(matching: DateComponents(hour: 0),
+                  majorAlignment: .page))
 ```
 
+For a date axis the visible length is in seconds; this shows one week.
+`valueAligned` snaps to midnight and pages by the visible width. Bucket dates
+with `unit:` as in `.value("Time", reading.date, unit: .day)`.
+
 ## Annotations
 
 ```swift
-BarMark(x: .value("Month", item.month), y: .value("Sales", item.sales))
-    .annotation(position: .top, alignment: .center, spacing: 4) {
-        Text("\(item.sales, format: .number)").font(.caption2)
+BarMark(x: .value("Quarter", row.quarter), y: .value("Orders", row.orders))
+    .annotation(position: .top, alignment: .center, spacing: 6) {
+        Text(row.orders, format: .number.notation(.compactName))
     }
-
-// Overflow resolution
-.annotation(
-    position: .top,
-    overflowResolution: .init(x: .fit(to: .chart), y: .padScale)
-) { Text("Label") }
 ```
 
+When annotations near the edge get cut off:
+`.annotation(position: .top, overflowResolution: .init(x: .fit(to: .chart), y: .disabled))`,
+or `y: .padScale` to grow the scale so the annotation fits.
+
 ## Legend
 
 ```swift
-.chartLegend(.hidden)                                           // Hide
-.chartLegend(position: .bottom, alignment: .center, spacing: 10) // Position
-.chartLegend(position: .bottom) {                                // Custom
-    HStack {
-        ForEach(categories, id: \.self) { cat in
-            Label(cat, systemImage: "circle.fill").font(.caption)
-        }
-    }
-}
+.chartLegend(.hidden)
+.chartLegend(position: .top, alignment: .leading, spacing: 8)
+.chartLegend(position: .bottom) { RegionLegend(regions: regions) }
 ```
 
-## Vectorized Plots (iOS 18+)
+## Vectorized Plots (iOS 18)
 
-Use for large datasets (1000+ points). Accept entire collections or functions.
+For about 1,000 points or more. They take a whole collection, or a function.
 
 ```swift
-// Data-driven
 Chart {
-    BarPlot(sales, x: .value("Month", \.month), y: .value("Revenue", \.revenue))
-        .foregroundStyle(\.barColor)
+    BarPlot(hourly, x: .value("Hour", \.hour), y: .value("Requests", \.requests))
+        .foregroundStyle(\.tint)
+        .opacity(0.9)
 }
 
-// Function plotting: y = f(x)
 Chart {
-    LinePlot(x: "x", y: "y", domain: -5...5) { x in sin(x) }
+    LinePlot(x: "Input", y: "Output", domain: -3...3) { x in x * x * x - 4 * x }
 }
 
-// Parametric: (x, y) = f(t)
 Chart {
-    LinePlot(x: "x", y: "y", t: "t", domain: 0...(2 * .pi)) { t in
-        (x: cos(t), y: sin(t))
+    LinePlot(x: "East", y: "North", t: "Phase", domain: 0...(2 * .pi)) { phase in
+        (x: cos(3 * phase), y: sin(2 * phase))
     }
 }
 ```
 
-Apply KeyPath-based modifiers before simple-value modifiers:
+Modifiers that take a key path must come before modifiers that take a plain
+value; the other order does not compile.
 
-```swift
-BarPlot(data, x: .value("X", \.x), y: .value("Y", \.y))
-    .foregroundStyle(\.color)    // KeyPath first
-    .opacity(0.8)                // Value modifier second
-```
+## 3D Charts (iOS 26)
 
-## 3D Charts (iOS 26+)
-
-Use `Chart3D` for spatial data or bivariate surfaces, not as a decorative
-replacement for ordinary 2D categorical or time-series charts. `Chart3D`
-accepts `SurfacePlot` plus 3D initializers of `PointMark`, `RuleMark`, and
-`RectangleMark`.
+Use `Chart3D` for data with three real spatial dimensions or a surface of two
+variables. Do not use it to decorate ordinary category or time-series data.
+`Chart3D` accepts `SurfacePlot` and the 3D initialisers of `PointMark`,
+`RuleMark` and `RectangleMark`.
 
 ```swift
-@State private var pose: Chart3DPose = .default
-
-Chart3D {
-    SurfacePlot(x: "x", y: "y", z: "z") { x, z in
-        sin(2 * x) * cos(2 * z)
+struct TerrainChart: View {
+    @State private var viewAngle: Chart3DPose = .default
+
+    var body: some View {
+        Chart3D {
+            SurfacePlot(x: "Longitude", y: "Elevation", z: "Latitude") { x, z in
+                sin(x) * cos(z)
+            }
+            .foregroundStyle(.heightBased)
+        }
+        .chartXScale(domain: -3...3)
+        .chartYScale(domain: -1...1)
+        .chartZScale(domain: -3...3)
+        .chart3DPose($viewAngle)
     }
-    .foregroundStyle(.heightBased)
 }
-.chartXScale(domain: -2...2)
-.chartYScale(domain: -1...1)
-.chartZScale(domain: -2...2)
-.chart3DPose($pose)
 ```
 
 ## Common Mistakes
 
-### 1. Missing series parameter for multi-line charts
-
-```swift
-// WRONG -- all points connect into one line
-Chart {
-    ForEach(allCities) { item in
-        LineMark(x: .value("Date", item.date), y: .value("Temp", item.temp))
-    }
-}
-
-// CORRECT -- separate lines per city
-Chart {
-    ForEach(allCities) { item in
-        LineMark(x: .value("Date", item.date), y: .value("Temp", item.temp))
-            .foregroundStyle(by: .value("City", item.city))
-    }
-}
-```
-
-### 2. Too many SectorMark slices
-
-```swift
-// WRONG -- 20 tiny sectors are unreadable
-Chart(twentyCategories, id: \.name) { item in
-    SectorMark(angle: .value("Value", item.value))
-}
-
-// CORRECT -- group into top 5 + "Other"
-Chart(groupedData, id: \.name) { item in
-    SectorMark(angle: .value("Value", item.value))
-        .foregroundStyle(by: .value("Category", item.name))
-}
-```
-
-### 3. Missing scale domain when zero-baseline matters
-
-```swift
-// WRONG -- axis starts at ~95; small changes look dramatic
-Chart(data) {
-    LineMark(x: .value("Day", $0.day), y: .value("Score", $0.score))
-}
-
-// CORRECT -- explicit domain for honest representation
-Chart(data) {
-    LineMark(x: .value("Day", $0.day), y: .value("Score", $0.score))
-}
-.chartYScale(domain: 0...100)
-```
-
-### 4. Static foregroundStyle overriding data encoding
-
-```swift
-// WRONG -- static color overrides by-value encoding
-BarMark(x: .value("X", item.x), y: .value("Y", item.y))
-    .foregroundStyle(by: .value("Category", item.category))
-    .foregroundStyle(.blue)
-
-// CORRECT -- use only the data encoding
-BarMark(x: .value("X", item.x), y: .value("Y", item.y))
-    .foregroundStyle(by: .value("Category", item.category))
-```
-
-### 5. Individual marks for 10,000+ data points
-
-```swift
-// WRONG -- creates 10,000 mark views; slow
-Chart(largeDataset) { item in
-    PointMark(x: .value("X", item.x), y: .value("Y", item.y))
-}
-
-// CORRECT -- vectorized plot (iOS 18+)
-Chart {
-    PointPlot(largeDataset, x: .value("X", \.x), y: .value("Y", \.y))
-}
-```
-
-### 6. Fixed chart height breaking Dynamic Type
-
-```swift
-// WRONG -- clips axis labels at large text sizes
-Chart(data) { ... }
-    .frame(height: 200)
-
-// CORRECT -- adaptive sizing
-Chart(data) { ... }
-    .frame(minHeight: 200, maxHeight: 400)
-```
-
-### 7. KeyPath modifier after value modifier on vectorized plots
-
-```swift
-// WRONG -- compiler error
-BarPlot(data, x: .value("X", \.x), y: .value("Y", \.y))
-    .opacity(0.8)
-    .foregroundStyle(\.color)
-
-// CORRECT -- KeyPath modifiers first
-BarPlot(data, x: .value("X", \.x), y: .value("Y", \.y))
-    .foregroundStyle(\.color)
-    .opacity(0.8)
-```
-
-### 8. Missing accessibility labels
-
-```swift
-// WRONG -- VoiceOver users get no context
-Chart(data) {
-    BarMark(x: .value("Month", $0.month), y: .value("Sales", $0.sales))
-}
-
-// CORRECT -- add per-mark accessibility
-Chart(data) { item in
-    BarMark(x: .value("Month", item.month), y: .value("Sales", item.sales))
-        .accessibilityLabel("\(item.month)")
-        .accessibilityValue("\(item.sales) units sold")
-}
-```
-
-### 9. Treating angle selection as category selection
-
-`chartAngleSelection(value:)` binds the selected plottable angle value. For
-pie and donut charts, map that numeric value through cumulative sector ranges
-before comparing it to a category label.
+| Mistake | Fix |
+|---------|-----|
+| Several series drawn as one zig-zag line | Add `.foregroundStyle(by:)` or `series:` |
+| A pie with 20 slices | Keep the top five and group the rest as "Other" |
+| No explicit domain where the zero baseline matters, so small changes look huge | `.chartYScale(domain: 0...100)` or `includesZero` |
+| `.foregroundStyle(.blue)` after `.foregroundStyle(by:)` | The fixed style overrides the encoding; keep only the encoding |
+| 10,000 individual marks | `PointPlot` and the other vectorized plots (iOS 18) |
+| `.frame(height: 200)` clipping axis labels at large Dynamic Type sizes | `.frame(minHeight: 200, maxHeight: 400)` |
+| A plain-value modifier before a key-path modifier on a vectorized plot | Put key-path modifiers first |
+| No accessibility on marks | `.accessibilityLabel` and `.accessibilityValue` per mark |
+| Comparing the `chartAngleSelection` value with a category name | Map the angle through cumulative sector ranges first |
 
 ## Review Checklist
 
-- [ ] Data model uses `Identifiable` or chart uses `id:` key path
-- [ ] Mark type matches goal (bar=comparison, line=trend, sector=proportion)
-- [ ] Multi-series lines use `series:` parameter or `.foregroundStyle(by:)`
-- [ ] Axes configured with appropriate labels, ticks, and grid lines
-- [ ] Scale domain set explicitly when zero-baseline matters
-- [ ] Pie/donut uses positive values, 5-7 sectors, and "Other" grouping
-- [ ] Selection binding type matches axis data type (`Date?` for date axis)
-- [ ] Pie/donut angle selection maps numeric angle values back to categories
-- [ ] Scrollable charts set `.chartXVisibleDomain(length:)` for viewport
-- [ ] Vectorized plots used for datasets exceeding 1000 points
-- [ ] KeyPath modifiers applied before value modifiers on vectorized plots
-- [ ] `Chart3D` used only for real 3D data or surfaces, with z scale and pose reviewed
-- [ ] Accessibility labels added to marks for VoiceOver
-- [ ] Chart tested with Dynamic Type and Dark Mode
-- [ ] Legend visible and positioned, or intentionally hidden
-- [ ] Ensure chart data model types are Sendable; update chart data on @MainActor
-
-## References
-
-- Extended patterns: [references/charts-patterns.md](references/charts-patterns.md)
-- Apple docs: [Swift Charts](https://sosumi.ai/documentation/charts)
-- Apple docs: [Creating a chart using Swift Charts](https://sosumi.ai/documentation/charts/Creating-a-chart-using-Swift-Charts)
-- Apple docs: [Swift Charts updates](https://sosumi.ai/documentation/updates/swiftcharts)
-- Apple docs: [Chart3D](https://sosumi.ai/documentation/charts/Chart3D)
-- Apple docs: [SurfacePlot](https://sosumi.ai/documentation/charts/SurfacePlot)
+- [ ] Data is `Identifiable` or has an `id:` key path
+- [ ] The mark suits the question: bars compare, lines show trends, sectors show shares
+- [ ] Multi-series lines use `series:` or `.foregroundStyle(by:)`
+- [ ] Axes have suitable labels, ticks and grid lines
+- [ ] An explicit domain where the zero baseline matters
+- [ ] Pies and donuts: positive values, five to seven slices, an "Other" group
+- [ ] Selection bindings match the axis type (`Date?` for a date axis)
+- [ ] Angle selection is mapped back to a category
+- [ ] Scrollable charts set `.chartXVisibleDomain(length:)`
+- [ ] Vectorized plots for more than about 1,000 points, key-path modifiers first
+- [ ] `Chart3D` reserved for genuine spatial data or surfaces; z domain and pose reviewed
+- [ ] Marks carry accessibility labels; checked at large text sizes and in Dark Mode
+- [ ] The legend is visible and placed, or hidden on purpose
+- [ ] Chart data types are `Sendable`, and chart data is updated on the main actor
+
+## Apple Documentation
+
+- [Swift Charts](https://developer.apple.com/documentation/charts)
+- [Building a first chart](https://developer.apple.com/documentation/charts/creating-a-chart-using-swift-charts)
+- [Swift Charts updates](https://developer.apple.com/documentation/updates/swiftcharts)
+- [Chart3D](https://developer.apple.com/documentation/charts/chart3d)
+- [SurfacePlot](https://developer.apple.com/documentation/charts/surfaceplot)