spec: add violin-grouped-swarm specification (#3530)

## New Specification: `violin-grouped-swarm`

Related to #3529

---

### specification.md

# violin-grouped-swarm: Grouped Violin Plot with Swarm Overlay

## Description

A grouped violin plot with individual data points overlaid as swarm
points, showing distributions across two categorical dimensions
simultaneously. Multiple violin plots are arranged by category on the
x-axis and grouped by a secondary variable using color/hue, with swarm
points revealing the underlying raw data. This visualization combines
distribution shape visualization with complete data transparency, ideal
for comparing how distributions differ across multiple factors.

## Applications

- Comparing drug efficacy distributions across multiple dosage levels
and treatment groups
- Analyzing performance metrics across departments and employee
seniority levels
- Visualizing experimental results across conditions and time points in
research studies
- Comparing customer satisfaction scores across product categories and
regions

## Data

- `category` (categorical) - Primary grouping variable for x-axis
positioning
- `group` (categorical) - Secondary grouping variable for hue/color
differentiation
- `value` (numeric) - Continuous variable values shown on the value axis
- Size: 20-150 observations per category-group combination, 2-4
categories, 2-4 groups
- Example: Response times across 3 task types and 2 expertise levels
with 40 observations each

## Notes

- Use distinct colors for each group with a clear legend
- Apply transparency to violins (alpha 0.4-0.6) so swarm points remain
visible
- Size swarm points appropriately (smaller than single-category version
due to space constraints)
- Ensure adequate spacing between grouped violins to prevent overlap
- Swarm points should match the hue of their corresponding violin
- Consider dodging swarm points to align with their respective violin
position

---

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

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

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

Author: github-actions[bot]

plots/violin-grouped-swarm/specification.md

@@ -0,0 +1,29 @@
+# violin-grouped-swarm: Grouped Violin Plot with Swarm Overlay
+
+## Description
+
+A grouped violin plot with individual data points overlaid as swarm points, showing distributions across two categorical dimensions simultaneously. Multiple violin plots are arranged by category on the x-axis and grouped by a secondary variable using color/hue, with swarm points revealing the underlying raw data. This visualization combines distribution shape visualization with complete data transparency, ideal for comparing how distributions differ across multiple factors.
+
+## Applications
+
+- Comparing drug efficacy distributions across multiple dosage levels and treatment groups
+- Analyzing performance metrics across departments and employee seniority levels
+- Visualizing experimental results across conditions and time points in research studies
+- Comparing customer satisfaction scores across product categories and regions
+
+## Data
+
+- `category` (categorical) - Primary grouping variable for x-axis positioning
+- `group` (categorical) - Secondary grouping variable for hue/color differentiation
+- `value` (numeric) - Continuous variable values shown on the value axis
+- Size: 20-150 observations per category-group combination, 2-4 categories, 2-4 groups
+- Example: Response times across 3 task types and 2 expertise levels with 40 observations each
+
+## Notes
+
+- Use distinct colors for each group with a clear legend
+- Apply transparency to violins (alpha 0.4-0.6) so swarm points remain visible
+- Size swarm points appropriately (smaller than single-category version due to space constraints)
+- Ensure adequate spacing between grouped violins to prevent overlap
+- Swarm points should match the hue of their corresponding violin
+- Consider dodging swarm points to align with their respective violin position

plots/violin-grouped-swarm/specification.yaml

@@ -0,0 +1,29 @@
+# Specification-level metadata for violin-grouped-swarm
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: violin-grouped-swarm
+title: Grouped Violin Plot with Swarm Overlay
+
+# Specification tracking
+created: 2026-01-09T16:38:22Z
+updated: null
+issue: 3529
+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:
+    - grouped
+    - distribution
+    - comparison