| name | validate-branded-doc |
| description | Validate canonical review-doc source and rendered HTML across layers — JSON Schema, Mermaid syntax/render, accessibility (Axe/WCAG AA), responsive layout, and print/PDF. Use before sharing or committing a branded review artifact, in CI, or as a pre-commit hook. |
validate-branded-doc
Layered validation for branded review documents. Schema validation runs first
and short-circuits the rest on failure — a structurally invalid artifact never
reaches the Mermaid, accessibility, responsive, or export checks.
When to use
- Before rendering/sharing a review artifact.
- In CI on changed canonical source files.
- As a pre-commit gate (schema + Mermaid are fast and dependency-light).
Layers
| Layer | Script | Pass condition |
|---|
| Schema | scripts/validate_schema.py | all required fields + enums valid (base + overlay) |
| Mermaid | scripts/validate_mermaid.mjs | every diagram parses (add --render for mmdc render in CI) |
| Accessibility | scripts/validate_accessibility.mjs | zero critical Axe violations; contrast ≥ WCAG AA |
| Responsive | scripts/validate_responsive.mjs | no horizontal overflow at desktop + mobile |
| Print/PDF | scripts/validate_export.mjs | PDF exports with ≥1 readable page; print completeness — every tab pane and details body visible, screen-only controls hidden |
For sources declaring theme.mode: dark or auto, an additional
accessibility-dark pass runs under dark color-scheme emulation
(--color-scheme dark) with the same WCAG AA thresholds.
The accessibility layer also runs widget checks: tabs keyboard-operable with
associated labels, diagram zoom toggles carry accessible names, and severity /
callout tag contrast is enforced via Axe's WCAG AA color-contrast rule.
Quick start
Run the whole suite (renders HTML automatically if --html is omitted):
python .claude/skills/validate-branded-doc/scripts/validate_all.py \
--input examples/architecture-review.yaml
Validate the same source under an explicit skin (matrix testing in CI):
python .claude/skills/validate-branded-doc/scripts/validate_all.py \
--input examples/architecture-review.yaml --skin editorial
Run a single layer:
python .claude/skills/validate-branded-doc/scripts/validate_schema.py --input source.yaml
node .claude/skills/validate-branded-doc/scripts/validate_mermaid.mjs --input source.yaml --render
node .claude/skills/validate-branded-doc/scripts/validate_accessibility.mjs --input doc.html
Behavior notes
- Short-circuit: a schema failure marks downstream layers
SKIP and fails the run.
- Graceful degradation: HTML layers need optional Node deps (
playwright,
@axe-core/playwright). When absent they report SKIP (not FAIL) so the
schema + Mermaid gate still works offline. Install deps to enforce them — see
the renderer skill's setup notes.
- Exit codes:
0 all pass, 2 any explicit failure. SKIP never fails the run.
- JSON output: pass
--json for machine-readable reports (CI).
Dependencies
- Python (project
.venv): jsonschema, pyyaml, referencing.
- Node:
playwright, @axe-core/playwright; optional @mermaid-js/mermaid-cli for --render.
