@blueprint-chart/docs 0.1.18

package/src/guide/scenes.md

@@ -0,0 +1,223 @@
+---
+title: Scenes
+---
+
+# Scenes
+
+> Same chart, different states — composed into a story that a reader can step through.
+
+## Why this matters
+
+Journalism rarely sits still on a single chart. A finding has a build-up, a turn, and a punchline. In Blueprint Chart, a **scene** is a named visualisation state — the same chart with different data, highlighting, annotations, or styling — and a sequence of scenes is the chart's **story**. You write scenes in the same `.bpc` document, and the runtime gives the reader Previous / Next controls (or your own UI) to walk through them.
+
+## Quickstart
+
+A bar chart with three narrative beats — each one highlights a different country:
+
+```bpc
+chart bar-horizontal {
+  title = "Five nations produce 80% of global CO₂"
+  description = "Annual emissions in billion tonnes, 2023"
+  source = "Global Carbon Project"
+  sourceUrl = "https://globalcarbonproject.org"
+  sort = descending
+  valueLabels = true
+  horizontalGridStyle = none
+  showVerticalAxis = true
+  showVerticalTicks = false
+  verticalGridStyle = none
+
+  data {
+    "China" = 11.90
+    "United States" = 4.78
+    "India" = 2.88
+    "Russia" = 1.78
+    "Japan" = 1.02
+  }
+
+  scene "China spotlight" {
+    title = "China emits more than the US and India combined"
+
+    highlight "China"
+  }
+
+  scene "India rising" {
+    title = "India surpassed the EU in 2023"
+
+    highlight "India"
+  }
+
+  scene "Japan declining" {
+    title = "Japan's emissions fell 20% from their peak"
+
+    highlight "Japan"
+  }
+}
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/co2-emissions-story.bpc` verbatim — three scenes, each one re-titling the chart and shifting the highlight to a new country. The base data stays the same; only the framing changes.
+:::
+
+Open this in the editor to see the scene timeline appear automatically; embed it on a page and readers get a Previous / Next nav.
+
+## How it works
+
+A scene block accepts the same member set as the top-level chart, **plus** annotation-visibility verbs. At parse time, each `scene` becomes a `SceneNode` in the AST. The DSL converter merges scene members on top of the base chart to produce the **effective** `ChartData` and `ChartOptions` for that scene.
+
+At render time:
+
+1. The runtime collects the chart's scenes into a `SceneDefinition[]`.
+2. `createSceneController(container, scenes, onSceneChange)` injects a small `<nav>` (Previous / Next / counter) into the container.
+3. On every scene change, the callback re-renders the chart with `transition = true`, which triggers the motion helpers (`snapshotForFadeOut`, `commitFadeOut`, `fadeIn`) and animates the crossfade.
+4. `goTo(index)` clamps and wraps so `goTo(-1)` cycles to the last scene.
+
+The pipeline that runs per scene is the same eleven-step sequence documented in [Embedding](/guide/embed) and the DSL spec — scene overrides are merged at step 3 (transforms), so everything downstream sees the post-scene state.
+
+## Recipes
+
+### Highlight a different point per scene
+
+The short-form `highlight "<name>"` is the workhorse. Drop one per scene and the rest of the chart greys out:
+
+```bpc
+scene "China spotlight" {
+  title = "China emits more than the US and India combined"
+
+  highlight "China"
+}
+
+scene "India rising" {
+  title = "India surpassed the EU in 2023"
+
+  highlight "India"
+}
+```
+
+::: tip From the sample library
+Two adjacent scenes from `packages/lib/src/samples/co2-emissions-story.bpc`. Each scene retitles the chart and shifts the spotlight without touching the base data.
+:::
+
+### Replace data wholesale in a scene
+
+Any scene can carry its own `data` block, which **replaces** the base data for that scene's render. The Bulgaria scene from `farm-compass` drops the EU-wide aggregate in favour of a country-specific time series, and keeps the same `area-stacked` chart type:
+
+```bpc
+scene "Bulgaria: subsidies explode" {
+  title = "Subsidies to Bulgarian farmers, million euros"
+  description = "85% of Bulgarian subsidies are direct payments — the highest share among new members"
+
+  data {
+    _series = "Indirect subsidies","Direct subsidies"
+    "2000" = 0,5
+    "2004" = 0,67
+    "2007" = 59,250
+    "2010" = 79,466
+    "2013" = 132,852
+    "2015" = 213,677
+  }
+
+  highlight "Direct subsidies"
+}
+```
+
+::: tip From the sample library
+Trimmed scene from `packages/lib/src/samples/farm-compass.bpc` (full sample has the 2000–2015 yearly series). The scene swaps data and keeps the parent chart's `area-stacked` type.
+:::
+
+### Switch chart type mid-story
+
+A scene can override the chart type with `type =`. The same `farm-compass` story leaves the parent `area-stacked` chart and pivots to a `line` for the "farms grew" beat, then back to an `area-stacked` later on:
+
+```bpc
+scene "Bulgarian farms grew" {
+  title = "Average farm size in Bulgaria quadrupled"
+  description = "Average farm size in hectares"
+  type = line
+
+  data {
+    "2005" = 5
+    "2007" = 6
+    "2010" = 12
+    "2013" = 18
+  }
+}
+```
+
+::: tip From the sample library
+Scene #5 of `packages/lib/src/samples/farm-compass.bpc`. The story changes chart type three times across nine scenes — `area-stacked` → `line` → `area` → `area-stacked` → bar — all from one document.
+:::
+
+### Hide an annotation in a later scene
+
+Use `hide_annotation`, `hide_range`, or `hide_note` with the annotation's id to peel things back as the story progresses:
+
+```bpc
+annotation "2015" {
+  id = "paris"
+  text = "Paris Agreement"
+}
+
+scene "Without Paris callout" {
+  hide_annotation "paris"
+}
+```
+
+To bring it back later, use `show_annotation "paris"` in a subsequent scene.
+
+### Drive playback from your own UI
+
+The controller is decoupled from the nav DOM it inserts — you can ignore the built-in buttons and call `next()`, `previous()`, or `goTo(index)` from any custom UI:
+
+```ts
+import { createSceneController } from '@blueprint-chart/lib/dist/runtime'
+
+const controller = createSceneController(container, scenes, (scene, index) => {
+  renderChart(canvas, scene.data, true)
+})
+
+document.querySelector('#my-next-button')!.addEventListener('click', () => {
+  controller.next()
+})
+
+// Programmatic jump:
+controller.goTo(2)
+```
+
+Call `controller.destroy()` to remove the injected nav when tearing the chart down.
+
+## API surface
+
+Exported from `@blueprint-chart/lib/dist/runtime`:
+
+| Symbol | One-liner |
+| --- | --- |
+| `createSceneController(container, scenes, onSceneChange)` | Build a scene controller, inject Previous / Next nav, call back on every scene change. |
+| `SceneDefinition` (type) | `{ name: string, data?: Record<string, unknown> }` — one scene's payload. |
+| `SceneController` (type) | Returned object with `currentScene`, `totalScenes`, `next()`, `previous()`, `goTo(index)`, `destroy()`. |
+| `createStepController` / `StepDefinition` / `StepController` | Deprecated aliases retained for backward compatibility — new code should use the `Scene*` names. |
+
+Motion helpers used internally during scene transitions (all exported from `@blueprint-chart/lib`):
+
+| Symbol | One-liner |
+| --- | --- |
+| `getTransitionDuration()` | Canonical fade duration shared with the editor's UI transitions. |
+| `snapshotForFadeOut(container)` | Capture the outgoing DOM for fade-out. |
+| `commitFadeOut(snapshot)` | Animate the snapshot out. |
+| `fadeIn(container)` | Animate the new render in. |
+| `getCachedChart(container)` | Last render, for diff-based interpolation. |
+
+DSL converter helpers (also exported from `@blueprint-chart/lib`):
+
+| Symbol | One-liner |
+| --- | --- |
+| `extractSceneOverrides(ast)` | Pull each scene's merged `ChartData` / `ChartOptions` from a parsed AST. |
+| `SceneNode` (type) | AST node for a `scene` block. |
+
+See the full list in the [API reference](/reference/api/).
+
+## See also
+
+- [BPC DSL — Scenes](/reference/dsl/scenes-and-transforms#scenes) for the source-level grammar.
+- [Embedding charts](/guide/embed) for how to drop a scenes-driven chart on a page.
+- [API reference](/reference/api/#runtime-entrypoint) for the runtime entry-point symbols.

package/src/handbook/accessibility.md

@@ -0,0 +1,109 @@
+---
+title: Accessibility
+---
+
+# Accessibility
+
+> Accessible charts are honest charts. CVD simulation, sufficient contrast, meaningful alt text, keyboard and screen-reader support, legible typography, and — above all — never encoding information in a single visual channel.
+
+## Color vision deficiency
+
+Around **8% of men** and **0.5% of women** have some form of color vision deficiency.
+
+- **Never rely on color alone** to convey meaning — combine with shape, pattern, label, or position
+- Ensure colors vary enough in **lightness** — convert your palette to grayscale as a quick test
+- Blue-orange is the safest hue combination for deuteranopia / protanopia
+- Avoid red-green combinations without additional encoding
+- Achieve at least **3:1 contrast ratio** between adjacent colors (WCAG)
+- Test with simulators: Color Oracle, Coblis, Sim Daltonism, Firefox colorblind addon
+
+## Text contrast
+
+- Minimum **4.5:1 contrast ratio** for normal text (WCAG AA)
+- Minimum **3:1** for large text (18px+ bold or 24px+ regular)
+- Higher contrast needed for small or distant chart elements
+
+## Alt text for charts
+
+Every chart needs two levels of text alternative:
+
+1. **Short alt text** — Identifies the chart type, subject, and scope. *Example: "Bar chart showing quarterly revenue for 2024 by product line"*
+2. **Long description** — Full textual representation of essential data. Can be a linked data table, a `<figcaption>`, or content referenced via `aria-describedby`
+
+## Keyboard and screen reader support
+
+- Interactive elements (tooltips, filters) must be keyboard-accessible
+- Use semantic HTML (`<figure>`, `<figcaption>`) to wrap charts
+- Provide data tables as an alternative view for complex interactive charts
+- Use `aria-describedby` to connect charts to their descriptions
+
+## Font accessibility
+
+- Minimum **12px** for chart text
+- Sans-serif fonts with distinct character shapes (l vs. 1 vs. I)
+- Avoid thin / light font weights for data labels
+- Consider **Atkinson Hyperlegible** for maximum legibility
+
+## Multiple encoding
+
+::: warning
+**Never encode information in a single visual channel.** Combine at least two.
+:::
+
+- Color + shape (circles vs. triangles)
+- Color + pattern (solid vs. hatched)
+- Color + label (direct text identification)
+- Position + size + color (scatter / bubble charts)
+
+## How Blueprint Chart applies accessibility
+
+Blueprint Chart ships a concrete accessibility toolkit:
+
+- `wcagContrastRatio` — computes WCAG contrast between two colors
+- `simulateCvdColor` — applies deuteranopia / protanopia / tritanopia simulation
+- `checkCvdColors` — validates that a palette is safe across CVD types
+
+These power the editor's live accessibility checks and the palette pickers in the UI. See the [API reference](/reference/api/) for the full helper surface.
+
+```ts
+import { wcagContrastRatio, checkCvdColors } from '@blueprint-chart/lib'
+
+wcagContrastRatio('#2563A0', '#ffffff')   // 5.13 — passes WCAG AA for normal text
+checkCvdColors(['#2563A0', '#F26A1F'])    // safe across deuteranopia / protanopia / tritanopia
+```
+
+## Worked example: lightness variation beats hue variation
+
+```bpc
+chart bar-vertical {
+  title = "Brazil produces more coffee than the next three countries combined"
+  colorPalette = "Harvey"
+  valueLabels = true
+
+  data {
+    "Brazil" = 66.4
+    "Vietnam" = 29
+    "Colombia" = 11.4
+    "Indonesia" = 9.9
+  }
+
+  colorize "Brazil" {
+    color = "#a4432d"
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/coffee-production.bpc`
+Coffee uses two encodings for the highlighted bar: a distinct hue (`#a4432d` red-brown vs. the muted Harvey palette) and clear *lightness* contrast against its neighbours. Convert the chart to greyscale and Brazil still reads as the darkest bar — the second encoding (lightness) carries the story even when CVD removes the first (hue). Compare with `valueLabels = true`, which adds a *third* encoding (the literal number).
+:::
+
+## Palette catalogue and CVD utilities
+
+Blueprint Chart ships 50+ palettes in `packages/lib/src/charts/palettes.ts`; each one is interpolated through HCL so adjacent colours vary in lightness as well as hue. The CVD simulation and validation helpers live in `packages/lib/src/charts/colorblind.ts`. Together they power the editor's live accessibility checks — any palette referenced by `colorPalette = "<name>"` in a `.bpc` file is run through `checkCvdColors` automatically.
+
+## See also
+
+- [Color & Palettes](/handbook/color)
+- [Typography](/handbook/typography)
+- [Tooltips & Interaction](/handbook/tooltips)
+- [Design Principles](/handbook/design-principles)

package/src/handbook/annotations.md

@@ -0,0 +1,143 @@
+---
+title: Annotations
+---
+
+# Annotations
+
+> Annotations guide the reader to the story in the data. They explain design elements, highlight significant values, and provide context the chart alone cannot convey. Used well, they do most of the storytelling.
+
+## Purpose
+
+Annotations guide the reader to the story in the data. They explain design elements, highlight significant values, and provide context that the chart alone cannot convey.
+
+A chart without annotations presents data. A chart *with* annotations tells a story.
+
+## Types of annotations
+
+| Type | Description | Use for |
+|------|-------------|---------|
+| **Reference line (horizontal)** | Line at a specific y-value | Averages, targets, benchmarks, thresholds |
+| **Reference line (vertical)** | Line at a specific x-value | Events in time, policy changes, milestones |
+| **Range band (horizontal)** | Shaded region between two y-values | Acceptable zones, confidence intervals |
+| **Range band (vertical)** | Shaded region between two x-values | Time periods (recessions, campaigns) |
+| **Point annotation** | Marker + label at a specific data point | Outliers, peaks, significant individual values |
+| **Callout** | Label with connector line | Explanations positioned away from crowded areas |
+
+## Best practices
+
+- Maximum **3-4 annotations per chart** to avoid overwhelming readers
+- Position explanatory text as close to the relevant data as possible
+- Use **two text hierarchy levels** within annotations (e.g., bold primary, regular secondary) — not more
+- Use text outlines when annotations overlay grid lines
+- On mobile, hide less important annotations or move them below the chart
+- Write annotations that add context beyond what the data shows ("why" not just "what")
+
+## Annotations as storytelling
+
+::: tip
+"If everything is emphasized, nothing is." Prioritize ruthlessly. The annotation should match the chart's headline — reinforce the main point, don't dilute it with tangential observations.
+:::
+
+A good annotation reads like a caption to a photograph: it tells the reader what matters here and why. Avoid restating what the axis already shows.
+
+::: info Example
+**Bad:** "March: 2,300 units" (redundant with the data label)
+
+**Good:** "New packaging launched March 3 — unit sales jumped 40%"
+:::
+
+## How Blueprint Chart applies annotations
+
+Blueprint Chart implements annotations as first-class citizens: **Point**, **Range**, and **Free** annotations are part of the DSL grammar and the rendering pipeline. Annotations are ordered and rendered above the chart geometry but below tooltips, so they sit visually in the foreground without interfering with hover interaction.
+
+```bpc
+chart line {
+  title = "Unit sales jumped after new packaging launched"
+
+  data {
+    "Jan" = 1600
+    "Feb" = 1700
+    "Mar" = 2300
+    "Apr" = 2350
+    "May" = 2420
+  }
+
+  annotation point {
+    at    = "Mar"
+    label = "New packaging launched March 3"
+  }
+}
+```
+
+See the [BPC DSL Specification](/reference/dsl/annotations) for the full annotation grammar.
+
+## Worked example: a point annotation tied to a peak
+
+```bpc
+chart line {
+  title = "Bitcoin surged past $90,000 in 2024"
+  description = "USD, year-end closing price"
+  source = "CoinGecko"
+  colors = "#f7931a"
+
+  data {
+    "2020" = 28949
+    "2021" = 46306
+    "2022" = 16547
+    "2024" = 93429
+  }
+
+  annotation "2021" {
+    text = "All-time high cycle"
+    dy = -12
+    showArrow = true
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/bitcoin-price.bpc`
+The annotation is keyed by the same x-value the data uses (`"2021"`), placed `-12` pixels above the point and connected with `showArrow`. One annotation, one observation — the chart stays under the 3–4 annotation ceiling and the label sits in the negative space above the data, not on top of the line.
+:::
+
+## Worked example: a callout with curved leader line
+
+```bpc
+chart bar-vertical {
+  title = "China emits more CO₂ than the US and India combined"
+  description = "Annual emissions in billion tonnes, 2023"
+  colors = "#abb8c3"
+  valueLabels = true
+
+  data {
+    "China" = 11.9
+    "United States" = 4.78
+    "India" = 2.88
+    "Russia" = 1.78
+  }
+
+  colorize "China" {
+    color = "#e15759"
+  }
+
+  annotation "India" {
+    text = "Surpassed EU in 2023"
+    showLine = true
+    anchorDirection = N
+    textOffsetX = 66
+    textOffsetY = -41
+    lineStyle = curve-left
+    showArrow = true
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/co2-emissions.bpc`
+A callout adds the *why* alongside the data ("Surpassed EU in 2023") — a sentence that the bar height alone cannot communicate. `lineStyle = curve-left` plus the text offsets keep the label well clear of the bars; `anchorDirection = N` attaches the leader line to the top of the "India" bar.
+:::
+
+## See also
+
+- [Frame Elements](/handbook/frame-elements)
+- [Labels & Legends](/handbook/labels)
+- [Design Principles](/handbook/design-principles)
+- [BPC DSL Specification](/reference/dsl/annotations)

package/src/handbook/anti-patterns.md

@@ -0,0 +1,85 @@
+---
+title: Anti-Patterns
+---
+
+# Anti-Patterns
+
+> A catalog of what goes wrong: misleading practices that distort the truth, design anti-patterns that obscure the story, and the statistical integrity rules that keep charts honest.
+
+## Misleading practices
+
+| Anti-pattern | Why it misleads | Fix |
+|--------------|-----------------|-----|
+| Truncated y-axis on bar charts | Exaggerates small differences | Start at zero |
+| Dual y-axes | Arbitrary scale alignment implies false correlation | Side-by-side charts or indexed values |
+| 3D effects | Tilted surfaces distort perceived values | Use flat 2D charts |
+| Cherry-picked time ranges | Supports a narrative without full context | Show complete timeframe; note any filtering |
+| Bubble size by radius | Exponential area distortion | Size by area |
+| Unnormalized choropleth | Shows population density, not the intended variable | Normalize per capita / per unit |
+| Rainbow color scales | Perceptually non-uniform; meaningless ordering | Use sequential or diverging palettes |
+
+See [Axes & Grid Lines](/handbook/axes) for the baseline rules behind the first row, and [Color & Palettes](/handbook/color) for palette guidance that prevents the last two.
+
+## Design anti-patterns
+
+| Anti-pattern | Problem | Fix |
+|--------------|---------|-----|
+| Spaghetti chart | Too many overlapping lines | Highlight key lines; grey the rest; small multiples |
+| Pie chart with 10+ slices | Unreadable small slices | Use bar chart or group into "Other" |
+| Decorative color | Color without meaning adds noise | Use grey for non-meaningful elements |
+| Legend far from data | Forces eye-travel; increases cognitive load | Direct labeling |
+| Rotated axis labels | Hard to read | Abbreviate labels or use horizontal bars |
+| Over-annotation | Competing for attention dilutes the message | Maximum 3-4 annotations; prioritize |
+| Missing context | Data without comparison has no story | Add reference lines, targets, time comparisons |
+| Stacking many small segments | Impossible to read individual values | Group small segments; use direct comparison |
+
+See [Labels & Legends](/handbook/labels) for direct-labeling technique and [Annotations](/handbook/annotations) for the 3–4 annotation ceiling.
+
+## Statistical integrity
+
+- **Start axes at zero** for area / bar charts unless there is a compelling, stated reason not to
+- **Avoid implying causation from correlation** (scatter plots show association only)
+- Show **confidence intervals and error bars** when data has uncertainty
+- Don't obscure sample size (**box plots hide it**; add individual points for small N)
+- **Tables are valid** — sometimes better than charts for conveying precise values
+
+## Worked example: a shared baseline instead of three deceptive single-bar charts
+
+A frequent anti-pattern is splitting a comparison across three charts with different y-axis ranges — each one tuned to "look interesting" in isolation. The honest alternative is one chart with a shared scale, so identical bar lengths mean identical values:
+
+```bpc
+chart bar-split {
+  title = "Singapore leads the world in all three PISA 2022 subjects"
+  description = "Mean scores in Mathematics, Reading, and Science for 15-year-olds"
+  source = "OECD PISA 2022"
+  valueLabels = true
+  sharedScale = true
+
+  data {
+    _series = "Mathematics","Reading","Science"
+    "Singapore" = 575,543,561
+    "Japan"     = 536,516,547
+    "Korea"     = 527,515,528
+    "Estonia"   = 510,511,526
+    "Canada"    = 497,507,515
+    "Australia" = 487,498,507
+  }
+}
+```
+
+::: tip Done right
+`sharedScale = true` forces every panel onto the same baseline-zero axis, so the eye can compare Mathematics directly against Reading directly against Science. `valueLabels = true` then exposes the exact number, removing any temptation to truncate the axis for visual drama. This is the corrective pattern for the "truncated y-axis", "dual y-axes", and "missing context" rows above. From `packages/lib/src/samples/pisa-scores.bpc`.
+:::
+
+## The meta-rule
+
+::: tip
+Every anti-pattern traces back to a design principle being violated. If a chart feels wrong, walk back through the [design principles](/handbook/design-principles) — purposefulness, clarity, data-ink, restraint, consistency, comparison. One of them will be out of place.
+:::
+
+## See also
+
+- [Design Principles](/handbook/design-principles)
+- [Choosing the Right Chart](/handbook/choosing)
+- [Axes & Grid Lines](/handbook/axes)
+- [Color & Palettes](/handbook/color)

package/src/handbook/axes.md

@@ -0,0 +1,116 @@
+---
+title: Axes & Grid Lines
+---
+
+# Axes & Grid Lines
+
+> When zero matters, when it doesn't, how grid lines should whisper rather than shout, how to format numbers, when to use logarithmic scales, and how aspect ratio silently changes a chart's story.
+
+## Baseline rules
+
+| Chart type | Must start at zero? | Reason |
+|------------|---------------------|--------|
+| Bar / column | **Yes** | Bar length encodes the value |
+| Stacked bar | **Yes** | Area encodes the value |
+| Area chart | **Yes** | Filled area encodes magnitude |
+| Line chart | **No** | Position (not length) encodes the value |
+| Scatter plot | **No** | Position encodes the value |
+
+::: warning
+Truncating the y-axis on a bar or area chart visually exaggerates differences. This is the single most common deceptive pattern in the wild. See [Anti-Patterns](/handbook/anti-patterns).
+:::
+
+## Grid lines
+
+- Grid lines should be **subtle**: light grey, thin (0.5–1px)
+- Y-axis grid lines are generally more useful than x-axis grid lines
+- Remove grid lines entirely when value labels are shown directly on data
+- Grid lines are reference aids, not primary content — they should never compete with data
+
+## Tick marks
+
+- Subtle or no ticks are preferred in modern chart design
+- Use consistent intervals (don't skip values)
+- Avoid excessive tick density — 5-7 ticks on a continuous axis is usually sufficient
+
+## Number formatting
+
+- Use abbreviated formats: **20k, 20m, 20b** (not "in millions")
+- Remove trailing zeros: **27%** not **27.0%**
+- Use thousands separators: **1,000** not **1000**
+- Repeat units on axis labels: **$20k** on each tick, not just "in thousands of dollars"
+
+## Logarithmic scales
+
+- Use for data spanning multiple orders of magnitude
+- Display relative changes and ratios
+- Add horizontal reference lines at meaningful values
+- Arrange symmetrically around the no-change point
+- Use ratio notation (1/4, 1/2, 1, 2, 4) rather than decimal notation
+- Label clearly — many audiences are unfamiliar with log scales
+
+## Aspect ratio
+
+- Default to roughly **4:3** or **16:9** for standard charts
+- Use **1:1** (square) when both axes share the same unit or meaning (observed vs. predicted, before vs. after)
+- Aspect ratio dramatically affects perceived slope and trend interpretation
+
+::: tip
+A trend that looks alarming at 3:1 can look flat at 3:4. When showing rate of change, pick an aspect ratio that reflects the underlying rate honestly — neither flattened nor exaggerated.
+:::
+
+## How Blueprint Chart applies axes
+
+Blueprint Chart's `AxisOptions` exposes scale type (linear / log), tick count, tick format, and baseline behavior. D3 scales drive the tick layout, and a shared number formatter is used by the axis, tooltip, and direct labels so the same value is rendered identically wherever it appears.
+
+See the [API reference](/reference/api/) for the public options that toggle grid lines, tick density, and baseline zero.
+
+## Worked example: number format on the axis
+
+```bpc
+chart line {
+  title = "Bitcoin surged past $90,000 in 2024"
+  description = "USD, year-end closing price"
+  source = "CoinGecko"
+  colors = "#f7931a"
+  verticalNumberFormat = ",.0f"
+  lineSymbols = true
+
+  data {
+    "2016" = 963
+    "2020" = 28949
+    "2021" = 46306
+    "2024" = 93429
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/bitcoin-price.bpc`
+`verticalNumberFormat = ",.0f"` uses a D3 format string to add thousands separators and drop decimals — so the axis shows `93,429` instead of `93429.00`. The same formatter feeds the tooltip and any direct value labels, so identical values render identically in every slot.
+:::
+
+## Worked example: gridlines that whisper
+
+```bpc
+chart line {
+  title = "2024 was the hottest year on record"
+  colors = "#e15759"
+  showVerticalAxis = false
+  showVerticalTicks = false
+  verticalGridStyle = "dashed"
+  showHorizontalAxis = true
+  showHorizontalTicks = false
+  horizontalGridStyle = "none"
+}
+```
+
+::: info From `packages/lib/src/samples/temperature-anomaly.bpc`
+The vertical axis line and ticks are off; only dashed horizontal gridlines remain as reference. The horizontal axis stays visible but loses its ticks. Net result: gridlines whisper, the line speaks.
+:::
+
+## See also
+
+- [Labels & Legends](/handbook/labels)
+- [Anti-Patterns](/handbook/anti-patterns)
+- [Design Principles](/handbook/design-principles)
+- [Frame Elements](/handbook/frame-elements)