/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` skills. 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

Scores and grades come from `skills/a11y-core/scripts/merge-findings.mjs`; do not compute them by hand. If the script cannot run, apply the formula below yourself; use only what you are given, and never say you scanned, ran or opened anything you did not. In summary:

penalty = sum over findings of weight x confidence factor
  weight: critical 10, serious 5, moderate 2, minor 1
  confidence factor: high 1, medium 0.7, low 0.4
checks  = max(findings + passed checks, 10)
score   = max(0, round(100 - (penalty / checks) x 20))

Score Grades

Each score, with its grade.

| Score | Grade | |-------|-------| | 90-100 | A | | 80-89 | B | | 70-79 | C | | 60-69 | D | | 0-59 | F |

Emoji Handling Modes

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

> **This repository:** The house style in `AGENTS.md` (no emoji, anywhere) means mode **`remove-all`** for this repo's own docs. 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 in the audited project (e.g., its `.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. This table and the emoji examples below contain emoji deliberately: they are input to match or examples of what not to write, not house style.

| 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) | | ⚡ | (Quic