@rokkit/cli 1.7.0 → 1.8.1

package/agents/rokkit-chart-reviewer.md

@@ -48,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.
 
@@ -67,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
 
@@ -80,7 +89,8 @@ 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
    (`categoricalPalette` /

package/agents/rokkit-components-reviewer.md

@@ -58,6 +58,11 @@ don't restate it.
   hardcoded `font-family:` or arbitrary `font-[...]` in component markup; map it to the right class.
 - Faces belong in config, not per-component. If a needed face isn't declared, the fix is to add it
   to `typography:` (a styling-config change — hand off to the styles review), not to inline it.
+- Heading LEVELS come from `[data-heading='1'..'4']` rules in `@rokkit/themes` (face, size,
+  weight, line-height and tracking together): a title takes `data-heading="2"`, and prose under
+  `data-prose` gets its `h1`–`h4` styled. Flag a hand-built heading (`text-2xl font-semibold`
+  on a title, or a per-component `font-size` for a heading) and map it to `data-heading`.
+  There are no `--text-*` scale tokens — a `var(--text-…)` read is a bug.
 
 ## Procedure
 
@@ -97,7 +102,7 @@ don't have. A piped/`| tail` exit status reports the pipe, not the command: read
   tier · the simpler rewrite (when demotable).
 - **Custom icons** — findings: unloaded collections, snippet-for-an-icon, inline SVG → `i-*` class.
 - **Typography** — hardcoded `font-family`/`font-[...]` findings → `font-heading/body/mono` (or a
-  `typography:` config addition to hand off).
+  `typography:` config addition to hand off); hand-built headings → `data-heading`.
 - **Contract hygiene** — off-contract usage (wrong data prop, manual focus, `onclick` on `[data-path]`).
 - **Verification evidence** — the pasted build output + Playwright snapshot summary (light/dark).
 - **### Verdict PASS/FAIL** — PASS only when each usage is at the simplest tier that works, icons and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/cli",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "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.7.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,19 +54,24 @@ 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):
 
 ```svelte
 <PlotChart {data} spec={{
   geoms: [
-    { type: 'bar',  channels: { x: 'quarter', y: 'revenue', fill: 'product' }, stat: 'sum' },
-    { type: 'line', channels: { x: 'quarter', y: 'forecast', color: 'class' } }
+    { type: 'bar',  x: 'quarter', y: 'revenue', fill: 'product', stat: 'sum' },
+    { type: 'line', x: 'quarter', y: 'forecast', color: 'class' }
   ]
 }} />
 ```
 
+Fields go on the geom itself. There is no `channels: { … }` wrapper, and a geom written with one
+draws nothing. Set `x`/`y`/`color` once on the spec and every geom inherits them. A spec value
+overrides the matching prop, except `orientation`, where the prop wins.
+
 ---
 
 ## Aesthetic channels
@@ -232,6 +238,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.
@@ -242,6 +298,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
 

package/skills/semantic-styles-rokkit/SKILL.md

@@ -351,6 +351,12 @@ aliases. Usage classes: `font-heading` (display face), `font-body` (UI face), `f
 <code class="font-mono text-xs text-ink-soft">path/to/file.ts</code>
 ```
 
+**Heading levels** come from `[data-heading='1'..'4']` rules in `@rokkit/themes` (face, size,
+weight, line-height and tracking together). Give a title its level with `data-heading="2"` —
+or put prose under `data-prose` and its `h1`–`h4` take the levels — rather than hand-picking
+`text-2xl font-semibold`. There are no `--text-*` scale tokens; override a level with the same
+selector.
+
 ---
 
 ## Shape / radius configuration