pmx-canvas 0.1.26 → 0.1.28

package/skills/tufte-viz/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: tufte-viz
+description: |
+  Ideate and critique data visualizations using Edward Tufte's principles, and map them onto
+  the PMX Canvas json-render chart catalog (graph / json-render nodes). Use this skill when:
+  (1) Designing or critiquing a canvas graph/json-render chart
+  (2) Choosing a chart type, color encoding (colorBy), or primitive (Sparkline, DotPlot, BulletChart, Slopegraph)
+  (3) Reviewing a board's dashboards/charts for graphical integrity and data-ink
+  (4) Deciding between a single-series bar, small multiples, or direct labeling
+  (5) Reducing chartjunk or improving data-ink ratio on canvas charts
+  Applies: data-ink ratio, chartjunk elimination, graphical integrity, lie factor, small multiples,
+  data density — and the canvas colorBy decision (color must encode data, not decorate).
+---
+
+# Tufte Visualization Ideation (PMX Canvas)
+
+Apply Edward Tufte's principles to design clear, honest, high-density data visualizations, then
+realize them with PMX Canvas `graph` / `json-render` nodes. Color must encode data, not decorate.
+
+## Workflow
+
+### For new visualizations:
+
+1. **Clarify the data story**
+   - What comparisons matter?
+   - What's the key insight to communicate?
+   - Who's the audience?
+
+2. **Select approach** using Tufte principles:
+   - High comparison need → Small multiples (several small `graph` nodes, shared scale)
+   - Dense data → Consider data tables (`json-render` Table), sparklines (`Sparkline`)
+   - Time-series → Line charts with minimal grid
+   - Part-to-whole → Avoid pie charts; prefer bar/table
+   - Ranked single metric across categories → DotPlot over a bar forest
+
+3. **Design with data-ink in mind**
+   - Start minimal, add only what's necessary
+   - Every element must earn its ink
+   - Default to a single accent; use the full palette only when color *encodes* a variable
+
+4. **Apply the eraser test before shipping**
+   - For every element (label, tick, gridline, border, annotation): can it be erased without losing
+     information that's not already conveyed elsewhere?
+   - Watch for duplicate encodings: numeric labels next to a value already marked by a tick; legends
+     duplicating direct labels; per-panel scale annotations duplicating a shared-scale caption.
+   - If two elements compete for the same job, keep the visual one and drop the textual one (or vice
+     versa) - not both.
+
+5. **Apply the collision test before shipping**
+   - For every text element in the plot (axis labels, point annotations, epoch labels, baseline
+     labels, explanatory notes): mentally draw its bounding box. Does anything else - another text
+     element, a data line, dense markers - live in or cross that box?
+   - The eraser test catches *redundant* elements; the collision test catches *crowded* ones. Both
+     must pass.
+   - Standard fixes: move explanatory prose out of the plot into a nearby markdown node; relocate
+     band/epoch labels to a dedicated strip above the plot; push baseline/reference labels to the
+     outside margin; give each in-plot annotation a leader line so the marker and the text occupy
+     clearly separated space.
+   - Watch especially: inverted axes; shared-scale small multiples (labels stacked near zero in every
+     panel); dense scatter (text vanishes into the dot cloud unless explicitly cleared).
+
+6. **Apply the Tufte test** (see references/tufte-principles.md)
+
+### For critiquing visualizations:
+
+1. **Check graphical integrity**
+   - Calculate lie factor if proportions seem off
+   - Verify baselines and scales (bar and area charts must start at zero)
+   - Look for 3D distortion
+
+2. **Identify chartjunk**
+   - Decorative elements
+   - Heavy grids
+   - Unnecessary 3D effects
+   - Moiré patterns
+   - Gratuitous per-category color on a single-series chart (decoration, not encoding)
+
+3. **Evaluate data-ink ratio**
+   - What can be erased?
+   - What's redundant?
+
+4. **Suggest improvements** with specific before/after recommendations
+
+## Mapping to the PMX Canvas chart catalog
+
+Realize these designs with `canvas_add_graph_node` (graph nodes) and `canvas_add_json_render_node`.
+The chart catalog: `LineChart`, `BarChart`, `PieChart`, `AreaChart`, `ScatterChart`, `RadarChart`,
+`StackedBarChart`, `ComposedChart`, plus the Tufte primitives `Sparkline`, `DotPlot`, `BulletChart`,
+and `Slopegraph`.
+
+### Color must encode data — the `colorBy` decision (single-series bar/column)
+
+A single-series `BarChart` measures **one** variable across categories. Coloring each bar differently
+encodes nothing — it is decoration (chartjunk). Use the `colorBy` prop:
+
+| `colorBy`   | When to use                                                                 |
+|-------------|-----------------------------------------------------------------------------|
+| `series` (default) | One accent for all bars, one bar highlighted (Tufte-safe emphasis). Use to draw the eye to the bar that *matters* (max, target, the row under discussion). |
+| `category`  | Opt in only when the category itself is a nominal variable the reader must map by color (e.g. team identity reused across several charts with a shared key). |
+| `value`     | Sequential shade by magnitude. Note this **double-encodes** — the bar's length already encodes the value — so reserve it for when the lightness ramp genuinely aids reading a ranked magnitude; otherwise `series`/`none` are more honest. |
+| `none`      | Flat single accent, no highlight. Maximal data-ink for dense small multiples. |
+
+Default to `series`. Do **not** reach for `category` to "make it colorful." Pie/radar/stacked-bar
+already rotate the palette because each slice/series **is** a distinct variable — leave those as-is.
+
+### Tufte primitives (prefer over heavier charts)
+
+- **`Sparkline`** — word-sized time-series, no axes/labels. Use inline in tables/dashboards and one
+  per row to show a trajectory at a glance. Replaces "trending up / volatile" prose with the shape.
+- **`DotPlot`** — ranked single metric across categories. Replaces a forest of bars: a dot per
+  category on a shared axis. Far higher data-ink ratio than bars; sorts make the macro pattern pop.
+- **`BulletChart`** — a measure against a target with qualitative bands. Replaces a gauge/dial
+  (which is chartjunk). Use for KPI-vs-target, progress-vs-goal.
+- **`Slopegraph`** — two-time-point comparison across many categories (before/after). Direct slope
+  encodes change and rank simultaneously; labels sit at the endpoints (direct labeling, no legend).
+  Lines default to a single neutral ink; set `colorByDirection` to accent rising lines and mute
+  falling ones only when the direction is the point (and beware it editorializes — a falling
+  error-rate is "good", a falling revenue is "bad").
+
+### Direct labeling over legends
+
+Legends force the eye to ping-pong between key and plot (a duplicate encoding). Prefer labeling the
+data directly: end-of-line labels on `LineChart`/`Slopegraph`, endpoint labels on `DotPlot`, the
+highlighted bar's value on `BarChart`. Set `showLegend: false` on graph nodes when one or two series
+are directly identifiable; reserve legends for genuinely many overlapping series.
+
+### Small multiples over many overlapping series
+
+When more than ~4 series would overlap in one chart, do **not** cram them into a single multi-color
+`LineChart`. Create several small `graph` nodes with an **identical shared scale** and consistent
+encoding, arranged in a grid (`canvas_arrange` grid, or a `group`). Position means the same thing in
+every panel; the sequence tells the macro story while each panel carries the micro detail. This is
+almost always better than color-coding 6+ lines.
+
+## Key Principles Reference
+
+- `references/tufte-principles.md` - core principles from *Visual Display of Quantitative Information*:
+  lie factor, data-ink, chartjunk, small multiples, integrity.
+- `references/analytical-design.md` - extensions from *Envisioning Information*, *Visual Explanations*,
+  and *Beautiful Evidence*: the 6 principles of analytical design, sparklines, layering & separation,
+  micro/macro, range-frames, causality, confections. Load when designing dashboards, dense displays,
+  sparklines, or explanatory graphics.
+
+**Quick checklist:**
+- [ ] Lie Factor ≈ 1.0 (no visual distortion; bars and areas start at zero)
+- [ ] Maximum data-ink ratio
+- [ ] Zero chartjunk (no per-category color unless color encodes a variable)
+- [ ] `colorBy` chosen deliberately — default `series` (single accent + one highlight); avoid `value` unless the magnitude ramp earns the double-encode
+- [ ] Clear labeling, direct over legend
+- [ ] Answers "compared to what?"
+- [ ] Shows causality or mechanism where relevant
+- [ ] Multivariate (not over-reduced)
+- [ ] Words, numbers, images integrated - not segregated
+- [ ] Reveals multiple levels of detail (micro + macro)
+- [ ] Layering: primary data dominates, secondary recedes
+- [ ] Appropriate data density — Sparkline/DotPlot considered before a heavier chart
+- [ ] >4 overlapping series → small multiples, not one rainbow chart

package/skills/tufte-viz/references/analytical-design.md

@@ -0,0 +1,217 @@
+# Analytical Design Principles
+
+Extended principles from *Envisioning Information*, *Visual Explanations*, and *Beautiful Evidence*.
+
+## Table of Contents
+
+1. [Six Principles of Analytical Design](#six-principles-of-analytical-design)
+2. [Sparklines](#sparklines)
+3. [Layering and Separation](#layering-and-separation)
+4. [Micro/Macro Readings](#micromacro-readings)
+5. [Range-Frames and Related Techniques](#range-frames-and-related-techniques)
+6. [Showing Causality](#showing-causality)
+7. [Confections](#confections)
+
+---
+
+## Six Principles of Analytical Design
+
+These govern the design of any serious analytical presentation - charts, maps, diagrams, or evidence displays.
+
+### 1. Show Comparisons, Contrasts, Differences
+
+- The fundamental analytical question is always "compared to what?"
+- Every display should make at least one comparison explicit
+- Side-by-side placement is stronger than sequential placement
+- Differences should be shown directly rather than requiring mental arithmetic
+
+### 2. Show Causality, Mechanism, Explanation, Systematic Structure
+
+- Go beyond "what happened" to "why it happened"
+- Show the causal mechanism, not just the correlation
+- Use arrows, annotations, or sequencing to indicate direction of effect
+- Integrate explanatory text with the data display
+
+### 3. Show Multivariate Data (More Than 1 or 2 Variables)
+
+- The real world is multivariate; flatten it at your peril
+- Use small multiples, color channels, size, position, and faceting to encode multiple dimensions simultaneously
+- Avoid over-reducing: a single average line hides the story in the distribution
+
+### 4. Completely Integrate Words, Numbers, and Images
+
+- The best analytical displays weave text, data, and graphics into a single coherent view
+- Don't segregate "the chart" from "the explanation" - put them together
+- Labels, annotations, and data should coexist in the same visual space
+- Source notes and methodology belong with the graphic, not in a footnote pages away
+
+### 5. Thoroughly Describe the Evidence
+
+- Provide a title that names the data, the measurement, and the context
+- Label axes with units, time range, and source
+- Document what data is excluded or transformed
+- Quality, relevance, and integrity of evidence should be self-evident
+
+### 6. Content Counts Most of All
+
+- Analytical presentations stand or fall on the quality and relevance of the content
+- No amount of design skill can rescue poor or irrelevant data
+- Choose the question carefully; then design the graphic to answer it with maximum clarity
+
+---
+
+## Sparklines
+
+Intense, simple, word-sized graphics that can be embedded in text, tables, or dashboards.
+
+### Characteristics
+
+- Typically the height of a text line (~20-30px at screen resolution)
+- No axes, no labels, no grids
+- Data pattern speaks entirely through shape
+- Usually time-series: left is past, right is present
+- Can show reference bands (normal range), endpoints, min/max dots
+
+### Design Guidelines
+
+- Keep aspect ratio approximately banking to 45 degrees (the average slope of the data should be ~45 degrees for optimal perception)
+- Use a small red/colored dot for the most recent value or the min/max
+- Embed in context: "Revenue grew steadily [sparkline] before the Q3 dip"
+- For tables: one sparkline per row provides pattern recognition across many entities at a glance
+
+### When to Use
+
+- Dashboards where space is precious
+- Inline with narrative text to show trends without interrupting reading flow
+- Tables of KPIs where each row benefits from a visual trajectory
+- Anywhere you'd otherwise write "trending up" or "volatile" - show it instead
+
+---
+
+## Layering and Separation
+
+Techniques for organizing complex displays so that different types of information are visually stratified.
+
+### The Problem
+
+When many data elements, labels, grids, and annotations share a single plane, the result is visual confusion - everything competes for attention equally.
+
+### Solutions
+
+1. **Color layering** - Primary data in high-contrast (black/dark); secondary reference data in low-contrast (light gray); structural elements (axes) in between
+2. **Weight layering** - Data lines thicker than grid lines; grid lines thinner than axis lines
+3. **Transparency/opacity** - Background elements at 20-40% opacity; foreground data at 100%
+4. **Spatial separation** - Use whitespace to group related elements and separate unrelated ones
+5. **The 1+1=3 effect** - Two adjacent dark elements create a perceived third element (the white gap between them). Be aware of this and control it
+
+### Practical Rules
+
+- Grid: lightest layer (if present at all)
+- Axes and frame: medium layer
+- Data: heaviest layer (darkest ink, thickest stroke)
+- Annotations: medium-dark, but positioned to avoid collision with data
+- Background: minimal or none (white/very light)
+
+---
+
+## Micro/Macro Readings
+
+Displays that simultaneously serve two levels of reading: the overall pattern (macro) and the individual data point (micro).
+
+### The Idea
+
+A well-designed high-resolution display rewards both:
+- A quick glance (macro): What's the overall shape, trend, or story?
+- Close inspection (micro): What are the individual values? Which points are outliers?
+
+### How to Achieve
+
+1. **High data density** - Show all the data, not just aggregates
+2. **Clear ordering** - Sort/arrange so the macro pattern emerges from the micro data
+3. **Progressive revelation** - Overall pattern visible at arm's length; detail visible up close
+4. **Direct labeling** - Selected important data points labeled directly, others readable by position
+
+### Examples in Practice
+
+- A map where individual data points form a visible geographic pattern
+- A scatter plot where the cloud shape tells the correlation story, but individual labeled outliers are identifiable
+- Small multiples where each panel is a micro view but the sequence tells a macro story
+
+---
+
+## Range-Frames and Related Techniques
+
+Alternatives to the conventional box axes that use less ink while conveying more information.
+
+### Range-Frame
+
+Instead of drawing axes from arbitrary round numbers to round numbers, the axis line spans only the range of the data (from min to max). This encodes additional information (the data range) into an element that was previously just structural.
+
+### Dot-Dash Plot
+
+Instead of tick marks at round intervals, place a tick mark at each actual data value along the axis. The distribution of ticks immediately shows data density and gaps.
+
+### Quarter-Frame
+
+Only two sides of the frame are drawn (typically left and bottom), and only as far as the data extends.
+
+### When to Use
+
+- Range-frames: almost always preferable to standard full-frame axes
+- Dot-dash: when showing distribution along an axis matters (scatter plots, strip plots)
+- Quarter-frame: when data doesn't approach all four edges of the plot area
+
+---
+
+## Showing Causality
+
+Techniques for moving beyond correlation to communicate mechanism and cause-effect relationships.
+
+### Principles
+
+1. **Temporal sequence** - Cause precedes effect; arrange displays chronologically when causality is temporal
+2. **Mechanism diagrams** - Show the pathway from cause to effect, not just the endpoints
+3. **Counterfactual comparison** - Show what happened alongside what would have happened without the intervention
+4. **Confound acknowledgment** - Note or visualize potential confounders rather than ignoring them
+
+### Visual Techniques
+
+- Before/after with a clear intervention marker
+- Parallel time-series: treatment vs. control
+- Flow diagrams showing causal chains
+- Annotations on inflection points explaining what changed
+
+### Honesty Requirements
+
+- Don't imply causation when you only have correlation
+- Show uncertainty bands where appropriate
+- If the causal mechanism is debated, note it
+- Show the data that argues against your interpretation alongside the data that supports it
+
+---
+
+## Confections
+
+Assemblages of many visual elements that together provide a richly informative, often explanatory, display.
+
+### What They Are
+
+Confections combine multiple modes of information:
+- Diagrams + data + annotations + comparisons in a single integrated display
+- Often narrative: they tell a story with a beginning, middle, and end
+- May mix scales, perspectives, or time periods in a single view
+
+### When to Use
+
+- Explaining complex systems or processes
+- Teaching: where understanding mechanism matters more than precision
+- Summarizing research findings with their context
+- Executive briefings that need to convey both "what" and "why"
+
+### Design Principles
+
+1. **Unity** - Despite multiple elements, the display should read as one coherent piece
+2. **Hierarchy** - The most important information is most prominent
+3. **Flow** - The reader's eye should move through the display in a logical sequence
+4. **Density** - Every region of the display should carry information; no dead zones
+5. **Integration** - Words and images work together; neither is redundant to the other

package/skills/tufte-viz/references/tufte-principles.md

@@ -0,0 +1,147 @@
+# Core Tufte Principles
+
+Reference for the fundamental principles from *The Visual Display of Quantitative Information*.
+
+## Table of Contents
+
+1. [Graphical Integrity](#graphical-integrity)
+2. [Data-Ink Ratio](#data-ink-ratio)
+3. [Chartjunk](#chartjunk)
+4. [Small Multiples](#small-multiples)
+5. [Data Density](#data-density)
+6. [The Tufte Test](#the-tufte-test)
+
+---
+
+## Graphical Integrity
+
+The representation of numbers on a graphic should be directly proportional to the numerical quantities represented.
+
+### Lie Factor
+
+```
+Lie Factor = (size of effect shown in graphic) / (size of effect in data)
+```
+
+- A lie factor of 1.0 means perfect honesty
+- Lie factors > 1.05 or < 0.95 distort perception
+- Common sources of distortion:
+  - Truncated baselines (bar charts not starting at zero)
+  - Area/volume encoding where length would suffice
+  - 3D perspective making nearer elements appear larger
+  - Non-linear axis scaling without clear labeling
+
+### Principles of Graphical Integrity
+
+1. Show data variation, not design variation
+2. Use clear, detailed, thorough labeling to defeat distortion
+3. In time-series displays, standardize monetary units (deflate for inflation)
+4. The number of information-carrying dimensions should not exceed the number of dimensions in the data
+5. Context: show the data in context - "compared to what?"
+
+---
+
+## Data-Ink Ratio
+
+The share of a graphic's ink devoted to non-redundant display of data-information.
+
+```
+Data-Ink Ratio = (data-ink) / (total ink used in graphic)
+```
+
+### Maximizing Data-Ink
+
+Within reason, the goal is to maximize the data-ink ratio:
+
+1. **Erase non-data-ink** - Remove elements that don't convey data (decorative borders, background fills, heavy axis boxes)
+2. **Erase redundant data-ink** - If the same information is encoded twice (e.g., both a label and a position), remove one
+3. **Revise and edit** - Iterate toward the simplest possible representation that retains all data meaning
+
+### Practical Applications
+
+- Replace heavy gridlines with light ones, or remove entirely if direct labels suffice
+- Use range-frame axes (axes that span only the data range, not arbitrary round numbers)
+- Remove chart borders/boxes
+- Use white gridlines on a light gray background (Tufte's "sparkline" aesthetic)
+- Let data points serve as their own tick marks where possible
+
+---
+
+## Chartjunk
+
+Non-data elements or redundant data elements that clutter a visualization without adding information.
+
+### Three Varieties
+
+1. **Unintentional optical art** - Moiré patterns from hatching, vibrating fills, and tight parallel lines that create visual interference
+2. **The grid** - Heavy, prominent grids that compete with or dominate the data
+3. **The duck** - Elaborate decorative structures built around the data (3D effects, pictorial embellishments, ornamental frames)
+
+### How to Eliminate
+
+- Default to no background fill, no border, no grid
+- Add gridlines only if the reader needs to extract precise values - and make them light/receding
+- Never use 3D unless the data is inherently three-dimensional
+- Remove legends when direct labeling is feasible
+- Remove decorative icons, clip art, or illustrations layered onto the data area
+
+---
+
+## Small Multiples
+
+A series of similar graphs or charts using the same scale and axes, allowing easy comparison across a varying condition.
+
+### When to Use
+
+- Comparing the same measure across many categories (regions, time periods, groups)
+- Showing change over time for multiple entities
+- Exploring multivariate data by faceting on one dimension
+- Whenever you're tempted to use color-coding to distinguish many overlapping series
+
+### Design Principles
+
+1. **Shared scales** - All panels must use identical axis ranges so position means the same thing everywhere
+2. **Consistent structure** - Same layout, same visual encoding in each panel
+3. **Minimal per-panel decoration** - Axis labels, ticks, and titles appear once (shared) rather than repeated in each panel
+4. **Clear ordering** - Arrange panels in a meaningful order (alphabetical, by outcome magnitude, by geography)
+5. **Reference elements** - Include a common reference (e.g., overall average) as a light/gray line in each panel for context
+
+### Density
+
+Small multiples can be packed tightly. Each panel should be large enough to reveal the data pattern but small enough that the eye can compare across many panels in a single view.
+
+---
+
+## Data Density
+
+The amount of data shown per unit area in a graphic.
+
+```
+Data Density = (number of entries in data matrix) / (area of data graphic)
+```
+
+### High-Density Displays
+
+- Most published graphics have far lower data density than they could achieve
+- Sparklines: intense, simple, word-sized graphics embedded in text or tables
+- Data tables with integrated graphical elements can achieve very high density
+- The human eye can resolve very fine differences - don't underestimate the reader
+
+### Shrink Principle
+
+Graphics can be shrunk far more than we usually think. A well-designed graphic retains meaning at small sizes because the data pattern (not the labels or decoration) carries the story.
+
+---
+
+## The Tufte Test
+
+A synthesis checklist for evaluating any completed visualization:
+
+1. **Is the lie factor close to 1.0?** - No distortions in area, length, or position
+2. **Is the data-ink ratio high?** - Could anything be erased without information loss?
+3. **Is there zero chartjunk?** - No decoration, no moiré, no unnecessary 3D
+4. **Does it answer "compared to what?"** - Context, baseline, or reference is present
+5. **Is labeling clear and integrated?** - Labels sit close to the data they describe, not in a distant legend
+6. **Is the data density appropriate?** - For the story being told, is enough data shown? Could a table or sparkline show more?
+7. **Would small multiples work better?** - If more than ~4 series overlap, consider faceting
+8. **Does every element earn its ink?** - One final pass: point to each mark and ask what it communicates