# Visual playbooks — router

Progressive references for DevRites `visual/` HTML + outline pairs.
Load **only** matching playbooks before writing HTML. Do not preload all seven.

**Spec / schema SSOT:** [`../workspace-artifact-schema.md`](../workspace-artifact-schema.md) (see What each file owns)  
**Outline companion:** [`outline-template.md`](outline-template.md)

## Load rules

1. Match the artifact against each `use_when` below.
2. **Open every matching playbook** (one page often combines several ids).
3. **Do not** open non-matching playbooks "just in case."
4. Always emit the dual-read pair: `visual/<name>.html` + `visual/<name>.outline.md`.
5. Copy required outline headings from [`outline-template.md`](outline-template.md).
6. **Dual-read:** the outline is SSOT — see `outline-template.md` § Dual-read rule.
7. No Lavish runtime: never require `window.lavish.*`, `data-lavish-*`, poll, queue, share, or ht-ml.app.

## Playbook ids

| ID | `use_when` | File |
| --- | --- | --- |
| `diagram` | Relationships, flows, state, architecture, spatial concepts | [`diagram.md`](diagram.md) |
| `table` | Dense comparable records that share the same fields | [`table.md`](table.md) |
| `comparison` | Options, before/after, tradeoffs, mutually exclusive directions | [`comparison.md`](comparison.md) |
| `plan` | Product or technical plan before build | [`plan.md`](plan.md) |
| `code` | Snippets, files, patches, diffs (prefer focused ranges) | [`code.md`](code.md) |
| `input` | Structured choices the human should make on the page | [`input.md`](input.md) |
| `slides` | Only when a paced deck / presentation is explicitly requested | [`slides.md`](slides.md) |

## Dual-read reminder

| Human | Agent |
| --- | --- |
| Opens HTML in a normal browser (`open-visual`) | Reads `.outline.md` first |
| Sees layout, SVG, tables, forms, open questions | Uses Purpose / ID inventory / Relationships / Citations / Open questions |
| Optional form answers on the page | Persists answers in outline `## Answers` and/or `questions.md` |
| May skim `#devrites-outline` JSON | Treats JSON as a mirror; **outline.md wins** on conflict |

**Preferred dual-read shape:** hand-authored inline SVG + `.outline.md` SSOT.
Mermaid is optional when a flowchart / sequence / state diagram is clearer than
hand SVG **and** the Mermaid source is embedded and mirrored in the outline —
not a default substitute.

Home: `.devrites/work/<slug>/visual/`. Optional artifact; never a new lifecycle phase; never readiness-required.

## Writer checklist (before HTML)

- [ ] Matching playbooks opened
- [ ] Outline headings prepared from template (including optional `## Open questions` when uncertainty remains)
- [ ] Stable `id`s planned for landmarks / nodes (include `viz-open-questions` when that section is present)
- [ ] Optional but recommended: `#devrites-outline` JSON embed planned (generated from outline; outline wins on conflict)
- [ ] CDN dependencies (if any) listed for the outline
- [ ] Claims cite real repo paths when they touch the tree
- [ ] After write: inventory ids present in HTML (`open-visual` warns inventory → HTML mismatches; HTML-only decorative ids are ignored)

## Anti-slop triggers (load polish / playbooks)

When HTML/visual work shows **two or more** of: generic Inter/system font with no
brief justification, hero-only layout, purple/blue gradient CTA with no brand token,
lorem or placeholder copy in shipped states, or identical card grid with no product
hierarchy — load [`rite-polish`](../../../rite-polish/SKILL.md) **ux_coverage** and
craft axes before sign-off.

**Failing case:** visual ships with three slop patterns and no axis record → Review
Important finding.