chart-sins/CLAUDE.md

Chart Sins — working notes

Conventions and gotchas for anyone (human or agent) working in this repo. Keep this current when a convention changes.

What this is

Chart Sins is "nohello.net for bad charts." The unit of value is a single, linkable, cited page you send someone instead of re-explaining, for the hundredth time, why their chart misleads. The gallery is secondary; the per-sin page is the product.

Each sin page follows one shape: poke → proof → why → the fix → receipts → share.

Voice & content conventions

• The title names the problem plainly; the poke carries the voice. A title is a label someone scans in the gallery and recognizes in a link — write "Truncated Y-Axis on a Bar Chart," not "The Truncated Temptation." Use the field's standard term for the sin where one exists. Save the wit for the poke; that's what it's for.
• The poke names the general sin, never the sample's specifics. A visitor didn't "start the axis at 90" — they mis-set the baseline. Write "Your bars don't start at zero…", not the numbers from our example data.
• Tone: cheeky, not moralizing. "Caught — here are the receipts," not "repent." Poke the mistake, keep it light.
• We condemn uses, not chart types. There is no banned form here. A pie chart showing three parts of a whole is doing its job; a second y-axis carrying °C against °F is fine. The sin is always a use — the workload the form can't carry, the alignment you picked yourself, the baseline you moved. Say so on the page when the form has honest uses, so nobody reads us as "pie charts are always wrong." Blanket bans are how dataviz advice turns into folklore, and folklore is what we're trying to replace with citations.
• Severity means something. Keep it consistent: 5 — reverses or fabricates meaning; no honest reading of the chart exists. 4 — actively misleads about magnitude or relationship, but the underlying form has legitimate uses. 3 — a sound form asked to do a job it can't; the reader can't extract what the chart claims to show. 2 — craft failure: nothing false, but the reader is made to work for no reason.
• Same numbers, both charts. The bad and fixed charts must share one dataset so the page proves dishonest-vs-honest by construction. Charts are authored as Vega-Lite specs and rendered at build time — never screenshots.
• The bad chart is intentionally wrong; the fixed chart must obey the rules. (e.g. the dual-axis "sin" deliberately breaks the one-axis rule; its fix uses separate honest panels.) When picking chart colors or building a new chart, run the dataviz skill and validate the palette with its validator.
• Citations are core, and generous. Every sin cites sources (src/lib/references.ts) under "Don't take our word for it." Don't invent authority — point at it, and point at as much of it as you honestly can. Five-ish sources per sin is normal; a reader who distrusts one author should find another in the list they don't. Adding a new reference is routine, not an editorial event — the file is a bibliography to grow, not a canon to curate, and coverage of it is not a goal in itself. Never stretch a source to fit: if it doesn't actually make the claim, cite one that does or leave it out. Getting an attribution wrong costs more than a thinner page. When you can't reach a source, don't guess and don't quietly settle for a weaker page — a lot of this material is behind 403s, paywalls and JSTOR. Add the link and the specific question to docs/source-requests.md; a human drops the content into docs/sources/ and you finish the note from it. Same file holds the register of claims already live on the site that rest on recall rather than a source anyone opened — add to it when you write from memory, rather than leaving the page looking better-sourced than it is. Never invent a URL to fill a url field; leaving it empty is the correct move (huff, shapeparameter, economistmistakes all ship without one). A source that complicates our position (Kosara on pie charts, Datawrapper's second thoughts on dual axes) is worth citing too — say so in the note.
• Internal build decisions stay out of visitor-facing content and the DOM. The design system (Carbon), the typeface (IBM Plex), and the inspiration (nohello.net) are engineering choices — they must not appear in page copy, the footer, meta tags, or CSS class names on the public site. (They were scrubbed once already; keep them out.) Naming them here, in repo docs, is fine. "Canon" is on that list too — it's our internal shorthand for the reference list; the site says "References" and links to /references/.

Adding a sin

1. Author two Vega-Lite specs in src/charts/, e.g. my-sin-bad.json and my-sin-fixed.json. Same underlying data in both. Omit $schema/config; explicit width/height are fine. The bad one breaks a rule on purpose; the fixed one is correct.
2. Add src/content/sins/my-sin.md with frontmatter (schema in src/content.config.ts):

   title, summary, poke, category, severity (1–5), tags[],
   badChart, fixedChart, date, draft, citations: [{ key, note }]
   

   badChart/fixedChart are the spec basenames (no .json). citations[].key must exist in src/lib/references.ts (build throws otherwise).
3. New reference? Add it once to src/lib/references.ts, then cite its key. Optional frontmatter worth knowing about:
   • wild[] — real specimens of the sin, rendered above the citations. Always credit the original and link sourceUrl where we found it. A chart that commits two sins goes on both pages with a different note on each.
   • related[] — slugs of neighbouring sins; validated at build, so a typo or a renamed slug fails the build rather than shipping a dead link.
   • compareNote — overrides "Same numbers, both charts," which is wrong on a sin whose whole point is an omission.
4. Draw the thumbnail: src/thumbs/<slug>.svg (see "Thumbnails" below). The build throws if it's missing.
5. npm run dev and check. The OG card for the sin is generated automatically.

Thumbnails

Every sin has a hand-drawn pictogram at src/thumbs/<slug>.svg, used as a banner across the top of its gallery tile and as a small glyph in the "Often found together" cross-links. Lookup is src/lib/thumbs.ts, rendered by SinThumb.astro; a missing file fails the build.

• A symbol of the sin, not a shrunken chart. In nearly every sin the tell lives in the axis, the scale or the legend — exactly what a chart loses when you shrink it to 120px. A miniature of the bad chart throws away the evidence and leaves a gallery of indistinguishable squiggles. Draw the tell: a cut baseline, a down-pointing axis arrow, class breaks that moved.
• The glyph shows the sin, not the fix. The tile is a rogues' gallery you scan for the one you recognise; the correction lives on the page.
• viewBox="0 0 72 48", fill="none", stroke-width 2 for structure. Neutral linework is currentColor; the offending element takes var(--thumb-accent). --thumb-alt and --thumb-third exist for glyphs that need to show two or three distinct series (dual axis, mismatched category colours).
• Those three vars resolve to site tokens in global.css, so unlike the charts, thumbnails follow the light/dark theme — they don't need the fixed --chart-canvas, and they must stay legible on both --layer-02 surfaces.
• Check the result at both sizes: the banner is ~72px tall, the cross-link glyph ~36px. A glyph that needs more than about six strokes won't survive the smaller one.

Design & rendering

• Astro 5, static output, zero client JS — the one exception is the small progressive-enhancement copy-link script on the sin page.
• Styling is a token layer (src/styles/global.css) built on Carbon design tokens: layered light/dark themes, 8px spacing scale, IBM Plex (self-hosted via @fontsource), square geometry, a 2px focus ring. Class prefix is site- (not cds-).
• Charts render to static SVG at build via the shared pipeline in src/lib/renderChart.ts (used by both the on-page component and the OG generator, so they stay identical). Charts sit on a fixed light canvas (--chart-canvas) in both themes so the single baked SVG keeps AA contrast.
• The categorical palette is Carbon's data-vis palette, validated for colorblind-safety/contrast on the chart surface. Re-validate if you change it.

OpenGraph cards

• Per-sin 1200×630 cards are generated at build time — no browser. src/lib/og.ts composes with satori, rasterizes with @resvg/resvg-js; endpoints are src/pages/og/[slug].png.ts and og/default.png.ts.
• Card content stays lean: poke + before/after charts + severity + category. No citation list on the card (that lives on the page).
• Fonts: three IBM Plex TTF weights are committed under src/og/fonts/ (satori and resvg need real font files; the @fontsource woff2 won't do).
• satori gotchas (all learned the hard way): empty <div>s in a flex row each need their own display:flex; don't put a quoted font-family in an inline style (it breaks the style parse — set the default font via satori's fonts instead); trim the markup so there's a single root node; give <img> dimensions in the style as px; cap charts by height so tall vconcat charts don't overflow.

Deploy & ops

• GitHub Pages via .github/workflows/deploy.yml, triggered on push to main (plus workflow_dispatch). Project path is configured in astro.config.mjs (site + base → /chart-sins).
• Known gotcha — the github-pages environment's branch allow-list. The build job goes green and the deploy job fails with zero steps and this annotation: Branch "main" is not allowed to deploy to github-pages due to environment protection rules. When GitHub auto-creates the github-pages environment it pins a deployment branch allow-list to whatever branch was default at that moment — here, the feature branch that was pushed into the empty repo first. Changing the repo's default branch later does not rewrite that list; we tried on 2026-08-05 and the deploy failed again, identically. Fix: Settings → Environments → github-pages → Deployment branches and tags → add main (or drop the restriction). Nothing in the workflow file or the default-branch setting can work around it.
• A zero-step deploy failure is always this: a protection rule refusing the job before it runs, never a build problem. Read the check-run annotation rather than the logs — a rejected job has no logs.
• The environments API is blocked by the agent proxy, so an agent can neither read nor fix this. It has to be a human in repo settings.
• Pages had to be enabled manually once (Settings → Pages → Source: GitHub Actions) — the Actions token can't create the Pages site itself.