# Design Language for xbom.wiki ## Aesthetics and Tone xbom.wiki is staged as **an exploded axonometric atlas of a software supply chain, drafted by a meticulous forensic cartographer who works exclusively in 30-degree projection**. The conceit reads precisely: imagine the inspection plates from a vintage aircraft maintenance manual — the kind where the whole airframe is pulled apart along invisible wires so every rivet, gasket, and wiring loom floats labelled in mid-air — but the airframe is a *piece of software*, and every floating part is a dependency, a build artifact, a signing key, a CVE, a transitive package three layers down. "XBOM" — the eXtended Bill of Materials — is the manifest that names every one of those parts. So this wiki is not a documentation site that happens to have diagrams; it **is** a diagram, an enormous isometric drafting sheet you scroll *into*, and the prose lives inside the callout balloons that point at the parts. The tone is **technical-precise but not cold** — the warmth comes from craftsmanship, not from rounded corners or pastel gradients. Think: the loving exactness of an exploded-view illustrator who measures shadow lengths with a protractor; the quiet authority of an engineering ministry's blueprint vault; the faint thrill of seeing something complicated rendered so legible that it becomes beautiful. Nothing here giggles. Nothing here is "playful." But the precision is generous — it wants you to *understand* the supply chain, not to be impressed by it. Crucially, this is **isometric without being a video-game town**. The web's isometric canon is cute: 2.5D cities, cartoon buildings, a SaaS hero with a tiny floating laptop. xbom.wiki refuses all of that. The projection here is **drafting-board axonometric** — true 30-30 isometric, no perspective convergence, hairline construction lines left visible, dimension arrows, section-cut hatching, leader lines with terminal dots. It is the difference between a Monument Valley screenshot and a 1962 Boeing maintenance manual fold-out. We are firmly the second thing. ## Layout Motifs and Structure The structural conceit is **isometric layered-depth** — not parallax-velocity layers, not a card grid tilted 15deg, but a genuine **stacked exploded assembly** read top-to-bottom as you descend through the supply chain. The page is one continuous vertical sheet, roughly 640vh, divided into **nine "plates"** (the manual's word for a fold-out diagram page). Each plate is one stratum of the supply chain, and the strata are stacked along the isometric Z so that scrolling downward feels like descending through the assembly from the shipped product at the top to the raw upstream commits at the bottom: 1. **Plate I — The Artifact.** The shipped thing: a single isometric cube, faces labelled (binary / container image / firmware). 2. **Plate II — The Manifest.** The XBOM document itself, drawn as a folded blueprint sheet seen in 30deg, its fold-creases catching light, leader lines erupting from it toward every plate below. 3. **Plate III — Direct Dependencies.** A row of isometric crates on a drafting grid, each a top-level package. 4. **Plate IV — The Transitive Lattice.** The deep tree: dozens of small iso-cubes connected by hairline edges, the famous "left-pad iceberg," exploded so you see how deep it goes. 5. **Plate V — Provenance & Attestation.** Signing keys drawn as iso-keys, SLSA provenance drawn as a chain of stamped seals, build steps as a conveyor in projection. 6. **Plate VI — The Toolchain.** Compilers, build runners, CI machines — drawn as iso-machinery with exposed gearing. 7. **Plate VII — Vulnerabilities.** CVEs drawn as fault-lines / red section-cuts slicing through the cubes above; the only place red appears at scale. 8. **Plate VIII — Licenses & Obligations.** Legal weight drawn as iso-weights stacked on a balance arm. 9. **Plate IX — Upstream.** The maintainers, the commits, the bus-factor — drawn small and far, at the bottom of the well, with the longest leader lines of all. **Spatial rules that hold on every plate:** - **The 30-30 grid is always visible.** A faint isometric grid (two line families at +30deg and -30deg from horizontal, 1px, very low opacity) underlies the entire sheet, like graph paper under a draft. Content snaps to it. - **Everything casts a true isometric shadow** — a parallelogram offset down-and-right at the projection angle, soft, single-source, consistent across the whole page. Shadows are how depth is communicated; there is almost no blur, almost no glassmorphism. - **Prose lives in callout balloons.** Body text never floats free. Each paragraph sits in a rectangular "balloon" with a leader line (hairline, with a terminal dot or arrowhead) connecting it to the part it describes. This is the load-bearing layout decision: the reading experience is *following leader lines*. - **The left rail is a "drawing index."** A persistent narrow column lists Plates I–IX as a drafting-manual contents block — monospace, dotted leaders to plate numbers, the current plate's row highlighted. It is the only navigation. No top nav bar, no hamburger, no mega-menu. - **Asymmetric within each plate.** The exploded assembly is never centered; it leans, with the construction lines and dimension arrows filling the "empty" side so no space is dead — it's all annotation. - **Section-cut hatching** (45deg parallel hairlines, the universal "this is a cut surface" convention) marks every place a concept is "sliced open" to show its interior. No bento boxes. No hero-with-CTA. No stat-counter grid. No pricing tiers. No testimonial carousel. ## Typography and Palette **Type stack — Google Fonts only, three families, assigned with drafting-room discipline.** - **IBM Plex Mono** — the *instrument lettering*. Every label, dimension callout, plate number, leader-line tag, the left-rail drawing index, all code, all package names, all hashes, all CVE IDs. This is the dominant voice of the page; the sheet should read as if a draftsman lettered it. Used at 12–14px for labels with +0.04em tracking and `text-transform: uppercase` for dimension tags; 14–15px for code blocks and inline identifiers, no transform. Plex Mono's slightly humanist mono shapes keep it from feeling like a terminal. - **Spectral** — the *explanatory prose*. The actual sentences inside the callout balloons — the wiki's explanations of what an XBOM is, why transitive depth matters, how attestation works — are set in Spectral, a screen-tuned serif with a calm, technical-manual-footnote authority. 17–19px, 1.6 line-height, generous measure (62–70ch where it fits in a balloon). It is the only serif on the page and it signals "read this part slowly." - **Archivo** — the *plate titles and the masthead*. Plate headings ("PLATE IV · THE TRANSITIVE LATTICE") and the site wordmark are set in Archivo (or Archivo Expanded where weight allows), a grotesque with engineered, slightly squared terminals — it looks machined, not friendly. Plate titles at clamp(28px, 4vw, 56px), weight 600, +0.02em tracking, uppercase. The masthead "XBOM.WIKI" sits top-left at ~22px, weight 700, with a tiny "/ eXtended Bill of Materials — a field atlas" subtitle in Plex Mono beneath it. **Palette — a drafting-vault palette: bone paper, graphite line, blueprint ink, with iron and a single danger-red. Eight values.** - `#F2EEE3` — **drafting bone**. The page background. Not white — the warm not-quite-cream of heavyweight drafting vellum under tungsten light. Everything sits on this. - `#E7E1D1` — **vellum shadow**. The fill colour for the isometric "ground" faces and for the very faint base-grid; one step darker than bone, so the grid reads as a watermark, not a line. - `#23262B` — **graphite**. The primary line colour and primary text colour — soft near-black with a cool cast, like a 4B pencil, never pure `#000`. Construction lines, leader lines, label text, balloon borders. - `#6B7077` — **silverpoint**. The secondary line/text — dimmed labels, the base isometric grid lines, dotted leaders in the index, captions. A cool mid-grey that recedes. - `#1B4F8C` — **blueprint ink**. The structural accent — used for the *active* leader line, the highlighted index row, the "you are here" plate marker, link underlines, and the top-light face of key cubes (the XBOM manifest sheet, the Artifact). A deep cyanotype blue. - `#3E7CB1` — **diazo blue**. A lighter blueprint blue, used for the *left/secondary* faces of iso-cubes and for hover states, so the assembly has a believable two-tone shading model (top = brighter, sides = blueprint, in two depths). - `#9C3B2C` — **oxide red**. Reserved almost entirely for Plate VII — CVE fault-lines, vulnerability section-cuts, the red leaders that point at the cracked cubes. Appears nowhere else at scale; one or two tiny "deprecated" tags elsewhere maximum. Its scarcity is what makes the vulnerability plate land. - `#B8A77C` — **brass tag**. A muted gold for the provenance/attestation seals on Plate V and for the masthead rule line — the only "warm metal," used sparingly, to mark *things that have been signed / certified*. Contrast spine: `#23262B` graphite text on `#F2EEE3` bone is the workhorse pair; `#1B4F8C` blueprint ink is the single chromatic accent that organizes attention; `#9C3B2C` oxide red is the alarm, hoarded for one plate. ## Imagery and Motifs **Three motif families, all hand-built in SVG — no stock photography, no 3D renders, no gradient meshes.** **1. The exploded axonometric assembly (load-bearing).** Every plate's centerpiece is a true-isometric SVG diagram: cubes, crates, keys, gears, seals, weights, drawn in 30-30 projection with a strict two-tone-plus-highlight shading model (`#1B4F8C` top face on hero objects / `#3E7CB1` left face / `#6B7077` right face for ordinary objects; flat-shaded, no gradients). Objects are connected by **hairline assembly edges** and pulled apart along faint dashed "explosion axes" — the classic maintenance-manual convention where a bolt floats six inches above its hole on a dotted line. The transitive-lattice plate is the showpiece: 40–80 tiny iso-cubes in a deep tree, exploded so the depth is visceral. **2. Drafting annotation furniture.** This is what fills the page and gives it its texture: **dimension lines** (hairline, with the little 30deg terminal ticks and a numeric value in Plex Mono mid-span — but the values are *supply-chain facts*: "DEPTH: 9 LEVELS", "TRANSITIVE: 1,204 PKGS", "UNSIGNED: 31%"); **leader lines** (hairline from balloon to part, terminating in a 2px filled dot or a tiny arrowhead); **section-cut hatching** (45deg parallel hairlines on any "sliced" surface); **revision clouds** (the bumpy cloud outline that marks "this changed" — used to flag recently-edited wiki sections); **the title block** in the bottom-right corner of each plate, a real drafting title block with fields: SHEET, SCALE ("NTS"), DRAWN BY ("xbom.wiki"), REV, DATE. The page should look *measured*. **3. The base grid + the well.** Under everything, the faint `#E7E1D1` isometric graph grid. And a structural metaphor: the nine plates together form **a well** — the artifact is at the rim (top), the upstream maintainers at the bottom — and a subtle continuous element (a single hairline "plumb line" with a small weight, dropping straight down the page's left-of-center, passing through every plate) ties the strata together and gives the scroll a sense of *descent*. The plumb-line weight's vertical position tracks scroll progress. Iconography is **iso-objects, never flat glyphs**: a dependency is a small crate, a signing key is a 3D key in projection, a CVE is a jagged red fault, a license is a stamped tablet, a maintainer is a tiny iso-figure at a workbench. Consistent light source (upper-left), consistent projection, always. ## Prompts for Implementation Build xbom.wiki as **one HTML document, one CSS file, one small ES module — no framework, no router, no SPA, no build step beyond one esbuild/rollup pass**. The page is one continuous ~640vh vertical sheet of nine plates. The visitor lands at the rim of the well (the shipped Artifact), scrolls down through nine strata of the software supply chain, and arrives at the upstream commits. There is no second page. The site does not link out except to genuinely cited specs (SPDX, CycloneDX, SLSA) which open in new tabs from inside Plex-Mono inline references. **Storytelling is the organizing principle, not navigation.** The nine plates compose **a single guided descent**: "Here is the thing you shipped. Here is the manifest that names its parts. Here are its direct parts. Here is how deep the parts go (further than you think). Here is how you'd prove any of it. Here is the machinery that made it. Here is where it's cracked. Here is what you legally owe. Here are the humans at the bottom holding it up." Every paragraph of wiki prose is a callout balloon hung off a part of that descent. A reader who scrolls the whole page has read a complete short course on extended bills of materials — the "wiki" depth (more plates, more cross-links between balloons) is layered *underneath* via expandable sub-balloons, but the spine is the descent. **Motion — restrained, mechanical, never bouncy.** The vibe is *a draftsman's table being assembled*, not a toy. Specifically: - **Assembly-on-reveal:** as each plate enters the viewport, its exploded parts **slide in along their explosion axes** to settle into floating position — linear or gentle ease-out, ~600–900ms, staggered part-by-part along the leader-line order. Parts that have arrived have a 1px settle (no spring overshoot — these are precise objects). - **Leader-line draw:** leader lines and dimension lines **draw themselves** on reveal via `stroke-dashoffset` animation (path-draw-svg) — hairline grows from the part toward the balloon, then the terminal dot pops. This is the signature animation; it should happen on every plate. - **The plumb line** drops continuously, its weight's `transform: translateY()` bound to scroll progress (scroll-triggered, no parallax velocity tricks — 1:1-ish). - **The drawing-index left rail:** the active plate's row highlights (`#1B4F8C` underline draws across it) as you scroll into each plate; clicking a row smooth-scrolls to that plate. Dotted leaders animate in. - **Hover on any iso-object:** its faces brighten one step toward `#3E7CB1`, and its associated leader line + balloon get the active-blueprint treatment; a tiny dimension callout for that object fades in. No tilt, no 3D rotation on hover — the projection is fixed; that's the point. - **CVE plate (VII) only:** the oxide-red fault-lines **draw in last and slightly faster**, with a single very subtle one-time shudder of the cracked cubes — the only moment of "alarm" motion on the whole page. Use it once, well. - **Respect `prefers-reduced-motion`:** parts appear already-assembled; leader lines appear already-drawn; plumb line still tracks scroll (it's information, not decoration); no shudder. **Build the iso geometry honestly.** Use a tiny shared JS helper that maps `(x, y, z)` grid coordinates to screen `(left, top)` via the 30deg projection matrix, and lay out every cube/crate/key/seal through it so the projection is consistent and the assembly edges actually connect. Cube faces are SVG ``s with flat fills from the palette; shadows are offset parallelogram ``s at the projection angle with low-opacity graphite fill. The base grid is two ``s of crossing 30deg hairlines. Title blocks are real `` groups with `` fields. **AVOID:** CTA-heavy layouts, "Get Started" buttons, pricing blocks, plan-comparison tables, stat-grids-as-hero, testimonial carousels, cookie-modal theatrics, hamburger menus, hero video, glassmorphism blur panels, gradient-mesh backgrounds, stock photography, cute 2.5D-village isometric, neon glow, spring/elastic overshoot motion, infinite-scroll feeds. The page is a drafting sheet, not a landing page. ## Uniqueness Notes Six differentiators this design commits to. None should be duplicated by any other CMassC site. 1. **Drafting-manual axonometric, not video-game isometric.** Frequency analysis: `isometric` aesthetic ~13%, `isometric-icons` imagery ~5% — and that canon is overwhelmingly the cute 2.5D-city / SaaS-floating-laptop register. xbom.wiki renders isometric as a **1960s aircraft-maintenance fold-out**: visible construction lines, true 30-30 projection with zero perspective convergence, dimension arrows, section-cut hatching, real drafting title blocks. The "exploded assembly where every floating part is a supply-chain element" conceit — and prose living inside leader-line callout balloons — is the signature and would be plagiarism if copied. 2. **Leader-line reading, not card reading.** `card-grid` is the registry's near-universal layout (~93%). This page has **no cards** — body text lives in annotation balloons tethered by hairline leader lines to the part being explained, and the core reading interaction is *following leaders down an exploded diagram*. The path-draw-svg leader animation is load-bearing, not decorative. 3. **Drafting-vault palette, not warm-gradient.** `warm` palette ~98%, `gradient` ~93% across the cohort. xbom.wiki uses **flat fills only — zero gradients anywhere** — on a bone-vellum / graphite / cyanotype-blue scheme (`#F2EEE3` / `#23262B` / `#1B4F8C` / `#3E7CB1`) with brass (`#B8A77C`) for "signed" things and oxide red (`#9C3B2C`) *hoarded for a single plate*. The warmth is the paper, not a sunset. 4. **Mechanical motion, not springy motion.** `spring` ~83%, `magnetic` ~77%, `elastic` ~22%, `cursor-follow` ~89% are the cohort defaults. This design uses **none of them** — motion is parts sliding along explosion axes and stroke-dashoffset line-draws, linear/ease-out, with deliberately *no overshoot* because the objects are precise instruments. No cursor-follow, no magnetic buttons, no tilt-3D-on-hover (the projection is fixed by design). 5. **The well as structural metaphor.** The nine plates aren't just stacked sections — they form a *well* you descend (shipped artifact at the rim, upstream maintainers at the bottom), tied together by a single continuous plumb-line whose weight tracks scroll. The descent *is* the narrative of an extended bill of materials: from the thing you ship down to the humans who hold up its foundations. 6. **Chosen seed/style:** `isometric technical docs` — taken literally and pushed all the way to forensic drafting cartography. Avoided overused patterns from frequency analysis: hand-drawn (~94%), glassmorphism (~85%), photography imagery (~98%), card-grid (~93%), full-bleed photo hero, warm/gradient palettes (~98%/~93%), mono-only-with-springy-motion clichés, cursor-follow (~89%), parallax-velocity layers (~87%).