Diagram-Design Template Variants: When to Use Light, Dark, and Full

The diagram-design skill provides three SVG template variants—light (minimal white background), dark (dark-mode palette), and full (editorial with summary cards)—that you select via the --variant flag to match your documentation context and visual presentation needs.

The cathrynlavery/diagram-design repository ships with three editorial SVG templates that define every exported diagram's look-and-feel. Selecting the appropriate template variant ensures your diagrams integrate seamlessly with their target platform, whether you're generating internal documentation or publication-ready visuals.

Understanding the Three Template Variants

Each template variant serves a specific visual context while maintaining consistent diagram generation workflows.

Light Template (Minimal White)

The light template is the default variant (--variant=light) located at skills/diagram-design/assets/template.html. It provides a clean white background with only the essential style rules, keeping file sizes small and focusing attention purely on diagram content.

Use the light template for simple diagrams, internal documentation, or any context that already uses a light UI. This minimal approach avoids visual overhead when you need rapid, clean exports.

Dark Template (Minimal Dark-Mode)

The dark template resides at skills/diagram-design/assets/template-dark.html and mirrors the light template's minimal layout while applying a dark-mode colour palette.

Select this variant when the surrounding page or application uses a dark theme, or when you require higher contrast on dark backgrounds. It maintains the same structural simplicity as the light version while preventing eye strain in dark UI contexts.

Full Template (Editorial with Summary Cards)

The full template at skills/diagram-design/assets/template-full.html represents the complete editorial design system. It adds a "summary-cards" panel, richer typography, colour accents, and comprehensive design-system styling.

Deploy the full template for published articles, formal reports, or any situation requiring a polished, magazine-style presentation. This variant excels when you need explanatory cards positioned beside the diagram to provide additional context.

How to Select a Template Variant via CLI

The --variant parameter controls template selection across import commands, as documented in commands/import-mermaid.md and commands/import-drawio.md. The system defaults to the light variant unless explicitly overridden.

Copy a template manually to start a new diagram:

# Minimal light template (default)

cp skills/diagram-design/assets/template.html my-diagram.html

# Minimal dark template

cp skills/diagram-design/assets/template-dark.html my-diagram.html

# Full editorial template with summary cards

cp skills/diagram-design/assets/template-full.html my-diagram.html

Execute imports with specific variants:

# Render Mermaid using dark template

pi import-mermaid diagram.mmd --variant=dark --format=svg

# Render Mermaid using full editorial template

pi import-mermaid diagram.mmd --variant=full --format=html

Source File Locations and Template Architecture

The diagram-design repository organizes templates and command documentation at specific paths:

• skills/diagram-design/assets/template.html – Minimal light template serving as the base scaffold for new diagrams
• skills/diagram-design/assets/template-dark.html – Minimal dark template with dark colour palette
• skills/diagram-design/assets/template-full.html – Full editorial template including summary-card side panels and enhanced styling
• commands/import-mermaid.md – Documentation for --variant options in Mermaid imports
• commands/import-drawio.md – Documentation for --variant options in Draw.io imports

Summary

• Light template: Default minimal white background for simple diagrams and internal docs
• Dark template: Dark-mode palette for dark UI contexts and high-contrast requirements
• Full template: Editorial style with summary cards for published articles and formal reports
• Selection method: Use --variant=light|dark|full with import-mermaid or import-drawio commands, or copy directly from skills/diagram-design/assets/

Frequently Asked Questions

What is the default template variant?

The light template is the default variant when you run import commands without specifying the --variant flag. According to the source code in commands/import-mermaid.md and commands/import-drawio.md, omitting the flag automatically selects --variant=light, providing the minimal white background template located at skills/diagram-design/assets/template.html.

Can I add motion effects to any template variant?

Yes. The repository includes an optional motion controller at skills/diagram-design/assets/template-motion.html that you can apply to any of the three base templates. Copy this file after selecting your base variant to introduce accessible motion controls to your diagram without altering the underlying colour scheme or layout structure.

When should I choose the full template over the light template?

Select the full template when producing content for external publication, formal reports, or presentations requiring explanatory context. Unlike the minimal light template, the full variant includes summary-card panels and richer typography that provide space for annotations beside your diagram, making it ideal for magazine-style layouts where the diagram requires additional narrative support.

How do I switch between variants for existing diagrams?

Change variants by copying the desired template file from skills/diagram-design/assets/ and re-running your import command with the appropriate --variant flag. For CLI-based workflows using import-mermaid or import-drawio, simply append --variant=dark or --variant=full to regenerate the output using the alternative styling while preserving your diagram's structural content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}