spec: add circlepacking-basic specification (#2506)

## New Specification: `circlepacking-basic`

Related to #2498

---

### specification.md

# circlepacking-basic: Circle Packing Chart

## Description

A circle packing chart displays hierarchical data as nested circles,
where each circle contains smaller circles representing its children.
Circle size is proportional to node value, and circles are packed
efficiently without overlap. This visualization excels at revealing
hierarchical structures while simultaneously showing quantitative
relationships through area encoding.

## Applications

- File and folder size visualization showing directory hierarchy and
storage consumption
- Organizational structure display with team sizes proportional to
headcount or budget
- Portfolio composition analysis breaking down investments by asset
class and holdings
- Taxonomy or classification hierarchies with proportional
representation of categories

## Data

- `id` (string) - unique identifier for each node
- `parent` (string) - parent node identifier (null for root)
- `value` (numeric) - size value determining circle area (for leaf
nodes)
- `label` (string) - display name for the node
- Size: 20-200 nodes across 2-4 hierarchy levels

## Notes

- Pack circles efficiently using force simulation or specialized packing
algorithms
- Color by depth level or category to distinguish hierarchy levels
- Display labels for larger circles; smaller circles may show labels on
hover
- Scale circle sizes by area (not radius) for accurate visual perception
- Root circle should encompass all children with appropriate padding

---

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

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

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

Author: github-actions[bot]

plots/circlepacking-basic/specification.md

@@ -0,0 +1,28 @@
+# circlepacking-basic: Circle Packing Chart
+
+## Description
+
+A circle packing chart displays hierarchical data as nested circles, where each circle contains smaller circles representing its children. Circle size is proportional to node value, and circles are packed efficiently without overlap. This visualization excels at revealing hierarchical structures while simultaneously showing quantitative relationships through area encoding.
+
+## Applications
+
+- File and folder size visualization showing directory hierarchy and storage consumption
+- Organizational structure display with team sizes proportional to headcount or budget
+- Portfolio composition analysis breaking down investments by asset class and holdings
+- Taxonomy or classification hierarchies with proportional representation of categories
+
+## Data
+
+- `id` (string) - unique identifier for each node
+- `parent` (string) - parent node identifier (null for root)
+- `value` (numeric) - size value determining circle area (for leaf nodes)
+- `label` (string) - display name for the node
+- Size: 20-200 nodes across 2-4 hierarchy levels
+
+## Notes
+
+- Pack circles efficiently using force simulation or specialized packing algorithms
+- Color by depth level or category to distinguish hierarchy levels
+- Display labels for larger circles; smaller circles may show labels on hover
+- Scale circle sizes by area (not radius) for accurate visual perception
+- Root circle should encompass all children with appropriate padding

plots/circlepacking-basic/specification.yaml

@@ -0,0 +1,28 @@
+# Specification-level metadata for circlepacking-basic
+# Auto-synced to PostgreSQL on push to main
+
+spec_id: circlepacking-basic
+title: Circle Packing Chart
+
+# Specification tracking
+created: 2025-12-29T23:55:27Z
+updated: null
+issue: 2498
+suggested: MarkusNeusinger
+
+# Classification tags (applies to all library implementations)
+# See docs/concepts/tagging-system.md for detailed guidelines
+tags:
+  plot_type:
+    - circle-packing
+    - hierarchy
+  data_type:
+    - hierarchical
+    - numeric
+  domain:
+    - general
+    - business
+  features:
+    - basic
+    - nested
+    - proportional