Technical Differences Between Light, Dark, and Full Diagram Variants

The Diagram Design skill generates three static renderings from a single YAML source: Minimal Light uses dark ink tokens on light paper backgrounds, Minimal Dark inverts these tokens for dark mode compatibility, and Full-Editorial adds a publishing wrapper with legends and cards while maintaining the same underlying SVG structure.

Understanding the technical differences between light, dark, and full diagram variants is essential when working with the cathrynlavery/diagram-design repository. Each variant serves a distinct presentation context while deriving from the same YAML specification, ensuring visual consistency across different embedding scenarios.

Semantic Color Tokens and Skin Architecture

The diagram system treats colour as semantic tokens rather than hard-coded values. Tokens such as ink, paper, accent, and muted resolve to different RGBA values depending on the active skin, enabling automatic contrast adaptation without modifying the underlying SVG structure.

Light vs. Dark Token Inversion

In skills/diagram-design/references/type-waterfall.md, the colour implementation demonstrates how the same semantic token produces opposite visual results across skins. The ink token resolves to rgba(45,49,66,0.55) for connector lines in the light variant, creating sufficient contrast against light paper backgrounds. When rendering the dark variant, the identical token inverts to rgba(245,245,245,0.40), ensuring the same connector elements remain visible against dark backgrounds while maintaining relative opacity relationships.

This token-swap mechanism guarantees that contrast ratios remain consistent across both modes without requiring manual colour adjustments for each diagram instance.

The Three Variant Implementations

The rendering engine produces three distinct outputs from a single source of truth, with differences confined to colour token resolution and wrapper composition.

Minimal Light (Default)

The Minimal Light variant serves as the default view for light-background pages. This implementation uses dark ink tokens on light paper backgrounds, limiting the output strictly to the diagram SVG without surrounding framing, legend cards, or additional UI elements. The resulting files are optimized for embedding directly within markdown documents or webpage content areas where external styling handles the container context.

Minimal Dark (Dark Mode)

The Minimal Dark variant provides the counterpart for dark-mode interfaces by swapping each token to its dark-mode counterpart. The ink token becomes a light colour while paper shifts to dark, maintaining the identical SVG geometry while ensuring visibility against dark backgrounds. As documented in the waterfall reference, this inversion applies consistently across all diagram elements, from connector lines to node fills.

Full-Editorial (Publishing Wrapper)

The Full-Editorial variant represents the publishing-ready version used in galleries, documentation, and presentations. According to skills/diagram-design/references/type-waterfall.md, this implementation adds editorial framing including container borders, summary cards, footer bars, and a comprehensive legend that maps semantic tokens to their visual meanings. While the underlying SVG uses the same colour-token system as the minimal variants, the additional wrapper elements provide context and explanatory metadata necessary for standalone presentation.

The legend component specifically ensures diagram comprehension remains consistent even when colour tokens swap between light and dark modes, mapping symbols to their semantic purposes independent of the current skin.

Generation Pipeline and Rendering Process

All three variants originate from a single YAML specification defining nodes, edges, colours, and optional cards. The rendering pipeline follows a consistent sequence:

1. The renderer loads the YAML diagram definition (e.g., type-process.yml)

2. The selected skin (light, dark, or full) determines which colour token set to apply

3. For light and dark variants, the engine outputs only the diagram SVG

4. For full variants, the renderer composes the SVG with the editorial wrapper and generates a complete HTML page

The system includes validation through scripts/verify-skin-polarity.py, which ensures the token-swap mechanism produces correct contrast ratios on both light and dark skins as referenced in the scatter diagram documentation.

Code Examples: Accessing Each Variant

The generated assets reside in skills/diagram-design/assets/ and follow a consistent naming convention. You can link directly to each variant using standard HTML anchor tags:

<!-- Minimal Light (SVG only, dark tokens on light background) -->
<a href="skills/diagram-design/assets/example-polar.html">Polar (light)</a>

<!-- Minimal Dark (SVG only, inverted tokens for dark backgrounds) -->
<a href="skills/diagram-design/assets/example-polar-dark.html">Polar (dark)</a>

<!-- Full-Editorial (HTML wrapper with legend, cards, and framing) -->
<a href="skills/diagram-design/assets/example-polar-full.html">Polar (full editorial)</a>

Each file opens directly in browsers without requiring additional build steps, making them suitable for immediate integration into documentation or presentation decks.

Summary

• Single Source of Truth: All variants derive from the same YAML specification, ensuring diagram consistency across rendering modes
• Token-Based Colour System: Semantic tokens (ink, paper, accent) automatically invert between light and dark skins while preserving contrast ratios
• Minimal vs. Full Architecture: Light and dark variants output SVG-only files optimized for embedding, while the full variant adds editorial wrappers, legends, and metadata cards
• Validation Pipeline: The verify-skin-polarity.py script ensures colour contrast compliance across both light and dark implementations

Frequently Asked Questions

How does the colour inversion work between light and dark variants?

The system uses semantic colour tokens that resolve to different RGBA values based on the active skin. For example, the ink token renders as rgba(45,49,66,0.55) in light mode and rgba(245,245,245,0.40) in dark mode. This token-swap approach ensures contrast ratios remain mathematically consistent without requiring separate diagram definitions for each mode.

Can I use the full editorial wrapper with dark mode colours?

Yes. The Full-Editorial variant supports both colour skins through the same token system used in minimal variants. The editorial wrapper—including legends, summary cards, and container framing—adapts to dark mode when the dark token set is applied, ensuring the legend accurately reflects the inverted colour meanings.

What is the file size impact of choosing the full variant over minimal?

The Full-Editorial variant generates larger HTML files because it includes the SVG plus additional structural elements such as legend markup, summary cards, and container divs. The minimal variants output SVG-only files optimized for smaller footprint and faster embedding within existing page layouts.

Where does the source of truth reside for these diagram variants?

The authoritative definition lives in YAML files within the repository (e.g., type-process.yml), which define all nodes, edges, and optional metadata. As documented in skills/diagram-design/references/type-process.md, these YAML files serve as the single source of truth, with the rendering engine applying different style tokens and wrapper options to produce the three final variants.

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