# Design Language for xanadu.wiki

## Aesthetics and Tone

xanadu.wiki is an imagined **hypertext pleasure-garden archive** — Ted Nelson's original Xanadu dream made tactile and slightly decayed. The aesthetic is **muji-meets-circuit-board**: the restraint and quiet of Japanese functional minimalism colliding with the faint ghost of printed circuit traces embedded in aged paper. The tone is **playful but erudite** — a librarian who has hidden joke footnotes in every entry, who uses monochrome because color would distract from the wit.

The mood is best described as: *a 1970s research memo that has been sitting in a manila folder under a Kyoto teahouse floor for forty years, discovered still legible, still funny, still correct.* Muji's philosophy — "no brand," "emptiness as intention," "beauty through omission" — governs every spatial decision. But the circuit motif keeps reminding you this is about computation, about the links, about the machine underneath the handmade paper.

Visual anchors:
- Off-white aged paper stock (`#F5F0E8`) as ground, never pure white
- Sparse circuit-trace hairlines (`#1A1A1A` at 12% opacity) ghosted behind text blocks
- Generous ma (negative space) — breathing room that makes content feel precious
- Playful asymmetry via diagonal section cuts: sections that slice across the page at 3–7° angles rather than sitting in horizontal bands
- Skeleton loading states that reveal content like watermarks emerging from paper when held to light

---

## Layout Motifs and Structure

The structural metaphor is the **hypertext card index** — a Rolodex of knowledge entries, each entry a diagonal-sliced card that slides slightly off-axis. The page is a single vertical scroll, but every major section is separated by a **diagonal cut line** at a consistent 4° angle — not just a visual device but a literal CSS `clip-path` on section backgrounds, so the sections actually overlap and nest like offset index cards.

**Grid logic:**
- Desktop: 12-column grid, 80px gutters, maximum content width 1080px
- The primary text column sits in columns 2–9 (deliberate asymmetry: more space on the left)
- A thin margin column (columns 10–12) carries circuit-trace annotations: small, rotated labels in `EB Garamond` italic at 11px, barely readable, that give cross-reference footnotes
- The diagonal section dividers use `clip-path: polygon(0 0, 100% 4%, 100% 100%, 0 96%)` — each section nudged by ±2° to feel hand-cut, not mechanical

**Section rhythm:**
1. **Masthead** — wordmark "xanadu.wiki" set in `EB Garamond` display at `clamp(72px, 12vw, 144px)`, weight 400, wide tracking. Below it: a single-sentence mission statement in `Cormorant Garamond` italic.
2. **Lede card** — diagonal-cut hero, aged paper texture, one large pull-quote from Ted Nelson set in oversized Garamond italic.
3. **Entry gallery** — a 3-column staggered card layout, cards slightly rotated (−1° to +2°), each card a wiki entry stub with skeleton-loading reveal.
4. **Circuit diagram section** — full-bleed SVG circuit trace pattern at 6% opacity behind a dense column of text, evoking a datasheet insert.
5. **Footnote ocean** — the site's most playful section: a field of footnote numbers (1–99) scattered in a CSS grid with `gap: 0`, each number an interactive link to a hidden aside. Diagonal cut at the top.
6. **Colophon / footer** — minimal, left-aligned, circuit hairline border top.

**Diagonal section recipe:**
Each section `<div>` has `clip-path: polygon(0 var(--top-indent), 100% 0, 100% calc(100% - var(--bot-indent)), 0 100%)` with `--top-indent` and `--bot-indent` set to `clamp(24px, 3vw, 64px)`. Adjacent sections overlap by 48px via negative `margin-top`, creating a layered card stack effect.

---

## Typography and Palette

**Typefaces (Google Fonts only):**

- **Primary display + body serif:** [`EB Garamond`](https://fonts.google.com/specimen/EB+Garamond) — weights 400, 500, 700; italic variant used extensively. EB Garamond's inktraps and historical texture give the aged-paper look authenticity. Used for all headings, pull quotes, body text, and the wordmark.
- **Secondary / annotation serif:** [`Cormorant Garamond`](https://fonts.google.com/specimen/Cormorant+Garamond) — weights 300, 400 italic. Used exclusively in the margin annotation column, footnotes, and caption text. Its extreme contrast between thick and thin strokes evokes a copperplate print.
- **Monospace accent:** [`IBM Plex Mono`](https://fonts.google.com/specimen/IBM+Plex+Mono) — weight 400 only. Used for circuit node labels, hyperlink URLs when displayed, and the skeleton-loading placeholder characters. The mix of humanist mono with Garamond serif creates productive tension.

**Type scale:**
- Display: `clamp(72px, 12vw, 144px)` / `EB Garamond` 400
- H1: `clamp(36px, 5vw, 64px)` / `EB Garamond` 500
- H2: `clamp(24px, 3vw, 40px)` / `EB Garamond` 400 italic
- Body: `18px / 1.75` / `EB Garamond` 400
- Annotation: `11px / 1.5` / `Cormorant Garamond` 300 italic, rotated −90° in margin
- Code/node: `13px` / `IBM Plex Mono` 400

**Palette — strict monochrome with paper warmth:**

| Role | Hex | Description |
|---|---|---|
| Paper ground | `#F5F0E8` | Aged cream, primary background |
| Deep ink | `#1A1A1A` | Near-black for all text |
| Mid-gray | `#6B6560` | Secondary text, annotations |
| Light gray | `#C8C2BA` | Borders, circuit traces, ruled lines |
| Pale rule | `#E2DDD5` | Section dividers, card borders |
| White accent | `#FDFBF7` | Card surfaces, elevated elements |
| Circuit ghost | `rgba(26,26,26,0.08)` | SVG circuit traces behind text blocks |

No color. Zero. If a UI state needs emphasis, it uses **weight**, **size**, or **spacing** — never hue. The only "color" event is the circuit trace overlay, which is not color but ink density.

---

## Imagery and Motifs

**No photographs.** The entire visual vocabulary is constructed from two families of generated form:

**1. Circuit Traces (SVG, procedurally patterned)**
The primary decorative motif is a PCB circuit trace network rendered as an SVG `<pattern>` tile. The pattern consists of:
- Orthogonal and 45° diagonal path segments, `stroke-width: 1px`, color `#1A1A1A` at 8% opacity
- Small circular pads (`r: 3px`) at junction nodes, filled `#1A1A1A` at 10% opacity
- Occasional SMD component outlines (empty rectangles, 4×2 proportions) at 6% opacity
- The tile repeats at `40×40px` — fine enough to read as texture at body text scale, recognizable as circuit at hero scale
- Used as `background-image: url(#circuit-pattern)` on section backgrounds, never over text directly (always behind a `#F5F0E8` semi-transparent overlay)

**2. Aged Paper Texture (CSS-only)**
No image files. Paper texture is synthesized entirely from CSS:
- `background-color: #F5F0E8` as base
- `background-image: repeating-linear-gradient(0deg, transparent, transparent 28px, rgba(26,26,26,0.03) 28px, rgba(26,26,26,0.03) 29px)` — faint ruled lines, like old notebook paper
- A subtle `filter: contrast(1.02) saturate(0.85)` on the `<body>` shifts the whole page toward the desaturated warmth of aged cellulose
- Section cards have `box-shadow: 2px 3px 12px rgba(26,26,26,0.08)` — the offset is deliberately asymmetric (more bottom-right) like a page that has curled slightly

**3. Skeleton Loading States (the playful element)**
Skeleton screens are not utilitarian placeholders here — they are a **content motif**. While wiki entry cards load, they display:
- A `#E2DDD5` rectangle where the title would be (width randomized between 40%–75%)
- Three `#E2DDD5` lines at body text height (widths: 100%, 92%, 67%), mimicking paragraph text
- An animated shimmer: `background: linear-gradient(90deg, #E2DDD5 25%, #FDFBF7 50%, #E2DDD5 75%)` shifted via `@keyframes shimmer` — the shimmer moves at `1.4s` ease-in-out, slow enough to feel like paper absorbing light, not a loading bar
- After load, the skeleton dissolves via `opacity: 0` + `transition: opacity 0.6s ease` while real content fades in beneath — the ghost paper yielding to text

**4. Rotated Index Card Motif**
Each wiki entry card is a `<article>` element with:
- `transform: rotate(var(--card-tilt))` where `--card-tilt` is set inline to a value between `−1.5deg` and `+1.8deg` per card
- A `::before` pseudo-element that adds a folded corner triangle in the top-right: `border-right: 12px solid #C8C2BA; border-bottom: 12px solid transparent`
- On hover: `transform: rotate(0deg) translateY(−4px)` with `transition: transform 0.3s cubic-bezier(0.34, 1.56, 0.64, 1)` — the spring easing makes the card "snap" upright, like a hand picking up an index card

---

## Prompts for Implementation

Build xanadu.wiki as a **single immersive scroll through a hypertext garden that knows it is a hypertext garden**. Every design decision should feel like it was made by someone who read "Literary Machines" cover to cover and then went to work at a Muji store for a decade.

**Story arc (single-column scroll, diagonal-section structure):**

**Section 0 — Masthead / Entry Vestibule**
Full-viewport-height opening. Circuit trace SVG pattern at 6% opacity on `#F5F0E8` paper. The wordmark "xanadu.wiki" in `EB Garamond` 400 at `clamp(72px, 12vw, 144px)` — no weight, no color, just the letterforms sitting on paper. Below it: `"Everything is deeply intertwingled."` — Ted Nelson, 1974, in `Cormorant Garamond` italic 300, `20px`, `#6B6560`. No hero image. No button. The only interactive element is a hairline scroll indicator: a `1px` vertical line in `#C8C2BA` that pulses with `opacity: 0.4 → 1.0` at `2s` ease-in-out.

Diagonal cut at bottom: `clip-path: polygon(0 0, 100% 0, 100% 92%, 0 100%)`.

**Section 1 — The Lede Card**
A diagonal-cut section with `background: #FDFBF7`. A single large pull-quote from Nelson fills the section — set at `clamp(32px, 4vw, 52px)` `EB Garamond` italic, left-aligned to column 2. In the right margin (column 10–12), a vertical stack of `IBM Plex Mono` 11px labels: `[ref: 001]`, `[ref: 002]` etc., rotated −90°, color `#6B6560`. These are hoverable: on hover a footnote popover appears in `Cormorant Garamond` italic 14px against `#1A1A1A` background / `#F5F0E8` text — inverted paper.

**Section 2 — Entry Gallery (skeleton-to-content reveal)**
Three-column card grid. On page load, all 9 cards show skeleton state (the shimmer pattern described above). Cards stagger-reveal with a 120ms delay between columns using `animation-delay`. Each card's skeleton reveals into real content: a wiki entry title in `EB Garamond` 500 `22px`, a two-sentence excerpt in `EB Garamond` 400 `16px / 1.7`, and a `IBM Plex Mono` `11px` node ID label like `XAN-0042`. Cards are slightly rotated. On hover, they snap upright and lift.

The transition from skeleton to content should use a CSS class toggle (`.loaded`) that swaps `opacity: 0` skeleton pseudo-elements for `opacity: 1` real content — not a JS framework component, just a clean class swap triggered by `IntersectionObserver`.

**Section 3 — Circuit Diagram Insert**
Full-bleed section. The circuit SVG pattern here is at **20% opacity** — much denser than elsewhere, so the trace network is clearly visible as a texture. The section contains a single dense column of body text (`EB Garamond` 400 `18px`) centered on the page, with a `#FDFBF7` background behind the text column at `90% opacity` — the paper sits on top of the circuit, the circuit bleeds through at the edges. This section evokes a printed circuit datasheet insert in an academic paper.

At the top of the section, a horizontal rule made of `IBM Plex Mono` characters: `─────────────────── [PCB-REF: XAN-CORE-001] ───────────────────` — this is not an `<hr>` but a `<p>` with `text-align: center; font-size: 11px; letter-spacing: 0.1em; color: #6B6560`.

**Section 4 — Footnote Ocean (the signature playful element)**
Dark section: `background: #1A1A1A`, text `#F5F0E8`. A field of footnote numbers 1–99 arranged in a CSS grid with `grid-template-columns: repeat(auto-fill, minmax(32px, 1fr))` and `gap: 4px`. Each number is a `<button>` in `EB Garamond` italic `14px`, `color: #C8C2BA`, that on click expands an inline `<details>` element revealing the footnote text beneath — pushing the number grid apart to make room, without a modal or overlay. The expansion uses `height: 0 → auto` via CSS grid row trick (no JS animation needed).

The playfulness is in the footnotes themselves: they are actual funny/insightful mini-essays about hypertext, citation, and knowledge. Footnote 23: `"This link goes nowhere, which is the point."` Footnote 47: `"The word 'xanadu' appears 17 times on this page. This is footnote 47."` The circuit trace pattern still ghosts behind this section at 4% opacity on the dark background — barely visible, like traces on a black PCB.

Diagonal cut at top: `clip-path: polygon(0 4%, 100% 0, 100% 100%, 0 100%)`.

**Section 5 — Colophon**
`background: #F5F0E8`. Left-aligned. A single `1px solid #C8C2BA` top border. The colophon text is set in `Cormorant Garamond` italic 300, `14px / 2.0`, `#6B6560`. It contains: the site's philosophy in one paragraph, a list of referenced works (Nelson, Bush, Engelbart) in `IBM Plex Mono` `12px`, and the wordmark repeated at `24px` `EB Garamond` 400 as the final element on the page.

**Animation principles:**
- No entrance animations on initial load — content is already there, only skeletons reveal
- Scroll-triggered reveals use `IntersectionObserver` with `threshold: 0.15` — elements fade from `opacity: 0, translateY(12px)` to `opacity: 1, translateY(0)` with `transition: 0.5s ease`
- The skeleton shimmer is the only perpetual animation — everything else is one-time
- The spring hover on cards (`cubic-bezier(0.34, 1.56, 0.64, 1)`) is the only bouncy easing — all other transitions use `ease` or `ease-out`
- No parallax, no scroll-jacking, no full-screen takeovers — the page scrolls naturally

---

## Uniqueness Notes

**Differentiators from the existing corpus:**

1. **Diagonal sections as index-card metaphor, not decorative slants.** The corpus has `diagonal-sections` at 3% usage but treats diagonal cuts as visual decoration. xanadu.wiki's diagonal cuts are *structurally motivated*: they enact the overlapping index-card metaphor of the original Xanadu hypertext system. Every cut is angled the same direction (4°), creating a consistent "stack of offset cards" reading as you scroll — a narrative form, not decoration.

2. **Skeleton loading as content motif, not utility pattern.** `skeleton-loading` appears at 3% in the corpus. No existing design has used skeleton states as an expressive medium. xanadu.wiki's skeletons are designed to feel like watermarks emerging from aged paper — the shimmer is tuned to `1.4s` (meditative, not impatient), the color matches the paper ground, and the transition to real content is a slow `0.6s` dissolve. The loading state is **the experience**, not a waiting room.

3. **Strict monochrome enforced through muji philosophy, not modernist aesthetics.** Monochrome at 11% in the corpus is typically high-contrast or dark-mode. xanadu.wiki's monochrome is warm (`#F5F0E8` paper, `#1A1A1A` ink) and derives from the muji principle that color creates hierarchy by distraction — the site instead creates hierarchy through **scale**, **weight**, and **spacing** alone. The palette is a philosophical statement about how knowledge should be presented, not a style choice.

4. **Circuit motif as text-layer substrate, not hero imagery.** Circuit appears at 15% in the corpus but always as primary visual (hero section art, card backgrounds). xanadu.wiki uses circuit traces exclusively as a *sub-perceptual texture* — at 6–8% opacity, they register as "paper has memory" rather than "tech aesthetic." The motif references the computational substrate of hypertext without screaming it.

5. **The Footnote Ocean as interactive playful centerpiece.** No corpus design uses footnotes as primary interactive content. The entire section of 99 expandable footnotes is the site's signature element — it enacts Nelson's vision of deep annotation and transclusion, while the playful footnote content (self-referential, funny) delivers the tone. This is unique in combining `pattern: skeleton-loading` (each footnote expands like a loaded reveal), `motif: circuit` (dark background, PCB feel), and `tone: playful` (the actual written content of the footnotes) into a single section.

**Chosen seed:** `muji clean functional` (from seeds.json) — applied through the lens of the xanadu.wiki domain: muji's emptiness as a container for dense hypertext knowledge, functional minimalism serving maximum information density without visual noise.

**Avoided patterns (per frequency analysis):**
- `parallax` (74% — avoided entirely, no scroll manipulation)
- `stagger` (49% — used only on skeleton reveal, not as primary animation)
- `warm gradient` (89%/77% — refused; the warmth comes from paper tone, not gradients)
- `centered layout` (83% — deliberately asymmetric 2–9 column placement)
- `photography` (87% imagery — zero photographs; all texture is CSS/SVG)
<!-- DESIGN STAMP
  timestamp: 2026-05-12T01:42:33
  domain: xanadu.wiki
  seed: choice
  aesthetic: xanadu.wiki is an imagined **hypertext pleasure-garden archive** — Ted Nelson's ...
  content_hash: 410b6ea2532a
-->