1---
2name: metapatterns-diagram-alt-audit
3description: Use when auditing metapatterns.io pages for diagram images, weak alt text, and exact replacement suggestions. Runs a deterministic scanner over a page or section, extracts current alt text plus nearby heading and prose context, and helps draft short replacement alts for architectural diagrams.
4---
5 
6# Metapatterns Diagram Alt Audit
7 
8Use this skill for `metapatterns.io` chapters that contain architecture diagrams under `/diagrams/`.
9 
10## Workflow
11 
121. Run the scanner first:
13 
14```bash
15python scripts/audit_diagram_alts.py https://metapatterns.io/basic-metapatterns/layers/
16```
17 
182. For a whole section, crawl linked pages under the same prefix:
19 
20```bash
21python scripts/audit_diagram_alts.py https://metapatterns.io/basic-metapatterns/ --crawl --limit-pages 25
22```
23 
243. Review candidates marked with `needs_update=true`.
25 
264. For unclear cases, open the image itself and inspect it before drafting replacement text.
27 
28## What the scanner does
29 
30- finds content images on `metapatterns.io`
31- strongly prefers images whose path contains `/diagrams/`
32- ignores obvious UI assets such as icons, logos, menus, and chevrons
33- captures the page title, nearest heading, nearby paragraph text, image source, current alt, and a suggested issue label
34- flags common weak alts such as missing alt text, filename-like alt text, and very short placeholder alt text
35 
36## Writing replacement alt text
37 
38- Keep the replacement short, usually one sentence.
39- Describe the structure and the main takeaway, not every label in the drawing.
40- Do not start with `image of` or `diagram of`.
41- Prefer concrete nouns over abstractions. Example: `Three stacked layers: use cases, domain logic, and data, with requests flowing downward.`
42- If the diagram is complex, write a short `alt` and add a longer explanatory sentence in nearby prose or a caption.
43 
44## Output shape
45 
46Default output is Markdown with one section per page and one bullet per candidate.
47 
48Use JSON when the result needs post-processing:
49 
50```bash
51python scripts/audit_diagram_alts.py <url> --json
52```
53 
54Use CSV when the result needs spreadsheet review or bulk editing:
55 
56```bash
57python scripts/audit_diagram_alts.py <url> --csv
58```
59 
60CSV columns:
61 
62- `page_url`
63- `page_title`
64- `nearest_heading`
65- `image_url`
66- `current_alt`
67- `needs_update`
68- `issue`
69- `context_paragraph`
70 
71## Notes
72 
73- This skill audits and drafts updates; it does not blindly rewrite the site.
74- If the site source is available locally, use the report to patch the exact `alt` attributes in the source files.
75