SVG authoring

Make complete, readable drawings that survive comparison and export.

Write the drawing the reviewer will actually see and export. A complete candidate contains metadata plus at least one light SVG, as shown in Your first session. This guide takes that structure from a tutorial into a grounded project explanation.

Begin with the explanation

Before drawing, identify the entities, states, and actions the reader needs to understand. Read the relevant implementation or documentation. Preserve exact product labels where the reader must recognize them in the interface.

Keep a shared brief.md for all candidates in a comparison round. State the teaching goal, fixed labels, source references, intended placement, and exclusions. If you vary explanatory structure as well as tone, describe that choice so the reviewer can tell what they are comparing.

The zudo-doc-cloud example provides a useful model. Its brief says that selected changes A and B move into Draft: Guide, while unselected C remains on Workbench. It explicitly omits dependency expansion, blockers, stale previews, and the optional copy mode. That scope gives the author a clear before/after relationship to draw without implying that every collection operation behaves like this successful Move example.

The zudo-ez-host example makes a different distinction: Save and Publish connect three separate places. Collapsing them into one arrow would lose the point of the drawing. Read each example's own brief before adapting its geometry.

Author at a useful coordinate size

Use an explicit viewBox. A reference drawing might use 720 by 400 units and appear at 360 by 200 CSS pixels. That leaves convenient drawing coordinates while keeping the intended display scale clear.

<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 720 400"
     role="img"
     aria-labelledby="diagram-title diagram-description">
  <title id="diagram-title">Example diagram title</title>
  <desc id="diagram-description">The relationship this drawing explains.</desc>
  <!-- Drawing elements and readable labels. -->
</svg>

This snippet shows the SVG wrapper; add drawing elements before using it as a candidate. The first-session SVG is complete, and the tone catalog provides 24 authored visual references.

Make labels work at the target size

Judge line weight, arrowheads, type size, and spacing in the placement preview. A label that reads well at the drawing's coordinate size may become too small in a help dialog.

Prefer short labels that carry meaning. Let surrounding prose hold details that do not need to appear inside the drawing. Check long translated labels if the target product will use another language. Set the intended CSS-pixel dimensions in session.json; enlarging the inspection stage does not change the target. The zudo-text fixture uses a 280 × 156 preview for its 720 × 400 viewBox, so every essential label has to survive substantial reduction.

Provide explicit artwork themes

The viewer loads SVGs as images. Author each asset with the colors it needs to display correctly. Do not assume a host document's CSS custom properties or selectors will style elements inside that image.

Declare the light and dark files separately when both are available:

{
  "assets": {
    "light": "diagram.light.svg",
    "dark": "diagram.dark.svg"
  }
}

This JSON is an assets fragment for candidate.json; both named files must exist in that candidate directory.

Keep meaning consistent between themes. A semantic color used to distinguish a signal, state, or action should remain recognizable when the surrounding palette changes. Background selection in the viewer does not synthesize a missing theme asset. The zzmod study intentionally stays dark in both theme variants so its cyan audio and purple control-voltage paths retain their meaning. A theme filename does not require a pale or dark canvas at the expense of the explanation.

Keep assets complete

Use internal shapes, text, and definitions. Keep IDs and references consistent, and avoid depending on remote images, fonts, stylesheets, or a script to make the SVG intelligible.

Treat exports as complete drawing files. Referenced assets outside the candidate directory cannot be assumed to accompany the exported SVG. The engine validates the asset format and reports unsupported constructs; do not bypass validation by embedding active content.

Accessibility follows the destination

Give the standalone SVG a useful title and description. At integration time, choose the alternative text or decorative treatment based on how the drawing relates to adjacent content.

If the nearby text already states the whole explanation and the diagram is decorative reinforcement, the host may deliberately hide that repetition from assistive technology. If the drawing conveys additional meaning, provide a text alternative that describes it. A file's internal title does not remove the need to check the actual HTML/component integration.

Refine the saved file

Receive the chosen ID and feedback through the conversation or a review export. Browser choices do not write into the workspace. Copy the selected SVG into a later round, give its candidate a new stable ID, and set parentCandidateId to the baseline. Follow the session file example for the round metadata.

Work on that saved geometry. Keep composition, labels, or palette when the user asks to retain them. In the tone-exploration fixture, the illustrative r02-c01 strengthens four connectors from r01-c01 while preserving positions, words, surfaces, and palette. This is an example of a bounded revision, not a user-approved selection.

Run pnpm check in the session after editing. Inspect every declared theme at the target dimensions and compare the new drawing with its parent. Editing a reviewed candidate in place can mark its prior feedback stale; new IDs preserve the actual versions for comparison.

Before integration, inspect the exported asset in the destination's real dimensions and theme. The gallery helps establish a direction; the final application determines the actual surrounding layout and accessibility behavior.

Export and inspect the standalone asset

In the session, export the exact ID and theme you reviewed:

pnpm exec zudo-diagram-gen export r02-c01 \
  --session . \
  --theme light \
  --out selected-diagram.svg

This assumes the refinement above exists. The command copies its declared asset and fails if the requested theme is missing. Open the exported file independently, then check it in the destination component with the intended dimensions and surrounding text. Use the CLI reference for the offline session snapshot and other output commands.