agemon 0.1.0 → 6.3.0

package/assets/skills/design/agemon-design/references/craft-intent.md

@@ -0,0 +1,162 @@
+# Craft Intent — Read, Variance, Signature
+
+Load on every `/agemon-design build`, default Build mode, and when the user asks for a full surface without naming a command. This file is the **generative front door** — declare intent before writing code.
+
+---
+
+## 1. Craft Read (mandatory before code)
+
+Before tokens or layout, output **one line** the user can react to:
+
+> **Craft Read:** *[surface kind] for [audience], [product | marketing] language, [theme/accent hint], variance [N], signature bet: [choice].*
+
+**Infer from:** page/app kind, vibe words ("minimal", "editorial", "dense", "playful"), references the user named, existing brand tokens, audience.
+
+**Examples:**
+
+- *Craft Read: invoice-matching dashboard for finance admins, product language, the client's navy and a pale ledger-paper ground, variance 4, signature bet: the oldest unmatched invoice pinned first in the queue, with its age shown as a ruled tally.*
+- *Craft Read: build-tool launch page for platform engineers, marketing language, the logo's orange on a light ground, variance 7, signature bet: a recorded first build replayed in the hero, cropped at the fold.*
+- *Craft Read: ceramicist's portfolio for gallery buyers, marketing language, unglazed-clay neutrals with one glaze-blue accent, variance 8, signature bet: a strip of glaze swatches that doubles as the project index.*
+
+Each bet comes from something in the subject (a ledger, a build, a glaze), not from a layout pattern. Worked examples get imitated: derive yours from the brief's subject instead of copying one of these.
+
+If the brief is ambiguous, ask **one** clarifying question — never a questionnaire. If inferable, declare the Craft Read and proceed.
+
+**Anti-default discipline:** Generated design without a committed read clusters into three defaults — (1) warm cream background (~`#F4F1EA`) + serif display + terracotta/brass accent; (2) near-black background + one bright acid-green or vermilion accent; (3) broadsheet layout — hairline rules, zero border-radius, dense columns. Each is legitimate only *when the brief asks for it*, never as a default answer to "no brand direction" — same goes for purple mesh gradients, symmetric three-icon-card heroes, full-black sidebars, and Inter-on-everything without a reason. The fuller, dated list is [tells-2026-11.md](tells-2026-11.md).
+
+**Second-order check (marketing surfaces):** name the aesthetic lane before building ("editorial type", "terminal-dark devtool", "warm-craft artisan"), then ask if someone could guess it from the domain alone — "devtool → dark mode + mono" is the first reflex, "AI tool that's not-purple → editorial serif restraint" is the same reflex one tier deeper. If the lane, or any default above, is guessable from the category, rework it until it isn't — the brand's specifics should pick the lane, not the category. Self-test: "would a similar brief for a *different* brand in this category produce this same plan?" If yes for any axis, that's a reflex, not a decision — revise it and state what changed.
+
+---
+
+## 2. DESIGN_VARIANCE knob (1–10)
+
+Separate from **VISUAL_DENSITY** (how much fits) and **CRAFT_LEVEL** (how refined). Variance controls **layout risk and creative amplitude**.
+
+| Variance | Product surfaces | Marketing surfaces |
+|----------|------------------|-------------------|
+| **1–3** | Symmetric grids, safe hierarchy | Centered hero OK only with asymmetric support |
+| **4–6** | Split layouts, metric hierarchy, one layout break | Split/bento heroes, alternating feature rows |
+| **7–8** | Strong typographic moments in shell (empty state, onboarding) | Asymmetric offsets, scroll-linked logo strip, display scale drama |
+| **9–10** | Rare — one experimental shell moment only | Kinetic type, scroll choreography — **explicit brief or user asks "experimental"** |
+
+**Defaults when user doesn't specify:**
+
+| Surface | Default variance |
+|---------|------------------|
+| Dashboard, settings, auth, tables | **4** |
+| Landing (live product) | **7** |
+| Landing (waitlist / pre-launch) | **6** |
+| Portfolio, case-study, launch event | **8** |
+
+"Bolder" raises variance (+1–2, cap 10) and motion (+1, cap 10). "Quieter" lowers both. Honor `prefers-reduced-motion` always.
+
+---
+
+## 3. Signature bet (mandatory — not polish-gated)
+
+Every `/agemon-design build` ships **exactly one** memorable decision, chosen at plan time and built in Step 3 — not deferred to `/agemon-design polish`.
+
+### Product surfaces (pick one)
+
+1. Custom empty-state motif (simple SVG tied to domain)
+2. Distinctive nav active indicator (left bar, pill, or dot) — system-wide
+3. Welcome / first-run panel — dismissible, value-focused
+4. Primary table row hover (subtle lift + shadow on the main table only)
+5. Command palette or keyboard hint (`⌘K`) when search/actions warrant it
+
+### Auth surfaces (pick one — load [recipe-auth.md](recipe-auth.md))
+
+1. Panel proof asset — one believable proof figure **or** one attributed quote (not both)
+2. Trust footer line — compliance / data residency in tertiary text at panel foot
+3. Domain-specific welcome line — verb tied to product ("Pick up where you left off"), not generic filler
+4. Real provider marks on SSO row — equal-weight neutral outlines, no fake icons
+5. Subtle panel motif — simple SVG tied to domain on the tinted panel only
+
+### Marketing surfaces (pick one)
+
+1. Hero crop — product visual cut mid-element at fold edge
+2. A detail taken from the subject — a real artifact, material or sample of the product's work, shown at true scale
+3. Section markers drawn from the domain's own vocabulary (only if the content is actually a sequence or a set)
+4. Distinctive CTA copy — specific verb, not "Get started"
+5. One scroll moment — logo strip or restrained headline entrance (variance ≥7)
+
+Name the bet in the Craft Read. Build it in the first pass.
+
+---
+
+## 4. Product surface patterns (apps, dashboards, settings)
+
+Apply on dashboard, auth, settings, onboarding, admin — load with [recipe-dashboard.md](recipe-dashboard.md).
+
+**Shell:** Tinted sidebar (not full black). Active nav = accent/10 + accent text. Page header row: title + context + primary action aligned.
+
+**Data:** One hero metric (larger, accent tint); secondaries neutral. Sparklines only in dashboard cards that answer a real trend question; leave them off cards where the current value is the point. Table rows with context (avatar, status dot, proportion bar) — not plain grids. Ghost buttons in filter toolbars; primary CTA lives outside the toolbar.
+
+**Type & color:** `tabular-nums` on numbers. Sentence case on nav and headers. Tinted surfaces (`accent/5` on primary card). Semantic green/red only when the domain expects it.
+
+**Motion:** Optimistic UI where saves matter. Skeletons match final layout. `:active` micro-push (`scale(0.98)`). One staggered entrance per section max, `once: true`.
+
+**States:** Empty states with icon + one sentence + CTA. Errors with retry/copy path. Onboarding checklists 3–5 steps, dismissible.
+
+**Avoid in product shells:** scroll pinning, kinetic body copy, mesh backgrounds behind tables, glass on dense forms, decorative carousels.
+
+**Ecosystem briefs use the official system.** When the brief names a platform with a mandated or expected design system, install and use the official package and its tokens instead of hand-rolling a lookalike — recreating a known system's CSS by hand is both more work and instantly off. One system per project; don't mix component libraries in the same tree.
+
+Naming the platform is not enough to act on. Install what the row says:
+
+| Brief reads as… | Install | Ships as |
+|---|---|---|
+| Microsoft 365 / Fluent-flavoured | `@fluentui/react-components` | React |
+| Atlassian-suite companion | `@atlaskit/button`, `@atlaskit/textfield`, … | React, one package per component |
+| Shopify app or admin surface | `@shopify/polaris` | React |
+| Material-flavoured product | `@material/web` | Web components — any framework |
+| IBM-style B2B / enterprise analytics | `@carbon/react` | React (`@carbon/styles` for the CSS alone) |
+| Salesforce / Lightning | `@salesforce-ux/design-system` | CSS — any framework |
+| Adobe-flavoured | `@adobe/react-spectrum` | React |
+| GitHub-flavoured developer tooling | `@primer/react` | React (`@primer/primitives` for tokens alone) |
+| UK public sector | `govuk-frontend` | Plain CSS + JS |
+| US federal / state service | `@uswds/uswds` | Plain CSS + JS |
+
+Check the third column against the project before adding a dependency. Most of these ship as React and installing one into a Vue, Svelte or Angular codebase is worse than hand-rolling: take the system's tokens and CSS instead, which is the part that makes it recognisable. Atlassian has no meta-package — install the components the surface actually uses.
+
+No row matches → this rule does not apply. Proceed with the normal token flow rather than reaching for the nearest big component library.
+
+---
+
+## 5. Marketing surface patterns (landings, portfolios)
+
+Apply on landing, portfolio, waitlist — load with [recipe-landing.md](recipe-landing.md) and [inspiration.md](inspiration.md) hero archetypes.
+
+**Composition:** Pick one hero archetype (product-forward, message-forward, proof-forward, bento, editorial figure, social proof strip). **No two adjacent sections share the same layout.**
+
+**Type:** Display 48–80px H1, tight tracking, sentence case. Font pairing from theme preset or brief — body + optional display. Keep type to one or two families; if you emphasize a headline word at all, make it because the content calls for it, not as a habit ([tells-2026-11.md](tells-2026-11.md)).
+
+**Color:** Pick a commitment strategy first ([color.md](color.md) Commitment Axis — restrained / committed / full palette / drenched, gated by variance); restrained (mostly neutral, one accent) is one option, not the default; rotate accent family when no brand (indigo, teal, rose, amber, forest). No default warm-beige + brass "premium" palette unless the brief names it.
+
+**Imagery:** marketing surfaces are visual products, not text-only pages — asset priority order, the div-built-screenshot ban, and the logo-wall rule live in [recipe-landing.md](recipe-landing.md) (Imagery is not optional).
+
+**Motion:** Hero stagger 50–80ms; one scroll reveal per section; multi-property hover on **one** featured block. No bounce, confetti, or idle float. Every animation must answer "what does this communicate?" in one sentence (hierarchy, sequence, feedback, state change) — "it looked cool" fails.
+
+**Portfolio:** Variable grid aspects; one hero project above fold; asymmetric about/contact — not centered template.
+
+---
+
+## 6. Rotation (when no brand direction)
+
+Rotate **one axis per build** so outputs don't converge:
+
+| Axis | Pool (pick 1) |
+|------|----------------|
+| Theme direction | Derive from the brief; a preset (Graphite, Porcelain, Signal, Carbon — [themes.md](themes.md)) only when the user asks or no direction exists |
+| Accent family | indigo, teal, rose, amber, forest (OKLCH-safe) |
+| Signature bet | from §3 lists |
+
+Declare the axis in the Craft Read so the user can say "warmer accent" on iteration.
+
+**Premium/artisan briefs must rotate palette families** — the default warm-beige + brass + espresso "premium" look is a convergence tell the moment the brief doesn't name those colors. Full family list and the never-twice-in-a-row rule: [themes.md](themes.md) Premium palette families.
+
+---
+
+## Cross-refs
+
+[recipe-dashboard.md](recipe-dashboard.md) · [recipe-landing.md](recipe-landing.md) · [recipe-auth.md](recipe-auth.md) · [inspiration.md](inspiration.md) · [themes.md](themes.md) · [dashboard.md](dashboard.md) · [review.md](review.md)

package/assets/skills/design/agemon-design/references/dashboard.md

@@ -0,0 +1,131 @@
+# Dashboard Patterns
+
+Detailed guidance for building data-heavy dashboards that feel designed, not generated.
+
+## Layout Structure
+
+A dashboard needs a sidebar + main content area. The sidebar is the navigation spine.
+
+**Sidebar navigation:**
+- Subtle background tint (e.g., `background: #f8fafc` / Tailwind: `bg-slate-50`, or `background: #030712` / Tailwind: `bg-gray-950`) — NOT full black unless Dark Premium style. A dark sidebar is a common AI pattern; prefer a subtle tint that complements the content area.
+- Muted nav text that brightens on hover/active. Active item gets accent background at low opacity (`background: oklch(var(--accent) / 0.1)` / Tailwind: `bg-accent/10`) + accent text.
+- Brand/logo at top, user profile at bottom.
+- `aria-label="Main navigation"` on `<nav>`, `aria-current="page"` on active item.
+- `overscroll-behavior: contain` on the sidebar if it scrolls independently.
+
+**Main content area:**
+- Filter/toolbar row at the top: ghost buttons for filters, active state uses accent bg at low opacity. Always include a date range selector for any time-series surface. **Why:** time-series data without an interactive range silently encodes the assumption that the default window is correct — when it isn't (and it usually isn't for power users), the dashboard becomes a screenshot. **When it breaks:** real-time monitoring surfaces with a fixed last-N-minutes window — the range is the affordance, not the picker.
+- Content grid below filters: metric cards → charts → tables/lists.
+- Minimum 3 different content types visible per viewport (e.g., metric cards + chart + table).
+
+## Metric Card Hierarchy
+
+Never show 4+ identical metric cards. Differentiate the primary metric. **Why:** a uniform grid of equal-weight cards triggers the AI-template tell — variety signals editorial decision; uniformity signals defaulted-out. It also fails the squint test: the eye can't lock on a primary at first glance. **How to differentiate:** primary card gets accent tint, slightly larger number, optional sparkline; secondaries are neutral with smaller type. See Signal-to-Noise Hierarchy section below.
+
+**Primary metric card:**
+- Accent-tinted background (`background: oklch(var(--accent) / 0.05)` / Tailwind: `bg-accent/5`) with accent-colored number, OR solid accent background with white text.
+- Slightly larger number (36px vs 28px for others).
+
+**Secondary metric cards:**
+- White background, subtle border (`1px solid oklch(92% 0.005 250)`).
+- Black number, secondary-color label.
+
+**All metric cards should include:**
+- Sparklines: 32px tall, polyline SVG, accent color with faded fill underneath.
+- Change text: "+2,149 from last month" in `var(--text-tertiary)`. **Never green arrows for positive, red for negative.** **Why:** color implies judgment that may not match user context — a 30% increase in costs is "positive" by sign and "bad" by goal; the green arrow encodes the wrong story. Render the magnitude in neutral and let the user's interpretation supply meaning. **When it breaks:** financial trading surfaces where positive/negative is universally tied to goal (gains green, losses red is the domain convention) — match the user's domain, don't fight it.
+- Label: sentence case, 12-13px, `font-weight: 500`, secondary color.
+- Value: 28-36px, `font-weight: 700`, `font-variant-numeric: tabular-nums`, `letter-spacing: -0.02em`.
+- NO colored top/left borders. NO colored change text. NO arrow icons next to percentages.
+
+## Chart Type Decision Matrix
+
+| Data story | Best chart | Why | Avoid |
+|-----------|-----------|-----|-------|
+| Trend over time | Area chart with gradient fill | Shows direction + volume | Vertical bar chart |
+| Comparing categories | Horizontal bar chart | Labels are readable, easy to scan | Vertical bar with rotated labels |
+| Comparing discrete values | Vertical bar chart | Natural for small sets (3-7 items) | Too many bars (>8) |
+| Part-of-whole | Donut/ring chart (use sparingly) | Center text shows total | Pie chart — harder to compare |
+| Inline trend in a card | Sparkline (32px polyline) | Minimal, contextual | Full chart crammed into a card |
+| Conversion/funnel | Progressive bars with stage labels | Shows drop-off clearly | Donut chart |
+| Never use | — | — | Pie charts, 3D charts of any kind |
+
+**Why never pie charts:** Cleveland-McGill perceptual hierarchy ranks angle (pie) below position (bar). Humans compare bar lengths to within a few percent; pie wedges fail at 4+ slices. **Why never 3D:** depth occludes data points and foreshortens position-based comparison. No 2D chart benefits from a third dimension. **When a two-segment donut is acceptable:** a donut with center label for binary proportions (used vs free, paid vs free) — only one comparison to make.
+
+## Chart Styling
+
+- **Single accent hue at varying opacities** for multi-series: `accent/100`, `accent/60`, `accent/30`. **Never rainbow colors.** **Why:** hue does not encode ordering — readers can't rank red vs green by magnitude. Single-hue opacity ramps preserve perceptual ordering and remain colorblind-safe. See `dataviz.md` for full palette guidance.
+- **Gradient fill underneath area lines**: line at full opacity, fill fades from ~15% at line to 0% at bottom.
+- **Label placement**: axis labels in secondary text, 11-12px. Data point labels only on hover (tooltip), not permanently displayed.
+- **Grid lines**: horizontal only, very subtle (`border-color: oklch(95% 0 0)` / Tailwind: `border-gray-100`). No vertical grid lines.
+- **No chart chrome**: skip legends when there's only one series. Put context in the card title instead.
+
+## Data Tables
+
+Tables are the workhorse of dashboards. Make them earn their space.
+
+- **Row context**: tiny avatars (24px), colored status dots (6px, not badges), flag icons, or proportion bars. Plain text tables feel like spreadsheets.
+- **Status indicators**: small colored dots (6-8px) inline with text. "Active" with a green dot, not a green badge/pill. The dot conveys status; the text provides the label. Badges add visual noise and are an AI-slop pattern.
+- **Proportion bars**: show relative values as width-proportional bars within cells. More visual than raw numbers.
+- **Row hover**: subtle background highlight (`background: #f9fafb` / Tailwind: `hover:bg-gray-50`).
+- **Headers**: sentence case, `font-weight: 500`, secondary color. **Never uppercase table headers.** **Why:** uppercase removes the lowercase letterforms that aid scan-pattern recognition; readers process uppercase ~13-20% slower than sentence case (Tinker 1969). Uppercase also reads as decorative-template, not data-functional.
+- **Alignment**: text left, numbers right, status center.
+- **Wrap every table in `overflow-x: auto`.** Horizontal, not `overflow-y` and not `overflow-hidden`. **Why:** a table is the one layout that cannot reflow — columns have minimum content widths, so at ~320px it either clips at the viewport edge or forces the whole page to scroll sideways. Vertical overflow solves a different problem and leaves this one intact.
+- **Put `position: sticky; top: 0` on `thead` past ~15 rows.** **Why:** once the header scrolls out of view every cell below it is an unlabelled string, and the user scrolls back up to remember which column is which. On an operator surface the table *is* the product, so this is not polish.
+- **Virtualize past 200 rows.** **Why:** every row is DOM the browser lays out, styles, and paints on each scroll frame — a 2,000-row table blows the 16ms budget before any of your CSS is at fault, and the fix is never "optimize the row component". Render a window (TanStack Virtual, `react-window`) or paginate. **When it breaks:** the table must be Cmd+F-searchable or printable in full — then paginate instead of virtualizing, since a virtual window hides rows from find-in-page.
+- **`scrollbar-gutter: stable` on every scroll container.** **Why:** on overlay-scrollbar platforms the track appears only on scroll, and the content reflows by its width at that moment — column edges jump the instant the user touches the wheel. Reserving the gutter costs nothing and removes the shift.
+
+## Filter & Toolbar Patterns
+
+- Ghost buttons for all filter controls — **never solid primary buttons in a toolbar.** **Why:** a toolbar holds 5-15 tertiary actions (filter, sort, group, export, refresh). Each solid primary button competes for the user's primary-action attention budget; the dashboard's actual primary action (drill-in, edit, alert config) gets buried. Hick's Law applied to visual weight.
+- Active filter state: accent background at low opacity + accent text, or subtle border change.
+- Group related filters visually. Date range selector deserves more prominence (slightly larger or separated).
+- "Reset filters" appears only when filters are active, as a text link — not a button.
+
+## Content Density
+
+Dashboards value density over breathing room (opposite of landing pages).
+
+- Metric cards: tight padding (16-20px), not the generous 32-48px of landing page cards.
+- Charts: minimize whitespace around the chart area. The data should fill the container.
+- Tables: compact row height (40-48px). Dense but scannable.
+- A dashboard should show enough data that a user can make a decision without scrolling. If the first viewport is just 4 large metric cards, you've wasted space.
+- Aim for: 3-4 metric cards + at least one chart + start of a table/list — all above the fold.
+
+---
+
+## Signal-to-Noise Hierarchy
+
+The most common AI-generated dashboard failure isn't any single bad choice — it's that every KPI, every chart, every card looks equally important. The user doesn't know where to look. Signal-to-noise hierarchy is the fix.
+
+### Tiers
+
+**Tier 1 — The hero metric.** One per dashboard. The number that answers "am I winning today?". Largest visual weight. Accent color is allowed here, and here only. Trend indicator adjacent (up/down + delta). Context micro-text below: "vs last 7 days" or "of monthly quota."
+
+**Tier 2 — Supporting metrics (2-4).** The breakdown of the hero — if the hero is revenue, supports are revenue by channel, by region, by segment. Neutral colors. Smaller type. Grouped visually with the hero (shared container, aligned baseline).
+
+**Tier 3 — Context (0-3 charts).** Trends, time series, comparisons. Chart type matches data shape (see `dataviz.md` and the Chart Type Decision Matrix above). Sparklines for micro-context inside cards. No large charts competing with the hero's visual weight.
+
+**Tier 4 — Deep-dive.** Tables, filters, raw data. Accessible but not crowding the viewport. Often collapsed by default, or lives on a separate tab / route. The user drills in when they need it.
+
+### The anti-pattern: "grid of 8 KPI cards with equal weight"
+
+Every card the same size, same color, same layout → the user's eye has nowhere to land → the user scrolls looking for meaning → the user leaves. This is the single most recognizable AI-generated dashboard shape.
+
+### The rule
+
+One hero. 2-4 supports. Context behind. Deep-dive one click away. Test by squinting at the dashboard: your eye should land on ONE thing first. If it lands everywhere, the hierarchy is broken.
+
+### Ranking decisions to document per dashboard
+
+Before building, answer these:
+
+- **What's the hero metric for this surface?** Different for exec view (revenue) vs operator view (tickets open) vs customer view (usage vs limit). See `personas.md` to ground this in concrete archetypes.
+- **What supporting metrics contextualize the hero?** The 2-4 that make the hero actionable, not the 8 you could show.
+- **What's deep-dive, not surface?** Everything the user needs once a week, not once a minute.
+- **Who's the user and what decision are they making in the next 60 seconds?** If you can't name the decision, the dashboard has no job.
+
+### Cross-references
+
+- `dataviz.md` — chart selection by data shape; Cleveland-McGill perceptual hierarchy (position-on-common-scale is most accurate — use it for the hero).
+- `heuristics.md` — Cleveland-McGill and Hick's Law checks for filter/nav choices.
+- `personas.md` — concrete user archetypes to ground "who's the user" in reality, not abstraction.

package/assets/skills/design/agemon-design/references/dataviz.md

@@ -0,0 +1,197 @@
+# Dataviz — Perceptual Accuracy
+
+Most AI-generated charts are rainbow 3-D pies on grid backgrounds with shouting legends. That's not dataviz — that's decoration. Dataviz is a science with names attached: Cleveland, McGill, Tufte, Bostock, Brewer. This file is the perceptual layer — `dashboard.md` handles dashboard chrome (sidebar, metric cards, toolbar); this handles what actually encodes information accurately.
+
+---
+
+## Cleveland-McGill Perceptual Hierarchy
+
+Source: Cleveland, W. S. & McGill, R. (1984). "Graphical Perception: Theory, Experimentation, and Application to the Development of Graphical Methods." JASA.
+
+Humans decode visual encodings with predictable, measurable accuracy. Ordered from most → least accurate:
+
+1. **Position on a common scale** — e.g., dot plot, aligned bar chart. Highest precision.
+2. **Position on unaligned scales** — e.g., small multiples with different baselines.
+3. **Length** — e.g., bar chart, progress bar.
+4. **Angle / slope** — e.g., line chart slopes, pie wedges.
+5. **Area** — e.g., bubble chart, treemap.
+6. **Volume** — e.g., 3-D bar (and yes, this is already worse than area).
+7. **Color saturation / lightness** — e.g., heatmap.
+8. **Color hue** — e.g., categorical colors. Lowest precision for quantities.
+
+**Implication:** if a numeric comparison is load-bearing, prefer bar over pie, line over stacked area, dot plot over heatmap. Color hue is for categories, not quantities.
+
+---
+
+## Chart Selection Matrix
+
+Match the data shape and analytical question to a chart. Fallbacks listed when the default isn't possible.
+
+| Data shape + question | Default | Fallback | Avoid |
+|----------------------|---------|----------|-------|
+| Time series, one metric | Line | Area (sparingly, single series) | Vertical bars per day |
+| Time series, categorical breakdown, totals | Stacked bar or stacked area | — | 100% stacked (hides totals) |
+| Time series, categorical breakdown, individual trends | Small multiples (one line per panel) | Multi-line (≤ 4 series) | Spaghetti line chart (> 5 series) |
+| Categorical, one metric | Horizontal bar (sorted) | Dot plot | Pie, unless n ≤ 3 and parts-of-whole is the story |
+| Parts of a whole | Stacked bar (100%) with labels | Donut (n ≤ 5) | Pie with n > 5; donut without center total |
+| Distribution of one variable | Histogram | Density / violin | Mean-only bar |
+| Distribution across groups | Box plot or violin | Strip plot with jitter | Mean + error bar alone |
+| Correlation of two variables | Scatter + trend line | Hex-bin (high n) | A correlation coefficient printed as a single number |
+| Ranking | Horizontal bar sorted desc | Dot plot with reference line | Vertical bar with rotated labels |
+| Geographic (regional) | Choropleth, **per-capita normalized** | Symbol map | Raw-count choropleth (shows population, not signal) |
+| Flow / transition | Sankey (sparingly) | Cohort table, small multiples | Chord diagram for > 8 categories |
+| Hierarchy | Tree / indented list | Treemap (area ≫ precision) | Sunburst for > 3 levels |
+
+**Rule of thumb:** if you can't name the question the chart answers, remove it.
+
+---
+
+## Color for Data
+
+Three families. Choose by the data's semantics, not by taste.
+
+### Sequential — one direction (low → high)
+
+For ordinal or continuous magnitude: revenue, count, score. Use perceptually uniform palettes.
+
+- **viridis, cividis** (perceptually uniform sequential — available in every charting stack) — colorblind-safe, print-safe.
+- **YlGnBu, YlOrRd** (ColorBrewer) — classic sequential, works on light backgrounds.
+
+Never use a rainbow (hue-only) palette for sequential data. Hue is not ordered — the eye cannot rank red vs green by magnitude. Ordered magnitude needs a luminance ramp (viridis, cividis, YlOrRd). Hue-only is also colorblind-hostile: red-green deficiency affects approximately 8% of men and 0.5% of women (Birch 2012; Sharpe et al. 1999) — exactly the mid-spectrum of a rainbow.
+
+### Diverging — centered on a meaningful midpoint
+
+For values with a neutral zero: surplus/deficit, above/below average, net promoter score.
+
+- **RdBu, PiYG, BrBG** (ColorBrewer).
+- The midpoint must be semantic, not arbitrary. Don't use diverging for "low to high" — that's sequential.
+
+### Categorical — nominal classes
+
+For discrete groups with no order: regions, departments, products.
+
+- **Okabe-Ito** (Okabe & Ito 2008, colorblind-safe, 8 hues). Values, in series order:
+  `#E69F00` orange, `#56B4E9` sky blue, `#009E73` bluish green, `#F0E442` yellow, `#0072B2` blue, `#D55E00` vermillion, `#CC79A7` reddish purple, `#000000` black.
+- **Cap at 7 hues.** After that, hues become indistinguishable. Options: (a) group remainder into "Other", (b) repeat hues with patterns, (c) direct-label each series and drop the legend.
+
+### Never-defaults
+
+- **Pie chart with > 5 slices** — Cleveland-McGill: angle is the fourth-lowest encoding in the perceptual hierarchy; humans cannot accurately compare more than 4–5 angular wedges. Use a horizontal bar chart sorted by magnitude instead.
+- **Rainbow / HSL-rotation palette for sequential or ordinal data** — hue carries no perceptual ordering; the eye cannot rank hues by magnitude without trial-and-error. Diverging data needs a two-direction luminance ramp (RdBu, PiYG); sequential data needs a single-direction luminance ramp (viridis, YlOrRd). Hue-only is also colorblind-hostile: red-green deficiency affects approximately 8% of men and 0.5% of women (Birch 2012; Sharpe et al. 1999). Test every palette with a colorblind simulator (Color Oracle, Coblis) — non-negotiable for status colors.
+- **Red and green as the only signal** — pair color with shape, icon, or text label; color alone fails for red-green deficient users (same citation above).
+- **3-D charts of any kind** — depth occludes data points; foreshortening distorts position-based comparison (Cleveland-McGill: volume is second-lowest in the hierarchy). No 2-D chart benefits from a third dimension.
+- **Chart library defaults without a palette override** — built-in palettes (Chart.js, Recharts) are designed for demos, not perceptual accuracy; always override with a named, colorblind-safe palette.
+- **Default grid at every tick** — Tufte's data-ink ratio: a dense grid is chartjunk. Use sparse grid lines (every 2nd or 3rd tick), or baseline + target lines only.
+
+---
+
+## Tufte Principles, Distilled
+
+Source: Tufte, E. R. (1983, 2001). *The Visual Display of Quantitative Information*.
+
+- **Data-ink ratio** — maximize ink spent on data, minimize ink spent on chrome. Every gridline, tick, border, legend box must earn its space.
+- **No chartjunk** — no 3-D, no gradients as decoration, no drop shadows on bars, no textures.
+- **Small multiples over animated dashboards** — the eye compares adjacent panels faster than it compares across a timeline.
+- **Annotation beats legend** — label the line, not a color swatch 200px away (see "Direct labeling" below).
+- **Bar charts start at zero.** Length encodes magnitude; truncating the axis lies.
+- **Line charts do NOT have to start at zero.** Position encodes change; a zero baseline can obscure the signal. Use judgment — when the story is "rose from 98 to 102", starting at zero hides it.
+
+---
+
+## Direct Labeling — the Quiet Superpower
+
+A legend forces: read color, look 200px away, match, remember, come back. Direct labels collapse that into one saccade.
+
+```jsx
+// Bad — legend + color lookup + cognitive hop
+<LineChart data={data}>
+  <Line dataKey="revenue" stroke="#1f77b4" />
+  <Line dataKey="costs" stroke="#ff7f0e" />
+  <Legend />
+</LineChart>
+
+// Good — label at the end of each line, legend gone
+<LineChart data={data}>
+  <Line dataKey="revenue" stroke="#1f77b4">
+    <LabelList dataKey="revenue" position="right" />
+  </Line>
+  <Line dataKey="costs" stroke="#ff7f0e">
+    <LabelList dataKey="costs" position="right" />
+  </Line>
+</LineChart>
+```
+
+Works for: bar charts (label inside or at end of bar), scatter (label the outlier dots), small multiples (title per panel replaces legend).
+
+---
+
+## Small Multiples
+
+Use when comparing the same metric across a dimension — 8 regions, 6 products, 12 months. The eye compares adjacent panels instantly; a single overlaid chart with 8 lines is a mess.
+
+**Layout rules:**
+- **Consistent axes across panels** — same x-scale, same y-scale. If scales differ, the comparison breaks.
+- **Consistent chart type** — all lines, all bars; never mix.
+- **One title explaining the one thing that varies** ("Revenue by region, Jan-Dec"), plus a small subtitle per panel naming that panel's dimension value.
+- **3-6 columns** typically. 10+ panels = let it wrap; keep row heights equal.
+- **Sort panels** by a meaningful order (magnitude, geography, alphabetical) — not by insertion order.
+
+---
+
+## Animated Transitions for Dataset Changes
+
+Animate to reveal change, not for decoration. The D3 enter / update / exit pattern — now standard in Recharts, VisX, Framer Motion, and Observable Plot:
+
+- **Enter** — new data points fade in and slide to position (200-300ms, `ease-out`).
+- **Update** — existing points tween to new values (300-500ms, `ease-in-out`). The tween is the insight — the user's eye tracks which point moved where.
+- **Exit** — removed points fade out and collapse (150-200ms, `ease-in`).
+
+**Rules:**
+- Tween values, not colors — category color stays stable so the eye can track a specific series.
+- Respect `prefers-reduced-motion` — collapse to instant transitions.
+- Never animate on mount just for the entrance. A dashboard loading is not a moment for choreography.
+
+See `references/motion.md` for easing curves and the duration scale.
+
+---
+
+## Anti-Slop Checklist (Dataviz)
+
+Ten items a reviewer will flag immediately. Fix before shipping.
+
+- [ ] 3-D charts of any kind. Zero exceptions.
+- [ ] Pie chart with > 5 slices, or any pie where parts-of-whole isn't the story.
+- [ ] Rainbow / HSL-rotation palette for sequential or numeric data.
+- [ ] Red and green as the only differentiator (color-blind failure — add shape or label).
+- [ ] Truncated y-axis on a bar chart (bars lie about magnitude).
+- [ ] Dense gridlines at every tick. Prefer sparse grid (every 2nd or 3rd), or baseline + target lines only.
+- [ ] Axis labels in scientific notation (`1.2e6`) when `1.2M` or `1,200,000` is readable.
+- [ ] Missing units on axes ("Revenue" vs "Revenue (USD, thousands)").
+- [ ] Legend with > 7 entries without direct labeling.
+- [ ] Choropleth of raw counts instead of per-capita / rate normalization.
+
+---
+
+## Triaging a Chart That Looks Wrong
+
+Where to look in this file:
+- More than five pie slices: § Cleveland-McGill + § Chart Selection Matrix
+- 3D effects: § Anti-Slop Checklist
+- A rainbow scale for ordered data: § Color for Data → Sequential
+- A legend where direct labels would fit: § Direct Labeling
+- A bar axis that does not start at zero: § Tufte Principles
+
+Cross-reference when a chart looks wrong.
+
+---
+
+## Sources
+
+- Cleveland, W. S. & McGill, R. (1984). "Graphical Perception." *JASA*.
+- Tufte, E. R. (2001). *The Visual Display of Quantitative Information*, 2nd ed.
+- Bostock, M. et al. (2011). "D3: Data-Driven Documents." *IEEE TVCG*.
+- Brewer, C. A. ColorBrewer 2.0 — [colorbrewer2.org](https://colorbrewer2.org/).
+- Okabe, M. & Ito, K. (2008). "Color Universal Design."
+- Wilke, C. O. (2019). *Fundamentals of Data Visualization*. O'Reilly.
+- Birch, J. (2012). "Worldwide prevalence of red-green color deficiency." *Journal of the Optical Society of America A*.
+- Sharpe, L. T. et al. (1999). "A new and popular explanation of colour blindness." In *Colour Vision: From Genes to Perception*. Cambridge University Press.