add skill to find and improve alt text for pkgdown documentation

.claude-plugin/marketplace.json

@@ -52,7 +52,8 @@
         "./r-lib/lifecycle",
         "./r-lib/r-package-development",
         "./r-lib/r-cli-app",
-        "./r-lib/mirai"
+        "./r-lib/mirai",
+        "./alt-text"
       ]
     },
     {
@@ -83,7 +84,7 @@
       "skills": [
         "./brand-yml",
         "./quarto/quarto-authoring",
-        "./quarto/quarto-alt-text"
+        "./alt-text"
       ]
     }
   ]

README.md

@@ -39,6 +39,7 @@ R package development skills for working with the r-lib ecosystem and modern R p
 - **[lifecycle](./r-lib/lifecycle/)** - Manage R package lifecycle according to tidyverse principles using the lifecycle package, covering deprecation workflows, function/argument renaming, superseding, and experimental stages
 - **[r-package-development](./r-lib/r-package-development/)** - R package development with devtools, testthat, and roxygen2, covering key commands, coding conventions, testing, documentation, and NEWS.md practices
 - **[mirai](./r-lib/mirai/)** - Async, parallel, and distributed computing in R using mirai, covering explicit dependency passing, daemon setup, parallel mapping with `mirai_map()`, Shiny integration, remote/HPC launchers, and migration from future/parallel
+- **[alt-text](./alt-text/)** - Generate and improve accessible alt text for data visualizations and images in pkgdown sites and Quarto documents, covering vignette code chunks (`fig.alt`), static markdown images, and multi-plot chunks
 
 ### ggsql
 
@@ -60,7 +61,7 @@ Skills for Quarto document creation and publishing.
 
 - **[brand-yml](./brand-yml/)** - Create and apply brand.yml files for consistent styling across Quarto projects, supporting HTML documents, dashboards, RevealJS presentations, Typst PDFs, and websites with automatic brand discovery and theme layering
 - **[authoring](quarto/README.md#quarto-authoring-skill)** - Comprehensive guidance for Quarto document authoring and R Markdown migration. Write new Quarto documents with best practices, convert R Markdown files, migrate bookdown/blogdown/xaringan/distill projects, and use Quarto-specific features like hashpipe syntax, cross-references, callouts, and extensions
-- **[quarto-alt-text](./quarto/quarto-alt-text/)** - Generate accessible alt text for figures in Quarto documents using Amy Cesal's three-part formula (chart type, data description, key insight). Supports code-generated plots and static images
+- **[alt-text](./alt-text/)** - Generate and improve accessible alt text for figures in Quarto documents using Amy Cesal's three-part formula (chart type, data description, key insight). Supports code-generated plots and static images
 
 ## Installation
 

quarto/quarto-alt-text/SKILL.md → alt-text/SKILL.md

@@ -1,25 +1,40 @@
 ---
-name: quarto-alt-text
-description: Generate accessible alt text for data visualizations in Quarto documents. Use when the user wants to add, improve, or review alt text for figures in .qmd files. Triggers for requests about accessibility, figure descriptions, fig-alt, screen reader support, or making Quarto documents more accessible.
+name: alt-text
+description: >
+  Generate and improve accessible alt text for data visualizations and images
+  in R packages and Quarto documents. Use when the user wants to add, improve,
+  or audit alt text for figures in a pkgdown site or .qmd files. Activate for
+  requests that mention fig-alt, fig.alt, figure descriptions, or alt text in
+  the context of an R package or Quarto document.
 metadata:
   author: Emil Hvitfeldt (@emilhvitfeldt)
-  version: "1.1"
+  version: "1.0"
 license: MIT
 ---
 
-# Write Chart Alt Text
+# Write Accessible Alt Text
 
-Generate accessible alt text for data visualizations in this project.
+Generate accessible alt text for data visualizations and images in this project.
 
 ARGUMENTS
-- label: (optional) specific fig- label to generate alt text for
-- file: (optional) specific .qmd file to process
+- label: (optional) specific figure label or chunk to target
+- file: (optional) specific file to process
 
-## Instructions
+## Detect project type
 
-When invoked, analyze the figure(s) and generate alt text following these guidelines:
+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:
 
-### Key Advantage: Source Code Access
+```bash
+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:
 
@@ -43,59 +58,59 @@ Unlike typical alt text scenarios where you only see an image, **we have access
 - 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)
+## Three-part structure (Amy Cesal's formula)
 
-1. **Chart type** - First words identify the format
-2. **Data description** - Axes, variables, what's shown
-3. **Key insight** - The pattern or takeaway (often found in surrounding text)
+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 fig-cap
+## Relationship to captions
 
-Read the `fig-cap` first. The alt text should **complement, not duplicate** it:
-- If caption states the insight, alt text can focus on describing the visual structure
-- If caption is generic, alt text should include the key insight
+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
+## 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")
+- 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 chapter's point
+- The key pattern that supports the surrounding point
 
 **Exclude:**
-- "Image of..." or "Chart showing..." (screen readers announce this)
+- "Image of…" or "Chart showing…" (screen readers announce this)
 - Decorative color descriptions (unless color encodes data)
-- Information already in fig-cap
+- Information already in the caption
 - Implementation details (package names, function internals)
 
-### Length Guidelines
+## 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 |
+| 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
+## 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 fig-cap
+- [ ] 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
+## 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"].
+[Shape: linear/curved/clustered]. [Specific pattern, e.g., "peaks when X is 25–50"].
 [Any overlaid fits or annotations].
 ```
 
@@ -132,7 +147,7 @@ Faceted [chart type] with [N] panels, one per [faceting variable].
 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, e.g., "unlike PCA, these are not orthogonal"].
+[If relevant: contrast with expected behavior].
 ```
 
 **Before/after comparison:**
@@ -149,30 +164,6 @@ Correlation [matrix/heatmap] of [what variables]. [Arrangement].
 [Which fits well vs. poorly and why].
 ```
 
-## Workflow
-
-### Finding Figures
-
-To find all figure chunks in the project:
-```bash
-# List all figure labels with file and line number
-grep -n "#| label: fig-" *.qmd
-
-# Find figures in a specific file
-grep -n "#| label: fig-" numeric-splines.qmd
-
-# Find a specific figure
-grep -rn "#| label: fig-splines-predictor-outcome" *.qmd
-```
-
-### For Each Figure
-
-1. **Locate** - Use grep to find file and line number
-2. **Read context** - Read ~50 lines around the chunk (prose before + code + prose after)
-3. **Extract details** - Note fig-cap, ggplot code, data generation, surrounding explanation
-4. **Draft alt text** - Apply three-part structure (type → data → insight)
-5. **Verify** - Check against quality checklist
-
 ## Example
 
 **Code context:**
@@ -186,15 +177,14 @@ plotting_data |>
 
 **Surrounding prose says:** "Normalization doesn't make data more normal"
 
-**fig-cap:** "Normalization doesn't make data more normal. The green curve indicates the density of the unit normal distribution."
+**Caption:** "Normalization doesn't make data more normal. The green curve indicates the density of the unit normal distribution."
 
 **Good alt text:**
 ```
-#| fig-alt: |
-#|   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.
-```
+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.
+```

alt-text/references/pkgdown.md

@@ -0,0 +1,152 @@
+# Alt Text in pkgdown Sites
+
+This reference covers how to find images and add alt text across a pkgdown site.
+
+## Where images appear
+
+| Location | Image type | Can have alt text? |
+|----------|------------|-------------------|
+| `vignettes/*.Rmd` or `vignettes/*.qmd` | code-generated plots | Yes — `fig.alt` chunk option |
+| `vignettes/*.Rmd` | static images via `knitr::include_graphics()` | Yes — `fig.alt` chunk option |
+| `README.Rmd` / `README.md` | code-generated plots | Yes — `fig.alt` chunk option |
+| `README.Rmd` / `README.md` | markdown images `![](path)` | Yes — fill in the bracket |
+| `README.Rmd` / `README.md` | HTML `<img src=...>` tags | Yes — add `alt="..."` attribute |
+| `R/*.R` `@examples` | code-generated plots | **No — pkgdown limitation** |
+
+There is currently no way to add alt text to plots generated in `@examples` blocks.
+Focus effort on vignettes and README.
+
+## Step 1 — Find missing alt text
+
+### Find chunks missing fig.alt in vignettes
+
+```bash
+# Find chunks that already have fig.alt (to see what's covered)
+grep -rn "fig\.alt\|fig-alt" vignettes/
+
+# Find all plot-producing chunks — each one needs a fig.alt
+grep -rn "ggplot\|geom_\|autoplot\|include_graphics" vignettes/
+```
+
+Compare the two lists to identify chunks with plots but no `fig.alt`.
+
+### Find static images missing alt text
+
+```bash
+# Markdown images with empty alt: ![](path)
+grep -rn "!\[\](" vignettes/ README.md README.Rmd
+
+# All markdown images — review each for descriptive alt text
+grep -rn "!\[" vignettes/ README.md README.Rmd
+
+# HTML <img> tags — check each for a non-empty alt attribute
+grep -rn "<img" vignettes/ README.md README.Rmd
+```
+
+Package logos are commonly written as HTML `<img>` tags at the top of
+`README.Rmd`. Check that the `alt` attribute is present and descriptive:
+
+```html
+<!-- Missing alt -->
+<img src='man/figures/logo.png' align="right" height="139" />
+
+<!-- Fixed -->
+<img src='man/figures/logo.png' align="right" height="139"
+  alt="Package hex logo: a blue hexagon with the package name." />
+```
+
+## Step 2 — Audit quality of existing alt text
+
+When alt text already exists, leave it alone unless it has a concrete problem.
+Only rewrite alt text that fails one of these checks:
+
+**Relative references** — alt text must be self-contained. Fix phrases like:
+- "A plot identical to the one above…" → describe the plot fully
+- "The same data as shown above…" → name the data explicitly
+
+**Missing key information** — fix if alt text omits chart type, axis labels, or
+the key pattern.
+
+**Grammar and spelling errors** — alt text is read aloud by screen readers.
+
+## Step 3 — Add fig.alt to Rmd chunks
+
+The `fig.alt` chunk option works for both code-generated plots and static
+images loaded with `knitr::include_graphics()`.
+
+### Hashpipe syntax (preferred)
+
+```r
+#| fig.alt: >
+#|   Scatter chart of bill length vs. bill depth for 344 penguins
+#|   across three species. Gentoo penguins form a distinct cluster
+#|   at higher bill depth. Adelie and Chinstrap overlap but separate
+#|   along the bill length axis, with Chinstrap skewing higher.
+plot_code_here()
+```
+
+### Knitr chunk option syntax
+
+````markdown
+```{r penguin-scatter, fig.alt="Scatter chart of bill length vs. bill depth..."}
+plot_code_here()
+```
+````
+
+### Multiple plots in one chunk
+
+When a chunk produces multiple plots, `fig.alt` accepts a vector — one string
+per plot, in order:
+
+```r
+#| fig.alt:
+#|   - "Histogram of bill length. Right-skewed distribution with a peak at 45–50mm."
+#|   - "Histogram of bill depth. Bimodal distribution with peaks at 15mm and 18mm."
+```
+
+## Step 4 — Add alt text to static markdown images
+
+For `![](path)` images, fill in the bracket:
+
+```markdown
+<!-- Before -->
+![](man/figures/logo.png)
+
+<!-- After -->
+![A hexagonal logo with a blue background and white text reading 'pkgdown'.](man/figures/logo.png)
+```
+
+For purely decorative images, leave the bracket empty intentionally and add a
+comment:
+
+```markdown
+<!-- Decorative banner, intentionally no alt text -->
+![](man/figures/decorative-banner.png)
+```
+
+## Step 5 — Verify
+
+Because pkgdown does not warn about missing alt text in vignettes, verify by
+re-running the same grep from Step 1 and confirming every plot-producing chunk
+now has a `fig.alt`:
+
+```bash
+# Should list every chunk with a plot
+grep -rn "ggplot\|geom_\|autoplot\|include_graphics" vignettes/
+
+# Should now match the same chunks
+grep -rn "fig\.alt\|fig-alt" vignettes/
+```
+
+For the home page, `build_site()` will warn if any README images are still
+missing alt text.
+
+## Quarto vignettes (`.qmd`)
+
+For vignettes using Quarto format, use `fig-alt` (hyphen) instead of `fig.alt` (dot):
+
+```r
+#| fig-alt: >
+#|   Scatter chart of bill length vs. bill depth for 344 penguins
+#|   across three species.
+```