From 238e676c6a74f6bbd7d75bd9e67e0a261d91bfc5 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Sun, 14 Dec 2025 18:16:26 +0000
Subject: [PATCH] spec: add sankey-basic specification

Created from issue #810
---
 plots/sankey-basic/specification.md   | 26 +++++++++++++++++++++++
 plots/sankey-basic/specification.yaml | 30 +++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 plots/sankey-basic/specification.md
 create mode 100644 plots/sankey-basic/specification.yaml

diff --git a/plots/sankey-basic/specification.md b/plots/sankey-basic/specification.md
new file mode 100644
index 0000000000..40753dd1bd
--- /dev/null
+++ b/plots/sankey-basic/specification.md
@@ -0,0 +1,26 @@
+# sankey-basic: Basic Sankey Diagram
+
+## Description
+
+A Sankey diagram visualizes flow or transfer between nodes using links with widths proportional to flow values. It excels at showing how quantities distribute from sources to destinations, revealing patterns in resource allocation, process flows, and system transitions. The diagram makes it easy to identify major pathways and compare relative magnitudes of different flows.
+
+## Applications
+
+- Visualizing energy flows from sources (coal, gas, nuclear) through transformation to end uses (heating, transport, industry)
+- Tracking budget allocations from revenue sources through departments to specific expense categories
+- Analyzing website traffic paths from entry pages through navigation to conversion or exit points
+
+## Data
+
+- `source` (categorical) - the origin node of each flow
+- `target` (categorical) - the destination node of each flow
+- `value` (numeric) - the magnitude of flow between source and target
+- Size: 5-50 flows (too many flows reduce readability)
+- Example: Energy flow data with sources like "Coal", "Gas", "Nuclear" flowing to sectors like "Residential", "Commercial", "Industrial"
+
+## Notes
+
+- Ensure no circular flows (source cannot equal target in the same link)
+- Node labels should be clearly visible and not overlap with links
+- Use distinct colors for different source categories or flow types
+- Link opacity can help when flows cross over each other
diff --git a/plots/sankey-basic/specification.yaml b/plots/sankey-basic/specification.yaml
new file mode 100644
index 0000000000..8b9a673485
--- /dev/null
+++ b/plots/sankey-basic/specification.yaml
@@ -0,0 +1,30 @@
+# Specification-level metadata for sankey-basic
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: sankey-basic
+title: Basic Sankey Diagram
+
+# Specification tracking
+created: 2025-12-14T18:16:04Z
+issue: 810
+suggested: MarkusNeusinger
+history: []
+
+# Classification tags (applies to all library implementations)
+tags:
+  plot_type:
+    - sankey
+    - flow
+  domain:
+    - general
+    - business
+    - energy
+  features:
+    - basic
+    - flow-visualization
+    - proportional
+  audience:
+    - intermediate
+  data_type:
+    - categorical
+    - numeric