Diagram Design: evidence-driven visual explanations
Diagram Design architecture: progressive references and independent validation contracts
Trace how requests select semantics and layout, then distinguish appearance, geometry, motion and metadata checks instead of calling them one quality gate.
What you will learn
- Load the references that explain this request
- The artifact carries several different contracts
- Pinned behavior still requires review
Before you start
- Basic HTML and SVG concepts
- Ability to distinguish a system relationship from its visual layout
Choose a useful representation, account for simplification and interpret checker findings within their real scope.
Key takeaways
- Reference selection is part of the authoring architecture.
- Geometry, metadata and motion checks establish different facts.
- Matching a pinned controller does not replace reviewing its source.
Load the references that explain this request
The documented loading model exposes a short name and description first, loads the main skill for a matching request, and then reads relevant type or behavior references. A simple flowchart and a branded Mermaid redraw do not need the same context. This is a routing design, not a measured claim about token savings across every agent host.
A request with meaningful system behavior selects a semantic pattern before its layout family. Import adds extraction and output-spec references; optional motion adds its own contract. The shared package therefore grows through specialized documents instead of putting every example and rule into a single prompt that every task must read.
The artifact carries several different contracts
HTML is the upstream authoring source of truth, with inline SVG and optional structured attributes. The traceable-block pattern keeps a small visible label while storing richer block identity and parent information as metadata. Its registry sidecar is generated from that metadata rather than maintained independently as a competing description.
Different validators answer different questions. Rectangle geometry checks a specific paint-order collision; block validation checks identifiers, parent resolution and cycles; motion checks controller identity and structure. A coherent metadata tree can still be drawn misleadingly, and a clean rectangle report cannot establish correct labels or truthful component relationships.
Pinned behavior still requires review
For optional motion, the design permits one reviewed controller whose content matches the template in the same revision. The architecture record explicitly notes that changing both template and copies can preserve the identity check. Source review therefore remains necessary; matching bytes prove consistency with that template, not universal security.
Static defaults provide a useful baseline for documents that must remain understandable without interaction. An application requiring arbitrary click handlers, live data or a custom 3D explorer is a separate product design, not a small per-diagram controller tweak supported by this contract. Keep those requirements explicit before choosing the package.
Implementation steps
- 1
Trace request routing to the relevant references.
- 2
Identify the authoritative artifact and derived exports.
- 3
Map each checker to its exact guarantee.
- 4
Review requirements that fall outside the static or pinned-motion contract.
Copy-ready example
request -> skill -> semantic pattern -> visual type
+ output spec / profile / import reference
|
HTML + SVG
|
geometry | metadata | motion checks
|
rendered human reviewFrequently asked questions
Does the block registry prove the picture matches implementation?
No. Structural metadata checks establish properties such as unique IDs and valid parents. Correspondence with source code and drawn geometry requires separate review.
Can each diagram customize the motion script?
The documented contract permits the exact reviewed controller, not arbitrary per-diagram modifications. Bespoke interaction is outside that contract.
Sources
- docs/adr/0001-static-by-default-single-pinned-controller.mdSource checked 2026-09-08
- docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.mdSource checked 2026-09-08
- docs/adr/0010-block-registry-metadata-contract.mdSource checked 2026-09-08