DESIGN.md@packages/site git:20260815.0bd8f82A

Immutable. This exact content is served forever at /api/v1/blob/8266c3a71b981f78.

# DESIGN.md — Skill Heaven landing prototype

> **Persona note (N7, 2026-08-06).** The figure named **Lucy** throughout this
> internal doc is the line's **internal working name only**. Its design is
> final, but the **public name is reserved and undecided** — never hard-code it
> in shipped copy or user-facing code. **Milim is the Gaia Research lab mascot,
> not this line's persona.**

## Lucy visual authority and state color canon

The production authority is the approved character sheet at
`src/assets/lucy/authority/lucy-character-sheet-master.png`, interpreted with
`docs/lucy/authority/LUCY_CANONICAL_CHARACTER_SHEET.md` and
`docs/lucy/authority/lucy-canon.json`. Earlier hero assets and iteration sheets
are provenance, not authority. Lucy's anatomy and outfit never transform;
gravity, eyes, shards, lighting, inversion, and weapon count communicate state.

**Anatomy correction (2026-08-13):** the supplied sheet and v1 Heaven, Hell,
and Ultra bodies contain a three-leg contamination. The sheet remains authority
for face, hair, uniform, ribbon, eyes, weapons, shards, colors, and materials,
but not for pose or limb anatomy. Every new full-body render must have exactly
two independently traceable legs and two feet. Written anatomy constraints win
over contaminated raster poses.

**Modesty guard:** ordinary skin, bare legs, and thigh exposure are permitted.
Visible underwear, under-skirt crotch framing, translucent/parted skirt exposure,
wardrobe-malfunction silhouettes, and intimate-area focal framing are not. The
opaque sailor skirt and pose must naturally cover the underwear section. A
generated master that breaches this guard is rejected and regenerated; it is
never hidden with a downstream crop.

**Anatomy proportion guide (advisory):** Lucy is slender, not abbreviated or
needle-limbed. Use the accepted Heaven v2 read as the current reference: long,
believable legs with hip/thigh volume, a readable knee transition, calf taper,
and slim ankle/foot; a narrow waist must still connect naturally to ribcage and
pelvis. Avoid wasp-waist pinching, an overlong torso, tiny pelvis, or a skirt
concealing an implausibly short hip-to-knee span. This guides judgment rather
than imposing a numeric rejection threshold.

**Katana authority:** all front-page katana components must follow the approved
katana panel embedded in `lucy-character-sheet-master.png` and the workbench
crop `Lucy_Katana_reference.png`. Older Hero A/B commissioned sword rasters are
provenance only and must not seed new weapon geometry. The approved construction
is a physically real curved steel blade; dark navy/black handle wrap with pale
diamond openings; ornate round/slightly floral antique-gold tsuba; dark saya;
restrained gold fittings; and a small braided/tassel ornament where shown.
State lighting may reflect on steel but may not turn the weapon into glass or
energy. Ultra uses two matching copies; Hell is the full inversion of Heaven's
same registered katana geometry.

| State | Working production color | Non-negotiable treatment |
|---|---|---|
| Zero | Cyan `#37D6E0` | Deep black field, closed eyes, normal gravity, no wings or shards. |
| Heaven | Blue `#7CC4FF` | Saturated cyan-blue refraction, both diamond eyes open, ordered glass shards. |
| Hell | Registered full-scene chromatic inversion of Heaven | Heaven's exact pose, anatomy, crop, alpha, hair, uniform, ribbon, katana, wings, shards, and spatial composition are preserved. Every foreground and scene RGB value—including skin—is inverted. Only both closed eyes and exactly one vivid red tear differ semantically; no standalone flat Hell-pink token is canonical. |
| Ultra | Gold `#FFD24A`–`#F7C84B` | Never inverted; exclusive gold refraction, asymmetric eyes, two matching katanas. |

These values supersede incidental color sampling from older concept images.
Chroma green used during transparent-background extraction is a production
surface only and must never enter the brand palette.

> **Prototype, not the product.** Eight hero variations behind a preview
> switcher (`src/components/Switcher.tsx`). All share one content source
> (`src/content.ts`) and the real, measured token figures — messaging stays
> constant while the visual world changes per route. The exception is Hero
> A/B (below): a separately-authored design-tool prototype with its own
> copy and its own risk-ladder framing, ported in as-is rather than rebuilt
> against `content.ts`.

## How the newer three were derived (impeccable provenance)

The first three routes (`/overdrive`, `/prism`, `/default`) were hand-authored
from the owner's concept pegs. The **second three** (`/manifesto`,
`/instrument`, `/onebit`) were derived through the **impeccable** design skill
(`.github/skills/impeccable/`, v4.0.4), fresh from the same pegs with **no
anchor to v1**, at the owner's request: *"I want to see from fresh start how
impeccable will use our pegs."*

- **The roll** — `concept-seed.mjs --scope direction --mode persuade`
  (`PRODUCT.md` present): seed key **`346e6ded`**, **assigned index 6** (build a
  grounded direction, not a challenger), six catalog challengers dealt.
- **Grounded brief** — audience: aesthetic-driven early adopters; the thing to
  prove: the **Heaven ↔ Hell tension**; relationship to v1: **fully fresh**.
- **Craft bar** judged against three challenger reference cards (wood-type
  manifesto, nixie lab counter, one-bit Mac desktop). Each new direction fuses
  the grounded index-6 read with one challenger.
- **detect.mjs** (60-rule anti-slop scanner) run over all three: the only
  standing flag is the one-bit dithered-dot **wallpaper**, which is the literal
  1-bit desktop surface (the rule's own canvas/measurement exception) — kept
  deliberately. The Instrument serif was swapped off the "overused" list
  (Fraunces → Spectral) to clear its flag.

## The eight routes

`#/hero-a` is the current winner — `/` and any unmatched route redirect there
(`src/main.tsx`). Hero A/B are ported from an external design-tool prototype
(`src/variations/hero/useHeroEngine.ts` — the shared 5-act, wheel/keyboard/
touch-driven state machine both routes render), not derived from the pegs/
impeccable process described below; the other six routes are unchanged.

| Route | Name | World |
|---|---|---|
| `#/hero-a` | **Hero A · Reredos** (current winner) | Full-viewport 5-act scrollytelling piece. Centered, monumental `SKILL / HEAVEN` typeset behind Lucy, symmetric single wing, katana slash on Act III. Act V hands off to a live 7-rung risk ladder (OFF..MAX, ULTRA sealed past the firebreak) driving Heaven/Hell/Ultra. |
| `#/hero-b` | **Hero B · Guillotine** | Same engine as Hero A, asymmetric frame-cropped layout: Lucy bleeds off the bottom-right corner, edge-to-edge `HELL` wordmark, vertical rail labels ("COMPOSED · NOT INSTALLED" / "SLASH TO SUMMON"). |
| `#/overdrive` | **Overdrive** (v1, prior winner) | Kinetic `SKILL / HEAVEN` typeset, glass wing, angel katana, scroll-world parallax, Heaven→Hell glitch slice. |
| `#/manifesto` | **Wood-Type Manifesto** | 1914 letterpress conviction. Dark-on-light "paper." Oversized imperative verbs `SUMMON THEM. / RESTRAIN. / BREAK LOOSE`, numbered ordinals (01 SUMMON / 02 ENTER / 03 GATED), `//` ticker. A red blade slices diagonally mid-scroll and **destroys the grid** — restraint vs the fall. One accent (a single warm red), no gradients, no glow. |
| `#/instrument` | **Honest Instrument** | Nixie-tube lab counter. Six CSS glass tubes glow the real standing dose **20176** on a machined chassis; `−28.9% vs native`. Interactive posture rail lights per-posture readouts. Serif headline "Numbers you can summon." Proves the **two-number honest-dosing / HH-Index** value. Amber-on-black, reverent; Hell = a cold tamper flicker. |
| `#/onebit` | **One-Bit Invert** | Classic 1-bit OS desktop. Dithered wallpaper, real window chrome (`HEAVEN.app`, `PROJECTS`, `POSTURES` control panel, `WELCOME.md`), desktop icons, gated `HELL.app` (a locked door raising a 1-bit alert dialog). Heaven→Hell is a **literal `filter: invert()`** — the invert *is* the material. Strictly monochrome. |
| `#/prism` | **Prism** | Luminance / prismatic. Lucy as a translucent glass-shard figure, holographic hair, refracting halo. |
| `#/default` | **Default** | White-on-black Swiss restraint. One prism accent. |

**Known deviation:** Hero A/B render Lucy from a transparent raster cutout
(`src/assets/lucy-hero.png`) rather than the pure-SVG `Art.tsx` primitives every
other route uses. The original JPG remains in the asset folder as provenance;
the production route uses the Gaia-prepared RGBA cutout so the page background
can invert cleanly behind her.

## Shared contract

- `src/content.ts` — `HEADLINE`, `HARNESSES`, `POSTURES` (real two-number
  doses: floor 19,661 tok; product-floor 20,176 tok / −28.9% vs native),
  `COMMANDS` (`/skill-heaven` · `claude-zero` · `/skill-hell`), `CTA`.
- `src/styles/tokens.css` — the Luminance/Prismatic tokens (deliberately **not**
  the research-repo pink/cyan). Each variation may override locally; every
  selector is scoped under a per-variation root (`.vo .vm .vi .vb .vp .vd-…`) to
  prevent cross-variation CSS collisions.

## Product-truth guardrails honored across all six

- `/skill-hell` is shown in **every** variation as a **locked, gated** door —
  never an activator (P2).
- The launcher story is **compose + exec, never mutate shared state** (P3) —
  reflected in the "Composed, Not Installed" / "nothing mutated" copy.
- Doses are always **two numbers**, never averaged into one.
- No fabricated testimonials, logos, pricing, or counts. Token figures are the
  real measured benchmark results.

## Regenerate the previews

```bash
npm -w @gaia-skill-heaven/site run dev            # :5178
# then, with Playwright resolvable (PW_ENTRY or an installed `playwright`):
node packages/site/scripts/shots.mjs         # the original three
node packages/site/scripts/shots-new.mjs     # the newer three
```

Output lands in `packages/site/preview/` (gitignored — regenerate locally).