에이전트 · 자동화원문 · prompts.chat

마크다운 접근성 및 대체 텍스트 검사

마크다운 문서의 대체 텍스트, 헤딩, 링크 등을 검사하여 개선된 문서와 CI용 Python 스크립트를 제공합니다.

원제 · Markdown Accessibility and Alt Text Checker

추천 툴: 코딩 에이전트(스킬)형식 기준 추천
쓰인 기법: 에이전트 스킬(SKILL.md)

프롬프트 원문

---
name: markdown-accessibility-checker
description: Reviews Markdown documentation (READMEs, docs sites, wikis, blog posts, changelogs) for accessibility - missing or poor image alt text, heading structure, vague or duplicate link text, bare URLs, empty table headers, color-only instructions, ALL CAPS, and emoji bullets - then writes good alt text for each image from context and returns a fix list or a corrected file. Use when a user asks to "check my README for accessibility", "write alt text for these images", "make our docs screen reader friendly", or wants an accessibility check for Markdown in CI.
---

# Markdown Accessibility Checker

You make Markdown documents work for everyone, including people who use screen readers, keyboard navigation, magnification, or reading aids. You find the problems a script can detect, then do the part a script cannot: write meaningful alt text and link text that fit the document's purpose.

## Files in this skill

- `scripts/check_md_a11y.py` - scans Markdown files or folders and reports problems with line numbers and severities (Python 3 standard library only)
- `references/alt-text-guide.md` - how to write alt text by image type (screenshots, diagrams, charts, photos, logos, badges, decorative images)
- `references/structure-and-links.md` - headings, link text, tables, lists, emphasis, and what each rule in the script means
- `templates/a11y-review.md` - the review report and the alt text worksheet
- `examples/example-readme-review.md` - a worked review of a project README

## Workflow

### 1. Scope the review
Ask which files or folders to check, who reads them (developers, end users, students), and whether the user wants a report, a corrected file, or both. If the documents are rendered by a site generator, ask whether it adds its own page title (then the Markdown may not need an H1).

### 2. Run the checker
```bash
python3 scripts/check_md_a11y.py README.md docs/
python3 scripts/check_md_a11y.py docs/ --json
python3 scripts/check_md_a11y.py docs/ --fail-on warn     # for CI
```
It ignores fenced code blocks and inline code. HIGH means content is lost for some readers (missing alt, empty link, empty heading), WARN should be fixed, INFO needs a human look. If you cannot run the script, check the same rules by reading the file and say so.

### 3. Write alt text
For every image flagged, and for every image with existing alt text, decide its purpose using `references/alt-text-guide.md`:
- Read the text around it: what is the image for at this point in the document?
- If you can see the image, describe what matters for that purpose. If you cannot, ask the user, or write a clearly marked draft from the file name and context (for example "DRAFT: check against the image").
- Decorative images get empty alt text; in Markdown prefer removing them, or use HTML `<img alt="">`.
Fill in the alt text worksheet in `templates/a11y-review.md`.

### 4. Fix structure and links
Apply `references/structure-and-links.md`: one H1, no skipped levels, real headings instead of bold lines, descriptive unique link text, tables with headers, instructions that do not rely on color alone.

### 5. Deliver
- Report: fill in `templates/a11y-review.md`, as in `examples/example-readme-review.md`, with the most important fixes first.
- Corrected file: return the full Markdown with fixes applied and a short change list. Do not change meaning, code samples, or links' destinations.
- Rerun the checker on the corrected file and include the before and after counts.

## Rules
- Never invent what an image shows. If you have not seen it, mark the alt text as a draft.
- Keep alt text short (usually under 150 characters); put long explanations (charts, diagrams) in the text or a caption and say so in the alt.
- Do not start alt text with "image of" or "picture of".
- Remember that automated checks find only part of the problems; always mention what still needs a manual check (color contrast in images, reading order, video captions).
- Respect the author's voice; fix accessibility, not style.
FILE:references/alt-text-guide.md
# Alt text guide

Alt text replaces the image for people who cannot see it. Ask: "If I read this document aloud, what would I say at this point instead of showing the image?" The answer depends on why the image is there, not only on what is in it.

## Basics
- Be specific and short: usually 5 to 20 words, rarely more than 150 characters.
- Lead with the important part. Do not start with "image of", "picture of", or "screenshot of" unless the type itself matters ("Screenshot" can help when the reader needs to find the same screen).
- End with a period so screen readers pause.
- Do not repeat the caption or the sentence next to the image word for word.
- Include text that appears in the image if the reader needs it (button labels, error messages).

## By image type

### Screenshots of an app or website
State the screen and the one thing the reader should notice.
- Weak: "screenshot"
- Better: "Settings screen with the Units toggle set to Metric."

### Hero images and banners
If it only sets the mood, it is decorative. If it shows the product, describe it in one sentence.
- "Trailhead Weather on a phone, showing a three-day forecast for a mountain pass."

### Diagrams and flowcharts
Give the main idea in the alt, and the full structure in the text or a list right after the image.
- Alt: "Architecture diagram: the mobile app calls the API, which reads from a forecast cache and a weather provider. Details in the list below."

### Charts and graphs
Give the type, the subject, and the key takeaway; put the data in a table if readers need numbers.
- "Line chart of daily active users, January to June 2026, rising from 2,000 to 9,500 with a dip in April."

### Photos
Describe what matters for the document's purpose: subject, action, setting.
- "Snow-covered ridge trail with orange marker poles leading to a hut."

### Logos
Use the organization or product name, plus "logo" only if it helps: "Trailhead Weather logo."
When the logo is a link, describe the destination: "Trailhead Weather home."

### Badges (build status, version, license)
Write the information the badge shows: "Build: passing", "License: MIT", "Version 2.4.1".

### Icons inside text or links
If the icon has a function, describe the function ("Download"); if it repeats nearby text, it is decorative.

### Animated GIFs and short videos
Describe what happens: "Animation: dragging a pin onto the map adds a new trailhead to the list." Videos also need captions and, for important content, a text alternative.

### Decorative images
Dividers, background textures, and purely visual flourishes. In HTML use `alt=""` so screen readers skip them. In Markdown, `![](divider.png)` is ambiguous (often a mistake), so prefer removing the image or using `<img src="divider.png" alt="">`.

## Common mistakes
- File names as alt text: "IMG_2041.jpg", "hero-final-v3".
- One word: "image", "logo", "chart".
- Keyword stuffing for search engines.
- Different alt text for the same image used in several places.
- Describing colors or layout when the reader needs the information, not the look.
FILE:references/structure-and-links.md
# Structure, links, and what each rule means

Screen reader users often jump through a document by headings or by links. Good structure is what makes that possible.

## Headings
| Rule | Severity | Why | Fix |
|---|---|---|---|
| empty-heading | HIGH | An empty heading is announced as "heading level 2" with nothing after it. | Add text or remove the #. |
| no-h1 | WARN | The page has no title in the heading outline. | Start with one `# Title`. Skip this if the site generator adds the H1 from front matter. |
| multiple-h1 | WARN | Several titles confuse the outline. | Keep one H1; use `##` for sections. |
| heading-skip | WARN | Jumping from H2 to H4 suggests a missing section. | Use the next level down (H3). Pick levels for structure, not for font size. |
| fake-heading | INFO | A bold line looks like a heading but is not in the outline. | Use a real heading if it starts a section; keep bold if it is just emphasis. |
| no-headings | INFO | Long text without headings is hard to scan. | Add section headings every few paragraphs. |

## Links
| Rule | Severity | Why | Fix |
|---|---|---|---|
| empty-link | HIGH | The link has no accessible name. | Add descriptive text. |
| vague-link | WARN | "Click here" or "read more" means nothing in a list of links. | Name the destination: "download the latest release", "setup guide". |
| same-text-different-url | WARN | Two links called "docs" that go to different places are indistinguishable. | Make each text unique: "API reference", "setup guide". |
| url-as-link-text | INFO | Long URLs are read character by character. | Use a short description; keep the URL only if readers must copy it. |
| bare-url | INFO | Same as above, and not always clickable. | Wrap in a descriptive link. |

Link text tips: put the important words first, keep it short, say when a link opens a file ("pricing sheet (PDF, 2 MB)"), and do not use "link" in the text.

## Images
| Rule | Severity | Why |
|---|---|---|
| img-missing-alt | HIGH | `![](file.png)` gives no alternative; some readers announce the file name. |
| img-no-alt | HIGH | `<img>` without an alt attribute; screen readers fall back to the file name. |
| img-generic-alt | WARN | "image", "screenshot", "logo" alone carry no information. |
| img-filename-alt | WARN | "IMG_2041.jpg" is not a description. |
| img-long-alt | WARN | Very long alt text cannot be navigated; move details to the text. |
| img-redundant-alt | INFO | "Image of" is redundant; screen readers already say "image". |
| img-decorative | INFO | `alt=""` hides the image; confirm it is truly decorative. |

See `alt-text-guide.md` for how to write the text.

## Tables
- table-empty-header (WARN): every column needs a header so screen readers can announce "Pro, Forecast days, 10". Add a header such as "Feature" to the first column.
- Use tables for data, not for layout. Keep them small; split very wide tables.

## Other rules
- color-only (WARN): "Press the green button" fails for color-blind readers and screen reader users. Name the button: "Select Save (the green button)".
- all-caps (INFO): long ALL CAPS text is harder to read, and some screen readers spell short caps words letter by letter. Use normal case and bold for emphasis.
- emoji-bullet (INFO): emoji are read aloud by name ("white heavy check mark Hourly forecasts"). Use normal list markers, and keep emoji rare and meaningful.

## Not checked by the script (check by hand)
- Whether alt text is accurate and useful.
- Color contrast and text inside images (screenshots with tiny text, charts with low contrast).
- Reading order of complex layouts, and HTML blocks embedded in Markdown.
- Captions and transcripts for videos and audio.
- Plain language: short sentences, defined jargon, and descriptive section names.
FILE:templates/a11y-review.md
# Accessibility Review: <document or folder>

Date: <YYYY-MM-DD>
Files checked: <n> (<list or folder>)
Audience: <who reads these docs>
Checker run: `python3 scripts/check_md_a11y.py <paths>` -> HIGH <n>, WARN <n>, INFO <n>

## Top fixes (most impact first)
1. <fix> (<file:line>)
2. <fix>
3. <fix>

## Alt text worksheet
| File:line | Image | Purpose in the document | Current alt | New alt | Seen the image? |
|---|---|---|---|---|---|
| | | informative / functional / decorative / complex | | | yes / draft |

## Headings
- Current outline: <H1 ... / H2 ... / H4 ...>
- Proposed outline: <H1 ... / H2 ... / H3 ...>

## Links
| File:line | Current text | New text | Destination |
|---|---|---|---|
| | | | |

## Other findings
| File:line | Rule | Change |
|---|---|---|
| | | |

## After fixes
Checker rerun: HIGH <n>, WARN <n>, INFO <n> (remaining INFO items explained below).
- <INFO item: reason it is acceptable>

## Manual checks still needed
- <for example: contrast of text in

‹ 라이브러리로

--- name: markdown-accessibility-checker description: Reviews Markdown documentation (READMEs, docs sites, wikis, blog posts, changelogs) for accessibility - missing or poor image alt text, heading structure, vague or duplicate link text, bare URLs, empty table headers, color-only instructions, ALL CAPS, and emoji bullets - then writes good alt text for each image from context and returns a fix list or a corrected file. Use when a user asks to "check my README for accessibility", "write alt text for these images", "make our docs screen reader friendly", or wants an accessibility check for Markdown in CI. --- # Markdown Accessibility Checker You make Markdown documents work for everyone, including people who use screen readers, keyboard navigation, magnification, or reading aids. You find the problems a script can detect, then do the part a script cannot: write meaningful alt text and link text that fit the document's purpose. ## Files in this skill - `scripts/check_md_a11y.py` - scans Markdown files or folders and reports problems with line numbers and severities (Python 3 standard library only) - `references/alt-text-guide.md` - how to write alt text by image type (screenshots, diagrams, charts, photos, logos, badges, decorative images) - `references/structure-and-links.md` - headings, link text, tables, lists, emphasis, and what each rule in the script means - `templates/a11y-review.md` - the review report and the alt text worksheet - `examples/example-readme-review.md` - a worked review of a project README ## Workflow ### 1. Scope the review Ask which files or folders to check, who reads them (developers, end users, students), and whether the user wants a report, a corrected file, or both. If the documents are rendered by a site generator, ask whether it adds its own page title (then the Markdown may not need an H1). ### 2. Run the checker ```bash python3 scripts/check_md_a11y.py README.md docs/ python3 scripts/check_md_a11y.py docs/ --json python3 scripts/check_md_a11y.py docs/ --fail-on warn # for CI ``` It ignores fenced code blocks and inline code. HIGH means content is lost for some readers (missing alt, empty link, empty heading), WARN should be fixed, INFO needs a human look. If you cannot run the script, check the same rules by reading the file and say so. ### 3. Write alt text For every image flagged, and for every image with existing alt text, decide its purpose using `references/alt-text-guide.md`: - Read the text around it: what is the image for at this point in the document? - If you can see the image, describe what matters for that purpose. If you cannot, ask the user, or write a clearly marked draft from the file name and context (for example "DRAFT: check against the image"). - Decorative images get empty alt text; in Markdown prefer removing them, or use HTML `<img alt="">`. Fill in the alt text worksheet in `templates/a11y-review.md`. ### 4. Fix structure and links Apply `references/structure-and-links.md`: one H1, no skipped levels, real headings instead of bold lines, descriptive unique link text, tables with headers, instructions that do not rely on color alone. ### 5. Deliver - Report: fill in `templates/a11y-review.md`, as in `examples/example-readme-review.md`, with the most important fixes first. - Corrected file: return the full Markdown with fixes applied and a short change list. Do not change meaning, code samples, or links' destinations. - Rerun the checker on the corrected file and include the before and after counts. ## Rules - Never invent what an image shows. If you have not seen it, mark the alt text as a draft. - Keep alt text short (usually under 150 characters); put long explanations (charts, diagrams) in the text or a caption and say so in the alt. - Do not start alt text with "image of" or "picture of". - Remember that automated checks find only part of the problems; always mention what still needs a manual check (color contrast in images, reading order, video captions). - Respect the author's voice; fix accessibility, not style. FILE:references/alt-text-guide.md # Alt text guide Alt text replaces the image for people who cannot see it. Ask: "If I read this document aloud, what would I say at this point instead of showing the image?" The answer depends on why the image is there, not only on what is in it. ## Basics - Be specific and short: usually 5 to 20 words, rarely more than 150 characters. - Lead with the important part. Do not start with "image of", "picture of", or "screenshot of" unless the type itself matters ("Screenshot" can help when the reader needs to find the same screen). - End with a period so screen readers pause. - Do not repeat the caption or the sentence next to the image word for word. - Include text that appears in the image if the reader needs it (button labels, error messages). ## By image type ### Screenshots of an app or website State the screen and the one thing the reader should notice. - Weak: "screenshot" - Better: "Settings screen with the Units toggle set to Metric." ### Hero images and banners If it only sets the mood, it is decorative. If it shows the product, describe it in one sentence. - "Trailhead Weather on a phone, showing a three-day forecast for a mountain pass." ### Diagrams and flowcharts Give the main idea in the alt, and the full structure in the text or a list right after the image. - Alt: "Architecture diagram: the mobile app calls the API, which reads from a forecast cache and a weather provider. Details in the list below." ### Charts and graphs Give the type, the subject, and the key takeaway; put the data in a table if readers need numbers. - "Line chart of daily active users, January to June 2026, rising from 2,000 to 9,500 with a dip in April." ### Photos Describe what matters for the document's purpose: subject, action, setting. - "Snow-covered ridge trail with orange marker poles leading to a hut." ### Logos Use the organization or product name, plus "logo" only if it helps: "Trailhead Weather logo." When the logo is a link, describe the destination: "Trailhead Weather home." ### Badges (build status, version, license) Write the information the badge shows: "Build: passing", "License: MIT", "Version 2.4.1". ### Icons inside text or links If the icon has a function, describe the function ("Download"); if it repeats nearby text, it is decorative. ### Animated GIFs and short videos Describe what happens: "Animation: dragging a pin onto the map adds a new trailhead to the list." Videos also need captions and, for important content, a text alternative. ### Decorative images Dividers, background textures, and purely visual flourishes. In HTML use `alt=""` so screen readers skip them. In Markdown, `![](divider.png)` is ambiguous (often a mistake), so prefer removing the image or using `<img src="divider.png" alt="">`. ## Common mistakes - File names as alt text: "IMG_2041.jpg", "hero-final-v3". - One word: "image", "logo", "chart". - Keyword stuffing for search engines. - Different alt text for the same image used in several places. - Describing colors or layout when the reader needs the information, not the look. FILE:references/structure-and-links.md # Structure, links, and what each rule means Screen reader users often jump through a document by headings or by links. Good structure is what makes that possible. ## Headings | Rule | Severity | Why | Fix | |---|---|---|---| | empty-heading | HIGH | An empty heading is announced as "heading level 2" with nothing after it. | Add text or remove the #. | | no-h1 | WARN | The page has no title in the heading outline. | Start with one `# Title`. Skip this if the site generator adds the H1 from front matter. | | multiple-h1 | WARN | Several titles confuse the outline. | Keep one H1; use `##` for sections. | | heading-skip | WARN | Jumping from H2 to H4 suggests a missing section. | Use the next level down (H3). Pick levels for structure, not for font size. | | fake-heading | INFO | A bold line looks like a heading but is not in the outline. | Use a real heading if it starts a section; keep bold if it is just emphasis. | | no-headings | INFO | Long text without headings is hard to scan. | Add section headings every few paragraphs. | ## Links | Rule | Severity | Why | Fix | |---|---|---|---| | empty-link | HIGH | The link has no accessible name. | Add descriptive text. | | vague-link | WARN | "Click here" or "read more" means nothing in a list of links. | Name the destination: "download the latest release", "setup guide". | | same-text-different-url | WARN | Two links called "docs" that go to different places are indistinguishable. | Make each text unique: "API reference", "setup guide". | | url-as-link-text | INFO | Long URLs are read character by character. | Use a short description; keep the URL only if readers must copy it. | | bare-url | INFO | Same as above, and not always clickable. | Wrap in a descriptive link. | Link text tips: put the important words first, keep it short, say when a link opens a file ("pricing sheet (PDF, 2 MB)"), and do not use "link" in the text. ## Images | Rule | Severity | Why | |---|---|---| | img-missing-alt | HIGH | `![](file.png)` gives no alternative; some readers announce the file name. | | img-no-alt | HIGH | `<img>` without an alt attribute; screen readers fall back to the file name. | | img-generic-alt | WARN | "image", "screenshot", "logo" alone carry no information. | | img-filename-alt | WARN | "IMG_2041.jpg" is not a description. | | img-long-alt | WARN | Very long alt text cannot be navigated; move details to the text. | | img-redundant-alt | INFO | "Image of" is redundant; screen readers already say "image". | | img-decorative | INFO | `alt=""` hides the image; confirm it is truly decorative. | See `alt-text-guide.md` for how to write the text. ## Tables - table-empty-header (WARN): every column needs a header so screen readers can announce "Pro, Forecast days, 10". Add a header such as "Feature" to the first column. - Use tables for data, not for layout. Keep them small; split very wide tables. ## Other rules - color-only (WARN): "Press the green button" fails for color-blind readers and screen reader users. Name the button: "Select Save (the green button)". - all-caps (INFO): long ALL CAPS text is harder to read, and some screen readers spell short caps words letter by letter. Use normal case and bold for emphasis. - emoji-bullet (INFO): emoji are read aloud by name ("white heavy check mark Hourly forecasts"). Use normal list markers, and keep emoji rare and meaningful. ## Not checked by the script (check by hand) - Whether alt text is accurate and useful. - Color contrast and text inside images (screenshots with tiny text, charts with low contrast). - Reading order of complex layouts, and HTML blocks embedded in Markdown. - Captions and transcripts for videos and audio. - Plain language: short sentences, defined jargon, and descriptive section names. FILE:templates/a11y-review.md # Accessibility Review: <document or folder> Date: <YYYY-MM-DD> Files checked: <n> (<list or folder>) Audience: <who reads these docs> Checker run: `python3 scripts/check_md_a11y.py <paths>` -> HIGH <n>, WARN <n>, INFO <n> ## Top fixes (most impact first) 1. <fix> (<file:line>) 2. <fix> 3. <fix> ## Alt text worksheet | File:line | Image | Purpose in the document | Current alt | New alt | Seen the image? | |---|---|---|---|---|---| | | | informative / functional / decorative / complex | | | yes / draft | ## Headings - Current outline: <H1 ... / H2 ... / H4 ...> - Proposed outline: <H1 ... / H2 ... / H3 ...> ## Links | File:line | Current text | New text | Destination | |---|---|---|---| | | | | | ## Other findings | File:line | Rule | Change | |---|---|---| | | | | ## After fixes Checker rerun: HIGH <n>, WARN <n>, INFO <n> (remaining INFO items explained below). - <INFO item: reason it is acceptable> ## Manual checks still needed - <for example: contrast of text in