architecture-viz-studio

# Architecture Visualization Studio Build pages that make software architecture and ideas *felt*, not just diagrammed. The goal is output that makes a viewer think "I've never seen our company's work look like this" — polished, animated, professional, **not AI-slop**. This skill bundles the hard-won code and taste from a long real build so you assemble from proven parts instead of rediscovering them. ## The two deliverables (often combined on one page) 1. **Scroll-story** — a fixed 3D low-poly world (Three.js) that the camera flies through as the user scrolls (GSAP ScrollTrigger). A request/object travels the world; sections reveal over it. For stakeholders to *feel* the product. → templates in `assets/scene/` + `assets/scroll/`. 2. **Architecture map** — a dark "blueprint" SVG system map with switchable **overlay lenses** (one map, N aspects: Systems / Data Flow / Ownership / Reliability / …), **clickable nodes** that open drill-down component diagrams, and an **ERD** for the data model. For architects to explore. → `assets/diagrams/`. Both are **design-system aware** (adapt to provided brand colors/fonts/logos; degrade to tasteful neutral defaults) and ship with **edit mode** (`assets/edit-mode/`). ## Workflow Treat this as: **brainstorm the narrative → scaffold → assemble from templates → polish → verify → enable edit mode.** 1. **Understand the system and pick the metaphor.** Read whatever design docs/PRD the user has. Decide what the scroll-story narrates (the journey of one entity through the system is a strong default) and what the architecture map's nodes/lenses are. If the 3D "world" metaphor doesn't fit the domain, say so and lean on the 2D diagrams (see `references/diagram-catalog.md` → "3D world metaphor: lands vs gimmicky"). 2. **Establish the design system BEFORE building — ask, don't assume.** Consistent visuals come from deciding the tokens once, up front. Unless the user already gave you a brand/design system, **ask them at the start** (a short, concrete intake — don't make them write a spec): - **Brand colors?** Primary/accent hex, or a logo/site to pull from. (If none, you'll propose one reserved accent + neutral greys.) - **Fonts?** A display + body pairing, or a brand font. (If none, you'll propose a tasteful pairing — not Inter-everywhere, which reads as AI slop.) - **Logo / wordmark?** To place in the nav. - **Aesthetic?** The two looks that read as professional here: the **dark "blueprint"** (architecture maps) and the **pale low-poly 3D world** (scroll-stories). Confirm which, or both. - **An existing page/screenshot to match?** The fastest path to consistency — extract its palette, type scale, spacing, and radius and mirror them. If the user has nothing, **don't silently default** — propose a concrete design system (show the accent + font pairing) and get a thumbs-up, OR point them at `references/finding-layout-inspiration.md` to pick a direction. Then wire the agreed tokens into the `:root` block in `assets/page-shell/styles.css` (`--primary-500`, `--neutral-*`, font vars) **before** building any component — so every piece is consistent from the first line. **Read `references/styling-and-anti-slop.md` now** — it is the difference between professional and slop, and it's cheap to get wrong. Capture the decision in a short `DESIGN-SYSTEM.md` next to the page so later edits (and the next session) stay consistent — see `references/styling-and-anti-slop.md` → "Design-system intake" for the token checklist. 3. **Scaffold from the page shell — and study the sample first.** `sample/` is a small but **complete, fully-debugged** scroll-story page that applies every convention correctly (render-on-demand 3D scene, every text element tagged, `vizSelectable:false` on the backdrop, edit-mode + manifest wired, anti-slop styling). Read it before building — it's the fastest way to see how the pieces fit, and it already avoids the bugs in `references/gotchas-and-lessons.md`. Then copy `assets/page-shell/index.html` + `styles.css` as your skeleton (section structure, importmap, modal scaffolds, token block) and pull in only the modules you need: - 3D world → `assets/scene/scene-setup.js`, `primitives.js`, `render-loop.js`. **These ship studio-grade by default** — `scene-setup.js` already wires the Biggest-5 lighting foundation (sRGB+ACES, PMREM/ `RoomEnvironment` IBL, a three-point rig **with a rim light**, FogExp2, a `glowMat()` for accents and a deep moody default palette). Don't strip it back to a single sun + ambient — that flat rig is the #1 amateur tell. Tune the numbers (frustum to your world size, palette to your brand); keep the structure. - ⭐ post-processing (Biggest-5 #3) → `assets/scene/post-processing.js` — OPTIONAL selective bloom + grain + vignette + SMAA. Wire it with `setComposer()` (the page-shell import graph shows the 3 lines). It needs the `postprocessing` importmap entry (already in `page-shell/index.html`; **must** be the raw `build/index.js`, not `/+esm`, or you get two three instances and bloom breaks). This is the last 20% of "wow" — add it for hero scenes, skip it for lightweight pages. - scroll choreography → `assets/scroll/scroll-journey.js` — ships a **Lenis smooth-scroll layer by default** (the `lenis` importmap entry is already in `page-shell/index.html`). This is what makes mouse-wheel scrolling glide instead of jerk/freeze — `scrub` alone does NOT fix that. Tune `duration` for feel; it's off under reduced motion. See the playbook → "Smooth scroll" for the why. - architecture map lenses → `assets/diagrams/overlay-lens-system.js` (`initOverlays` → the `drill` flag) - drill-down component diagram → `assets/diagrams/component-detail-modal.js` (`initDrill` — `data-drill` nodes) - ERD → `assets/diagrams/erd-diagram.js` (`initErd` — `data-erd` nodes; bundles the whole open/close/ draw-on-double-rAF/pause lifecycle, so you don't re-derive it; pass `intro`/`columns` to fit your schema) - pan/zoom on any diagram → `assets/diagrams/pan-zoom-viewport.js` - selectable arrows → `assets/diagrams/edge-hit-proxies.js` (`tagSvgEdges`) — gives every thin SVG edge a wide transparent hit area so it's clickable in edit mode (otherwise a 2px arrow is nearly impossible to select). Call it once per SVG (main map + each drill/ERD modal, after render). These are wired with one line each — see the import graph in `assets/page-shell/index.html`, and `sample/` for a complete, genericized instance (a neutral CDN domain — copy the wiring, swap the copy/data). 4. **Build with the AI-tweakable convention from the start.** This is not optional polish — it's what makes the page revisable. **Every DOM component gets `data-viz-id="dotted.name"`; every 3D object gets `registerVizObject(obj, 'scene.name')`.** And tag **every text element**, not just containers — headings, paragraphs, nav links, the footer/header text, badges/numbers each get their own dotted id (`card.audit.title`, `footer.copyright`). Edit-mode can only select a node that carries its own id, so untagged text isn't pointable — hovering it just grabs the whole card. Use small named builder functions (one per object), grouped layout constants at the top, config objects over deep nesting. Read `references/ai-collaboration-protocol.md`. The reason: when the user gives feedback later, the edit-mode tool hands you exact ids, and you map each id straight to its builder — no guessing which "box" they meant. 5. **Choose layouts deliberately.** Don't default to generic arrangements. For each diagram consult `references/diagram-catalog.md` — it has the right layout per situation (e.g. ERD → hub-and-spoke so lines never cross; pipeline → horizontal band with annotations dropping below; system map → region lanes + overlay lenses). Edge routing rules (even anchor distribution, crow's-foot at the "many" end, cardinality at endpoints, labels following the arrow) are in that doc too — they were earned through many revisions. 6. **Verify in a real browser — and run the checks.** This is mandatory; these pages are visual and animation-timed, so you cannot confirm them by reading code. Serve locally (`python3 -m http.server`) and drive it with the chrome-devtools tools: screenshot each scroll state and each overlay/modal, check the console is clean. Then run the bundled checks for the objective layer a screenshot misses: - `node scripts/verify.mjs <url> --out report.json --shots shots/` — console, layout probes across 3 viewports (overflow / overlap / text-clipping), axe-core a11y+contrast JSON, a real check that the WebGL canvas actually rendered, and scroll **jank/CPU** (not fps — headless fps is not representative). - `node scripts/slop-lint.mjs <url> --json slop.json` — the mechanical AI-slop tells (see anti-slop bar). - `node scripts/text-audit.mjs <url>` — fails if any text element lacks its own `data-viz-id` (so the user can point at every heading/paragraph/footer line, not just containers). ⚠️ It only sees the **static** page — it never opens the drill/ERD modals, so it reports their JS-rendered bodies as clean when they're untagged. **Audit popups LIVE too** (open each modal, walk it for text nodes without their own id; different drill tabs can have SEPARATE rail builders) — see visual-verification. - **For a 3D geometry bug** (head off the tip, a gap, a cap not covering, an object mis-placed), don't eyeball screenshots — **reach into the live scene and MEASURE** (capture the page's `{THREE,scene,camera,renderer}` ctx, compare world/screen positions; freeze the render loop before posing a custom camera). The technique is in `references/visual-verification.md` → "Reaching INTO the live scene"; it's what ends the guess-and-check loop. - **Re-check with a HARD reload** (cache-bypass) — the page caches `main.js`/`styles.css`, so a plain reload serves the stale bundle and your just-applied fix looks like it did nothing. A clean run is a **floor** ("nothing mechanically broken, no slop markers"), not a ceiling. The taste calls — does the metaphor land, does it feel premium, is the motion tasteful — still need your eyes and the user's. Read `references/visual-verification.md` for the exact stack and the honest human boundary. (Scripts need Playwright: `npm i -D @playwright/test axe-core && npx playwright install chromium`.) **If the page has a Three.js scene, TWO checklists are MANDATORY before you call it done:** ⭐ **(a) The WOW quality gate** (`references/wow-quality-bar.md` → "The Biggest-5"). "No bugs / clean verify" is the FLOOR, not the bar — the user expects something a professional 3D designer would ship, that makes people *wow*. A correct-but-flat scene (ambient-only light, raw `MeshStandardMaterial`, default linear render, no post, linear camera) reads as a student exercise and is a FAIL. Apply at least the Biggest-5: (1) tone mapping + sRGB + DPR≤2; (2) HDRI/`RoomEnvironment` IBL via PMREM; (3) `pmndrs/postprocessing` — selective bloom + depth-of-field; (4) three-point lighting with a **rim light** + soft contact shadows; (5) eased, **staged** GSAP reveal + `FogExp2`. Then look at it: does it actually say "wow"? If it looks normal, it isn't done — that's a taste judgment you (and the user) must make. ⚡ **(b) The performance checklist** (`references/gsap-threejs-playbook.md` → "Mandatory performance checklist"). The wow can't tank perf or it isn't wow. Render-on-demand so **idle GPU ≈ 0** (or, for a continuous animated scene, pause when the stage is off-screen / tab-hidden / a modal is open — observe the content that scrolls OVER the fixed canvas, not the canvas itself), fps capped at 60 on GSAP's single ticker, DPR ≤2, repeated meshes instanced, post chain merged into one `EffectPass`, shadow map ≤2048, bake what's static, no per-frame allocation. **Measure it** (`verify.mjs` reports jank) — never trust "looks smooth". A scene that's beautiful but janky fails (b); a scene that's smooth but flat fails (a). 7. **Generate the viz-manifest (optional but recommended).** Run `node scripts/gen-viz-manifest.mjs <pageDir> --as-js` to emit a `viz-manifest.json` (+ `.js`) mapping every `data-viz-id` / `userData.vizId` to its `{file, line, builderFn, cssRule}`. Load it before edit-mode. This is the one-hop bridge from "what the user pointed at" to "the code that makes it" — and it is the ONLY bridge for Three.js objects (they have no DOM node to grep). Edit-mode then stamps each comment with its `source`, and `window.__viz` (`assets/edit-mode/viz.js`) lets you query ids at runtime. 8. **Enable edit mode and hand off.** Wire `assets/edit-mode/edit-mode.js` + `.css` (see its header for the 3-step wiring); optionally also include `assets/edit-mode/viz.js`. Tell the user: toggle with the ✎ button or `e`; the toolbar has **Normal/Expert views** (Normal reveals a component's rect + id on hover; Expert shows all ids at once — both for DOM and 3D objects) and four tools — **Pointer** (interact with the page normally — no highlights, clicks pass through; for when the user wants to drive the page while the toolbar stays up), **Select** (click an element to add it as a comment; **ctrl/⌘+click builds a multi-select** — keep ctrl/⌘+clicking to add more, ctrl/⌘+click again to remove, then Enter/plain-click to turn the whole set into ONE comment with many targets), **Snip** (drag a rectangle), and **Brush** (paint a freehand region). Comments collect in a (draggable) side panel. **Getting feedback back to you — "Copy for AI" is the one button, made smarter by the bridge:** - **Serve with `scripts/serve.sh` (recommended):** `./scripts/serve.sh <pageDir>` starts BOTH the page server (8800) and the feedback-bridge (8910) together, so the bridge is always up whenever the page is — no separate process to forget. Init edit-mode with `{ bridge: 'http://localhost:8910' }`. Now **"Copy for AI"** both copies the markdown AND POSTs the batch + snip PNGs to the bridge, which writes them to `/tmp/viz-edit/`. The user just says "read the feedback" — you read `edit-feedback.json` (each comment carries an absolute `imagePath`) and the PNGs directly. If the bridge ever isn't running, "Copy for AI" silently falls back to a normal clipboard copy. (Bare alternative: run `node scripts/feedback-bridge.mjs` and `python3 -m http.server` yourself.) - **Without the bridge:** "Copy for AI" copies the markdown to paste into chat — fine for id/text comments, but snip images aren't included. Or use **Download** (`edit-feedback.json` + `snip-N.png`) then `node scripts/receive-feedback.mjs` to land them in `/tmp/viz-edit/` at the paths the JSON names. You consume the batch by resolving each id to its builder (the `source` field or grep the id), reading any `imagePath` for visual context, and using `sceneContext` to reproduce the exact 3D moment. 9. **Export a standalone HTML for sharing.** Always offer a single-file export the user can send or open without a server: `node scripts/bundle-standalone.mjs index.html` inlines all local CSS/JS into one `.html`. **Edit-mode is stripped by default** (an export is a publish artifact). Add `--vendor` to also inline the CDN libs (three/gsap) for a fully offline file; `--keep-edit` to retain the authoring tool. ## Operating knowledge (read on demand) - **`references/gotchas-and-lessons.md`** — ⚠️ **READ THIS FIRST.** A catalog of real bugs that each cost a debugging round in a prior build: the SVG `.hidden` no-op, `[hidden]` losing to a `display` class, `contains(window)` throwing, DOM-over-3D hover hijacking, un-raycastable thin tubes, unregistered vizId objects, idle-GPU render loops, the `readPixels`-reports-black trap, the dead swiftshader flag, ESM module resolution, and the tag-every-text rule. Skim it before writing edit-mode wiring, 3D selection, a render loop, or a verification script — it is the cheapest rework you can avoid. - **`references/gsap-threejs-playbook.md`** — GSAP + Three.js technique and gotchas: ScrollTrigger scrub, the piecewise camera-param remap, `getPointAt` (arc-length) vs `getPoint` and when each is right, draw-on tubes, InstancedMesh, canvas-texture labels, bezier-tangent label rotation, and the **PERFORMANCE / render-pause pattern** (pause the loop when the 3D stage is off-screen or a modal is open — the single biggest CPU/GPU win). Read before writing any scene or scroll logic. - **`references/wow-quality-bar.md`** — ⭐ **the studio-grade gate. "No bugs" is not the bar; "wow" is.** What separates a professional 3D hero from a student exercise: the tone-mapping/sRGB pipeline, HDRI/PMREM environment lighting, `pmndrs/postprocessing` (selective bloom + DOF + grade), three-point + rim lighting + soft contact shadows, eased/staged GSAP camera & reveal choreography, atmosphere (fog/particles/god-rays), and the **Biggest-5** ordered list. A hero scene is NOT done until it clears the Biggest-5. Read before and after building any 3D scene. - **`references/styling-and-anti-slop.md`** — taste and restraint; the anti-slop checklist; how to adopt a design system. Read before styling. - **`references/diagram-catalog.md`** — per-diagram layout patterns + universal edge-routing rules + the overlay-lens model. Read before laying out any diagram. - **`references/finding-3d-models.md`** — **MODEL objects with real detail, don't stack generic boxes** (a server = rack + slats + LED, not three cubes); procedural-first decision tree; a vetted catalog of free model sources (Kenney/Quaternius/KayKit CC0, Poly Pizza, Sketchfab, Poly Haven HDRIs, the three.js-examples-are-NOT-MIT caveat) with per-license shipping rules; AI generators (tier-dependent licenses); the GLTFLoader → recolor → glTF-Transform optimize pipeline. Read when building/​importing any 3D object, and to find a model online. - **`references/finding-layout-inspiration.md`** — where to find scroll-story and diagram inspiration online (Awwwards, the vectrfl/Stripe/Linear scrollytelling genre, C4, the Oxygen-Not-Included overlay metaphor) and how to steal structure, not skin. - **`references/ai-collaboration-protocol.md`** — the `data-viz-id` / `userData.vizId` convention, the reads-like-language code structure, and the exact JSON/markdown contract the edit-mode tool emits so you know how to consume feedback. Read before writing components and when receiving edit-mode feedback. - **`references/visual-verification.md`** — how to read and validate the page like a machine: the `scripts/verify.mjs` stack (layout probes, axe contrast, canvas-rendered check, GSAP `.progress()` frame