How to Use the Terminal CLI-Window Variant in Diagram-Design

The terminal CLI-window variant applies a fixed faux-shell aesthetic defined by nine custom CSS tokens in primitive-terminal.md, rendered either via the --variant terminal CLI flag or manual substitution into template-terminal.html.

The diagram-design repository provides an optional terminal skin that wraps SVG diagrams inside a simulated command-line interface window. Unlike standard templates that dynamically inherit brand tokens from style-guide.md, this variant operates as a fixed second-level skin with its own isolated color palette and typography rules, specifically engineered for developer-focused visual outputs.

Architectural Overview

The terminal variant is architecturally distinct from the primary light and dark templates because it intentionally bypasses the onboarding token system. Instead, it relies on a hardcoded set of CSS variables that mimic a classic terminal environment.

CSS Token System

The terminal skin defines nine specific tokens documented in [primitive-terminal.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-terminal.md):

• terminal-page (background)
• terminal-paper (surface)
• terminal-bar (title bar)
• terminal-border (window chrome)
• terminal-ink (primary text)
• terminal-muted (secondary text)
• terminal-soft (subtle fills)
• terminal-accent (highlight)
• terminal-accent-tint (accent variation)

These variables are declared in the <style> block of [template-terminal.html](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-terminal.html), mapping to concrete hex values (e.g., --color-page: #0a0a0a;). When the variant is active, the rendering engine substitutes any default design tokens (like paper or ink) with their terminal-* equivalents, ensuring the diagram colors remain consistent with the shell aesthetic.

HTML Structure and Typography

The base template provides a strict structural wrapper:

• Window Chrome: A div.terminal container featuring a .titlebar with three colored dots (red, yellow, green) simulating the classic traffic-light window controls.
• Prompt Line: A .prompt element displaying a simulated shell prompt (e.g., >) to reinforce the CLI context.
• Typography: All text elements render in Geist Mono, a monospaced typeface required by the terminal specification for authentic command-line appearance.
• SVG Container: The diagram itself injects into a <main class="frame"> element wrapping an <svg> tag with proper role="img" and ARIA attributes.

This structure is demonstrated concretely in [example-loop-terminal.html](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-loop-terminal.html), which shows a complete Loop diagram embedded within the terminal chrome.

Rendering Methods

You can generate terminal-styled diagrams through automated CLI commands or manual template manipulation.

CLI Flag Rendering

The recommended approach uses the diagram-design CLI with the variant flag. According to the skill documentation in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), the terminal variant "replaces any of the above" standard templates when invoked:

diagram-design render \
  --type loop \
  --variant terminal \
  --output example-loop-terminal.html

When executed, the CLI automatically processes the diagram through the terminal token substitution pipeline, outputting a complete HTML file with the faux-window wrapper already applied.

Manual Template Integration

For custom workflows or static site generation, copy the base template and substitute placeholders:

# Copy the terminal scaffold

cp assets/template-terminal.html my-diagram.html

# Replace metadata placeholders

sed -i \
  -e 's/\[file.sh\]/my-script.sh/' \
  -e 's/\[diagram-slug\]/my-custom-loop/' \
  -e 's/\[command that "generated" this\]/diagram-design render --type loop/' \
  -e 's/\[Diagram title\]/My Self-Improving Loop/' \
  my-diagram.html

After substitution, insert your diagram's SVG markup (generated separately without the terminal flag) inside the <svg>...</svg> element of the copied template.

Core Files and References

File	Purpose	Source Link
primitive-terminal.md	Grammar definition, token table, and usage constraints	View on GitHub
template-terminal.html	Base HTML scaffold with CSS variables and window chrome	View on GitHub
example-loop-terminal.html	Concrete implementation showing a Loop diagram in terminal skin	View on GitHub
SKILL.md	Master index listing terminal as optional variant replacing standard templates	View on GitHub

When to Use the Terminal Variant

The terminal skin is strictly intended for developer-oriented contexts such as CLI tool documentation, GitHub repository social cards, and technical blog posts where a command-line aesthetic adds semantic value. According to the reference documentation, it should not be used for long-form editorial content or brand-matched marketing materials because it is a fixed skin that deliberately ignores the project's standard brand tokenization system. Additionally, the specification enforces that only one accent dot may appear in the design to maintain visual hierarchy within the constrained terminal palette.

Summary

• The terminal CLI-window variant uses nine isolated CSS tokens (defined in primitive-terminal.md) rather than the standard brand palette.
• Rendering occurs via the --variant terminal CLI flag or by manually copying template-terminal.html and substituting placeholders.
• The skin enforces Geist Mono typography and a three-dot titlebar structure for authentic shell simulation.
• Use this variant exclusively for technical, developer-focused outputs; avoid for general brand content.

Frequently Asked Questions

How do I switch back to the default light or dark template after using the terminal variant?

Remove the --variant terminal flag from your CLI command. The default rendering pipeline automatically applies the standard token set from style-guide.md. If you manually edited a copied template, revert to template.html or template-dark.html as your base scaffold.

Can I customize the colors of the terminal window chrome?

No. The terminal variant is intentionally a fixed skin that does not inherit customizable brand tokens. The nine terminal colors (page, paper, bar, border, ink, muted, soft, accent, accent-tint) are hardcoded in template-terminal.html to ensure consistency across all terminal-styled outputs.

Where does the diagram SVG actually render inside the terminal window?

The SVG injects into the <main class="frame"> element within template-terminal.html, specifically replacing the placeholder <svg> tag. This container is positioned below the .titlebar and .prompt elements, ensuring the diagram appears inside the faux terminal window while maintaining proper ARIA accessibility attributes.

Is the Geist Mono font required, or can I substitute another monospaced font?

Geist Mono is required. The primitive-terminal.md specification explicitly mandates this typeface to preserve the authentic terminal aesthetic. Substituting other fonts (even monospaced alternatives like monospace or Consolas) violates the grammar rules and may break the visual consistency expected by the terminal skin processor.

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