HTML Widget

One system map on one screen: sources on the left, a glowing core in the middle, deliverables on the right, and a machinery box underneath. Hovering a node lights up its connection, dims the rest, and explains it in a tooltip card.

Built for a projector. One fixed 16:9 coordinate space that scales with pure CSS, so it looks the same at 1280×800 and 1920×1080. No build, no server, no external calls — a double-clickable file.

⛔ Only permitted workflow

Never write the widget from scratch. Always start from whichever of the four files in references/examples/ is closest to your content — they are finished, debugged starting points: the curve geometry, tooltip placement, idle cycle, and scaling are all fixed through actual testing in a browser. From scratch, you lose all of that, and every entry in Pitfalls comes back.

Steps 1–3 are questions to actually ask — batch them into one message — before touching any file, even when the request is a single terse instruction like "run the system-map skill on X" with no preferences stated. A prompt that doesn't mention a palette or a language is not the same as the user having no preference; it means you haven't asked yet.

1. Ask the user which of the four examples is the closest match for their content (or pick for them if it's obvious from context), and read that file into context.
2. Ask which color direction they want — see references/palette.md for the four options. Default to Neutral only if, once asked, the user says they don't care.
3. Ask whether they want a second language. Default is English only, with no language-switching machinery at all. If they want a second language, see "Adding a second language" below.
4. Clarify the content with the user (see Content model).
5. Run scripts/layout.py <left-count> <right-count> if the number of nodes changes. It prints finished coordinates, <g> blocks, and CSS rules. Use every block it prints, not just the curves. Change the curves without the nodes' top: values and the curves end up in one place, the nodes in another — the bug looks like "the curves are floating loose" and is easy to miss in a screenshot.
6. Swap in text, icons, and nodes. Keep all the CSS machinery.
7. Run scripts/selfcheck.js in the browser at both 1920×1080 and 1280×800. Everything must be ALL PASS before you ship it. See Verification.

Content model

Columns don't need equal node counts. The band is the same, so different density still reads as two equally tall blocks.

The bottom box's two rows carry a point the reference examples make on purpose: row 1 is the units, row 2 is the pattern that repeats in each of them. Use that structure when it fits, and collapse to one row when it doesn't.

Every tooltip opens with a bold sentence that's the whole point, then one to three sentences of detail. Fact-check every name and number against the source before shipping — a system map with a wrong detail is worse than no system map.

Keep the core's visible label short (one or two words). A long label widens the core's bounding box enough to collide with the nearest tooltips — see self-check H. Put the fuller description in the aria-label and the .ctip text underneath instead.

Geometry

Everything is measured in a 1600×900 space. The scaling is pure CSS, no JS:

--u: calc(min(100vw, 177.78vh) / 100);   /* 1u = 1% of the stage width */
.stage{width:min(100vw,177.78vh);aspect-ratio:16/9}

The SVG layer uses viewBox="0 0 1600 900" and scales itself. Nodes are positioned in %. All typography is set as calc(var(--u) * n).

Fixed anchor points: the core at (800, 395) with radius 58, the node band at y 200–590, the left column at x 56–368, the right column at x 1232–1544, the bottom box at y 645–872.

The column width of 312 (19.5%) is set by the longest label you actually use, not by aesthetics. Check your longest label against it — self-check F requires at least 8px of clearance, in every language you support. Need longer labels, increase COL_W in layout.py and regenerate the curves — don't shrink the font size, it's set for projector readability.

The curves are hand-drawn beziers between fixed points. That's why the layout is fixed rather than responsive: a fluid layout would need JS that measures the nodes and recomputes the curves on every resize. Let layout.py compute them.

Tooltip placement

Tooltips are the part most likely to end up off-stage. The rules:

The bottom box's tooltips are centered on the chip, but the tooltip is 30u wide against a chip under 10u. At the edge of the row it then runs out past the node columns. The rule that fixes it, regardless of chip count:

.chip:first-child .tip{left:0;right:auto;transform:none}
.chip:last-child .tip{left:auto;right:0;transform:none}

The bottom box's tooltip has to clear both the core's underside and the box's top edge. If it gets too tall, make it wider rather than moving it — a wider card gets shorter.

The tooltip covers the middle part of the curve it explains. That's intentional and matches the reference examples' behavior; the alternatives collide with something worse.

Adding a second language

Default is one language (English) and zero language machinery. If the user wants a second language, add this on top of an otherwise-finished widget:

1. Set data-lang="en" on .stage: <main class="stage" data-lang="en">.

2. Wrap every piece of text that actually differs between the two languages in a pair of spans, using the second language's two-letter code (no, fr, de, whatever the user asked for) instead of en:

   <span class="tr tr-en">Customer request</span><span class="tr tr-CODE">…</span>

   Only wrap strings that actually differ. Folder names, filenames, and proper nouns are usually identical in both languages — leave them as plain text.

3. Add the display-toggle CSS (CODE is the language code from step 2):

   .stage .tr{display:none}
   .stage[data-lang="en"] .tr-en{display:contents}
   .stage[data-lang="CODE"] .tr-CODE{display:contents}

   display:contents is deliberate — the wrapper disappears from layout, so flex-gap on nodes and display:block on <b> inside tooltips behave the same in both languages. display:inline would add an extra flex item.

4. Add the language buttons and the L keyboard shortcut:

   <div class="lang"><button data-set="en">EN</button><button data-set="CODE">CODE-UPPER</button></div>

   .lang{position:absolute;left:2.4%;bottom:2.6%;display:flex;gap:calc(var(--u)*.35);z-index:30}
   .lang button{font-family:inherit;font-size:calc(var(--u)*.82);letter-spacing:.07em;
     padding:calc(var(--u)*.3) calc(var(--u)*.8);border-radius:calc(var(--u)*.38);
     border:1px solid rgba(255,255,255,.12);background:transparent;color:var(--txt-3);
     cursor:pointer;transition:.22s}
   .lang button:hover{color:var(--txt-2);border-color:rgba(255,255,255,.28)}
   .stage[data-lang="en"] .lang button[data-set="en"],
   .stage[data-lang="CODE"] .lang button[data-set="CODE"]{
     color:var(--accent);border-color:rgba(var(--accent-rgb),.5);background:rgba(var(--accent-rgb),.10)}
   .lang button:focus-visible{outline:none;box-shadow:0 0 0 2px rgba(255,255,255,.4)}

   <script>
   var stage = document.querySelector('.stage');
   function setLang(l) {
     stage.dataset.lang = l;
     document.documentElement.lang = l;
   }
   document.querySelectorAll('.lang button').forEach(function (b) {
     b.addEventListener('mousedown', function (e) { e.preventDefault(); });
     b.__mdGuard = true;
     b.addEventListener('click', function () { setLang(b.dataset.set); });
   });
   addEventListener('keydown', function (e) {
     if (e.key === 'l' || e.key === 'L') {
       setLang(stage.dataset.lang === 'en' ? 'CODE' : 'en');
     }
   });
   </script>

   The mousedown → preventDefault() guard matters: without it, a mouse click gives the clicked button focus, and the very next keypress makes the browser treat the session as keyboard-driven, so the focused button matches :focus-visible and inherits the selected button's accent color — both languages end up looking selected. b.__mdGuard = true is what lets self-check D confirm the guard is actually attached (event listeners are otherwise invisible from JS).

5. Update the hint text and <title> to mention the language switch, and translate every wrapped string.
6. Re-run scripts/selfcheck.js — it detects the .tr-CODE classes automatically and runs checks E (language pairs) and F–H once per language. If you want automatic detection of untranslated leftover text, write your own probe for your specific two languages — the check isn't generic across arbitrary language pairs, so it isn't built in.

Palette

See references/palette.md for the four color directions (Neutral, Ember, Signal, Volt) and their exact variable values. Every glow, shadow, and gradient color in the stylesheet is written as var(--accent) or rgba(var(--accent-rgb), alpha) (and the -2/-3 equivalents) — swap the six variables in :root and the whole widget recolors, including the gradient (wired through the .stopA/.stopB/.stopC classes on the <stop> elements).

Ask the user which direction fits before you build, or default to Neutral.

Pitfalls

All of these are real bugs from building the reference examples, found in a browser. The right column shows which self-check catches them again.

Verification

Paste scripts/selfcheck.js into the browser console on the widget. Run it at both 1920×1080 and 1280×800. ALL PASS is required before you ship it.

Don't cherry-pick individual checks from here and run them by hand — the whole reason this file exists is that manual partial checks let three bugs through in a row. Run the whole file, at both resolutions.

Check C and D require group buttons to set b.__mdGuard = true where the mousedown guard is attached. Without the flag, the test can't see it — event listeners are otherwise invisible from JS.

Beyond the self-check, which is still manual: zero console errors, and fact-check every name and number in the tooltips against the source.

About the preview panel

Two things that look like bugs in the widget but are the panel:

• A mouse click lands in the wrong place. The tool reports one coordinate and the page receives another. Use read_page + ref, or test by keyboard.
• Style changes on a single element don't re-layout. el.style.top = … changes the style attribute without getBoundingClientRect() moving. An injected <style> does work. If you want to sabotage layout to test it, do it through a stylesheet or by changing a curve's d.

Files