Documentation For Components

Why this matters

As a Data Visualization Engineer, you ship charts, legends, tooltips, axes, and data-driven UI components that many teams rely on. Clear documentation is the difference between a reusable component and a one-off widget. Good docs reduce support tickets, speed adoption, and prevent inconsistent visualizations across dashboards and reports.

• Real tasks you will face:
  • Explain when to use a LineChart vs. AreaChart.
  • Document props like colorScale, xAccessor, and onBrush with examples and defaults.
  • Provide accessibility guidance for keyboard navigation and screen readers.
  • Show performance limits (e.g., max 50k points; recommend downsampling).
  • Record breaking changes and migration steps in a changelog.

Concept explained simply

Component documentation is a single, reliable page that answers: what the component is for, how to use it safely, how to configure it, and how to avoid mistakes. Think of it as a user manual plus guardrails.

Mental model

Use the 6-box model. Each doc page should include:

• Purpose: when to use, when not to.
• Anatomy: labeled diagram of parts (axis, grid, legend, tooltip).
• API: props/events/slots with types, defaults, ranges.
• Usage: examples, do/don't, patterns, performance notes.
• Accessibility: keyboard, ARIA, color contrast, data table alt view.
• Status & Versioning: stability, compatibility, changelog, migration.

Title: ComponentName

1) Purpose
- What problem it solves
- When to use / not use

2) Anatomy
- Labeled parts

3) API
- Props: name, type, default, required, description
- Events: name, payload shape, when fires
- Slots/Children: expected structure

4) Usage & Patterns
- Minimal example
- Variants (e.g., stacked, grouped)
- Performance limits & tips
- Theming/tokens used

5) Accessibility
- Keyboard interactions
- ARIA roles/labels
- Contrast & color-blind safe options
- Data table alternative

6) Status & Versioning
- Stability badge (alpha/beta/stable)
- Changelog excerpt
- Migration notes

7) Known issues
- Current constraints
    

Worked examples

Example 1 — BarChart page outline

• Purpose: Compare discrete categories. Avoid for continuous time series (prefer LineChart).
• Anatomy: Bars, X axis (categories), Y axis (values), gridlines (optional), tooltip, legend.
• API (excerpt):
  • data: Array<{category: string; value: number}> — required.
  • xAccessor: (d) => string — default: d => d.category.
  • yAccessor: (d) => number — default: d => d.value.
  • colorScale: categorical palette token — default: viz.categorical.10.
  • orientation: 'vertical'|'horizontal' — default: 'vertical'.
  • onBarClick: (event, datum) => void — optional.
• Usage: Use horizontal when category labels are long. Add data labels only if bars are tall enough.
• Accessibility: Bars focusable; arrow keys move focus; Enter triggers onBarClick. Provide aria-description summarizing insights.
• Performance: Recommended ≤ 200 categories; consider filtering or grouping beyond this.
• Status: Stable. Changelog: 2.1 added orientation.

Example 2 — Tooltip guidelines

• Purpose: Show contextual values on hover or focus.
• API (excerpt): position: 'auto'|'top'|'right'|'bottom'|'left' (default: 'auto'); formatValue: (n) => string; delayMs (default: 0).
• Usage: Keep under 2 lines; include units and formatted numbers; avoid duplicating legend labels.
• Accessibility: Tooltip content must be reachable via keyboard focus. Use role="tooltip" and describe it from the focused element.
• Performance: Memoize tooltip content rendering for large charts.

Example 3 — ColorScale tokens

• Tokens: viz.categorical.10, viz.sequential.blue, viz.diverging.redBlue.
• Guidelines: Use sequential for ordered magnitudes; diverging when there is a meaningful midpoint (e.g., zero).
• Accessibility: Ensure contrast ratio ≥ 3:1 against background for line/marker elements. Provide a non-color encoding (shapes, dashes) when lines overlap.
• API: colorScale can accept token id or custom function(d, i) => string.

How to write a doc page (step-by-step)

1. Collect real usage: scan 3–5 dashboards to see how the component is used and misused.
2. Define Purpose and Anti-patterns: write 3 bullets each.
3. List public API: props, events, slots. Add types, defaults, and constraints.
4. Add a minimal code example and one variant.
5. Write Accessibility: keyboard map, ARIA roles, color guidance, data table alternative.
6. Document performance: data size limits, rendering mode (canvas/SVG), sampling advice.
7. Include Theming/Tokens: which tokens affect it and safe ranges.
8. Publish Status and Changelog entry. Note migration if anything changed.

Who this is for

• Data Visualization Engineers documenting reusable chart components.
• Analytics engineers owning BI component libraries.
• Design system contributors writing or reviewing visualization guidelines.

Prerequisites

• Basic charting concepts (bar, line, area, scatter, legend, axis).
• Comfort with component APIs (props, events, slots) in your stack.
• Familiarity with your design tokens (color, spacing, typography).

Learning path

1. Review your visualization tokens and naming (categorical, sequential, diverging).
2. Document a primitive: Tooltip or Legend page using the template.
3. Document a chart: LineChart with variants (markers on/off, smoothing).
4. Add cross-cutting sections: Accessibility and Performance playbooks.
5. Set up version notes and a minimal changelog format.
6. Run a peer review with one designer and one engineer; refine.

Common mistakes and self-check

• Missing defaults in API. Self-check: Can a user copy-paste an example and run it without guessing values?
• Only screenshots, no code. Self-check: Is there at least one runnable minimal example?
• Ignoring accessibility. Self-check: Can you tab to all interactive elements and get a description?
• Vague do/don't. Self-check: Are your rules testable (e.g., "≤ 7 categories")?
• No performance guardrails. Self-check: Did you state data size limits and fallback strategies?

Templates and checklists

Practical projects

• Create a full doc page for LineChart, including a minimal example and an accessibility section.
• Write a performance note for ScatterPlot with 100k points, including downsampling advice.
• Draft a tokens guide explaining when to use categorical vs. sequential scales.

Exercises

Do these now. The quick test below checks the same skills. Note: The quick test is available to everyone; only logged-in users get saved progress.

1. Exercise 1 — LineChart API spec
   • Write API entries for: data, xAccessor, yAccessor, colorScale, showMarkers, onPointFocus.
   • Include type, default, required, and a one-line description with constraints.
2. Exercise 2 — Legend accessibility rules
   • Draft 4 do/don't bullets to ensure legends are readable and navigable.
   • Add one testable metric (e.g., minimum tap target size).

Mini challenge

Pick one interactive component you own (e.g., BrushSelector). In 30 minutes, write Purpose, minimal example, and Accessibility. Keep it to 12–15 lines. Share with a teammate for feedback.

Next steps

• Publish one completed doc page and ask two consumers to try it without your help. Collect what confused them and improve.
• Add changelog and version badges to all existing component docs.
• Plan quarterly doc audits: check accuracy, examples, and accessibility.