Dark Terminal Document Design System

Why this skill exists

Standard markdown renders poorly in meetings, portfolios, and async handoffs. Notion exports are generic, Confluence is ugly, and spinning up a React/Next.js site for a one-off comparison table is overkill. This skill produces a single self-contained HTML file — no dependencies, no build step, no framework — that looks like a polished internal developer tool: dark IDE aesthetic, dense tables, semantic status colors. The output opens directly in any browser, can be emailed as an attachment, or dropped into GitHub Pages.

Naive approaches fail because: ad-hoc inline styles drift from the design system, font loading order breaks the monospace/sans split, and brand accent colors used directly in body text create contrast issues (they need pastelizing).

Workflow

1. Confirm the document type from the user's request:
   • Comparison doc (two subjects side by side) → use all columns + summary cards
   • Reference/cheatsheet (one subject, many rows) → Command / Syntax / Description
   • Changelog/release notes (chronological) → Change / Impact / Description
   • Feature breakdown (one product, feature × status) → Feature / Status / Notes
2. Identify brand colors for comparison docs. For single-subject docs, pick one --brand-a accent and omit --brand-b.
3. Load the CSS design system from references/css-design-system.md and copy the token block verbatim. Override only --brand-a and --brand-b.
4. Use the HTML skeleton from references/html-skeleton.md. Fill section headers with emoji prefixes. Every row that has a clear winner gets a winner-badge after the explanatory text in the notes column.
5. Write the file as a single .html file using the Write tool. No external CSS files, no JS frameworks, no CDN scripts (Google Fonts import is the only external call — degrades gracefully offline).
6. Verify by describing the output structure to the user — number of sections, rows, and which brand wins the summary (for comparison docs).

Hard Rules

1. Always produce a single self-contained .html file. No external CSS files, no JavaScript frameworks, no CDN scripts beyond the Google Fonts import.
2. Never use solid backgrounds for tags or badges. All fills must use rgba with 12–15% opacity so the dark --bg bleeds through.
3. Brand accent colors (--brand-a, --brand-b) must be pastelized for body text in data cells. Using the full-saturation color directly on body text causes glare and contrast issues.
4. Winner badges belong in the notes column, after the explanatory text — badge is a visual summary, not a lead-in.
5. Never use light backgrounds, Inter/Roboto fonts, purple gradients, glassmorphism, or rounded hero cards. This is a terminal aesthetic, not a marketing page.
6. Never drop the generic font fallback. 'Syne', sans-serif and 'IBM Plex Mono', monospace keep the page readable when the Google Fonts import is blocked — offline, behind a proxy, or under a strict Content-Security-Policy. The import is the one permitted external call precisely because it degrades; a bare font-family: 'Syne' does not.
7. No harness features. The output is a .html file opened from file://. It requires no agent runtime, no skills, no subagents, no build step — and must keep requiring none.
8. Summary cards are mandatory for comparison docs — three boxes: brand-a wins / brand-b wins / tie. Single-subject docs (cheatsheets, changelogs) may omit them.
9. Max-width is 1200px throughout, not 960px — comparison tables need horizontal breathing room.
10. Section headers must use text-transform: uppercase, letter-spacing: 2px, and an emoji prefix to create visual rhythm and scanability in long tables.
11. Diagrams use the canonical dark Mermaid palette — the init line from config/docs/mermaid-init.txt per rules/dev/documentation-standards.md — unless the user asks for another palette for this document.

What NOT To Do

Quick-Reference Checklist

Before handing off the HTML file, verify:

• Single .html file — no external dependencies except Google Fonts import
• CSS variables match the token reference exactly (--bg, --surface, --surface2, --border, --text, --muted, --yes, --no, --partial, --brand-a, --brand-b)
• --brand-a and --brand-b overridden to match the document's subjects
• Table header columns use th-brand-a, th-brand-b, th-meta classes
• Data cells use col-brand-a/col-brand-b with pastelized hex values, not full-saturation vars
• Section headers: uppercase, 2px letter-spacing, emoji prefix
• Tags use rgba fills (not solid colors)
• Winner badges placed after explanatory text in notes column
• Summary cards present (for comparison docs only)
• Subtitle under h1 in IBM Plex Mono with // title · date pattern
• max-width: 1200px on all top-level containers
• border-radius: 16px on .table-wrap

Reference Files