SKILL.md — generate isometric drafting-style architecture documents (single-file HTML, monochrome, SVG block-chart)

SKILL.md

Isometric Architecture Documentation

Produce a single, self-contained HTML file (no external assets, no build step) that documents a software system in the visual language of engineering schematics and retro-computing manuals. The result should read like a photocopied drafting sheet: stark, mechanical, monochrome.

When to use

• The user asks for an architecture / design / technical report as HTML.
• The deliverable is meant to be shared as one file (opened locally, attached, or hosted statically).
• The content is structural: components, data flows, ownership boundaries, capacity, phasing, risk registers.

Not for: marketing pages, dashboards with live data, or anything that needs color to convey meaning (this style is deliberately monochrome).

1. Global style tokens

Hard rules:

• Two colors total. If you are tempted to add a third, add a border instead.
• Monospace everywhere, including headings, nav, table cells, and in-SVG labels.
• All headings uppercase with letter-spacing (.08em–.12em) — drafting lettering.
• No floating text. Everything lives inside a border: 1px solid compartment.
• No font-weight emphasis in prose. Emphasis = the inverted .hl span, sparingly (one or two per section, at the load-bearing sentence).

2. Document architecture (top to bottom)

1. Sticky header — a persistent top bar of metric cells separated by thin vertical borders (display: flex; cells with border-right). Each cell is KEY (small, uppercase, ~60% opacity) over VALUE (bold). 5–8 cells: project name, scale, counts, status. This is the "instrument strip."
2. Title block — a drafting-sheet title block: a bordered grid (grid-template-columns: 2fr 1fr 1fr) with the document title, doc number, revision, date, and scope. Give every document a DOC NO and REV; it costs nothing and sells the aesthetic.
3. Bill of Materials (front nav) — a bordered table that doubles as the index. Columns: REF | DESCRIPTION | VALUE/QTY. Group rows (inverted-background cells) per section. Every row is an anchor link to its section id. Assign each section a short alphanumeric ref (A1, B3, C7) and echo that ref in the section heading — the cross-referencing is what makes it feel like a real schematic.
4. The Master Blueprint — one large isometric SVG block-chart of the whole system (section 3 below), wrapped in a bordered figure with a caption strip (FIG. N — TITLE) and a legend strip along the bottom.
5. Detail sections — sequential, scrollable compartments (section 4 below).
6. Footer — inverted-caps line: doc number, revision, one-line summary, date.

Target 2–3 logical screen lengths of continuous scroll. No tabs, no page reloads.

3. The isometric block-chart (the centerpiece)

Render as inline SVG, generated by a small inline (cleaner than hand-writing coordinates, and adjustable by editing constants).

Projection — strict isometric parallel, no vanishing points:

const U = 42;                          // unit size in px
const OX = 260, OY = 125;              // origin offset on screen
const C = Math.cos(Math.PI / 6);       // cos 30°
const pt = (x, y, z = 0) => [
  OX + (x - y) * C * U,                // screen x
  OY + (x + y) * 0.5 * U - z * U       // screen y (z grows upward)
];

Blocks are cuboids, and the geometry must be honest:

• Each node occupies a footprint (x, y, w, d) on the floor plane and rises to a height h along Z. Height encodes a real metric — pick one and say so in the legend (system weight, criticality, data volume, request rate). The tallest tower should be the source of truth or the most critical component.
• Side faces (the two visible vertical faces) filled with a diagonal hatch pattern:

• Top faces are flat, light-colored planes (#f2ecd9, slightly stronger stroke) carrying one centered monospace label — a short code (PG, API, CACHE), not a full name. Full names go in the legend or a side annotation.
• Draw traces before blocks so lines disappear under towers.

Routing rules (this is where it stops looking like a flowchart):

• Connections are thin solid polylines running on the floor plane (z = 0).
• Lines only turn along isometric axes — a 3D 90° turn reads as 120° on screen. Never draw a diagonal-on-screen line that isn't axis-aligned in 3D space.
• Put a small solid circle (r≈3) at each bend and each endpoint — transit nodes, like pads on a PCB.
• Enclose the whole cluster in a dashed rectangle on the floor plane (stroke-dasharray="6 4") — the system boundary / ground plane.
• Annotate sparingly with tiny uppercase notes (font-size ~9–10px, ~75% opacity).

Sanity-check the layout: towers must not overlap on screen, labels must not collide, and the composition should fit the viewBox with margin. If it's cramped, move footprints apart in floor coordinates — don't shrink the type.

4. Detail sections

Each section is a bordered compartment:

  
A1 — Section TitleREF A1 / QTY
  
    
    
  

• The h2 is an inverted (black) bar with the section ref on the left and a REF / VALUE code on the right — sheet-header style.
• Long sections end with a two-column split: OVERVIEW (concept, trade-offs) and IMPLEMENTATION (concrete mechanism), divided by a vertical border.
• Flows render as monospace one-line traces, not diagrams: NODE →(STOP)→ NODE, where nodes are bold and "stops" (actions/events) are small labeled pills. Horizontal scroll is acceptable on narrow screens.
• Tables have black inverted header rows; first column often uppercase.
• Callouts are bordered boxes whose caption is an inverted tab (FINDING, NOTE, REJECTED, RULE) punched into the top border.
• Sequences (phases, hazards, rules) render as striped rows: a black inverted ID cell (P0, H1, R1) on the left, content on the right.

5. Content discipline

The style only works if the document behaves like an engineering artifact:

• Every section states its quantity in the BOM and heading (SOCKETS: 2, 4 HAZARDS) — forces you to enumerate instead of wave hands.
• Name the decision, not just the choice: include the rejected alternative with its rationale as a first-class section (REJECTED: …).
• Prefer tables and traces over paragraphs; paragraphs top out at 3 sentences.
• Identifiers, event names, and env vars in code spans — the monospace grid makes alignment visible, so keep padding/units consistent.

6. Delivery checklist

Before finishing, verify:

• Opens correctly from file:// with zero network requests (fonts fall back to system monospace).
• Sticky header cells don't wrap into garbage on ~700px width; sections collapse to one column below that.
• SVG renders in Chrome + Firefox; the inline generator script runs on load.
• Every BOM row anchors to an existing section id; every section heading echoes its ref.
• Exactly two colors in use; emphasis is inversion only.
• Block heights are labeled with what they encode, in the legend.
• Doc number, revision, and date present in title block and footer.