spec: add violin-swarm specification (#3528)

## New Specification: `violin-swarm`

Related to #3526

---

### specification.md

# violin-swarm: Violin Plot with Overlaid Swarm Points

## Description

A violin plot with individual data points overlaid as a swarm plot,
combining smooth kernel density estimation with raw data visibility. The
violin shape shows the distribution density while the swarm points
reveal actual observations, enabling viewers to see both the overall
distribution pattern and individual data values simultaneously. This
hybrid approach provides maximum transparency, showing exactly how many
observations exist at each level while maintaining the smooth
distribution visualization.

## Applications

- Comparing gene expression levels across treatment conditions in
biological research
- Analyzing response time distributions across experimental groups while
showing individual trials
- Visualizing patient biomarker values across clinical groups with full
data transparency
- Presenting survey response distributions where sample sizes vary
between groups

## Data

- `category` (categorical) - Group labels for comparison on the
categorical axis
- `value` (numeric) - Continuous variable values shown on the value axis
- Size: 20-200 observations per category, 2-5 categories
- Example: Reaction times (ms) across 4 experimental conditions with 50
observations each

## Notes

- Overlay swarm points on top of the violin, centered within the violin
shape
- Use transparency on the violin (alpha 0.3-0.5) so swarm points remain
visible
- Size swarm points appropriately to avoid excessive overlap while
remaining visible
- Consider using a contrasting color for points vs violin fill
- Swarm points should spread horizontally to avoid overlap, staying
within the violin boundary

---

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

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

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

Author: github-actions[bot]

plots/violin-swarm/specification.md

@@ -0,0 +1,27 @@
+# violin-swarm: Violin Plot with Overlaid Swarm Points
+
+## Description
+
+A violin plot with individual data points overlaid as a swarm plot, combining smooth kernel density estimation with raw data visibility. The violin shape shows the distribution density while the swarm points reveal actual observations, enabling viewers to see both the overall distribution pattern and individual data values simultaneously. This hybrid approach provides maximum transparency, showing exactly how many observations exist at each level while maintaining the smooth distribution visualization.
+
+## Applications
+
+- Comparing gene expression levels across treatment conditions in biological research
+- Analyzing response time distributions across experimental groups while showing individual trials
+- Visualizing patient biomarker values across clinical groups with full data transparency
+- Presenting survey response distributions where sample sizes vary between groups
+
+## Data
+
+- `category` (categorical) - Group labels for comparison on the categorical axis
+- `value` (numeric) - Continuous variable values shown on the value axis
+- Size: 20-200 observations per category, 2-5 categories
+- Example: Reaction times (ms) across 4 experimental conditions with 50 observations each
+
+## Notes
+
+- Overlay swarm points on top of the violin, centered within the violin shape
+- Use transparency on the violin (alpha 0.3-0.5) so swarm points remain visible
+- Size swarm points appropriately to avoid excessive overlap while remaining visible
+- Consider using a contrasting color for points vs violin fill
+- Swarm points should spread horizontally to avoid overlap, staying within the violin boundary

plots/violin-swarm/specification.yaml

@@ -0,0 +1,29 @@
+# Specification-level metadata for violin-swarm
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: violin-swarm
+title: Violin Plot with Overlaid Swarm Points
+
+# Specification tracking
+created: 2026-01-09T16:30:41Z
+updated: null
+issue: 3526
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/reference/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - violin
+    - swarm
+  data_type:
+    - numeric
+    - categorical
+  domain:
+    - statistics
+    - research
+    - general
+  features:
+    - distribution
+    - comparison
+    - combined