@blueprint-chart/docs 0.1.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pirhoo and Blueprint Chart contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @blueprint-chart/docs
+
+Public documentation for [Blueprint Chart](https://blueprintchart.com) — handbook, guide, BPC DSL spec, and lib API reference.
+
+This package serves two consumers:
+
+1. **The VitePress site** at [`docs.blueprintchart.com`](https://docs.blueprintchart.com) — `pnpm dev` / `pnpm build`.
+2. **Programmatic access** for tooling such as `@blueprint-chart/mcp`:
+
+```ts
+import { listDocs, getDoc } from '@blueprint-chart/docs'
+
+const handbookPages = listDocs('handbook')
+const { entry, content } = getDoc('handbook', 'design-principles')
+```
+
+Each `dist/manifest.json` entry has `{ slug, group, title, blurb, mdPath }`. Markdown content lives under `src/` and is shipped in the published package.
+
+## Groups
+
+- `handbook` — dataviz pedagogy (design principles, color, typography, ...)
+- `guide` — usage guides (scenes, palettes, data transforms, ...)
+- `charts` — per-chart-type docs (bar, line, area, ...)
+- `reference/dsl` — BPC DSL specification
+- `reference/api` — `@blueprint-chart/lib` API reference
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,13 @@
+export type DocGroup = 'handbook' | 'guide' | 'charts' | 'reference/dsl' | 'reference/api';
+export interface DocEntry {
+    slug: string;
+    group: DocGroup;
+    title: string;
+    blurb: string;
+    mdPath: string;
+}
+export declare function listDocs(group?: DocGroup): DocEntry[];
+export declare function getDoc(group: DocGroup, slug: string): {
+    entry: DocEntry;
+    content: string;
+};

package/dist/api.js

@@ -0,0 +1,29 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+let cached;
+function loadManifest() {
+    if (cached) {
+        return cached;
+    }
+    const manifestPath = join(PKG_ROOT, 'dist', 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`@blueprint-chart/docs: manifest.json not found at ${manifestPath}. `
+            + `Did you run \`pnpm --filter @blueprint-chart/docs build\`?`);
+    }
+    cached = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    return cached;
+}
+export function listDocs(group) {
+    const all = loadManifest().entries;
+    return group ? all.filter(e => e.group === group) : all;
+}
+export function getDoc(group, slug) {
+    const entry = loadManifest().entries.find(e => e.group === group && e.slug === slug);
+    if (!entry) {
+        throw new Error(`@blueprint-chart/docs: no doc at ${group}/${slug}`);
+    }
+    const content = readFileSync(join(PKG_ROOT, 'src', entry.mdPath), 'utf8');
+    return { entry, content };
+}

package/dist/manifest.json

@@ -0,0 +1,242 @@
+{
+  "entries": [
+    {
+      "slug": "accessibility",
+      "group": "handbook",
+      "title": "Accessibility",
+      "blurb": "> 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",
+      "mdPath": "handbook/accessibility.md"
+    },
+    {
+      "slug": "annotations",
+      "group": "handbook",
+      "title": "Annotations",
+      "blurb": "> 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 s",
+      "mdPath": "handbook/annotations.md"
+    },
+    {
+      "slug": "anti-patterns",
+      "group": "handbook",
+      "title": "Anti-Patterns",
+      "blurb": "> 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.",
+      "mdPath": "handbook/anti-patterns.md"
+    },
+    {
+      "slug": "axes",
+      "group": "handbook",
+      "title": "Axes & Grid Lines",
+      "blurb": "> 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.",
+      "mdPath": "handbook/axes.md"
+    },
+    {
+      "slug": "choosing",
+      "group": "handbook",
+      "title": "Choosing the Right Chart",
+      "blurb": "> 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 ",
+      "mdPath": "handbook/choosing.md"
+    },
+    {
+      "slug": "color",
+      "group": "handbook",
+      "title": "Color & Palettes",
+      "blurb": "> 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.",
+      "mdPath": "handbook/color.md"
+    },
+    {
+      "slug": "design-principles",
+      "group": "handbook",
+      "title": "Design Principles",
+      "blurb": "> 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.",
+      "mdPath": "handbook/design-principles.md"
+    },
+    {
+      "slug": "frame-elements",
+      "group": "handbook",
+      "title": "Frame Elements",
+      "blurb": "> 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 tha",
+      "mdPath": "handbook/frame-elements.md"
+    },
+    {
+      "slug": "labels",
+      "group": "handbook",
+      "title": "Labels & Legends",
+      "blurb": "> 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.",
+      "mdPath": "handbook/labels.md"
+    },
+    {
+      "slug": "tooltips",
+      "group": "handbook",
+      "title": "Tooltips & Interaction",
+      "blurb": "> Tooltips progressively disclose detail, they never replace critical information. Interaction must be consistent, accessible, and keyboard-reachable. Crosshairs and hover states support — not replace",
+      "mdPath": "handbook/tooltips.md"
+    },
+    {
+      "slug": "typography",
+      "group": "handbook",
+      "title": "Typography",
+      "blurb": "> Type in charts must be small, sharp, and legible at a glance. Use sans-serifs with unambiguous character shapes, size ruthlessly, never rotate, prefer sentence case, and left-align.",
+      "mdPath": "handbook/typography.md"
+    },
+    {
+      "slug": "accessibility",
+      "group": "guide",
+      "title": "Accessibility",
+      "blurb": "> WCAG contrast checks, colour-vision-deficiency simulation, and palette-safety audits — built into the library.",
+      "mdPath": "guide/accessibility.md"
+    },
+    {
+      "slug": "data-transforms",
+      "group": "guide",
+      "title": "Data Transforms",
+      "blurb": "> A composable pipeline that shapes raw tabular data into the rows the chart actually renders.",
+      "mdPath": "guide/data-transforms.md"
+    },
+    {
+      "slug": "dsl-editor",
+      "group": "guide",
+      "title": "DSL Editor",
+      "blurb": "> The BPC source editor — CodeMirror 6, a Lezer-generated grammar, syntax highlighting tuned for prose-shaped charts, and two-way sync with the visual panels.",
+      "mdPath": "guide/dsl-editor.md"
+    },
+    {
+      "slug": "embed",
+      "group": "guide",
+      "title": "embed",
+      "blurb": "Blueprint Chart is **static-first**: every chart is a self-contained artifact independent of any vendor server. There are three ways to put one on a page, and they all run entirely in the browser.",
+      "mdPath": "guide/embed.md"
+    },
+    {
+      "slug": "getting-started",
+      "group": "guide",
+      "title": "getting started",
+      "blurb": "Blueprint Chart is published as three packages on NPM. Pick the one that matches what you're building.",
+      "mdPath": "guide/getting-started.md"
+    },
+    {
+      "slug": "palettes",
+      "group": "guide",
+      "title": "Palettes",
+      "blurb": "> 50+ curated categorical palettes, plus the helpers to resolve, audit, and adjust them for the background you render against.",
+      "mdPath": "guide/palettes.md"
+    },
+    {
+      "slug": "scenes",
+      "group": "guide",
+      "title": "Scenes",
+      "blurb": "> Same chart, different states — composed into a story that a reader can step through.",
+      "mdPath": "guide/scenes.md"
+    },
+    {
+      "slug": "area-stacked",
+      "group": "charts",
+      "title": "Stacked area chart",
+      "blurb": "> Multi-series stacked area chart for composition over time; supports percent stacking.",
+      "mdPath": "charts/area-stacked.md"
+    },
+    {
+      "slug": "area",
+      "group": "charts",
+      "title": "Area chart",
+      "blurb": "> Single-series area chart for magnitude over time; pairs with `areaFill`.",
+      "mdPath": "charts/area.md"
+    },
+    {
+      "slug": "bar-grouped",
+      "group": "charts",
+      "title": "Grouped bar chart",
+      "blurb": "> Multi-series grouped vertical bar chart for grouped categorical comparison across a second dimension.",
+      "mdPath": "charts/bar-grouped.md"
+    },
+    {
+      "slug": "bar-horizontal",
+      "group": "charts",
+      "title": "Horizontal bar chart",
+      "blurb": "> Single-series horizontal bar chart for long category labels and ranked bars.",
+      "mdPath": "charts/bar-horizontal.md"
+    },
+    {
+      "slug": "bar-multi",
+      "group": "charts",
+      "title": "Multi-series bar chart",
+      "blurb": "> Multi-series vertical bar chart for side-by-side comparison of a small group of series.",
+      "mdPath": "charts/bar-multi.md"
+    },
+    {
+      "slug": "bar-split",
+      "group": "charts",
+      "title": "Split bar chart",
+      "blurb": "> Diverging vertical bar chart for values around a shared baseline (positive/negative).",
+      "mdPath": "charts/bar-split.md"
+    },
+    {
+      "slug": "bar-stacked",
+      "group": "charts",
+      "title": "Stacked bar chart",
+      "blurb": "> Stacked horizontal bar chart for composition within a category, emphasising the total.",
+      "mdPath": "charts/bar-stacked.md"
+    },
+    {
+      "slug": "bar-vertical",
+      "group": "charts",
+      "title": "Vertical bar chart",
+      "blurb": "> Single-series vertical bar chart for ranked categorical comparison, small N.",
+      "mdPath": "charts/bar-vertical.md"
+    },
+    {
+      "slug": "column-stacked",
+      "group": "charts",
+      "title": "Stacked column chart",
+      "blurb": "> Stacked vertical column chart for composition over discrete columns; supports percent stacking.",
+      "mdPath": "charts/column-stacked.md"
+    },
+    {
+      "slug": "donut",
+      "group": "charts",
+      "title": "Donut chart",
+      "blurb": "> Circular part-to-whole chart with a central label slot.",
+      "mdPath": "charts/donut.md"
+    },
+    {
+      "slug": "line-multi",
+      "group": "charts",
+      "title": "Multi-line chart",
+      "blurb": "> Multi-series line chart for comparing several time series or trends.",
+      "mdPath": "charts/line-multi.md"
+    },
+    {
+      "slug": "line",
+      "group": "charts",
+      "title": "Line chart",
+      "blurb": "> Single-series line chart for continuous trend over an ordered domain.",
+      "mdPath": "charts/line.md"
+    },
+    {
+      "slug": "pie",
+      "group": "charts",
+      "title": "Pie chart",
+      "blurb": "> Circular part-to-whole chart for very small N.",
+      "mdPath": "charts/pie.md"
+    },
+    {
+      "slug": "annotations",
+      "group": "reference/dsl",
+      "title": "annotations",
+      "blurb": "Two families of named blocks that target specific data values to draw the eye: **color directives** (`colorize`, `highlight`, `areafill`) recolor or emphasize parts of the chart, and **annotations** (",
+      "mdPath": "reference/dsl/annotations.md"
+    },
+    {
+      "slug": "properties",
+      "group": "reference/dsl",
+      "title": "properties",
+      "blurb": "Value-bearing constructs in a `.bpc` document: key/value properties on the chart, the `data` block carrying values, and `series` overrides for per-series visual control. See [DSL overview](/reference/",
+      "mdPath": "reference/dsl/properties.md"
+    },
+    {
+      "slug": "scenes-and-transforms",
+      "group": "reference/dsl",
+      "title": "scenes and transforms",
+      "blurb": "Story-level constructs: **scenes** compose multiple visualisation states into a stepable narrative, and **transforms** describe data-pipeline operations applied before rendering. Scenes can override a",
+      "mdPath": "reference/dsl/scenes-and-transforms.md"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@blueprint-chart/docs",
+  "version": "0.1.18",
+  "description": "Public documentation for Blueprint Chart — handbook, guide, BPC DSL spec, and lib API reference.",
+  "type": "module",
+  "license": "MIT",
+  "author": "pirhoo",
+  "homepage": "https://docs.blueprintchart.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blueprint-chart/blueprint-chart.git",
+    "directory": "packages/docs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js",
+      "default": "./dist/api.js"
+    },
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "files": [
+    "dist",
+    "src/handbook",
+    "src/guide",
+    "src/charts",
+    "src/reference",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "dev": "vitepress dev src --host 0.0.0.0 --port 4445",
+    "build:vitepress": "vitepress build src",
+    "build:manifest": "tsx scripts/build-manifest.ts",
+    "build:api": "tsc --project tsconfig.api.json",
+    "build": "pnpm run build:vitepress && pnpm run build:manifest && pnpm run build:api",
+    "preview": "vitepress preview src --host 0.0.0.0 --port 4445",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@blueprint-chart/lib": "workspace:*",
+    "@blueprint-chart/ui": "workspace:*",
+    "@types/node": "^22.10.0",
+    "@fontsource-variable/geist": "^5.2.8",
+    "@fontsource-variable/geist-mono": "^5.2.7",
+    "@fontsource/dm-serif-display": "^5.2.8",
+    "@iconify-json/ph": "^1.2.2",
+    "@vue/test-utils": "^2.4.6",
+    "@vueuse/core": "^14.2.1",
+    "gray-matter": "^4.0.3",
+    "jsdom": "^26.1.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7",
+    "unplugin-icons": "^23.0.1",
+    "vitepress": "^1.5.0",
+    "vitest": "^3.2.4",
+    "vue": "^3.5"
+  }
+}

package/src/charts/area-stacked.md

@@ -0,0 +1,64 @@
+---
+title: Stacked area chart
+---
+
+# Stacked area chart
+
+> Multi-series stacked area chart for composition over time; supports percent stacking.
+
+`area-stacked` layers multiple series on top of each other so readers can see both the individual trends and the cumulative total. Set `stackPercent = true` to switch to a 100 % normalised view. Supports `interpolation`, `lineSymbols`, `crosshair`, and `tooltips`.
+
+## When to use
+
+- Showing how composition changes over time
+- When the overall total matters as much as the individual parts
+- Datasets with at least ~10 time points (use [`column-stacked`](./column-stacked) for fewer)
+- 100 % stacked view (`stackPercent = true`) when relative share is the story
+
+## When NOT to use
+
+- Data with negative values (stacking breaks down)
+- Precise comparison of individual series — stacking obscures the readings above the baseline
+- More than ~5 series — the layers become unreadable
+
+## Example
+
+```bpc
+chart area-stacked {
+  title = "Renewables rose from 18 % to 23 % of global energy since 2000"
+  description = "Share of primary energy by source, 2000–2023"
+  source = "Our World in Data"
+  sourceUrl = "https://ourworldindata.org/energy-mix"
+  stackPercent = true
+  areaSortMode = descending
+  areaFillOpacity = 0.85
+
+  data {
+    _series = "Coal","Oil","Gas","Renewables"
+    "2000" = 25,36,21,18
+    "2005" = 27,35,22,16
+    "2010" = 29,33,23,15
+    "2015" = 28,32,24,16
+    "2020" = 26,30,25,19
+    "2023" = 24,29,24,23
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Series above the baseline are hard to compare — put the most important one at the bottom
+- Too many small categories disappear in the stack; consolidate into "Other"
+- 100 % stacking hides absolute change; pair it with a separate total chart if the magnitude matters
+
+## Related types
+
+- [`area`](./area) — single-series area
+- [`line-multi`](./line-multi) — when individual trends matter more than the total
+- [`column-stacked`](./column-stacked) — same idea, but for a small number of discrete columns
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/area.md

@@ -0,0 +1,65 @@
+---
+title: Area chart
+---
+
+# Area chart
+
+> Single-series area chart for magnitude over time; pairs with `areaFill`.
+
+`area` is a line chart with the region below the line filled in, emphasising the magnitude of a single series rather than just its direction. Honours `areaFill`, `areaFillOpacity`, and custom `areaFills: AreaFillConfig[]`. Supports `interpolation`, `lineSymbols`, `crosshair`, and `tooltips`.
+
+## When to use
+
+- When the cumulative total or visual volume matters, not just the trend
+- A single series where the filled region adds emotional weight to the story
+- Editorial contexts where the chart needs to read at a glance
+
+## When NOT to use
+
+- Overlapping multiple un-stacked series — filled regions obscure each other
+- When readers need precise value reading (the fill blurs the line)
+- When you have multiple series — use [`area-stacked`](./area-stacked) instead
+
+## Example
+
+```bpc
+chart area {
+  title = "Apple stock climbed 36 % through 2024"
+  description = "Monthly closing price in USD"
+  source = "Yahoo Finance"
+  sourceUrl = "https://finance.yahoo.com"
+
+  data {
+    "Jan" = 183
+    "Feb" = 182
+    "Mar" = 171
+    "Apr" = 170
+    "May" = 192
+    "Jun" = 210
+    "Jul" = 222
+    "Aug" = 229
+    "Sep" = 233
+    "Oct" = 225
+    "Nov" = 237
+    "Dec" = 249
+  }
+}
+```
+
+
+## Common pitfalls
+
+- The y-axis must start at zero — the filled area encodes magnitude
+- A fully opaque fill hides the line itself; keep `areaFillOpacity` around 0.2–0.3
+- Don't stack two area charts by overlapping them; reach for [`area-stacked`](./area-stacked)
+
+## Related types
+
+- [`line`](./line) — when the trend matters and the magnitude doesn't
+- [`area-stacked`](./area-stacked) — when you have multiple series to compose
+- [`bar-vertical`](./bar-vertical) — when the x-axis is categorical
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/bar-grouped.md

@@ -0,0 +1,60 @@
+---
+title: Grouped bar chart
+---
+
+# Grouped bar chart
+
+> Multi-series grouped vertical bar chart for grouped categorical comparison across a second dimension.
+
+`bar-grouped` clusters bars from several series under each category, exposing a second dimension of comparison. Honours `sort`, `sortMode`, `valueLabels`, and `valueLabelPosition`.
+
+## When to use
+
+- Comparing 2–3 series across categories where the second dimension matters (revenue by product by quarter, capacity by source by region)
+- When individual series values matter more than their sum
+- A small, fixed list of groups — the structure stays legible
+
+## When NOT to use
+
+- More than 3–4 series per group — the clusters become unreadable
+- When the cumulative total per group is the story (use [`bar-stacked`](./bar-stacked))
+- When series share the same units and you want a direct comparison without a grouping dimension (use [`bar-multi`](./bar-multi))
+
+## Example
+
+```bpc
+chart bar-grouped {
+  title = "Asia Pacific holds more renewable capacity than all other regions combined"
+  description = "Installed capacity in gigawatts (GW)"
+  source = "IRENA"
+  sourceUrl = "https://www.irena.org"
+  valueLabels = true
+
+  data {
+    _series = "Solar","Wind","Hydro"
+    "Asia Pacific"  = 680,540,840
+    "Europe"        = 250,300,200
+    "North America" = 200,180,190
+    "Latin America" = 30,50,200
+    "Africa"        = 15,10,40
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Too many bars per group overwhelms the reader — keep series to three or fewer
+- Inconsistent colour encoding across groups or across charts in a dashboard
+- Sorting by the wrong dimension when both groups and series carry meaning
+
+## Related types
+
+- [`bar-multi`](./bar-multi) — side-by-side series without a grouping dimension
+- [`bar-stacked`](./bar-stacked) — when the total per group matters
+- [`column-stacked`](./column-stacked) — vertical composition over discrete columns
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/bar-horizontal.md

@@ -0,0 +1,71 @@
+---
+title: Horizontal bar chart
+---
+
+# Horizontal bar chart
+
+> Single-series horizontal bar chart for long category labels and ranked bars.
+
+`bar-horizontal` is the same encoding as a vertical bar chart turned on its side — categories run down the left, bars extend to the right. It honours `sort`, `sortMode`, `valueLabels`, and `valueLabelPosition`. The alias `horizontal-bar` is registered against the same renderer.
+
+## When to use
+
+- Category labels are long (country names, survey responses, product names)
+- Ranking displays — high-to-low from top to bottom reads intuitively
+- Mobile-friendly layouts — horizontal bars grow vertically, adapting to narrow screens
+
+## When NOT to use
+
+- Time-based data (the horizontal axis conventionally represents time — use [`line`](./line))
+- A handful of categories with short labels — [`bar-vertical`](./bar-vertical) is more compact
+
+## Example
+
+```bpc
+chart bar-horizontal {
+  title = "Japan leads in life expectancy while the US lags behind"
+  description = "Selected countries, years (2023)"
+  source = "World Bank"
+  sourceUrl = "https://data.worldbank.org"
+  note = "Figures are estimates and may differ from national statistics"
+  sort = descending
+  colors = "#59a14f"
+  horizontalLabelPosition = off
+  horizontalGridStyle = none
+
+  colorize "United States" {
+    color = "#e15759"
+  }
+
+  data {
+    "Japan" = 84.8
+    "Switzerland" = 83.8
+    "Australia" = 83.5
+    "Sweden" = 83.1
+    "Canada" = 82.7
+    "France" = 82.5
+    "Germany" = 81.4
+    "United Kingdom" = 81.2
+    "United States" = 78.5
+    "China" = 78.2
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Forgetting to sort — an unranked horizontal bar chart loses most of its power
+- Mixing the horizontal axis with time, which reads as a flipped line chart
+- Long labels still cause issues at very narrow widths; truncate or shorten before publishing
+
+## Related types
+
+- [`bar-vertical`](./bar-vertical) — when labels are short and you have room horizontally
+- [`bar-stacked`](./bar-stacked) — when each bar should break down into segments
+- [`bar-split`](./bar-split) — when values can be positive or negative
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)