/kb-markdown-accessibility

name: kb-markdown-accessibility
description: Reference data, not a reviewer. Audit and fix markdown for accessibility. Covers ambiguous links, anchors, emoji (remove/translate), Mermaid/ASCII templates, heading hierarchy, table descriptions, and severity scoring.
license: MIT
disable-model-invocation: true
user-invocable: false
metadata:
  tier: reference
  domain: cross-cutting
  output: none
  effort: low
  title: Markdown Accessibility

Markdown Accessibility Skill

Reusable knowledge module for the `markdown-a11y-assistant`, `markdown-scanner`, and `markdown-fixer` agents and the `markdown-accessibility` always-on instructions. Provides pattern libraries, severity scoring, fix templates, emoji translation maps, diagram description templates, and GitHub anchor generation rules for comprehensive markdown accessibility auditing across 9 domains.

Domains Covered

1. **Descriptive Links** (WCAG 2.4.4) - Ambiguous link text, bare URLs, repeated identical text 2. **Image Alt Text** (WCAG 1.1.1) - Missing, empty, filename-as-alt, generic placeholders 3. **Heading Hierarchy** (WCAG 1.3.1 / 2.4.6) - Skipped levels, multiple H1s, bold-as-heading 4. **Table Accessibility** (WCAG 1.3.1) - Missing descriptions, empty headers, layout tables 5. **Emoji** (WCAG 1.3.3 / Cognitive) - Remove-all, remove-decorative, translate, or leave-unchanged modes 6. **Mermaid and ASCII Diagrams** (WCAG 1.1.1 / 1.3.1) - Replace with accessible text + collapsible source 7. **Em-Dash / En-Dash Normalization** (Cognitive) - Normalize to ` - ` or leave unchanged 8. **Anchor Link Validation** (WCAG 2.4.4) - Validate `#anchor` links against actual headings 9. **Plain Language and List Structure** (Cognitive) - Emoji bullets, passive voice, sentence length

Severity Scoring

Each issue, with its severity, WCAG and auto-fix.

| Issue | Severity | WCAG | Auto-fix? | |-------|----------|------|-----------| | Image missing alt text | Critical | 1.1.1 (A) | No - needs visual judgment | | Mermaid diagram with no text alternative | Critical | 1.1.1 (A) | Partial - simple diagrams auto-described; complex need human | | ASCII diagram with no text description | Critical | 1.1.1 (A) | Partial - flag and wrap; description needs human or auto-gen | | Broken anchor link | Serious | 2.4.4 (A) | No - confirm which end changes | | Ambiguous link text ("here", "click here") | Serious | 2.4.4 (A) | Yes - rewrite using surrounding context | | Skipped heading level | Serious | 1.3.1 (A) | Yes - interpolate missing level | | Multiple H1s | Serious | 1.3.1 (A) | Yes - demote all but first | | Emoji in heading | Moderate | Cognitive | Yes - remove or translate per preference | | Consecutive emoji (2+) | Moderate | 1.3.3 (A) | Yes - remove sequence or translate | | Emoji used as bullet | Moderate | 1.3.1 (A) | Yes - replace with `-` | | Em-dash in prose | Moderate | Cognitive | Yes - replace with ` - ` | | Table without preceding description | Moderate | 1.3.1 (A) | Yes - add one-sentence summary | | Bold text used as heading | Minor | 2.4.6 (AA) | Yes - convert to appropriate heading | | Bare URL in prose | Minor | 2.4.4 (A) | Yes - wrap with descriptive text | | Emoji used for meaning, single inline | Minor | 1.3.3 (A) | Conditional - remove-all: yes; remove-decorative: flag; translate: translate |

Scoring Formula

File Score = 100 - (sum of weighted findings)

Critical: -15 pts each
Serious:  - 7 pts each
Moderate: - 3 pts each
Minor:    - 1 pt each

Floor: 0

Score Grades

Each score, with its grade and meaning.

| Score | Grade | Meaning | |-------|-------|---------| | 90-100 | A | Excellent - accessible documentation | | 75-89 | B | Good - minor issues | | 50-74 | C | Needs Work - several barriers | | 25-49 | D | Poor - significant barriers | | 0-24 | F | Failing - critical AT barriers |

Emoji Handling Modes

The agent supports four modes. The **active mode is determined by the nearest `markdown-accessibility.instructions.md` file** in scope. If no instructions file sets a mode, the default is `remove-decorative`.

> **This repository:** The `.github/instructions/markdown-accessibility.instructions.md` file in this repo sets mode to **`remove-all`**. All emoji are removed, not translated. This overrides the skill default.

| Mode | Description | Default? | |------|-------------|----------| | `remove-all` | Strip every emoji from prose, headings, and bullets. Keep surrounding plain-text meaning. | No (repo override sets this) | | `remove-decorative` | Remove emoji in headings, bullets, and consecutive sequences; flag single inline for review | **Skill default (no override)** | | `translate` | Replace known emoji with `(English)` text; flag unknown for review | No | | `leave-unchanged` | Do not flag or modify any emoji | No |

**Mode resolution order:**

1. Agent system prompt or per-task explicit mode override 2. Nearest `*.instructions.md` file in scope (e.g., `.github/instructions/markdown-accessibility.instructions.md`) 3. Skill default (`remove-decorative`)

Emoji Translation Map

When using `translate` mode, replace each emoji with the parenthesized English equivalent:

| Emoji | Translation | Emoji | Translation | |-------|------------|-------|------------| | 🚀 | (Launch) | ✅ | (Done) | | ⚠️ | (Warning) | ❌ | (Error) | | 📝 | (Note) | 💡 | (Tip) | | 🔧 | (Configuration) | 📚 | (Documentation) | | 🎯 | (Goal) | ✨ | (New) | | 🔍 | (Search) | 🛠️ | (Tools) | | 👋 | (Hello) | 🎉 | (Celebration) | | ⭐ | (Featured) | 💬 | (Discussion) | | 🏠 | (Home) | 📊 | (Data) | | 🔒 | (Security) | 🌐 | (Web) | | 📦 | (Package) | 🔗 | (Link) | | 📋 | (Checklist) | 🏆 | (Achievement) | | ⚡ | (Quick) | 👍 | (Approved) | | 👎 | (Rejected) | 🐛 | (Bug) | | 🤝 | (Collaboration) | 🎓 | (Learning) | | 🔑 | (Key) | 📌 | (Pinned) | | ℹ️ | (Info) | 🔄 | (Refresh) | | ➕ | (Add) | ➖ | (Remove) | | 💻 | (Code) | 🔔 | (Notification) | | 📣 | (Announcement) | 🧪 | (Test) | | 🎨 | (Design) | 🌟 | (Highlight) | | 📈 | (Incre