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

> Learn to use the terminal CLI-window variant in diagram-design. Apply a fixed faux-shell aesthetic with custom CSS tokens via CLI flag or HTML template substitution.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-18

---

**The terminal CLI-window variant applies a fixed faux-shell aesthetic defined by nine custom CSS tokens in [`primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md), rendered either via the `--variant terminal` CLI flag or manual substitution into [`template-terminal.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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/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/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/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:

```bash
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:

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md) | Grammar definition, token table, and usage constraints | [View on GitHub](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-terminal.md) |
| [`template-terminal.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-terminal.html) | Base HTML scaffold with CSS variables and window chrome | [View on GitHub](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-terminal.html) |
| [`example-loop-terminal.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-loop-terminal.html) | Concrete implementation showing a Loop diagram in terminal skin | [View on GitHub](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-loop-terminal.html) |
| [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) | Master index listing terminal as optional variant replacing standard templates | [View on GitHub](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) |

## 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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md)) rather than the standard brand palette.
- Rendering occurs via the `--variant terminal` CLI flag or by manually copying [`template-terminal.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). If you manually edited a copied template, revert to [`template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) or [`template-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.