{"id":"alt-text","name":"alt-text","summary":"RパッケージやQuartoドキュメントのデータ可視化や画像用のアクセス可能なオルタナティブテキストを生成・改善します。","body":"# Write Accessible Alt Text\n\nGenerate accessible alt text for data visualizations and images in this project.\n\nARGUMENTS\n- label: (optional) specific figure label or chunk to target\n- file: (optional) specific file to process\n\n## Detect project type\n\nBefore proceeding, identify the project context and read the relevant reference.\nCheck for a `_pkgdown.yml` file in the project root to detect a pkgdown site:\n\n```bash\nls _pkgdown.yml 2>/dev/null && echo \"pkgdown\" || echo \"not pkgdown\"\n```\n\n- **pkgdown site** (`_pkgdown.yml` present) → read `references/pkgdown.md`\n- **Quarto documents** (no `_pkgdown.yml`, `.qmd` files present) → read `references/quarto.md`\n\nIf the context is still ambiguous, ask the user which format they are working in.\n\n## Key advantage: source code access\n\nUnlike 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:\n\n**From plotting code:**\n- Variable mappings → exact variable names for axes\n- Color/fill mappings → what color encodes\n- Plot type functions → scatter, histogram, line chart, etc.\n- Trend lines or fitted curves → overlaid statistical fits\n- Faceting/subplots → number of panels and what varies\n- Color scales → encoding scheme (sequential, diverging, categorical)\n- Axis labels and titles → customized labels\n\n**From data generation code:**\n- Random distributions → expected distribution shape\n- Transformations → what was done to data\n- Feature engineering → preprocessing applied\n- Filtering/subsetting → what subset is shown\n\n**From surrounding prose:**\n- Text before/after the chunk explains the **purpose** and **key insight**\n- Chapter context tells you what the figure is meant to teach\n- This is often the best source for the \"key insight\" part of alt text\n\n## Three-part structure (Amy Cesal's formula)\n\n1. **Chart type** — first words identify the format\n2. **Data description** — axes, variables, what is shown\n3. **Key insight** — the pattern or takeaway (often found in surrounding text)\n\n## Relationship to captions\n\nRead the caption (`fig-cap`, `fig.cap`) first. Alt text should **complement, not duplicate** it:\n- If the caption states the insight, alt text can focus on describing the visual structure\n- If the caption is generic, alt text should include the key insight\n- Together they should give a complete understanding\n\n## Content rules\n\n**Include:**\n- Chart type as first words\n- Axis labels and what they represent\n- Specific values/ranges when code reveals them (e.g., \"peaks between 25–50\")\n- Number of panels/facets\n- What color/size encodes if used\n- The key pattern that supports the surrounding point\n\n**Exclude:**\n- \"Image of…\" or \"Chart showing…\" (screen readers announce this)\n- Decorative color descriptions (unless color encodes data)\n- Information already in the caption\n- Implementation details (package names, function internals)\n\n## Length guidelines\n\n| Complexity | Sentences | When to use                                  |\n|------------|-----------|----------------------------------------------|\n| Simple     | 2–3       | Single geom, no facets, obvious pattern      |\n| Standard   | 3–4       | Multiple geoms or color encoding             |\n| Complex    | 4–5       | Faceted, multiple overlays, nuanced insight  |\n\n## Quality checklist\n\n- [ ] Starts with chart type (Scatter chart, Histogram, Faceted bar chart, etc.)\n- [ ] Names the axis variables\n- [ ] Includes specific values/ranges from code when informative\n- [ ] States the key insight from surrounding prose\n- [ ] Complements (not duplicates) the caption\n- [ ] Would make sense to someone who cannot see the image\n- [ ] Uses plain language (avoid jargon like \"geom\" or \"aesthetic\")\n\n## Template patterns\n\n**Scatter chart:**\n```\nScatter chart. [X var] along the x-axis, [Y var] along the y-axis.\n[Shape: linear/curved/clustered]. [Specific pattern, e.g., \"peaks when X is 25–50\"].\n[Any overlaid fits or annotations].\n```\n\n**Histogram:**\n```\nHistogram of [variable]. [Shape: right-skewed/bimodal/normal/uniform].\n[If transformed: \"after [transformation], the distribution [result]\"].\n[Notable features: outliers, gaps, multiple modes].\n```\n\n**Bar chart:**\n```\nBar chart. [Categories] along the x-axis, [measure] along the y-axis.\n[Key comparison: which is highest/lowest, relative differences].\n[Pattern: increasing/decreasing/grouped].\n```\n\n**Tile/raster chart:**\n```\nTile chart [or heatmap]. [Row variable] along the y-axis, [column variable] along the x-axis.\nColor encodes [what value]. [Pattern: where values are high/low].\n[If faceted: \"N panels showing [what varies]\"].\n```\n\n**Faceted chart:**\n```\nFaceted [chart type] with [N] panels, one per [faceting variable].\n[What's constant across panels]. [What changes/varies].\n[Key comparison or insight across panels].\n```\n\n**Correlation heatmap:**\n```\nCorrelation [matrix/heatmap] of [what variables]. [Arrangement].\n[Overall pattern: mostly positive/negative/mixed].\n[Notable clusters or strong/weak pairs].\n[If relevant: contrast with expected behavior].\n```\n\n**Before/after comparison:**\n```\n[N] [chart type]s arranged [vertically/in grid]. [Top/Left] shows [original].\n[Bottom/Right] shows [transformed]. [Key difference/similarity].\n[If overlay: \"[color] curve shows [reference]\"].\n```\n\n**Line chart with overlays:**\n```\n[Line/Scatter] chart with overlaid [fits/curves]. [Axes].\n[Number] of [lines/fits] shown: [list what each represents].\n[Which fits well vs. poorly and why].\n```\n\n## Example\n\n**Code context:**\n```r\nplotting_data |>\n  ggplot(aes(value)) +\n  geom_histogram(binwidth = 0.2) +\n  facet_grid(name~., scales = \"free_y\") +\n  geom_line(aes(x, y), data = norm_curve, color = \"green4\")\n```\n\n**Surrounding prose says:** \"Normalization doesn't make data more normal\"\n\n**Caption:** \"Normalization doesn't make data more normal. The green curve indicates the density of the unit normal distribution.\"\n\n**Good alt text:**\n```\nFaceted histogram with two panels stacked vertically. Top panel shows\noriginal data with a bimodal distribution. Bottom panel shows the same\ndata after z-score normalization, retaining the bimodal shape. A green\nnormal distribution curve overlaid on the bottom panel clearly does not\nmatch the data, demonstrating that normalization preserves distribution\nshape rather than creating normality.\n```","author":"@posit-dev","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/posit-dev/skills/tree/main/alt-text","license":"MIT","category":"writing","lang":"en","tokens":1507,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/pkgdown.md","size":4807,"sha256":"d5b173f42b32fb97ff42839c7e180c57e3d8c02ece31a13e6e4aa473e3df14cd"},{"path":"references/quarto.md","size":1846,"sha256":"a59ba84a250ebc8250e41bb85729969dd7a688d09aedf57bbf503d2faec7f854"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}