@blueprint-chart/docs 0.1.18

package/src/handbook/choosing.md

@@ -0,0 +1,120 @@
+---
+title: Choosing the Right Chart
+---
+
+# Choosing the Right Chart
+
+> Before picking a visualization type, answer three questions about goal, content, and audience. Then pick the simplest chart that answers the question. Increase complexity only when the simpler form cannot convey the insight.
+
+## Start with the question, not the chart
+
+Answer three questions *before* sketching a single axis:
+
+1. **What is the goal?** — Analysis (exploring data) or communication (presenting a finding)?
+2. **What do you want to show?** — A comparison, a trend, a proportion, a distribution, a relationship?
+3. **Who is the audience?** — Executives want high-level dashboards; analysts need granular detail; general audiences need familiar forms.
+
+Write the chart's main statement first. It becomes a compass for every design decision that follows.
+
+## Decision framework by goal
+
+| Goal | Primary chart types | Avoid |
+|------|---------------------|-------|
+| **Compare categories** | Bar (vertical/horizontal), grouped bar, dot plot, bullet graph | Pie (if > 5 categories) |
+| **Show change over time** | Line, area, column, slope chart | Pie/donut (no time axis) |
+| **Show proportions / part-to-whole** | Stacked bar (100%), donut, waffle, treemap | Line charts |
+| **Show distribution** | Histogram, box plot, violin plot, density plot | Bar chart (categorical only) |
+| **Show relationships / correlation** | Scatter plot, bubble chart, heatmap | Bar charts |
+| **Show ranking** | Horizontal bar (sorted), lollipop, slope chart | Pie charts |
+| **Show flow / movement** | Sankey diagram, alluvial diagram | Static charts |
+| **Show hierarchy** | Treemap, sunburst, tree diagram | Flat charts |
+| **Show geographic patterns** | Choropleth, symbol map, bubble map | Non-spatial charts |
+| **Show deviation from baseline** | Diverging bar, bullet graph, surplus/deficit line | Standard bar |
+
+## Decision by data shape
+
+| Data shape | Chart types |
+|------------|-------------|
+| 1 numeric variable | Histogram, density plot, box plot |
+| 1 categorical variable | Bar chart, lollipop, pie/donut |
+| Numeric + categorical (1 observation per group) | Bar chart, lollipop, dot plot |
+| Numeric + categorical (many observations per group) | Box plot, violin plot, grouped bar |
+| 2 numeric variables | Scatter plot, line chart (if ordered) |
+| 3+ numeric variables | Bubble chart, parallel coordinates, heatmap |
+| Multiple series over time | Multi-line, stacked area, small multiples |
+| Hierarchical categories | Treemap, sunburst, circle packing |
+| Network / flow | Sankey, chord diagram, network diagram |
+
+## Complexity escalation rule
+
+::: tip
+Start with the simplest chart that answers the question. A bar chart that communicates clearly is better than a beautiful but confusing stream graph.
+:::
+
+Increase complexity only when the simpler form cannot convey the insight. Stream graphs, sunbursts, radar charts, and chord diagrams are powerful — and dangerous. Each added dimension must earn its place.
+
+## When a table is better
+
+If you have fewer than 5 numbers to present, a table often communicates more effectively than a chart. Tables allow precise value comparison; charts excel at showing patterns, trends, and relationships.
+
+::: info Example
+To display "revenue this quarter vs. last quarter, and year-over-year growth" — that is three numbers. A small table beats any chart.
+:::
+
+## Worked example: two stories, two chart types
+
+The same dataset rarely fits every story. The two samples below answer different questions about different shapes of data — and each picks the simplest form that works.
+
+**Trend over time → line chart:**
+
+```bpc
+chart line {
+  title = "Bitcoin surged past $90,000 in 2024"
+  description = "USD, year-end closing price"
+  source = "CoinGecko"
+  colors = "#f7931a"
+
+  data {
+    "2016" = 963
+    "2020" = 28949
+    "2021" = 46306
+    "2022" = 16547
+    "2024" = 93429
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/bitcoin-price.bpc`
+Position over time is what the reader needs — a line uses x-position for the date and y-position for the value. A bar chart of the same data would force length comparisons that obscure the trend.
+:::
+
+**Part-to-whole → donut chart:**
+
+```bpc
+chart donut {
+  title = "Chrome dominates with two-thirds of the desktop browser market"
+  description = "Worldwide, January 2025"
+  source = "StatCounter"
+  displayAsPercentage = true
+
+  data {
+    "Chrome" = 65.7
+    "Edge" = 13.1
+    "Safari" = 8.9
+    "Firefox" = 6.3
+    "Opera" = 3.1
+    "Others" = 2.9
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/browser-market.bpc`
+Six categories summing to 100 % — the question is "how big a slice does Chrome own?" A donut answers it directly; a line chart cannot.
+:::
+
+## See also
+
+- [Design Principles](/handbook/design-principles)
+- [Anti-Patterns](/handbook/anti-patterns)
+- [Frame Elements](/handbook/frame-elements)
+- [BPC DSL Specification](/reference/dsl/)

package/src/handbook/color.md

@@ -0,0 +1,141 @@
+---
+title: Color & Palettes
+---
+
+# Color & Palettes
+
+> Palette types, seven key rules, the perceptual-uniformity trap (HCL vs. HSL), ten techniques for reducing color usage, dark mode adjustments, and the components of an organizational palette system.
+
+## Palette types
+
+| Type | Use | Example |
+|------|-----|---------|
+| **Sequential** | Ordered data, low → high | Light blue → dark blue |
+| **Diverging** | Data with a meaningful midpoint | Blue → grey → red |
+| **Categorical** | Distinct categories, no order | Blue, orange, green, purple |
+
+## Key rules
+
+1. **Grey is the most important color.** Use it to de-emphasize supporting data, grid lines, and context elements.
+2. **Maximum 7 categorical colors** before confusion sets in. Beyond that, consider grouping, small multiples, or a different chart type.
+3. **Vary lightness across colors.** This ensures distinguishability in grayscale and for colorblind users.
+4. **Blue-orange is the safest combination** — it works for colorblind users, prints well, and appears in top publications.
+5. **Never max saturation + max brightness together.** It creates a neon, untrustworthy appearance.
+6. **Avoid pure hues.** Shift 5-10 degrees from exact 0/60/120/180/240/300 positions on the color wheel.
+7. **Color must encode meaning, not decoration.** If your color does not represent anything, don't use it.
+
+## Perceptual uniformity
+
+HSV/HSL color spaces are **not** perceptually uniform. Fully saturated yellow and blue have the same HSV "value" but appear dramatically different in brightness. Use CIELAB (L\*a\*b\*) or HCL (Hue-Chroma-Lightness) for interpolation instead.
+
+**Tools:** Chroma.js for HCL interpolation, D3.js CIELAB plugin, ColorBrewer for pre-made safe palettes.
+
+::: tip
+Blueprint Chart uses chroma.js throughout the library and ships 50+ built-in palettes resolved through perceptually uniform interpolation.
+:::
+
+## Reducing color usage (10 techniques)
+
+1. Remove color entirely when position already distinguishes items
+2. Use shades of one hue instead of multiple hues
+3. Highlight only key categories; grey everything else
+4. Direct-label instead of using color legends
+5. Merge minor categories into "Other"
+6. Separate same-colored items with white strokes
+7. Change chart type to encode by position instead of color
+8. Use small multiples (one color per panel)
+9. Add symbols, patterns, or dashes instead of colors (limit to 3-4)
+10. Use tooltips for progressive disclosure
+
+## Dark mode considerations
+
+- Avoid pure black backgrounds; keep lightness between 10-25%
+- Keep background saturation below 20%
+- Colors that work on light backgrounds may need adjustment (different contrast dynamics)
+- Increase saturation slightly for colors on dark backgrounds
+
+## Organizational palette components
+
+A complete chart color system includes:
+
+- Categorical colors (5-7)
+- An accent / highlight color
+- Greys for data de-emphasis
+- Greys for non-data elements (axes, grid lines)
+- Sequential gradients
+- Diverging gradients
+- Optionally, map element colors
+
+## How Blueprint Chart applies color
+
+Blueprint Chart ships categorical, sequential, and diverging palettes — all derived via chroma.js with perceptually-uniform interpolation. Accessibility is enforced through helpers for WCAG contrast ratio and CVD simulation. See the [Accessibility](/handbook/accessibility) page for details on the contrast and color-vision-deficiency toolkit.
+
+```bpc
+chart line {
+  title  = "Renewable capacity outgrew coal in 2024"
+  colors = "#2563A0"   // single highlight; the rest defaults to grey
+
+  data {
+    "2020" = 10
+    "2021" = 14
+    "2022" = 19
+    "2023" = 27
+    "2024" = 35
+  }
+}
+```
+
+## Worked example: a named palette for distinct categories
+
+```bpc
+chart donut {
+  title = "Chrome dominates with two-thirds of the desktop browser market"
+  description = "Worldwide, January 2025"
+  source = "StatCounter"
+  colorPalette = "Heep"
+  displayAsPercentage = true
+
+  data {
+    "Chrome" = 65.7
+    "Edge" = 13.1
+    "Safari" = 8.9
+    "Firefox" = 6.3
+    "Opera" = 3.1
+    "Others" = 2.9
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/browser-market.bpc`
+Six unordered categories, so a categorical palette ("Heep") is the right tool — its hues vary in lightness, which means the donut survives a grayscale conversion. The rule "maximum 7 categorical colors" is exactly at the limit here.
+:::
+
+## Worked example: one accent hue, everything else grey
+
+```bpc
+chart line {
+  title = "2024 was the hottest year on record"
+  description = "Deviation from the 1951–1980 average, in °C"
+  colors = "#e15759"
+  verticalGridStyle = "dashed"
+  horizontalGridStyle = "none"
+
+  data {
+    "1980" = 0.26
+    "2000" = 0.42
+    "2015" = 0.9
+    "2024" = 1.29
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/temperature-anomaly.bpc`
+A single red hue carries semantic weight (warming) while the dashed horizontal grid stays neutral. This is technique 3 from the "Reducing color usage" list: highlight one series, grey everything else.
+:::
+
+## See also
+
+- [Accessibility](/handbook/accessibility)
+- [Design Principles](/handbook/design-principles)
+- [Anti-Patterns](/handbook/anti-patterns)
+- [Axes & Grid Lines](/handbook/axes)

package/src/handbook/design-principles.md

@@ -0,0 +1,111 @@
+---
+title: Design Principles
+---
+
+# Design Principles
+
+> The core principles behind every good chart: purposefulness, clarity, data-ink ratio, restraint, consistency, starting with grey, the power of comparisons, and the refusal to use 3D.
+
+## Purposefulness
+
+Every visual element must advance the communicative goal. If it doesn't help the reader understand the data, remove it. A decorative stroke, a background gradient, a stray shadow — each is a distraction tax. The test is simple: *delete it and see if anything is lost*.
+
+## Clarity over aesthetics
+
+Prioritize legibility and interpretation accuracy. A clear chart that looks plain is better than a beautiful one that misleads or confuses. Beauty follows from clarity, not the other way around.
+
+## Data-ink ratio
+
+Maximize the share of ink (pixels) devoted to data. Reduce grid lines, borders, backgrounds, and decorative elements. As Tufte prescribed: **erase non-data-ink**.
+
+::: tip
+If a line doesn't carry data, ask whether it can be lighter, thinner, or simply removed. Most grid lines can be dropped entirely when value labels sit on the data.
+:::
+
+## Restraint
+
+- Remove redundant elements
+- Use the minimum number of colors needed
+- Avoid 3D effects, shadows, gradients, and decorative illustrations
+- Do not add features, axes, or dimensions that don't serve the story
+
+Restraint is the discipline that separates editorial charts from dashboard clutter. A chart is not a brochure.
+
+## Consistency
+
+- Use the same color for the same category across all charts in a dashboard
+- Maintain consistent axis scales when comparing charts side by side
+- Use the same number format throughout
+
+Consistency reduces cognitive load. A reader who has learned that "blue = Q1" in chart A should not have to relearn it in chart B.
+
+## Start with grey
+
+::: tip
+Grey everything out first. Then selectively add color and emphasis to the elements that carry the story. This forces intentional hierarchy.
+:::
+
+When grey is the default, color becomes meaningful. Every colored element must earn its place.
+
+## Comparisons make the story
+
+Data in isolation has no meaning. Data in context — compared to another time period, another category, a target, an average — becomes insight. The comparison you choose determines the story you tell.
+
+::: info Example
+"Unemployment is 4.1%" is a number. "Unemployment is 4.1%, down from 6.5% two years ago" is a story. The comparison does the work.
+:::
+
+## Avoid 3D
+
+::: warning
+Unanimously across all sources: **avoid 3D charts entirely**. Tilted surfaces create perceived differences where none exist. Accurate value reading requires mental projection against axis walls — a task humans perform poorly.
+:::
+
+No 3D bar charts. No 3D pie charts. No extruded columns. No perspective shading.
+
+## Worked example: start with grey, then highlight one thing
+
+```bpc
+chart bar-vertical {
+  title = "Brazil produces more coffee than the next three countries combined"
+  description = "Million 60-kg bags, 2023/24 crop year"
+  source = "International Coffee Organization"
+  colorPalette = "Harvey"
+  valueLabels = true
+  verticalGridStyle = "none"
+  horizontalGridStyle = "none"
+
+  data {
+    "Brazil" = 66.4
+    "Vietnam" = 29
+    "Colombia" = 11.4
+    "Indonesia" = 9.9
+    "Ethiopia" = 8.7
+    "Honduras" = 6.3
+  }
+
+  colorize "Brazil" {
+    color = "#a4432d"
+  }
+
+  transform sort {
+    column = "value"
+    direction = descending
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/coffee-production.bpc`
+Five bars stay in muted neutrals; the `colorize "Brazil"` block lifts the one bar the title is about. `valueLabels = true` removes the need for a y-axis altogether — direct labels carry the precise numbers, and gridlines drop out entirely. Restraint, purposefulness, and "start with grey" applied in a single chart.
+:::
+
+## How Blueprint Chart applies these principles
+
+These principles drive the project's visual defaults: grey axis lines, minimal grid, flat geometry, direct labeling where possible, and brand tokens that nudge toward restraint. The renderer leans toward removal — every default exists because it earns its place.
+
+## See also
+
+- [Color & Palettes](/handbook/color)
+- [Anti-Patterns](/handbook/anti-patterns)
+- [Axes & Grid Lines](/handbook/axes)
+- [Frame Elements](/handbook/frame-elements)

package/src/handbook/frame-elements.md

@@ -0,0 +1,98 @@
+---
+title: Frame Elements
+---
+
+# Frame Elements
+
+> A well-structured chart frame has a clear information hierarchy: title, description, chart area, annotations, axis labels, note, source, and credit. Each element has a role and a style treatment that reflects its priority.
+
+## Frame hierarchy
+
+| Element | Priority | Style guidance | Content |
+|---------|----------|----------------|---------|
+| **Title** | 1st (most prominent) | Largest, boldest, highest contrast | Main takeaway — state the insight, not just the topic |
+| **Description** | 2nd | Medium size, regular weight | Context: what the reader sees, time period, units |
+| **Chart area** | 3rd | Maximum visual space | The data itself |
+| **Annotations** | 4th | Two hierarchy levels | Explanations, callouts, reference lines |
+| **Axis labels** | 5th | Medium, consistent | Units, categories, formatted values |
+| **Note** | 6th | Small, subdued | Methodology, caveats, definitions |
+| **Source** | Last | Smallest, grey, low contrast | Data attribution |
+| **Credit** | Last | Smallest, grey | Chart author / publication |
+
+## Title strategy
+
+- Write **declarative / takeaway titles** that state the insight: *"Housing prices doubled in five years"* not *"Housing prices 2019–2024"*
+- Imagine describing the chart to a friend — use that conversational phrasing
+- Question titles create uncertainty; save them for exploratory dashboards
+- Keep titles short and impactful
+
+::: info Example
+**Topic title (weak):** "Quarterly revenue by region"
+
+**Takeaway title (strong):** "APAC overtook EMEA for the first time in Q3"
+:::
+
+## Source and credit conventions
+
+- Sources appear as small, grey text at the bottom
+- Format: *"Source: [Organization/Dataset]"* and *"Chart: [Author/Publication]"*
+- Always present, never competing with the data for attention
+- Credit lines build institutional trust and enable verification
+
+## Note vs. description
+
+A **description** (or subtitle) sits near the top and tells the reader what they're looking at: units, period, scope. A **note** sits near the bottom and addresses caveats: methodology, excluded categories, data revisions. Keep them separate.
+
+## How Blueprint Chart applies the frame
+
+Blueprint Chart's `FrameOptions` matches this hierarchy almost one-to-one: title, description, note, source, and credit are all first-class frame fields. The frame layer is independent of the chart layer, so the same frame can wrap any chart type without changing the type's internals. See the [API reference](/reference/api/) for `createFrame` and the frame options.
+
+A minimal BPC source illustrates the structure:
+
+```bpc
+chart bar-vertical {
+  title       = "APAC overtook EMEA for the first time in Q3"
+  description = "Quarterly revenue, USD millions"
+  note        = "Q3 figures preliminary; EMEA excludes Russia"
+  source      = "Company filings"
+  credit      = "Chart: Blueprint Chart"
+
+  data {
+    "AMER" = 142
+    "APAC" = 118
+    "EMEA" = 115
+  }
+}
+```
+
+## Worked example: every frame slot, none wasted
+
+```bpc
+chart line {
+  title = "US inflation peaked at 9.1% before retreating to near 3%"
+  description = "Consumer Price Index, year-over-year change (%)"
+  source = "Bureau of Labor Statistics"
+  sourceUrl = "https://bls.gov/cpi/"
+  byline = "Pierre Romera"
+  note = "All items, seasonally adjusted, urban consumers"
+  colors = "#f28e2b"
+
+  data {
+    "Jan 2021" = 1.4
+    "Jun 2022" = 9.1
+    "Jan 2023" = 6.4
+    "Jan 2025" = 3.0
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/inflation-rate.bpc`
+A declarative title carries the insight (`"…peaked at 9.1% before retreating to near 3%"`), `description` fixes the unit and time period, `note` confines the methodology footnote to the bottom, `source` plus `sourceUrl` form the attribution pair, and `byline` is the credit slot. Each field maps one-to-one onto `FrameOptions`.
+:::
+
+## See also
+
+- [Typography](/handbook/typography)
+- [Annotations](/handbook/annotations)
+- [Design Principles](/handbook/design-principles)
+- [BPC DSL Specification](/reference/dsl/)

package/src/handbook/index.md

@@ -0,0 +1,91 @@
+---
+title: Dataviz Handbook
+---
+
+# Dataviz Handbook
+
+> An opinionated field guide for designing honest, clear, and accessible charts — the editorial principles behind Blueprint Chart, distilled into a working reference.
+
+This handbook is not API documentation. It is the editorial point of view that shapes every default in Blueprint Chart: what to draw, what to strip, what to highlight, and what to refuse.
+
+## What you'll find here
+
+The handbook reflects how we think charts should be built for journalism, research, and any context where the reader's understanding matters more than the author's flourish.
+
+- **Decision frameworks** for picking the right chart type before you sketch a single axis.
+- **Visual rules** for axes, grid lines, color, typography, labels, and annotations.
+- **A catalog of anti-patterns** — what to avoid and why.
+- **Accessibility guidance** that treats CVD support, contrast, and keyboard reach as baseline, not bonus.
+
+## The shape of a good chart
+
+Every page in this handbook orbits the same set of principles:
+
+- **Purposefulness** — every visual element earns its place.
+- **Data-ink ratio** — maximize pixels devoted to data; whisper everything else.
+- **Start with grey** — color becomes meaningful only when grey is the default.
+- **Comparisons make the story** — data in isolation has no meaning.
+- **No 3D, ever** — tilted surfaces lie.
+
+If you read only one page, read [Design Principles](/handbook/design-principles). Everything else is the application of those rules to a specific surface of the chart.
+
+## One chart that uses every principle
+
+```bpc
+chart line {
+  title = "2024 was the hottest year on record"
+  description = "Deviation from the 1951–1980 average, in °C"
+  source = "NASA GISS"
+  colors = "#e15759"
+  interpolation = "monotoneX"
+  showVerticalAxis = false
+  verticalGridStyle = "dashed"
+  horizontalGridStyle = "none"
+  lineSymbols = true
+  lineSymbolShowOn = "firstLast"
+
+  data {
+    "1980" = 0.26
+    "2000" = 0.42
+    "2015" = 0.9
+    "2024" = 1.29
+  }
+
+  annotation "2015" {
+    text = "2015 Paris Agreement to limit global warming to 1.5°C"
+    showLine = true
+    lineStyle = curve-right
+    showArrow = true
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/temperature-anomaly.bpc`
+A takeaway title states the insight; a single red hue carries meaning; gridlines whisper; an annotation points the reader at the moment that matters. Each principle on every page traces back to a chart like this one.
+:::
+
+## Where to start
+
+| If you want to... | Read |
+| --- | --- |
+| Decide which chart fits your data | [Choosing the Right Chart](/handbook/choosing) |
+| Internalize the foundations | [Design Principles](/handbook/design-principles) |
+| Avoid the most common mistakes | [Anti-Patterns](/handbook/anti-patterns) |
+| Structure the chart frame | [Frame Elements](/handbook/frame-elements) |
+| Type for legibility | [Typography](/handbook/typography) |
+| Pick safe, meaningful color | [Color & Palettes](/handbook/color) |
+| Tame axes and grids | [Axes & Grid Lines](/handbook/axes) |
+| Label directly | [Labels & Legends](/handbook/labels) |
+| Tell the story with annotations | [Annotations](/handbook/annotations) |
+| Design interaction honestly | [Tooltips & Interaction](/handbook/tooltips) |
+| Make charts accessible to everyone | [Accessibility](/handbook/accessibility) |
+
+## How this connects to Blueprint Chart
+
+Blueprint Chart is the tool we built to make these principles the path of least resistance: grey defaults, baseline-zero where it matters, CVD-aware palettes, direct labeling, and a frame model that mirrors the hierarchy described here. The handbook is editorial; the [Guide](/guide/getting-started), [DSL Spec](/reference/dsl/), and [API Reference](/reference/api/) are how you put it into practice.
+
+## See also
+
+- [Choosing the Right Chart](/handbook/choosing)
+- [Design Principles](/handbook/design-principles)
+- [Getting Started](/guide/getting-started)

package/src/handbook/labels.md

@@ -0,0 +1,117 @@
+---
+title: Labels & Legends
+---
+
+# Labels & Legends
+
+> Direct labeling beats legends wherever possible. When you must use a legend, place it where it helps. Use value labels when precision matters and the layout allows.
+
+## Direct labeling is preferred
+
+Place labels directly on or adjacent to data elements instead of using a separate legend. This eliminates the back-and-forth eye movement between legend and data.
+
+**Direct labeling works well for:**
+
+- **Line charts** — label at the end of each line
+- **Bar charts** — label at the end of each bar
+- **Pie / donut charts** — label each slice
+- **Area charts** — label within or adjacent to each area
+
+::: tip
+**Match label color to data color** for instant association.
+:::
+
+## When to use legends
+
+- Mobile or small screens where direct labels would overlap
+- Too many series to label directly without clutter
+- When the same visualization appears at multiple sizes
+
+**Legend placement:**
+
+- **Top of chart (horizontal legend)** — default for most charts
+- Adjacent to the relevant data (right side of line chart)
+- Never covering data
+- Never at the bottom where it's missed
+
+## Value labels
+
+- Show value labels when precision matters to the reader
+- On bar charts: inside the bar (if wide enough) or at the end
+- On line charts: at key data points only, not every point
+- On pie / donut charts: outside for small slices, inside for large ones
+- Position labels to avoid overlap; use tooltips as a fallback for dense data
+- Use "auto" positioning that chooses inside vs. outside based on available space
+
+::: warning
+Labeling every point on a dense line chart creates visual noise. Label extremes (peaks, troughs, end values) and let the reader rely on the axis or tooltip for the rest.
+:::
+
+## Label legibility checklist
+
+- Does the label color contrast enough with its background?
+- Is there a text outline (stroke) when the label overlays data or grid lines?
+- Can the label be read without rotation? (Never rotate.)
+- Does the label use the chart's number formatter so units match the axis?
+
+## How Blueprint Chart applies labels
+
+Blueprint Chart exposes a legend renderer with placement, orientation, and wrapping options. Direct labels are available for line, bar, and pie-family charts; the renderer falls back to legends on narrow layouts automatically. See the [API reference](/reference/api/) for `renderLegend` and the per-chart label options.
+
+## Worked example: value labels replace the axis
+
+```bpc
+chart bar-vertical {
+  title = "E is the most frequent letter in English"
+  description = "How often each letter appears in typical English text"
+  sort = descending
+  valueLabels = true
+  verticalLabelPosition = off
+  verticalGridStyle = none
+
+  data {
+    "E" = 12.70
+    "T" = 9.06
+    "A" = 8.17
+    "O" = 7.51
+    "I" = 6.97
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/letter-frequency.bpc`
+`valueLabels = true` puts the precise number at the end of every bar, so the y-axis label position can be set to `off` and the gridlines removed entirely. Direct labelling replaces both the legend and the axis labels — a clean application of the data-ink rule.
+:::
+
+## Worked example: legend at the top, direct value labels at the bar end
+
+```bpc
+chart bar-multi {
+  title = "USA tops Paris 2024 with 126 medals across all categories"
+  description = "2024 Paris Summer Games — top six nations"
+  colors = "#eeca3b, #c0c0c0, #cd7f32"
+  legendPosition = "top"
+  valueLabels = true
+  verticalGridStyle = none
+  verticalLabelPosition = off
+  sort = descending
+
+  data {
+    _series = "Gold","Silver","Bronze"
+    "USA" = 40,44,42
+    "China" = 38,32,18
+    "Japan" = 27,14,17
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/medal-count.bpc`
+A multi-series bar chart needs a legend to map the three hues to Gold / Silver / Bronze — placed at the top so the eye reaches it before scanning the bars. Inside each bar, `valueLabels = true` prints the exact count, eliminating the need to read against a vertical scale.
+:::
+
+## See also
+
+- [Typography](/handbook/typography)
+- [Annotations](/handbook/annotations)
+- [Tooltips & Interaction](/handbook/tooltips)
+- [Accessibility](/handbook/accessibility)