architecture-viz-studio

Files (46)

• SKILL.md
• component-detail-modal.js · assets/diagrams/
• edge-hit-proxies.js · assets/diagrams/
• erd-diagram.js · assets/diagrams/
• overlay-lens-system.js · assets/diagrams/
• pan-zoom-viewport.js · assets/diagrams/
• edit-mode.css · assets/edit-mode/
• edit-mode.js · assets/edit-mode/
• viz.js · assets/edit-mode/
• DESIGN-SYSTEM.md · assets/page-shell/
• index.html · assets/page-shell/
• styles.css · assets/page-shell/
• post-processing.js · assets/scene/
• primitives.js · assets/scene/
• render-loop.js · assets/scene/
• scene-setup.js · assets/scene/
• scroll-journey.js · assets/scroll/
• evals.json · evals/
• ai-collaboration-protocol.md · references/
• diagram-catalog.md · references/
• finding-3d-models.md · references/
• finding-layout-inspiration.md · references/
• gotchas-and-lessons.md · references/
• gsap-threejs-playbook.md · references/
• styling-and-anti-slop.md · references/
• visual-verification.md · references/
• wow-quality-bar.md · references/
• DESIGN-SYSTEM.md · sample/
• README.md · sample/
• component-detail-modal.js · sample/diagrams/
• erd-diagram.js · sample/diagrams/
• overlay-lens-system.js · sample/diagrams/
• pan-zoom-viewport.js · sample/diagrams/
• index.html · sample/
• main.js · sample/
• styles.css · sample/
• viz-manifest.js · sample/
• viz-manifest.json · sample/
• bundle-standalone.mjs · scripts/
• feedback-bridge.mjs · scripts/
• gen-viz-manifest.mjs · scripts/
• receive-feedback.mjs · scripts/
• serve.sh · scripts/
• slop-lint.mjs · scripts/
• text-audit.mjs · scripts/
• verify.mjs · scripts/

SKILL.md (first lines)

# 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

From bmad-labs/skills, MIT.

More from bmad-labs/skills