posit-dev/alt-text

Write Accessible Alt Text

Generate accessible alt text for data visualizations and images in this project.

ARGUMENTS

• label: (optional) specific figure label or chunk to target
• file: (optional) specific file to process

Detect project type

Before proceeding, identify the project context and read the relevant reference. Check for a _pkgdown.yml file in the project root to detect a pkgdown site:

ls _pkgdown.yml 2>/dev/null && echo "pkgdown" || echo "not pkgdown"

• pkgdown site (_pkgdown.yml present) → read references/pkgdown.md
• Quarto documents (no _pkgdown.yml, .qmd files present) → read references/quarto.md

If the context is still ambiguous, ask the user which format they are working in.

Key advantage: source code access

Unlike typical alt text scenarios where you only see an image, we have access to the code that generates each chart. Use this to extract precise details:

From plotting code:

• Variable mappings → exact variable names for axes
• Color/fill mappings → what color encodes
• Plot type functions → scatter, histogram, line chart, etc.
• Trend lines or fitted curves → overlaid statistical fits
• Faceting/subplots → number of panels and what varies
• Color scales → encoding scheme (sequential, diverging, categorical)
• Axis labels and titles → customized labels

From data generation code:

• Random distributions → expected distribution shape
• Transformations → what was done to data
• Feature engineering → preprocessing applied
• Filtering/subsetting → what subset is shown

From surrounding prose:

• Text before/after the chunk explains the purpose and key insight
• Chapter context tells you what the figure is meant to teach
• This is often the best source for the "key insight" part of alt text

Three-part structure (Amy Cesal's formula)

1. Chart type — first words identify the format
2. Data description — axes, variables, what is shown
3. Key insight — the pattern or takeaway (often found in surrounding text)

Relationship to captions

Read the caption (fig-cap, fig.cap) first. Alt text should complement, not duplicate it:

• If the caption states the insight, alt text can focus on describing the visual structure
• If the caption is generic, alt text should include the key insight
• Together they should give a complete understanding

Content rules

Include:

• Chart type as first words
• Axis labels and what they represent
• Specific values/ranges when code reveals them (e.g., "peaks between 25–50")
• Number of panels/facets
• What color/size encodes if used
• The key pattern that supports the surrounding point

Exclude:

• "Image of…" or "Chart showing…" (screen readers announce this)
• Decorative color descriptions (unless color encodes data)
• Information already in the caption
• Implementation details (package names, function internals)

Length guidelines

| Complexity | Sentences | When to use | |------------|-----------|----------------------------------------------| | Simple | 2–3 | Single geom, no facets, obvious pattern | | Standard | 3–4 | Multiple geoms or color encoding | | Complex | 4–5 | Faceted, multiple overlays, nuanced insight |

Quality checklist

• [ ] Starts with chart type (Scatter chart, Histogram, Faceted bar chart, etc.)
• [ ] Names the axis variables
• [ ] Includes specific values/ranges from code when informative
• [ ] States the key insight from surrounding prose
• [ ] Complements (not duplicates) the caption
• [ ] Would make sense to someone who cannot see the image
• [ ] Uses plain language (avoid jargon like "geom" or "aesthetic")

Template patterns

Scatter chart:

Scatter chart. [X var] along the x-axis, [Y var] along the y-axis.
[Shape: linear/curved/clustered]. [Specific pattern, e.g., "peaks when X is 25–50"].
[Any overlaid fits or annotations].

Histogram:

Histogram of [variable]. [Shape: right-skewed/bimodal/normal/uniform].
[If transformed: "after [transformation], the distribution [result]"].
[Notable features: outliers, gaps, multiple modes].

Bar chart:

Bar chart. [Categories] along the x-axis, [measure] along the y-axis.
[Key comparison: which is highest/lowest, relative differences].
[Pattern: increasing/decreasing/grouped].

Tile/raster chart:

Tile chart [or heatmap]. [Row variable] along the y-axis, [column variable] along the x-axis.
Color encodes [what value]. [Pattern: where values are high/low].
[If faceted: "N panels showing [what varies]"].

Faceted chart:

Faceted [chart type] with [N] panels, one per [faceting variable].
[What's constant across panels]. [What changes/varies].
[Key comparison or insight across panels].

Correlation heatmap:

Correlation [matrix/heatmap] of [what variables]. [Arrangement].
[Overall pattern: mostly positive/negative/mixed].
[Notable clusters or strong/weak pairs].
[If relevant: contrast with expected behavior].

Before/after comparison:

[N] [chart type]s arranged [vertically/in grid]. [Top/Left] shows [original].
[Bottom/Right] shows [transformed]. [Key difference/similarity].
[If overlay: "[color] curve shows [reference]"].

Line chart with overlays:

[Line/Scatter] chart with overlaid [fits/curves]. [Axes].
[Number] of [lines/fits] shown: [list what each represents].
[Which fits well vs. poorly and why].

Example

Code context:

plotting_data |>
  ggplot(aes(value)) +
  geom_histogram(binwidth = 0.2) +
  facet_grid(name~., scales = "free_y") +
  geom_line(aes(x, y), data = norm_curve, color = "green4")

Surrounding prose says: "Normalization doesn't make data more normal"

Caption: "Normalization doesn't make data more normal. The green curve indicates the density of the unit normal distribution."

Good alt text:

Faceted histogram with two panels stacked vertically. Top panel shows
original data with a bimodal distribution. Bottom panel shows the same
data after z-score normalization, retaining the bimodal shape. A green
normal distribution curve overlaid on the bottom panel clearly does not
match the data, demonstrating that normalization preserves distribution
shape rather than creating normality.