markdown-a11y

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Use

- Reviewing markdown files (READMEs, docs, blog posts, GitHub profiles) for accessibility
- Creating new documentation and wanting to ensure inclusivity from the start
- Auditing existing markdown content for screen reader compatibility
- When asked to improve documentation quality with accessibility in mind

## Critical Patterns

- **Descriptive Links:** Never use "click here", "here", "this", "read more" as link text. Link text
  must make sense when read out of context.
- **Image Alt Text:** Every image needs meaningful alt text. Empty alt `![]()` is only acceptable
  for explicitly decorative images. Filenames and generic words like "screenshot" are not valid alt
  text.
- **Heading Hierarchy:** One H1 per document, never skip levels (e.g., `##` to `####` is a
  violation), and never use bold text as a fake heading.
- **Proper Lists:** Always use markdown list syntax (`-`, `*`, `+`, `1.`). Never use emoji or
  special characters as bullet points.
- **Emoji Restraint:** Don't stack multiple consecutive emoji. Don't use emoji as the sole conveyor
  of meaning.

## Review Priority

When multiple issues exist, fix in this order:

1. Missing or empty alt text on images
2. Skipped heading levels or heading hierarchy issues
3. Non-descriptive link text
4. Emoji used as bullet points or list markers
5. Plain language improvements

## Code Examples

### 1. Descriptive Links

```markdown
<!-- BAD: generic link text -->
Read my blog post [here](https://example.com).
For more info, [click here](https://example.com/docs).
Check out [this](https://example.com/guide) guide.

<!-- GOOD: descriptive, self-contained link text -->
Read my blog post "[Crafting an accessible resume](https://example.com)".
For more info, see the [API authentication guide](https://example.com/docs).
Check out the [getting started guide](https://example.com/guide).

<!-- BAD: bare URL in prose -->
See https://example.com/docs for details.

<!-- GOOD: wrapped in descriptive link -->
See the [project documentation](https://example.com/docs) for details.

<!-- BAD: identical text, different destinations -->
See [documentation](https://example.com/api) for the API.
See [documentation](https://example.com/cli) for the CLI.

<!-- GOOD: unique, distinguishable text -->
See the [API documentation](https://example.com/api).
See the [CLI documentation](https://example.com/cli).
```

**Why it matters:** Screen readers can present all links as an isolated list. "here", "here", "here"
tells the user nothing. Each link must stand on its own.

### 2. Image Alt Text

```markdown
<!-- BAD: empty alt text (unless intentionally decorative) -->
![](screenshot.png)

<!-- BAD: filename as alt text -->
![img_1234.jpg](img_1234.jpg)

<!-- BAD: generic placeholder -->
![screenshot](dashboard.png)
![image](chart.png)

<!-- GOOD: succinct, descriptive alt text -->
![Screenshot of the dashboard showing 3 active alerts](dashboard.png)
![Bar chart comparing Q1 and Q2 revenue: Q1 $2.1M, Q2 $2.8M](chart.png)

<!-- GOOD: decorative image (explicitly empty alt) -->
![](decorative-divider.png)
<!-- Only valid when the image adds no informational value -->
```

**For complex images** (charts, infographics), summarize the key data in alt text and provide a
longer description:

```markdown
![Sales by region: North 45%, South 30%, East 15%, West 10%](sales-chart.png)

<details>
<summary>Detailed sales breakdown</summary>

| Region | Sales   | % of Total |
|--------|---------|------------|
| North  | $4.5M   | 45%        |
| South  | $3.0M   | 30%        |
| East   | $1.5M   | 15%        |
| West   | $1.0M   | 10%        |

</details>
```

**Important:** When suggesting alt text improvements, present them as recommendations. Only the
author can properly assess visual content and context.

### 3. Heading Hierarchy

```markdown
<!-- BAD: skipped heading level (## to ####) -->
## Installation
#### Prerequisites    <!-- skips H3! -->

<!-- GOOD: proper hierarchy -->
## Installation
### Prerequisites

From dallay/agents-skills, MIT.

More from dallay/agents-skills