spec: add area-stacked-confidence specification (#3551)

## New Specification: `area-stacked-confidence`

Related to #3549

---

### specification.md

# area-stacked-confidence: Stacked Area Chart with Confidence Bands

## Description

A stacked area chart that displays multiple data series as cumulative
areas, with each series surrounded by uncertainty or confidence bands.
This visualization combines the composition insight of stacked areas
with the statistical rigor of confidence intervals, making it ideal for
showing how parts contribute to a whole while simultaneously
communicating uncertainty in each component. The bands reveal where
estimates are precise versus uncertain across the stacked series.

## Applications

- Forecasting market share by competitor with prediction intervals
- Displaying portfolio allocation over time with risk bands for each
asset class
- Showing energy consumption breakdown by source with measurement
uncertainty
- Visualizing population projections by age group with demographic
uncertainty

## Data

- `x` (datetime/numeric) - continuous axis values, typically time
periods
- `y1, y2, y3, ...` (numeric) - central values for each series to be
stacked
- `y1_lower, y1_upper, ...` (numeric) - lower and upper bounds of
confidence bands for each series
- `category` (categorical) - labels identifying each series
- Size: 20-100 time points, 2-5 series
- Example: quarterly revenue forecasts by product line with 90%
prediction intervals

## Notes

- Use distinct colors for each series, with matching lighter shades for
confidence bands
- Semi-transparent fills (alpha 0.2-0.4) for bands to show overlap
without obscuring data
- Stack order should be consistent between central values and their
bands
- Consider using gradient fills from lower to upper bound for visual
clarity
- Include legend identifying each series and what the bands represent
- Bands should be symmetric around each series or explicitly labeled if
asymmetric

---

**Next:** Add `approved` label to the issue to merge this PR.

---
:robot: *[spec-create
workflow](https://github.com/MarkusNeusinger/pyplots/actions/runs/20866456345)*

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

plots/area-stacked-confidence/specification.md

@@ -0,0 +1,30 @@
+# area-stacked-confidence: Stacked Area Chart with Confidence Bands
+
+## Description
+
+A stacked area chart that displays multiple data series as cumulative areas, with each series surrounded by uncertainty or confidence bands. This visualization combines the composition insight of stacked areas with the statistical rigor of confidence intervals, making it ideal for showing how parts contribute to a whole while simultaneously communicating uncertainty in each component. The bands reveal where estimates are precise versus uncertain across the stacked series.
+
+## Applications
+
+- Forecasting market share by competitor with prediction intervals
+- Displaying portfolio allocation over time with risk bands for each asset class
+- Showing energy consumption breakdown by source with measurement uncertainty
+- Visualizing population projections by age group with demographic uncertainty
+
+## Data
+
+- `x` (datetime/numeric) - continuous axis values, typically time periods
+- `y1, y2, y3, ...` (numeric) - central values for each series to be stacked
+- `y1_lower, y1_upper, ...` (numeric) - lower and upper bounds of confidence bands for each series
+- `category` (categorical) - labels identifying each series
+- Size: 20-100 time points, 2-5 series
+- Example: quarterly revenue forecasts by product line with 90% prediction intervals
+
+## Notes
+
+- Use distinct colors for each series, with matching lighter shades for confidence bands
+- Semi-transparent fills (alpha 0.2-0.4) for bands to show overlap without obscuring data
+- Stack order should be consistent between central values and their bands
+- Consider using gradient fills from lower to upper bound for visual clarity
+- Include legend identifying each series and what the bands represent
+- Bands should be symmetric around each series or explicitly labeled if asymmetric

plots/area-stacked-confidence/specification.yaml

@@ -0,0 +1,30 @@
+# Specification-level metadata for area-stacked-confidence
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: area-stacked-confidence
+title: Stacked Area Chart with Confidence Bands
+
+# Specification tracking
+created: 2026-01-09T21:45:47Z
+updated: null
+issue: 3549
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/reference/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - area
+    - stacked
+  data_type:
+    - numeric
+    - timeseries
+  domain:
+    - general
+    - statistics
+    - finance
+  features:
+    - stacked
+    - uncertainty
+    - cumulative
+    - temporal