Visual Writing
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill writing-expert/references/visual-writing.md
↓ Facts as markdownall context files
Reference for the words that ship with images, charts, and infographics: alt text, captions, chart titles, axis labels, and annotations. The image is half the message. This skill is the other half.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Visual Writing
- Reference for the words that ship with images, charts, and infographics: alt text, captions, chart titles, axis labels, and annotations. The image is half the message. This skill is the other half. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#visual-writing]
The one rule: visual writing makes images legible without the image
- Every other rule in this skill follows from one premise: a reader who cannot see the image must still receive the load-bearing information. That reader may be a blind user with a screen reader, a sighted user on a slow network, a sighted user skimming for the chart's takeaway, or a search engine indexing the page. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#the-one-rule-visual-writing-makes-images-legible-without-the-image]
- The alt text serves the screen reader. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#the-one-rule-visual-writing-makes-images-legible-without-the-image]
- The caption serves the skimmer. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#the-one-rule-visual-writing-makes-images-legible-without-the-image]
- The chart title serves the takeaway. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#the-one-rule-visual-writing-makes-images-legible-without-the-image]
- The annotation serves the trend. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#the-one-rule-visual-writing-makes-images-legible-without-the-image]
- They are four jobs, not one. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#the-one-rule-visual-writing-makes-images-legible-without-the-image]
Core concept 1 — The alt-text triple
- Alt text answers three questions: [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-1-the-alt-text-triple]
- What's there? - concrete, observable content [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-1-the-alt-text-triple]
- Why is it there? - the function the image serves in the page [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-1-the-alt-text-triple]
- What does it show? - the specific information a sighted reader gets [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-1-the-alt-text-triple]
Core concept 3 — Caption vs alt text vs long description
- Alt text is for users who cannot see the image. It lives in alt="". Typically 5 to 15 words. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-3-caption-vs-alt-text-vs-long-description]
- Caption is visible to everyone. It lives in <figcaption>. Adds context, attribution. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-3-caption-vs-alt-text-vs-long-description]
- Long description is a structured prose alternative for complex images. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-3-caption-vs-alt-text-vs-long-description]
Core concept 4 — Tufte's principles
- Above all else, show the data. Title and labels exist to disclose the data. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-4-tuftes-principles]
- Maximize the data-ink ratio. Erase ink that doesn't carry data. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-4-tuftes-principles]
- Erase redundant data-ink. A bar chart with a legend, title, axis labels, and a redundant data table embeds the same fact four times. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-4-tuftes-principles]
- Reject chartjunk. Heavy gridlines, moiré fills, 3-D effects, drop shadows. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-4-tuftes-principles]
- Use sparklines for in-line trend. Caption a sparkline like a word - usually with just the latest value. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-4-tuftes-principles]
Core concept 5 — The Knaflic "action title" rule
- The chart title states the takeaway. The axis labels confirm it. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-5-the-knaflic-action-title-rule]
- Generic title (descriptive only): > Quarterly Revenue, 2023–2024 [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-5-the-knaflic-action-title-rule]
- Action title (takeaway-bearing): > Q4 2024 revenue exceeded plan by 18% - the strongest quarter on record [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-5-the-knaflic-action-title-rule]
- Rule of thumb: no chart without a takeaway. If you cannot state in one sentence what the chart is for, either find the takeaway or delete the chart. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-5-the-knaflic-action-title-rule]
Core concept 6 — Axis labels
- Label the units. "Revenue (USD millions)" not "Revenue." [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-6-axis-labels]
- Date axes get human dates. "Jan 2024" - not raw timestamps, not "Q1". [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-6-axis-labels]
- Avoid axis label rotation. If labels overflow horizontally, the chart probably has too many categories. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-6-axis-labels]
Core concept 7 — Annotations
- An annotation is a written assertion attached to a specific data point. Use annotations for: [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-7-annotations]
- The single highest or lowest point ("peak: 8,420 - Aug 14") [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-7-annotations]
- A regime change ("← deploy of v2.3") [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-7-annotations]
- An anomaly ("backfill artifact; ignore") [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-7-annotations]
- Annotations are journalism inside a chart. Empty annotations ("note this") are wasted ink. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-7-annotations]
Core concept 8 — Accessible data-viz captioning
- The "describe the trend, then the value" pattern: [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-8-accessible-data-viz-captioning]
- > Sales increased steadily from January to July, then declined through December. The peak was 8,420 units in July. The lowest month was December at 3,100 units. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-8-accessible-data-viz-captioning]
- Anti-pattern: read every value. > January was 4,200, February was 4,800, March was 5,100... [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-8-accessible-data-viz-captioning]
- If every value matters, provide a <table> and skip the chart alt-text recital. [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#core-concept-8-accessible-data-viz-captioning]
References
- W3C WAI: Images Tutorial and Alt Decision Tree [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#references]
- Edward Tufte, The Visual Display of Quantitative Information (2nd ed., 2001) [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#references]
- Cole Nussbaumer Knaflic, Storytelling with Data (2015) [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#references]
- UK GDS: Text descriptions for data visualisations [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#references]
- WCAG 2.1, Success Criterion 1.1.1 (Non-text Content) [archived source: https://llms-explorer.com/sources/mdb-context-hub/visual-writing/#references]
Where this helps
- Writing alt text, captions, and chart titles for a report or dashboard that will be read by both sighted skimmers and screen-reader users. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding what information a chart's title, axis labels, and annotations should each carry so the reader gets the takeaway without needing to study the image. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Auditing an existing data visualization for chartjunk or redundant data-ink before publishing it in a customer-facing or executive document. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing accessible descriptions for complex charts with trends or multiple series, where reading every raw value aloud would overwhelm a screen-reader user. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Apply the alt-text triple (what's there, why it's there, what it shows) when writing alt text for any image that carries information, not just decoration. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Rewrite a descriptive chart title ("Quarterly Revenue, 2023–2024") into an action title that states the takeaway ("Q4 2024 revenue exceeded plan by 18%"). [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Use the "describe the trend, then the value" pattern for accessible data-viz captions instead of reciting every data point. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Apply Tufte's data-ink principles when reviewing a chart: maximize the data-ink ratio, erase redundant ink, and reject chartjunk like heavy gridlines or 3-D effects. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Duplicating the same information in both alt text and caption, forcing a screen-reader user to hear the same sentence twice. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Reading every value aloud in a chart's accessible description instead of describing the trend and the standout value, when a full data table would serve better. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Publishing a chart with no stated takeaway — if you can't state in one sentence what the chart is for, the fix is to find the takeaway or delete the chart. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing an empty or vague annotation ("note this") on a data point instead of a specific, journalistic assertion about what happened there. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- The right visual-writing choice depends on which of four distinct readers you're serving (blind screen-reader user, slow-network sighted user, skimmer, search engine) — optimizing for one can shortchange another. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Long descriptions for complex images are structured prose alternatives that take real effort to write well and are often skipped even when the image is complex enough to warrant one. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Axis-label overflow that forces rotation is usually a symptom of too many categories on the chart, not a labeling problem to be fixed with smaller text. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Sparkline-captioning conventions (caption like a word, usually just the latest value) don't generalize cleanly to charts with more than one meaningful series. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- Alt-Text (Decorative/Informational/Functional/Complex) (frontier)
- Image and Photo Captions (frontier)
- Video Captions and Sub-Captions (frontier)
- Chart Titles and Axis Labels (frontier)
- Data-Viz Annotations (frontier)
- Edward Tufte Principles (data-ink ratio, chartjunk) (frontier)
- Cole Nussbaumer Knaflic Action Title Rule (frontier)
- Infographic Copy (frontier)
- Pull Quotes and Callouts (frontier)
Frontier under this node: Alt-Text (Decorative/Informational/Functional/Complex), Chart Titles and Axis Labels, Cole Nussbaumer Knaflic Action Title Rule, Data-Viz Annotations, Edward Tufte Principles (data-ink ratio, chartjunk), Image and Photo Captions, Infographic Copy, Pull Quotes and Callouts, Video Captions and Sub-Captions