microcharts: Instructions file for Claude Code

microcharts — contributor & agent guide

Word-sized charts for React: zero runtime dependencies, ~2–7 kB interactive · ~1–4 kB static per chart, accessible by default, handcrafted-feeling. They're built to sit inside an interface — a sentence, a table cell, a KPI card, a tab header, a streamed AI reply — and to be safe for a model to emit and a person to read. Package: @microcharts/react.

This file is the working contract for anyone (human or AI) changing the code. The rules below are not style preferences — several are enforced in CI, and violating them is a bug.

Design principles

1. Earn every mark: each pixel must encode data, state, structure, or a useful interaction cue.
2. First read instant, second read rewarding: clarity at a glance may reveal finer structure on inspection.
3. Prefer uncommon questions over uncommon shapes: add a chart only when it answers a practical decision the catalog cannot already answer well.
4. Delight without lying: motion, rhythm, texture, and direct manipulation may delight, but never change what the data means.
5. Tiny size is a design material, not a limitation: composition, contrast, and summaries must survive the smallest supported context.

Charts must remain excellent in light, dark, print, and dense product contexts. "Modern" means sharper thinking and better behavior — not neon glow, glass, dashboard chrome, or decorative complexity.

Non-negotiables (violating any of these is a bug)

1. Zero runtime dependencies. dependencies: {} forever, CI-enforced. React is a peer: "react": "^18.0.0 || ^19.0.0". Scales, paths, easing, color, stats, summaries — all in-house. All chart types ship in the one @microcharts/react package. Any third-party dev-dependency must be verified actively maintained before adoption.
2. Budgets are CI gates, applied in this order. (1) Per-subpath budget: every subpath carries its own limit in scripts/size-budgets.json, set to measured + max(50 B, 2%); styles.css ≤ 12 kB. .size-limit.json is generated (scripts/gen-size-limits.mjs from that file), never hand-edited. (2) Regression diff: every PR is diffed against its base branch — scripts/size-snapshot.json records the measured gzip bytes of all 218 subpaths, CI re-measures against a fresh build (size-snapshot.mjs --check), and the size-diff job replies with a per-subpath table. Growth over 1% on any subpath fails; regenerate with pnpm build && pnpm size:snapshot, and label the PR size-increase-approved when an increase is deliberate. (3) Admission bar for a NEW chart: static ≤ 3 kB (≤ 2 kB target, "Delta-class" ≤ 1.5 kB), interactive ≤ static + 3.25 kB, ≤ ~6 SVG nodes typical, 0 client JS for static charts in RSC. (4) Catalog ceiling: static 4.35 kB / interactive 7 kB. The interactive wall is hard — no subpath crosses it, and no sign-off raises it, because "~2–7 kB interactive" is quoted in the README, the docs and the package description. sparkline defines the top of both scales (4256 / 6983 measured) and its interactive budget is pinned at the wall: 7000 B, 17 B of headroom. Growing that entry fails the gate on purpose — buy room by shrinking it, never by raising the number.