fabioc-aloha Print SVG Style Guide
Create visual artifacts that survive markdown preview, PDF export, and print.
Scope
Use for:
- SVG figures in documentation
- exported chart SVGs
- print/PDF-ready visual assets
- style guidance for generated figures
- visual consistency across Alex ACT Scout docs
Style rules
| Area | Rule |
|---|---|
| Canvas | Use a clear viewBox and avoid unnecessary whitespace. |
| Typography | Prefer system fonts; keep body labels at readable sizes. |
| Contrast | Meet strong contrast for text and essential marks. |
| Stroke | Use consistent stroke widths; avoid hairlines below print-safe thickness. |
| Color | Do not rely on color alone; labels or direct values should carry meaning. |
| Margins | Leave space for titles, legends, axis labels, and annotations. |
| Export | Prefer SVG for scalable docs, PNG for Scout conversation display. |
| Theme | Define semantic color tokens once and reuse them across SVG, Canvas, HTML, and chart-library marks. |
| Labels | Give labels explicit collision rules; do not rely on the renderer's default label placement. |
SVG hygiene
- Include
role="img"and a useful<title>when authoring standalone SVG. - Keep IDs stable and descriptive when the SVG will be styled or tested.
- Avoid external font and image dependencies.
- Avoid scripts in committed SVG assets.
- Use inline styles or attributes that survive GitHub and markdown sanitization.
- Test the SVG in the target renderer, not just a browser tab.
Chart export guidance
For Flint charts:
- Use
format: "png"when the immediate target is Scout chat display. - Use
format: "svg"when the target is documentation or print and the backend supports SVG. - Use a white or explicit background when the chart will appear in unknown themes.
- Keep titles and subtitles in the chart when the image may be separated from its surrounding prose.
Mixed-renderer gallery guidance
When a visual artifact combines generated charts with custom SVG, Canvas, D3, or HTML widgets:
- Put the active palette and semantic tokens at the top of the script or stylesheet.
- Theme custom tables, legends, badges, annotations, grid lines, range bands, and helper text, not just the chart marks.
- Use alpha variants of palette colors for heatmaps and background bands instead of fixed RGB ramps.
- Keep contrast text intentional: white is acceptable inside dark marks, but fixed gray helper text should usually become a theme token.
- Preserve page position when changing themes or palettes so exploration does not reset the reader to the top.
- Run a browser overflow check on each visual container after changes.
Print readiness checklist
- Open the artifact at 100 percent zoom.
- Confirm all text is readable.
- Confirm the figure still works in grayscale.
- Confirm no marks are clipped.
- Confirm the artifact has enough context if copied alone.
- Confirm file size is reasonable for repository storage.
- Confirm labels do not overlap marks or each other at the intended display size.
- Confirm two representative themes still render coherently if the artifact supports theme switching.
Related skills
render-verifyfor final output inspection.flint-chartfor chart rendering.markdown-mermaidfor diagrams rather than data charts.