@ggts-sh/skill 0.43.1 → 0.43.2

package/SKILL.md

@@ -21,9 +21,15 @@ and Svelte adapters. A chart spec carries the same grammar between surfaces.
 4. In every agent sandbox, install `@ggts-sh/cli` and `@ggts-sh/skill`
    at matching local versions and keep the lockfile. Expose
    the installed skill to the agent, refreshing any copied skill on upgrades.
-   Run `ggts check chart.json`, apply relevant diagnostics, then
-   `ggts render chart.json > chart.svg` and inspect the output. A local npm
-   install exposes these commands through `npm exec -- ggts`.
+   Run `ggts check chart.json`, apply relevant diagnostics, then render at the
+   intended final width and height with
+   `ggts render chart.json --width W --height H > chart.svg` and inspect that
+   SVG. Re-render and visually inspect after every width, layout, or theme
+   change, including responsive reflow: label wrapping, rotation, thinning,
+   temporal ticks, and legend placement are width-dependent. Apply the ≤480px
+   viewport and <320px panel rules at that final size. Headless SVG cannot
+   validate tooltip content; hover and pin in a browser. A local npm install
+   exposes these commands through `npm exec -- ggts`.
 
 ## Registration (call these)
 
@@ -187,7 +193,7 @@ or linked-view code.
   [themes.md](references/themes.md) (every product theme name, shells,
   role overrides),
   [composition-surfaces.md](references/composition-surfaces.md) (coords,
-  facets, guides, merge semantics),
+  facets, multi-chart layout, guides, labs, merge semantics),
   [interactions.md](references/interactions.md) (tooltips, selection, linking),
   [recipes.md](references/recipes.md) (long-tail chart recipes).
   Registration calls live in the [registration reference](references/registration.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggts-sh/skill",
-  "version": "0.43.1",
+  "version": "0.43.2",
   "description": "Agent skill for the shared grammar of graphics: TypeScript, React, Svelte, portable JSON, and the ggts check/render feedback loop. Versions with all framework adapters.",
   "keywords": [
     "agent-skill",

package/references/composition-surfaces.md

@@ -102,6 +102,20 @@ with `facet-form-missing`.
   (left/right strips take layout space rather than overlaying the panel);
   `show` (default true) — set false when direct labels are authored elsewhere.
 
+## Multi-chart layout review
+
+Allocate space by chart density and comparison relationships when composing
+independent charts into a dashboard:
+
+- Give dense time series and long-category charts a full-width or otherwise
+  spacious panel instead of forcing every chart into a 2×2 grid.
+- Choose panel spans from density and which charts readers compare. Repetition
+  of an appropriate encoding across panels is not a defect.
+- Align shared label gutters and keep heights matched within a comparison row;
+  mismatched fixed heights distort visual comparisons.
+- Inspect the whole dashboard and each chart at its final rendered size.
+  Repeat both inspections after resizing or responsive reflow.
+
 ## Guides, legend, labs
 
 Guides are keyed by aesthetic channel: `x`, `y`, `color`, `fill`, `size`,
@@ -113,13 +127,35 @@ channel). `<GuideLegend channel="color" position="bottom"/>` assembles
 `guides: {"color": {"type": "legend", "position": "bottom"}}`.
 
 - Top-level `guides` override a scale-local `guide`.
-- Shared options: `title`, `theme` (bounded size/gap overrides), `collision`;
-  non-position guides add integer `order` (placement rank), `position`
-  `"auto"|"right"|"bottom"`, `direction` `"auto"|"vertical"|"horizontal"`,
-  and `force` (show a guide suppressed by default, e.g. identity scales).
+- Shared options: `title`, `theme`, `collision`; non-position guides add
+  integer `order` (placement rank), `position` `"auto"|"right"|"bottom"`,
+  `direction` `"auto"|"vertical"|"horizontal"`, and `force` (show a guide
+  suppressed by default, e.g. identity scales).
+- Axis `collision`: on a horizontal band `x` axis, `auto` uses measured
+  band-label escalation and `ellipsis` forces single-line labels truncated to
+  fit. `preserve` keeps full single-line labels on either axis even when they
+  overlap or overflow. Setting any explicit collision value drops a scale-local
+  band guide pin; omitting `collision` leaves that pin in place, so the default
+  `auto` behavior does not override it. A `y` axis `ellipsis` value does not
+  select a separate band-collision path.
+- `GuideThemeSpec` bounds one guide's presentation:
+
+  | Option              | Range  | Controls                        |
+  | ------------------- | ------ | ------------------------------- |
+  | `titleSize`         | 8–32   | Guide title font size           |
+  | `labelSize`         | 8–24   | Guide label font size           |
+  | `keyGap`            | 0–32   | Gap between a key and its label |
+  | `rowGap`            | 0–32   | Gap between legend rows         |
+  | `blockGap`          | 0–64   | Gap between guide blocks        |
+  | `colorbarThickness` | 4–48   | Colorbar thickness              |
+  | `colorbarLength`    | 48–512 | Colorbar length                 |
+
 - Responsive rule: `auto`-positioned non-position guides move below the panel
   when the viewport is 480px wide or less, or when a right guide would leave
   under 320px of panel (after an estimated 80px of other chrome).
+- For long legends, shorten series names, remove redundant guide titles, use
+  direct labels where practical, or reduce the series/small-multiple structure.
+  Keep labels readable; change the content or layout before shrinking text.
 - `<Legend order="stable-domain"|"present-first-seen"|"sorted"/>` is the
   plot-wide legend ENTRY-SORT enum (default `stable-domain`; ordering never
   changes color assignments). Distinct from `<GuideLegend order={2}/>`, a
@@ -127,6 +163,12 @@ channel). `<GuideLegend channel="color" position="bottom"/>` assembles
 - `Labs` takes flat string props: `title`, `subtitle`, `caption`, `x`, `y`,
   `color`, `fill`, `size`, `linewidth`, `alpha`, `shape`, `linetype`. The
   spec type is re-exported from `@ggts-sh/svelte` as `LabsSpec`.
+  Give each text field one role: title carries the chart's message or subject;
+  optional subtitle carries measure, scope, period, or units; caption carries
+  only a unique source or caveat. Keep adjacent disclosures, axis titles,
+  subtitle content, and hedging prose out of the caption. Default tooltips and
+  humanized axis/legend titles also read from `labs`, so concise field labels
+  improve both chart chrome and tooltip content.
 
 ```svelte fragment
 <GGPlot

package/references/geoms-and-stats.md

@@ -19,6 +19,13 @@ params from `GEOM_PARAM_KEYS` — do not hand-edit `packages/svelte/src/lib/geom
 />
 ```
 
+`color` and `fill` are aesthetics, not geom `params` keys or direct component
+props. Use the canonical constant form, for example
+`aes: { fill: { value: "#0072B2" } }` in JSON or
+`aes={{ fill: { value: "#0072B2" } }}` on a component. Map a column of raw hex
+values only when the colors vary with the data; a repeated column adds an
+unnecessary identity mapping when a constant aesthetic would suffice.
+
 Omit `stat`/`position` to get the geom's defaults (normalize fills them in). Each layer
 declaration allows only its own stat and position values — anything else is a schema error.
 

package/references/scales-and-palettes.md

@@ -52,6 +52,33 @@ events use semantic values.
 "scales": { "x": { "type": "linear", "transform": "log10", "limits": [1, 1000] } }
 ```
 
+Band axes also accept a scale-local `guide` with `mode`, `angle`, and `wrap`:
+
+```json fragment
+"scales": {
+  "x": {
+    "type": "band",
+    "guide": { "mode": "auto", "angle": -45, "wrap": 2 }
+  }
+}
+```
+
+- `mode`: `auto` (default), `single`, `wrap`, `rotate`, or `off` (hide labels).
+  On a horizontal band axis, auto escalates from single-line labels to wrapping,
+  wrap-then-rotate, full-string rotation, truncation, and label thinning; if
+  labels still cannot fit, layout can warn about overlap or margin overflow.
+  An explicit mode pins that presentation instead of auto-escalating. On a
+  vertical band axis (native `y`, or categorical `x` after `coord_flip`), only
+  `off` changes label visibility; the other modes use the legacy vertical path.
+- `angle`: rotation in degrees, normalized to −90…0 (positive values mirror to
+  negative). It sets the angle for horizontal `rotate`; in `auto`, the
+  wrap-then-rotate stage can still choose −45°, so use `mode: "rotate"` when
+  the angle must be enforced.
+- `wrap`: maximum wrapped lines on a horizontal band axis, from 1–8 (default 2).
+
+The top-level axis guide's `collision` policy can override this layout; see
+[Guides, legend, labs](composition-surfaces.md#guides-legend-labs).
+
 ### Color and fill scales
 
 Five types, each gating its own option set (`ColorScaleSpec`; forbidden