Metapatterns Diagram Alt Audit

Use this skill for metapatterns.io chapters that contain architecture diagrams under /diagrams/.

Workflow

1. Run the scanner first:

python scripts/audit_diagram_alts.py https://metapatterns.io/basic-metapatterns/layers/

1. For a whole section, crawl linked pages under the same prefix:

python scripts/audit_diagram_alts.py https://metapatterns.io/basic-metapatterns/ --crawl --limit-pages 25

1. Review candidates marked with needs_update=true.

1. For unclear cases, open the image itself and inspect it before drafting replacement text.

What the scanner does

• finds content images on metapatterns.io
• strongly prefers images whose path contains /diagrams/
• ignores obvious UI assets such as icons, logos, menus, and chevrons
• captures the page title, nearest heading, nearby paragraph text, image source, current alt, and a suggested issue label
• flags common weak alts such as missing alt text, filename-like alt text, and very short placeholder alt text

Writing replacement alt text

• Keep the replacement short, usually one sentence.
• Describe the structure and the main takeaway, not every label in the drawing.
• Do not start with image of or diagram of.
• Prefer concrete nouns over abstractions. Example: Three stacked layers: use cases, domain logic, and data, with requests flowing downward.
• If the diagram is complex, write a short alt and add a longer explanatory sentence in nearby prose or a caption.

Output shape

Default output is Markdown with one section per page and one bullet per candidate.

Use JSON when the result needs post-processing:

python scripts/audit_diagram_alts.py <url> --json

Use CSV when the result needs spreadsheet review or bulk editing:

python scripts/audit_diagram_alts.py <url> --csv

CSV columns:

• page_url
• page_title
• nearest_heading
• image_url
• current_alt
• needs_update
• issue
• context_paragraph

Notes

• This skill audits and drafts updates; it does not blindly rewrite the site.
• If the site source is available locally, use the report to patch the exact alt attributes in the source files.