@rokkit/cli 1.6.0 → 1.8.0

package/agents/rokkit-chart-reviewer.md

@@ -39,7 +39,8 @@ the vocabulary — cite it, don't restate it.
   Colours/patterns/symbols come from `createChartPreset()` shared via `<ChartProvider>` (nest to
   scope a subtree); named presets (`default`/`accessible`/`print`, or `helpers.presets`) go through
   `spec.preset`. Adding a *new* colour/pattern/symbol means extending a registry
-  (`lib/palette.json` / `patterns/patterns.js` `PATTERNS` / `lib/brewing/marks/points.js`
+  (`@rokkit/core` `categoricalPalette` / `patterns/patterns.js` `PATTERNS` /
+  `lib/brewing/marks/points.js`
   `SYMBOL_NAMES`+`SYMBOL_TYPES`) then naming it in a preset — never inlining scattered raw colours.
 - **Colour follows the theme.** Preset shades resolve per light/dark mode; a chart should reskin
   from the preset/skin, not from hardcoded per-mark hex. Token-literal fills are fine when
@@ -47,6 +48,12 @@ the vocabulary — cite it, don't restate it.
 - **Accessibility is not free.** Colour-only encoding fails for print/colourblind — patterns
   (`pattern` channel) dual-code series. Interactive charts need `keyboard`/`onselect` and the
   `role`/`aria-label` the geoms provide.
+- **Plane annotations go first, and the theory fixes the frame.** `Region`, `Hull` and `Contour`
+  describe the metric plane, and SVG paints in document order — placed after `Plot.Point` they
+  paint over it. A `Region` never moves the scales, so a plane defined by theory (Martin's
+  `[0,1]×[0,1]`) needs `xDomain`/`yDomain` on `PlotChart`, or a zone shrinks to wherever the rows
+  fall. `Rule slope` is ignored on a band axis. Thresholds on skewed metrics belong at a high
+  percentile of the data (p95), not a guessed constant.
 - **Evidence beats assertion.** You do not say "it themes" — you build and snapshot and paste what
   you saw.
 
@@ -66,6 +73,9 @@ the vocabulary — cite it, don't restate it.
 8. Is there a colour-independent encoding (pattern) where accessibility/print matters, and are
    interactive charts keyboard/aria-enabled?
 9. Does the chart hold up in light AND dark mode (no invisible marks, no overflow)?
+10. Are `Region` / `Hull` / `Contour` placed before the marks they sit behind, and is the domain
+    fixed where a region — not the data — defines the frame? Do many overlapping hulls default to
+    off rather than stacking into mud?
 
 ## Procedure
 
@@ -79,9 +89,11 @@ results than blind grep. Fall back to Grep/Glob only if a tool errors or returns
    `orientation`, `alpha`, and preset config.
 3. Grep the app's `.svelte` for the smells: `<Plot ` (stale root), `<GeomBar`/`<GeomLine` used as a
    root, `opacity=` on a chart, `stack\b` as a boolean prop, `palette=` / `preset=` on a chart,
-   raw `#[0-9a-fA-F]{3,8}`/`oklch(`/`rgb(` inside chart props. Map each hit to the correct
+   raw `#[0-9a-fA-F]{3,8}`/`oklch(`/`rgb(` inside chart props, and a `Plot.Region`/`Plot.Hull`/
+   `Plot.Contour` that follows a `Plot.Point` in the same chart. Map each hit to the correct
    channel/preset fix.
-4. If a new palette/pattern/symbol was added, verify it's in the right registry (`palette.json` /
+4. If a new palette/pattern/symbol was added, verify it's in the right registry
+   (`categoricalPalette` /
    `PATTERNS` / `SYMBOL_*`) with the right shape, and referenced by name in a preset. Run
    `rokkit doctor` if available and fold in its advisories.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/cli",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Command line utilities for icon bundling and conversion.",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@mdi/svg": "^7.4.47",
-    "@rokkit/unocss": "1.6.0",
+    "@rokkit/unocss": "1.8.0",
     "sade": "^1.8.1",
     "@iconify/tools": "^5.0.14",
     "@iconify/types": "^2.0.0",

package/skills/charts-rokkit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: charts-rokkit
-description: Use when building, styling, customizing, or theming data visualizations with @rokkit/chart in a Svelte 5 app — the ggplot-style geom/aesthetic model (fill/color/pattern/group/size/symbol/alpha/position/orientation + literal-colour tokens), the PlotChart root + Plot.* geom namespace and prebuilt chart shapes, the spec API, and the preset system (colors/patterns/symbols via createChartPreset + ChartProvider, plus how to ADD a new colour palette, pattern, or symbol to the library).
+description: Use when building, styling, customizing, or theming data visualizations with @rokkit/chart in a Svelte 5 app — the ggplot-style geom/aesthetic model (fill/color/pattern/group/size/symbol/alpha/position/orientation + literal-colour tokens), the PlotChart root + Plot.* geom namespace and prebuilt chart shapes, plane annotations (Rule with slope/intercept, Region bands/polygons, Hull per group, density Contour) and the architecture-analysis recipes built from them (Martin's main sequence, hotspots, complexity × coverage, fan-in/fan-out, god modules), the spec API, and the preset system (colors/patterns/symbols via createChartPreset + ChartProvider, plus how to ADD a new colour palette, pattern, or symbol to the library).
 ---
 
 # Charts — Rokkit (`@rokkit/chart`)
@@ -12,7 +12,8 @@ and symbols. There is no per-chart `palette` array prop; customization goes thro
 
 ```text
 data + channels (or spec)
-   → PlotState  (scales, colorMap, patternMap, symbolMap, geom registry, selection, zoom)
+   → PlotState  (a composition of job classes: config, geoms, frame, channels, orientation,
+                 interaction, scales, aesthetics, axes — see docs/design/20-chart.md)
    → PlotChart  (SVG: geoms + axes + grid + legend + tooltip + overlays)
 
 preset (colors / patterns / symbols / shades / opacity)
@@ -53,7 +54,8 @@ Shapes: `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `ScatterPlot`, `Bubble
 `Plot` is a **namespace object** (`Plot.Bar`, `Plot.Line`, …), not a component — the root is
 `PlotChart`. Each member equals its `Geom*` export (`Plot.Bar === GeomBar`); use either. Full set:
 `Bar`, `Line`, `Area`, `Point`, `Jitter`, `Arc`, `Box`, `Violin`, `Heatmap`, `Hexbin`,
-`Candlestick`, `Waterfall`, `Ribbon`, `Rule`, plus overlays `Highlight` / `Trend`.
+`Candlestick`, `Waterfall`, `Ribbon`, `Radar`, `Rule`, `Region`, `Hull`, `Contour`, plus overlays
+`Highlight` / `Trend`.
 
 **3. Spec API** (full control from a plain object — same result as composition):
 
@@ -119,7 +121,8 @@ Every categorical encoding is driven by a **preset** (`packages/chart/src/lib/pr
 
 Each list is **names into a registry**, cycled across your data's distinct values:
 
-- `colors` → palette names in **`lib/palette.json`** (each name → 11 shades `50–950`).
+- `colors` → palette names in **`@rokkit/core`'s `categoricalPalette`** (each name → 11 shades
+  `50–950`).
   `assignColors(values, mode, preset)` picks `palette[name][shades[mode].fill|stroke]` — so a chart
   re-colours correctly for light/dark automatically.
 - `patterns` → names in **`patterns/patterns.js`** (`PATTERNS`, the SVG mark defs).
@@ -134,7 +137,7 @@ and share it via `ChartProvider`:
 <script>
   import { ChartProvider, createChartPreset, BarChart, LineChart } from '@rokkit/chart'
   const preset = createChartPreset({
-    colors: ['teal', 'orange', 'rose'],   // subset/reorder of palette.json names
+    colors: ['teal', 'orange', 'rose'],   // subset/reorder of categoricalPalette names
     patterns: ['dots', 'hatch'],
     shades: { dark: { fill: '400' } }      // partial shade override (merges)
   })
@@ -157,7 +160,8 @@ and share it via `ChartProvider`:
 
 ### Add a NEW colour palette
 
-1. Add an 11-shade entry to `packages/chart/src/lib/palette.json` (shades `50`→`950`, light→dark):
+1. Add an 11-shade entry to `packages/core/src/colors/categorical.json` (shades `50`→`950`,
+   light→dark). It lives in core because `@rokkit/chart` and `@rokkit/graph` both consume it:
 
    ```json
    "brand": { "50": "#f4f7ff", "100": "…", "300": "#93b4ff", "500": "#3b6cff",
@@ -230,6 +234,56 @@ decorations expose `data-*` hooks: `[data-plot-geom="<type>"]`, `[data-plot-elem
 
 ---
 
+## Annotating the plane — Rule, Region, Hull, Contour
+
+These describe the metric PLANE, not a row. SVG paints in document order, so place them **before**
+the marks they sit behind.
+
+```svelte
+<PlotChart data={components} xDomain={[0, 1]} yDomain={[0, 1]} legend tooltip>
+  <Plot.Region name="pain" points={[[0, 0], [0.5, 0], [0, 0.5]]} label="Zone of pain" />
+  <Plot.Region name="uselessness" points={[[1, 1], [0.5, 1], [1, 0.5]]} label="Zone of uselessness" />
+  <Plot.Hull x="instability" y="abstractness" color="package" />
+  <Plot.Contour x="instability" y="abstractness" bandwidth={28} />
+  <Plot.Rule slope={-1} intercept={1} label="main sequence" />
+  <Plot.Point x="instability" y="abstractness" color="package" size="loc" />
+</PlotChart>
+```
+
+- **`Rule`** — `x` / `y` values, or `slope` + `intercept` (ggplot's abline), clipped to the visible
+  domain and labelled at its midpoint along the line. A slope is ignored on a band axis.
+- **`Region`** — `x` / `y` as `[lo, hi]` (a `null` end runs to the axis edge: `[p95, null]`), or a
+  polygon `points`. Reads no data, never moves the scales, clipped to the plot. `name` →
+  `data-plot-region` for theming; `label` at the centroid or `labelAt`.
+- **`Hull`** — one padded convex hull per value of `fill` / `color`; the group field joins the
+  shared palette. A one- or two-member group still draws (dot, capsule).
+- **`Contour`** — kernel-density contours per group; `bandwidth` is in pixels; `filled` for bands.
+
+**The frame comes from the theory, not the data.** A region never moves the scales, so fix the
+domain on `PlotChart` (`xDomain` / `yDomain`) when the plane is defined — or a zone shrinks because
+no row happens to fall in it.
+
+### Architecture analysis (recipes, not components)
+
+The library ships no architecture vocabulary — the recipes are ordinary geoms over metric rows the
+consumer computes (the learn site measures rokkit itself with
+`apps/learn/scripts/build-architecture-metrics.mjs`):
+
+| Recipe | x × y | Annotations |
+|--------|-------|-------------|
+| Main sequence (Robert Martin) | instability `Ce/(Ca+Ce)` × abstractness | zone polygons, `Rule slope={-1} intercept={1}`, `Hull` per package, `Contour` for the pile-up at A = 0 |
+| Hotspots | complexity × churn | `Region x={[p95, null]} y={[p95, null]}` |
+| Complexity × coverage | complexity × coverage | `Region` for complex-and-under-tested, `Rule y={0.8}` |
+| Fan-in × fan-out | fan-out × fan-in | `Region` for hubs and for reaches-everywhere |
+| God modules | complexity × fan-out | `Region` past p95 on both |
+
+Martin's metrics are per COMPONENT (a package or top-level folder); per file, most points sit
+exactly on (0,0) or (1,0). Take thresholds as percentiles of the codebase, and the 95th rather than
+the 90th — these distributions are heavy-tailed. For dependency structure and hidden coupling, reach
+for `@rokkit/graph`: `DependencyMatrix`, and edges flagged `overlay` (drawn, never shaping layout).
+
+---
+
 ## Gotchas
 
 - The root is **`PlotChart`**, not `<Plot>` — `Plot` is the geom namespace object.
@@ -240,6 +294,8 @@ decorations expose `data-*` hooks: `[data-plot-geom="<type>"]`, `[data-plot-elem
 - `position="stack"` supersedes the boolean `stack` prop; grouping needs a `fill`/`color`/`group`
   field (a stack with no group field renders individual bars, not a stacked total).
 - A literal colour on `fill`/`color` is applied directly — it is **not** a legend group.
+- `Region`, `Hull` and `Contour` placed AFTER `Plot.Point` paint over the points. Put them first.
+- A `Hull` over many overlapping groups stacks translucent fills into mud — offer it as a toggle.
 
 ## Verify