DESIGN.md@site git:20261013.098088bA

Immutable. This exact content never changes and is served at /api/v1/blob/799ef050281c6109.

# DESIGN.md — GEODE site (mangowhoiscloud.github.io/geode)

> Google Stitch DESIGN.md format — 9 sections. AI agents read this before writing UI for this codebase.
> Audience: developers, recruiters reviewing engineering work, technical reviewers.
> Surface: Next.js 16 + Tailwind 4 + React 19, static export at GH Pages.
> Aesthetic: GEODE Axolotl Rose — **cool near-black + one signature accent**, drawn from the GEODE character.
> Last verified against code: 2026-06-11 (PR-DOCS-REDESIGN-TOKENS).

---

## Current landing and docs contract (2026-09-08)

### Main restoration and Research isolation (operator-directed 2026-10-12)

The main landing (`/` and `/portfolio/`) restores the design from commit
`fcd0a3b9`, before the TypeUI white-canvas change. Restore its existing dark
palette, rose controls, spacing, recorded-run surface, agent loop, package
responsibilities and RSI section. Do not reinterpret or embellish that design.
Publication lists, cover previews and the Research selector are absent from the
main body. The header and hero Research links open `/research/` in the current
language; the existing footer retains its direct source links.

The independent `/research/` collection and readers retain their layout and
source artwork. The operator-directed 2026-10-13 revision below aligns their
collection colors with the restored main. The subsequent reader rollback below
restores the light artifact workspaces; PDFs/PPT, slide pixels, figures and
videos keep their original palettes and bytes.

**CSS ownership.** `landing.css` is scoped to `.geode-home` and restores the
prior main declarations. `research.css` is scoped to `.geode-research` and
preserves collection geometry while inheriting the shared colors. Global document selectors use
`:has()` with the corresponding root. Both stylesheets can remain loaded during
client navigation without recoloring the other surface. Shared global tokens,
Docs and About styles are unchanged.

**Navigation.** The restored `#features`, `#distill` and `#roadmap` sections
again use native in-page navigation. Old Research fragments still replace-
navigate to the independent collection, preserving language and selected
publication. No publication artifact is removed when its main-body preview is
removed.

**Collection behavior.** A tab click selects and pushes its fragment without
scrolling. Incoming fragments select the same publication. Panel IDs remain
separate from selection hashes; Arrow/Home/End move focus and Enter/Space
activate. GEODE, Jev and JEVDB headers retain `GEODE / Research` return links.
Each return link retains its publication selection (no hash for the default
GEODE report, `#jev`, or `#jevdb`) and language. Collection selection
URLs remain valid; scene-reading links use the explicit resource path, with
`lang` for language and a page/scene hash for position.

### Research color and copy revision (operator-directed 2026-10-13)

The main and publication collection share the §2 palette. Research keeps its
existing spacing, typography, selector and unframed media layout. Its dark
substrate and secondary text inherit `globals.css`; focus uses the rose
identity accent. Metadata uses the readable secondary ink.

### Reader light-canvas restoration (operator-directed 2026-10-13)

All three “Read scene by scene” destinations retain the light reader chrome
from `889f2874^`: `/research/geode/`, `/research/jev-system1-offloading/`,
and `/research/jevdb/`. Restore the existing cool-neutral canvas, dark ink,
blue focus, neutral download action, and light contents/source sheets without
changing layout or copy. GEODE and JEVDB share the scoped `.jevdb-reader`
palette; the standalone Jev projection uses its frozen light reader styles.
No global token changes or theme switcher apply to the dark main and Research
collection. Original PDF/PPT, images, diagram semantic colors, slide text and
build behavior remain source-owned.

Surface copy leads with actions, artifacts and observations. Keep sample
counts, common denominators, configuration pins, uncertainty, missing-data
status and author/study attribution next to the relevant evidence. Consolidate
repeated defensive prose into the existing measurement or source sections;
removing a disclaimer cannot imply measured superiority or a new experiment.

### Reader touch navigation (2026-10-13)

The artwork canvas accepts a single-finger horizontal swipe: left selects the
next scene and right the previous scene, without wrapping at either boundary.
GEODE/JEVDB use their existing selection functions; the Jev route projection
uses `show()` for whole-scene swipes while its original pager keeps in-scene
build navigation. The shared `src/lib/reader-swipe.mjs` owns recognition for
all three readers. Frozen Jev source, PDFs, PPT and slide artwork stay intact.

Start away from the outer 24px browser-navigation edges and move at least
48–96 CSS pixels (12% of canvas width), within 650ms, with horizontal distance
at least 1.5 times vertical distance. A vertical/diagonal onset, cancellation,
second contact, scroll, selection or modal abandons the gesture. Only the
artwork handles swipes; prose, controls, links within Jev scenes and overview
thumbnails retain their native interactions. Tapping an image still opens it
at full size. Swipes never add history at the first/last boundary.

The canvas permits `pan-y pinch-zoom`; at a zoomed visual viewport it restores
`auto` for panning. Do not disable selection, browser zoom or vertical scroll.
No mouse drag or trackpad-wheel interception applies. Buttons, keyboard,
language links and accessible scene announcements remain available.

### Research route ownership (2026-10-12)

`/research/` is the standalone publication collection with its existing
header layout and full publication selector. The restored main header links to this
collection; no publication list or preview is rendered in the main body.
Readers live at `/research/geode/`, `/research/jev-system1-offloading/`, and
`/research/jevdb/`. Canonical metadata and the sitemap identify these resources.
Language queries select a display language; fragments identify pages or scenes.
Within the collection, fragments select publications: the default GEODE report
uses no fragment; Jev uses `#jev` and JEVDB uses `#jevdb`. Historical
`#research-geode`, `#research-jev`, and `#jevdb-paper-review` addresses still
select the same publication and normalize with `replaceState`. This preserves
Back/Forward without adding a redirect entry. Selecting the active tab adds no
history entry. DOM tab/panel IDs remain separate from public URL fragments.
Queries stay before fragments; changing language retains selection or scene.
The collection and readers default to Korean; the existing landing defaults to
English. Compatibility navigation preserves that distinction.

The old homepage Research hashes and `/resaerch/jev-system1-offloading/` use
replacement navigation, preserving language and scene without a Back loop.
The frozen Jev publication remains checked in at its historical location.
`npm run build` runs `export-research-routes.mjs` after Next static export:
it projects routes/history and touch navigation, and rebases file references to the old served
asset addresses. No PDF, scene source, font, image, or video is regenerated.
Validate canonical and compatibility behavior against `site/out`, not Next dev.

### Research publications (operator-directed 2026-10-12 revision)

The Research landing is a media-led publication selector. The operator rejected
large framed description boxes and question/observation/materials columns.
Use one real, uncropped publication canvas with three visible document tabs:
GEODE report, Jev study, JEVDB review. Labels and a quiet selected underline
identify the document; no card background, border frame, corner treatment,
shadow, autoplay, or decorative illustration is added. The original artwork
retains its own palette and diagrams. The surface uses the shared dark GEODE tokens through `research.css`.

The original cover opens that same first page or scene. A caption identifies
the edition and language. Short copy distinguishes the historical GEODE
report, separate Jev measurements, and external JEVDB review. Inline links
name actual reader/PDF/PPT/video/evidence destinations. Keep all three tab
labels visible on mobile. Manual keyboard tab activation avoids changing the
large image on every arrow press; Arrow keys and Home/End move tab focus.
Scaffold, Seed, SIL, and related-work directions follow as unframed text.

References inspected for this revision:

- [Primer Brand MediaPlaylist](https://primer.github.io/brand/components/MediaPlaylist/):
  visible media choices and a shared presentation area.
- [Primer Brand River](https://primer.github.io/brand/components/River/):
  concise explanation beside actual media and direct inline links.
- [Carbon global header](https://www.carbondesignsystem.com/building-blocks/core/patterns/global-header):
  consistent global document actions separated from local content navigation.

These are interaction and composition references. No library package or new
visual theme is installed. Native React and the existing typography implement
the patterns. Unlike Primer's general preference against text-heavy imagery,
these previews deliberately reproduce the requested source report covers.

`/research/geode/` presents both existing 92-page PDFs in the Jev reading
workspace. Language changes artwork, text, and PDF while preserving page.
Chapter navigation, page search, full-size images, overview, extracted text,
keyboard paging, focus view, and a native source sheet support reading.
Original page claims are historical, not reevaluated or relabeled as current.
The Jev reader retains all 57 scenes and 81 builds; focus view and full-scene
text reveal the original content without redrawing figures or changing results.

### Harness and research entry (2026-10-06)

The landing leads with **Autonomous Agent Harness** and its separate
**Experimental Loop**. Self-hosted describes deployment, not the product's
whole identity. A solid runtime frame and dashed experimental frame show
execution observations flowing into research. The caption explicitly separates
search acceptance, independent validation, and release. This is a conceptual
map, never an animated/live status display.

Keep the existing `#0B0A10` substrate, `#14121B` surface, `#F2EEF5` ink,
`#ABA4BC` secondary text, and `#F49BC4` identity accent. The current landing
uses Outfit headings, Inter body, and Galmuri for the brand; preserve that
hierarchy and the existing rose primary action. Do not reintroduce the
historical full-rose choreography below. New sections add no automatic motion.
Desktop pairs the proposition with the two-layer map; mobile stacks them with
both layer names in the opening text. Research questions use flat rows rather
than four identical feature cards. Explicit KO/EN controls retain deep links.

Progressive disclosure is navigational: proposition → question → study →
source. The new `research/overview` page sits in the existing Experimental Loop
section, is directly linked from the docs index and the runtime/research reader
area, and uses visible question/design/observation/limit sections. The sitemap
still owns routes. Jev points to the existing frozen reader and matching
language; no report, PDF, or historical result is rewritten. SIL is a Scaffold
Search implementation flow, not a separately proven improvement result.

Official references inspected on 2026-10-06 informed information hierarchy:

- [LangGraph overview](https://docs.langchain.com/oss/python/langgraph/overview):
  explains runtime/framework/harness responsibilities before deeper references.
  GEODE adopts the explicit two-layer distinction.
- [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/): a small
  initial model, quickstart, then task-to-document routing. GEODE preserves an
  install action and adds question-led research entry points.
- [OpenHands introduction](https://docs.openhands.dev/overview/introduction):
  maps components to responsibilities and source. GEODE separates implementation
  links from the experimental verdicts they do and do not support.
- [Hermes docs](https://hermes-agent.nousresearch.com/docs/): distinct starting,
  usage, developer, and reference paths. GEODE retains its four shallow reader
  areas and visible chapter lists instead of adding another navigation tree.

These are information-design references, not copied brands or components.
Scientific comparisons are separately sourced on the research page: SelfSearch
uses no downstream reward during search; GEODE's evaluator-guided experiments
are not retrospectively described as a reproduction or direct influence.

The restored landing replaces the historical full-rose choreography below on
`/` and `/portfolio/` only. Both routes share `landing-page.tsx`; the
author/about/archive surfaces retain their existing design. Keep the GEODE
palette and character, with a dark reading substrate, visible navigation,
recorded Task/Tool/Result evidence, and install choices. Release labels read
`generatedSOT`; historical measurements retain their measured version.

The docs shell projects the existing sitemap into four directly selectable
reader areas. Topics and Experimental Loop chapters use visible headings, not
nested triangle disclosures; title/summary/path filtering searches all areas
in the sidebar, mobile dialog, and index. The sitemap remains
the sole route and previous/next authority. Preserve bilingual routes,
Markdown twins, keyboard focus and explicit language queries. Do not introduce
another navigation catalog, a UI dependency, or a site-wide CSS reset.
Mobile navigation uses a native dialog with explicit Close, Escape dismissal,
focus restoration and a separately scrollable list. Header actions use an
unframed icon and label, a 44px hit target, and a compact neutral keyboard-focus
outline; do not stack a colored ring around a permanent button border. Destination rows use
neutral titles with existing sitemap summaries; reserve color for selected
state and focus, not a wall of aqua underlines. Non-selected areas remain in
the HTML so Markdown exports retain the complete document index. Both inline
labels and descriptions include real whitespace for copying and accessibility.
The homepage's comparison limits, documentation index's design background,
benchmark records, Judge guidance and seed-run records stay directly readable.
Apple's [sheet guidance](https://developer.apple.com/design/human-interface-guidelines/sheets)
and [Linear's UI hierarchy](https://linear.app/now/how-we-redesigned-the-linear-ui)
inform the restrained controls; these are local web patterns, not vendor components.

Benchmark charts disclose the common denominator and uncertainty. The native
Terminal-Bench replay and recovered cache/phase evidence remain intact; neither
replay nor a runtime self-judge owns benchmark scores. Public evidence snapshots
are presentation data, not a new evaluator or release gate. Keep missing usage
distinct from zero and a partial subtotal distinct from a complete bill.

Before publication: run `npm run test:docs`, the landing evidence regression,
the static build and Markdown export, link/metadata checks, then desktop and
mobile browser checks for landing, docs filtering, active chapters, language
links, replay navigation, overflow and console errors. A local preview is not
deployment proof.

## 1. Visual Theme & Atmosphere

### JEVDB paper review reader (operator-approved 2026-10-12)

`/research/jevdb/` reuses the Decision Offloading reader described below:
its 224px flat scene list, compact header/toolbar,
large slide canvas, native mobile contents dialog, and right source sheet.
Reuse the existing Pretendard/mono assets, layout and scoped cool-neutral
light reader palette. The 19 v25 slide images and original PPT remain unchanged. KO/EN
controls translate navigation and reading notes; they do not claim a second
slide edition. The video and PPT stay in the opening header. Every slide has
one settled build, without artificial animation or a nonfunctional motion
control. Provide full-size images and original slide text for small screens.
Paper measurements, schematic examples, future directions, and the separate
GEODE U8c study keep their own conditions and sources beside the canvas.

### Jev research artifact exception (operator-approved 2026-09-28)

`/resaerch/jev-system1-offloading/` (the operator's literal path) preserves the
approved film's light slide canvas and embedded typography as a scoped artifact. This
is not a site light mode or permission to restyle landing/docs. Keep the
preview's build navigation, explicit KO/EN selection and language-matched PDF
download. Strip private production notes and local links; preserve research
failures and limitations. The user chose the existing six-track music edition,
including its track credits and cover art, without a claim of verified rights
documentation. Keep the final film on its approved external host. Only the
approved asset allowlist and its font licenses may accompany the artifact.

The outer reader is redesign-preserve, for external technical reviewers:
DESIGN_VARIANCE 4, MOTION_INTENSITY 2, VISUAL_DENSITY 4. Keep a compact header
with GEODE return, report title, explicit language state and one filled neutral
PDF action. Group Contents, overview, motion and step navigation near the canvas;
align labels horizontally and vertically, use the existing cool-neutral film
tokens and Pretendard/mono assets, 4px controls within 6px groups, and targets
of at least 44 CSS px. Mobile explicitly wraps the header and navigation. Preserve
focus, hover, disabled states, reduced motion, build API and scene hashes.
The 224px desktop scene panel is a flat, directly selectable list from the
existing slide inventory, not another navigation catalog. Below 1024px the
same list opens in a native dialog with explicit Close and Escape behavior.
The compact canvas toolbar stays visible while scrolling its content area.
Do not use triangular disclosures or nested accordions in the reader. Slide
progressive builds remain unchanged. Keep the footer's source entry singular.
At the user's request, sources open in a native modal right sheet: 600px on
desktop and viewport-fit on mobile, with a fixed title/Close row and only the
content scrolling. Escape, backdrop and Close return focus to the entry button;
Tab stays inside, background scrolling and slide keyboard shortcuts are isolated.
The `#readerSources` deep link opens the same sheet. This source panel separates
pinned study records, TypeSafe documentation, related research, and design
references. Use quiet ID/title columns, no citation pills or cards. Preserve
each destination and reference ID, and distinguish unlinked historical records
outside the public package instead of styling them as available downloads.
No new theme, font, library, marketing hero or card decoration is authorized.
The design reference is [Linear's first-party UI redesign](https://linear.app/now/how-we-redesigned-the-linear-ui):
chrome/content separation, alignment, restrained chroma and navigation hierarchy.
[getdesign.md's Linear analysis](https://getdesign.md/linear.app/design-md) is an
independent visual reference, not an official component system or endorsement.
Apple's first-party [toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars),
[segmented controls](https://developer.apple.com/design/human-interface-guidelines/segmented-controls),
[buttons](https://developer.apple.com/design/human-interface-guidelines/buttons),
and [sidebars](https://developer.apple.com/design/human-interface-guidelines/sidebars)
inform the logical action groups, equal-width language options, visible
selection and discoverable scene panel. Our 44px web targets adapt the native
44pt guidance; they are not the same unit. The 12/16/24px spacing, 18/16px title,
13px controls and 12px secondary text are local choices, not copied Apple or
Linear tokens. No official Apple CSS, Liquid Glass or Linear component claim.
The source sheet borrows the explicit Close and one-sheet-at-a-time principles
from [Apple's sheet guidance](https://developer.apple.com/design/human-interface-guidelines/sheets).
Its browser focus, inert background and Escape behavior use the native
[`dialog` contract](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog),
not an imitation of an Apple component.

**Mood**: a modern dark developer surface keyed to the GEODE character — a rose axolotl explorer with a gold headlamp and an aqua magnifier (`public/images/geode-*.png`). Cool near-black substrate with a violet undertone, one saturated signature accent (rose) carried everywhere as low-opacity tints, gold reserved for action, aqua for information. Reads like a well-lit terminal, not a leather desk.

**Adjectives**: cool dark, signature-tinted, character-grounded, restrained, single-substrate.

**What it is not**: brown-warm stone, navy deep-sea, neon, multi-accent rainbow, motion-decorated. Pure-black surfaces (`#000`) and pure-white text (`#fff`) are forbidden.

**Inspiration touchstones**: Hermes docs (one bold accent + tinted hairlines + dot-grid texture on near-black), Anthropic docs (typographic restraint), Cursor (developer-first dark).

## 2. Color Palette & Roles

| Role | Hex | Usage |
|---|---|---|
| `--paper` | `#0B0A10` | App background. Cool near-black, violet undertone. |
| `--paper-2` | `#14121B` | Card / elevated surface (sidebar, callout, hover). |
| `--paper-deep` | `#06050A` | Code block (inset). |
| `--ink` | `#F2EEF5` | Primary text. |
| `--ink-1` | `#E5DFEC` | Headings. |
| `--ink-2` | `#ABA4BC` | Body secondary. |
| `--ink-3` | `#6E6880` | Captions, metadata. |
| `--rule` | `rgba(244,155,196,.12)` | Hairline borders. **Rose-tinted**, never neutral gray. |
| `--rule-soft` | `rgba(244,155,196,.06)` | Softer divider, table header background. |
| `--acc-artifact` | `#F49BC4` | **AXOLOTL ROSE** — the signature. Logo, wordmark, active nav, selection, reference chip. The character's body color. |
| `--acc-line` | `#FFD66B` | **LAMP GOLD** — action. CTA, emphasis, string literals, tutorial chip. The explorer's headlamp. |
| `--acc-soft` | `#F7B3D2` | Rose hover / elevated state. |
| `--acc-aqua` | `#7FD8E8` | **AQUA** — information. Links, inline code, how-to chip. The magnifier lens. |
| `--acc-si` | `#4D9BFF` | **PETRI-BLUE** — scoped. Only the 04-self-improving docs section + petri-bundle bridge (the vendored hub viewer keeps Bootstrap blue). Never a general accent. |
| `--acc-si-soft` | `#7FB5FF` | Self-improving hover. |
| `--code-bg` | `#06050A` | Code block background. |
| `--code-text` | `#E5DFEC` | Code block text. |
| `--code-string` | `#FFD66B` | Code strings (lamp gold). |

**Identity rationale.** The palette is extracted from the GEODE character, so
the mascot, the site, and the brand read as one thing. Rose is deliberately
contrarian for a developer tool (Hermes owns gold, Anthropic terracotta,
petri-bundle Bootstrap blue) — it is distinctive and it is literally the
product's face. The Hermes lesson applied here is not its color but its
**tint discipline**: the signature accent appears at 6–15% opacity in every
hairline, table header, callout background, and active state, which is what
makes a dark surface read as designed rather than default.

**Color semantics — fixed, never improvised**:
rose = identity (who), gold = action (do), aqua = information (read).
A screen should never have all three competing; rose tints carry the surface,
gold and aqua appear only where their meaning applies.

**Single substrate.** Every page is dark by design. No light mode, no
dark-panel-on-light-page. Character PNGs were authored on transparent
backgrounds and sit naturally on this substrate. Scoped exceptions: the
original artwork and the operator-restored light research readers. The
Research collection retains the same dark substrate as the main landing.

**Petri-blue is scoped, not dead.** `--acc-si` keeps the hub's Bootstrap-blue
identity on exactly two surfaces: the 04-self-improving docs section
(`data-doc-section` + `--section-accent` mechanism in docs-shell.tsx /
docs.css) and the petri-bundle bridge pages. The vendored Inspect viewer
cannot be re-skinned, so the section accent preserves continuity into it.

**Generated art assets (PIL, reproducible).** `public/images/geode-lab-scene.png`
— the representative character image (operator brief 2026-07-10: dot art x
Lanthimos; Poor Things porthole sky + gold sun, The Favourite checkerboard
marble in one-point perspective, Sacred Deer symmetric columns, the canonical
GEODI_PIXELS sprite centered as the specimen; 240x300 pixel canvas, NEAREST
x5, 6-color palette from §2 + gold) and `geode-gallery-blur.jpg`
(gaussian-blur gallery band behind the floating terminal), plus
`geode-etch-line.png` (white-line engraving variant, currently unmounted).
Regeneration recipes live in the introducing PRs; keep inks inside §2.
Motion (operator-approved): /portfolio uses framer-motion choreography —
hero stagger, scene idle float, terminal rise, petri-dish spring, cadence-bar
growth — all gated by `useReducedMotion`. The docs surface keeps the old
motion budget.

**Rose-and-white loop-punk composition (operator-directed 2026-07-10 final,
supersedes the two-surface band rule).** /portfolio is one rose field
(`--acc-artifact`) written in warm white `#FFF0F8` — two colors only; the
terminal mock keeps its dark product-screenshot colors by standing exception.
White appears three ways: as ink (serif statements, mono stamps, hairline
grids at 55-75% alpha), as paper plates carrying rose line-art schematics,
and as the stage of the finale. The distillation and the laboratory are one
continuous sticky act: white token rain converges through dissolving-gradient
hairline thresholds, fills the full-bleed pixel wordmark, and further scroll
fades in the reveal — a white stage enters and the rose field becomes a
specimen slide. LazyWeb formula (sharp corners, technical line-art, terminal
hero) carried in the two-color register; hierarchy from white alpha, never a
third hue. **Deep-rose ink `#C2447F` (2026-07-11 legibility pass)**: the
signature `#F49BC4` fails as ink on the white plates (~1.8:1), so anything
written on white (line-art strokes, plate titles/captions, command-chip
text, the winning memory band) uses the darkened same-hue ink (~4.5:1);
the signature stays the field/fill color. Plate textures sit behind an 80%
paper scrim. The one sanctioned exception is the terminal mock, which keeps its dark
product-screenshot colors (`--paper-deep` + ink tokens) because it is a
product artifact, not page chrome. Scroll is choreography, not paging:
curtain-stack sections over a pinned hero, `StageLight` scroll-linked
dimming, the distillation act (token rain converging band-by-band through
hairline filters labeled with Astryx `Token` chips, piling onto the GEODE
word as a top-down fill), and the wordmark-to-laboratory crossfade finale.
The hero keeps decorative pixels inside a right-side crop. A solid rose
copy-safe layer clears the title area without a gradient, while a deep-rose
outline preserves the warm-white letterforms at unusual zoom levels or aspect
ratios. Compact field labels use the same accessible deep-rose ink
(`#7F1747`, 4.88:1 against the signature field).
The docs surface keeps the single dark substrate rule.

**Texture.** `.rose-grid` (globals.css) is a 1px rose dot grid at 5% opacity,
28px pitch — for the landing/hero surfaces only. It is a pattern, not a color
gradient; the no-gradient rule below stays intact.

## 3. Typography Rules

| Variable | Family | Weights | Usage |
|---|---|---|---|
| `--font-inter` | Inter | 400, 500, 600, 700 | UI chrome, body sans |
| `--font-display` | Outfit | 600, 700, 800 | Page titles (h1), section labels |
| `--font-fira-code` | Fira Code | 400, 500 | Code blocks, file paths, version chips |
| `--font-serif-display` | Noto Serif KR 600/900 (next/font/google, unicode-range 슬라이스) | 600, 900 | Editorial display (operator-approved 2026-07-10, Hermes-landing register): hero statements, section titles, chapter-band declarations. Pairs with pixel wordmark + mono labels. `word-break: keep-all`. |
| `--font-pixel` | Galmuri11 (OFL, vendored woff2 in `src/fonts/`) | 400, 700 | Character-facing display (operator-approved 2026-07-10): /portfolio h1/h2/era titles/stat numbers, docs-shell wordmark. Matches the GEODI_PIXELS dot mascot. Loads only on pages importing `src/fonts/galmuri.ts`; never for body prose. Always `letter-spacing: 0` (pixel glyphs break under negative tracking). |

**Body is sans (Inter), not serif.** Editorial restraint comes from spacing, line-height, and color discipline — not from a serif body. A dark substrate and serif body together would feel funereal; Inter on near-black reads as a professional dossier.

**Korean (KO mode)**: same families. Korean glyph rendering falls back through `Apple SD Gothic Neo`, `Noto Sans KR`, `Malgun Gothic`. No additional Korean web font.

**Scale** (page prose):

| Element | Size | Line height |
|---|---|---|
| h1 (hero) | clamp(3rem, 8vw, 5rem) | 1.02 |
| h1 subhead | clamp(1.25rem, 2.5vw, 1.6rem) | 1.30 |
| h2 (section) | 1.6–2rem (~26–32px) | 1.20 |
| h3 (subsection) | 1.2–1.4rem | 1.25 |
| body | 16px | 1.65–1.75 |
| caption | 13px | 1.45 |
| code (inline) | 13px | 1.50 |
| code (block) | 12.5px | 1.65 |
| table cell | 13–14px | 1.50 |

**No text gradients. No clip-text effects.** Solid `--ink-1` for hero headlines.

## 4. Component Stylings

### Page-level wrapper

```tsx
<main className="min-h-screen bg-[var(--paper)] text-[var(--ink)]">
```

### Sticky header (when present)

`sticky top-0 z-30 border-b border-[var(--rule)] bg-[var(--paper)]/85 backdrop-blur`

### Sidebar

- Width 256px, sticky, own scroll.
- Section labels: `text-[10px] uppercase tracking-[0.18em] text-[var(--ink-3)]`.
- Item: `text-[13px] text-[var(--ink-2)]`. Active: `bg-[var(--paper-2)] text-[var(--ink)]`.

### Cards

- `rounded-lg border border-[var(--rule)] bg-[var(--paper-2)] hover:border-[var(--ink-3)] p-5 transition-colors`
- No shadow. Hairline border only.

### Locale toggle

- Two-button group, hairline border, mono `text-[11px]`.
- Active state: `bg-[var(--paper-2)] text-[var(--ink)]`. Inactive: `text-[var(--ink-3)] hover:text-[var(--ink)]`.

### Hero

- Single-column 720px content max-width.
- h1 in display font, `--ink` color, no gradient.
- Subhead in display font, `--ink-1` color.
- Two narrative paragraphs, body sans, `--ink-2`.
- A single mono code block (or none).
- Nav links as small bordered chips, hairline border, hover swaps to rose.

### Tables

- `border-collapse: collapse; font-size: 13–14px`.
- `border: 1px solid var(--rule)` on every cell.
- Header row: `bg-[var(--paper-2)]; font-weight: 600; color: var(--ink-2)`.

### Code

- Inline: `bg-[var(--paper-2)]; padding: 0.1rem 0.4rem; border-radius: 3px; color: var(--code-string)`.
- Block: `bg-[var(--code-bg)]; border: 1px solid var(--rule); border-radius: 6px; padding: 1rem 1.25rem; color: var(--code-text)`. Horizontal scroll allowed; never wraps.

### Mascot

- Geodi PNG sits naturally on `--paper` (cool near-black) — no inset wrapper needed; the PNG was authored for dark mediums and matches the substrate. Placement budget: landing hero, quickstart finish, 404/empty states. Never inside docs prose.
- 36×40px in hero, 32px in footer. Always static, never animated.
- **Portfolio-hero exception (operator-approved 2026-07-10)**: the /portfolio character card renders the canonical pixel sprite via `GeodiSprite` (`src/components/geode/geodi-sprite.tsx`, grid transcribed from `core/ui/geodi_art.py::GEODI_PIXELS`) at large scale, with a 2-frame eye blink on a 7s `step-end` cycle (`prefers-reduced-motion` disables it). Animated mascot budget (blink + 2-frame idle bob + prompt caret) is scoped to /portfolio; the pose PNGs (`geode-idle/discover/focus`) may mark growth-era rows and section dividers there at 44-52px with `image-rendering: pixelated`. The docs-shell header wordmark carries a STATIC `GeodiSprite` at scale 2 (operator-approved 2026-07-10) — the one docs-chrome mascot placement; still never inside docs prose.

### Blockquotes

- Use a neutral hairline (`var(--rule)`) or spacing; do not add a colored accent bar.

## 5. Layout Principles

- **Single column** for prose-led pages (landing, scaffold, docs body): 720px content max-width, centered. The geode landing composes this.
- **Three-column** for docs index: sidebar 256px · content 720px · gutter 32px. Outer max 80rem.
- **Vertical rhythm**: 96–128px between major sections. 48px between subsections. 1.4rem between paragraphs.
- **Sticky surfaces**: header, sidebar (own scroll). No sticky footers.
- **Whitespace policy**: prefer empty space to filler. Below H1 sits a single muted summary line, no decorative dividers above.

## 6. Depth & Elevation

- **Borders, not shadows.** Hairline `--rule` (rose tint at 12% opacity) demarcates cards and sticky surfaces. The single substrate already does the contrast work.
- **Tone shifts.** Elevation comes from `--paper` → `--paper-2` (~6% lighter), not from luminance bumps. Code blocks go the other direction: `--paper-deep` (~8% darker) for inset code.
- The only blur is sticky-header `backdrop-blur` over the page background.
- No glow, no neon, no emboss.

## 7. Do's and Don'ts

**Do**:
- Default to `--paper` substrate everywhere. Single dark mode.
- Use `--acc-artifact` for OS / artifact / runtime / model content.
- Use `--acc-line` for scaffold / process / discipline / CI content.
- Use tables for structured comparison; bullet lists for narrative enumeration.
- Cite repository paths in mono `--code-string`; use line numbers only in revision-pinned evidence links.
- Use code blocks for any literal Python / TS snippet, even one-liners.
- Trust solid colors. Never compose colors via gradient.

**Don't**:
- Don't introduce a light mode. The substrate is fixed.
- Don't use pure black `#000` or pure white `#fff` — both are too cold.
- Don't introduce gradients (text or background).
- Don't add motion beyond `transition-colors`, with ONE sanctioned exception: the `FallIn` scroll-entrance (`src/components/geode-docs/fall-in.tsx`, hermes-agent landing style — element drops from above and spring-settles ONCE when it first scrolls into view, honors `prefers-reduced-motion`, stagger ≤0.1s per item, tilt ≤1°). Use `FallIn` for card/list entrances; do not hand-roll other springs, slides, or fade-ins beyond the once-per-page-load 0.4s opacity fade.
- Don't add emojis to UI chrome (titles, headings, labels).
- Don't introduce new accent colors. Rose for identity, gold for action, aqua for information, scoped petri-blue for the self-improving bridge, and that is it.
- Don't use `dark-panel` or `mascot-inset` utilities — they were transitional and are removed in the dark-mode reset.
- Don't add larger corner radii than `rounded-lg` (8px).
- Don't append decorative arrows (`→`, `▸`) to links, CTAs, or stat values (operator 2026-07-10, slop signal). Link text alone carries the affordance; version/date ranges use `~`.

## 8. Responsive Behavior

- **md (≥768px)**: full layout, sidebar visible (where applicable).
- **<md**: sidebar collapses, content fills with `px-6` margins.
- Tables overflow horizontally on small screens; never collapse to stacked card layout (the comparison value is lost).
- Code blocks scroll horizontally on overflow; never wrap.
- Touch targets: ≥32×32px effective hit area.

## 9. Agent Prompt Guide

When asked to build or modify UI in this portfolio repo:

1. **Read this DESIGN.md first.** Tokens are defined here; do not introduce new ones.
2. **Use `var(--*)` tokens, not hex literals.** New components reference `var(--paper)`, `var(--ink-1)`, etc. Hex literals are only acceptable in legacy components scheduled for migration.
3. **Single substrate.** Every page wraps in `bg-[var(--paper)] text-[var(--ink)]`. Section-level dark or light overrides are forbidden.
4. **Mascot images sit naturally on the substrate** — do not wrap in inset containers. Geodi was authored for dark mediums.
5. **Two-mode accents.** When emitting an artifact (OS, runtime, prompt, hash) reference, use `--acc-artifact`. When emitting a line (scaffold, ratchet, CI, kanban) reference, use `--acc-line`. Mixing them within a single section is acceptable only when comparing the two modes (recursion table).
6. **English portfolio, Korean-first docs.** `<html lang="ko">` comes from `src/app/layout.tsx`. The portfolio fixes its surface locale to English, marks its content root with `lang="en"`, hides the locale control, and disables query-string language overrides. Docs remain fully bilingual through `<Bi ko={...} en={...} />`, and localized component prose uses `t(locale, ko, en)`.
7. **Verification**: choose checks by the changed surface using the [verification reference](../.agents/skills/geode-workflow/references/verification-gates.md). `npm run build` includes TypeScript checking; repeat a standalone type check only when it adds new evidence.

**Forbidden additions** (without explicit user approval):
- New web fonts.
- New color tokens.
- shadcn/ui new components beyond Dialog / Slot / Tabs / Tooltip (already installed).
- Animation libs beyond Framer Motion (already installed, used minimally).
- A second design surface (light mode, marketing-style hero, etc.).
- The legacy `--sea-*`, `--glow-*` palette references in new code. Existing references will migrate over time.

**Reference DESIGN.md examples for similar aesthetic**: VoltAgent/awesome-design-md → Anthropic (dark variant inferred), Cursor, Linear (dark mode). Do not borrow gradient or neon patterns from any of them.

**Astryx (scoped, operator-approved 2026-07-10).** `/portfolio` mounts
`@astryxdesign/core` (Meta's open-source design system, React + precompiled
StyleX CSS) as its component foundation: SegmentedControl, MetadataList,
ProgressBar, Token. Astryx tokens are attribute-scoped
(`[data-astryx-theme]`), and `src/app/portfolio/astryx-geode.css` remaps the
semantic color/font tokens onto the §2 palette, so components render in
GEODE identity, not Meta neutral. Rules: (1) Astryx components stay inside
`data-astryx-theme` wrappers on /portfolio; do not spread them to docs
pages without a new approval. (2) Never import `@astryxdesign/core/reset.css`
(unscoped global reset). (3) `theme-neutral` globally sets
`color-scheme: light dark`; the bridge CSS pins `:root { color-scheme: dark }`
back. If the bridge file is removed, remove the theme import with it.

---

## 10. Portfolio Patterns (researched)

The hub at `/portfolio/` and the project pages adopt patterns proven on
high-attention developer portfolios and on top-starred Claude Code tool
READMEs. This section names the patterns and their sources, so future
edits stay anchored to the right reference instead of drifting into
generic SaaS-marketing layouts.

### Adopted patterns

| Pattern | Source / Precedent | Why we adopt it |
|---|---|---|
| **Single dated header** ("Portfolio · 2026-05-03") | leerob.io, paco.me | Shows the site is alive, makes the operator accountable to its currency. |
| **§ Now section** (current focus, dated entries) | nownownow.com convention, derek sivers | Recruiters read this first. Three lines that fit on one screen, freshest at top. |
| **§ Selected Work, not full CV** | brittanychiang.com, leerob.io | Two or three exhibits with concrete numbers beats a chronological resume. |
| **§ Recognition** (awards, talks, blog/yt counts) | senior-eng portfolios across industry | Outside validation in three lines max. No badges, no logos. |
| **§ Influences** (named people / projects + one-line note) | rauchg.com, paco.me's "things I like" | Signals intellectual lineage. Lifts the portfolio above task lists. |
| **Honest "currently looking for X" only when applicable** | (deliberately omitted today) | Adds friction when not actively job-seeking; remove if false. |
| **Code blocks in landing** | Cursor docs, Vercel docs landing | Shows the operator works in code, not slides. |
| **Mono `file:line` citations** | Anthropic docs, Linear changelog | Citations as content, not footnotes. |
| **Footer = nav, not legalese** | brittanychiang.com, leerob.io | Plain links to deeper pages. No decorative arrow suffixes. |

### Researched references — top-starred Claude Code tools

Their READMEs and landings consistently:

- Open with one-sentence purpose ("X for Y").
- Show install in three lines max.
- List concrete capabilities, not adjectives.
- Hide setup notes / troubleshooting in deeper sections.
- Use `code blocks` instead of marketing prose where possible.

Examples to study (publicly available repositories):

- `claude-code-action` — GitHub action; README is install + ready-to-paste YAML.
- `ccmanager` — CLI; README is install + commands + screenshots.
- `claude-flow` — orchestration; README is concept diagram + mode list.
- `awesome-claude-code` — curated list; sectioned by use case, no editorial fluff.

### Anti-patterns we avoid

- Generic "About me" paragraphs that read as cover-letter prose.
- Logos of past employers as visual proof.
- Skill bars / radar charts.
- Quote callouts from press / "What people say".
- Animated counters of GitHub stars / downloads.
- "Let's chat" CTA buttons. Contact lives in the footer as plain text.
- Theme switcher. We have one substrate.
- Light mode of any kind.

### Hub structure (canonical)

```
[Header]                  Name + role + bio paragraph (≤2 sentences)
[§ Now]                   3 dated entries, freshest at top
[§ Selected Work]         2–3 cards, each with concrete numbers
[§ Recognition]           ≤4 lines, label + detail
[§ Influences]            3–5 named references with one-line notes
[Footer]                  Plain mono links to deeper pages
```

Mobile collapses the three-column header to a single column; everything
else is already single-column.

### Voice guideline

Korean prose follows 합니다체 — the formal register that Korean tech
blogs (토스, 우아한형제들, 네이버 D2) use for engineering content.
Avoid 한다체 (literary), 해요체 (casual), 평어체 (academic). Numbers
stay Arabic in metric strips; in body prose they remain Arabic too
(64회, 5,523개) — this matches Korean tech-blog convention more than
prose convention (예순넷, 오천오백이십삼).

English prose stays declarative and concrete. Avoid em-dash chains
beyond two per paragraph. No "let's", "we'll", "exciting", "powerful",
"revolutionary". Past tense for shipped work, present tense for what
the system does today.

### Anti-LLM-smell checklist for new copy

Before merging copy changes, verify the prose does not exhibit any of:

- [ ] Slogan-as-equation ("X = Y. Y = Z.") — break into sentences.
- [ ] Em-dash heaped lists — convert to clauses.
- [ ] Unspecific verbs ("수행한다", "처리한다", "활용한다") — replace
      with concrete action verbs.
- [ ] "Frontier 어디에도 없다" or other unverifiable superlatives.
- [ ] Quotes around English terms purely for emphasis.
- [ ] Korean morphology of large numbers (예순네, 다섯, 아홉) outside
      narrative prose.
- [ ] Marketing-flavored adjectives (powerful, robust, seamless,
      elegant, beautiful).
- [ ] Sentences that translate cleanly back to "we built X to solve Y."

---

## 11. Petri-bundle bridge surfaces

The generated hub and vendored Inspect viewer are separate static surfaces.
[Pages](../.github/workflows/pages.yml) copies `docs/self-improving/` after the
Next.js build. `docs/petri-bundle/index.html` only redirects the legacy URL.

| Surface | Published path | Source |
|---|---|---|
| Hub | `/geode/self-improving/` | `docs/self-improving/index.html` |
| Inspect viewer | `/geode/self-improving/petri-bundle/` | `docs/self-improving/petri-bundle/` |
| Seed bundle | `/geode/self-improving/petri-bundle/seeds/` | The viewer's `seeds/` subtree |
| Seed detail | `/geode/docs/petri/seeds/<run_id>/<candidate_id>/` | Next.js static-export page |

Use the viewer route `#/logs/<encodeURIComponent(eval_filename)>`, keyed on
`logs/listing.json`; `#/tasks/...` is not a supported route. Raw candidate links
use the seed bundle's `<run_id>/candidates/<id>.md` path. Omit unmatched eval
links rather than guessing a task ID. The current contract is also shown in
`src/app/docs/petri/bundle/page.tsx`.

Keep the viewer's generated assets intact. Trace the existing `geode hub build`
entrypoint in `core/cli/commands/seed_pool.py` to its renderer before editing;
do not add a second template or hand-edit a generated page.

### 11.1 Color policy on bridge surfaces

Inspect's Bootstrap palette stays in its own bundle; the Next.js shell uses §2
tokens. `--acc-si` remains scoped to the self-improving section and its bridge,
not a general accent. Read the hub's [color policy](../docs/design/self-improving-hub-system.md#3-color-palette--roles)
alongside its current renderer. Do not copy palette literals into another table.

Seed Markdown is rendered at build time with `gray-matter` and `marked`.
Keep normal prose styles, accessible headings, and explicit missing-data states.
Use plain destination links without decorative arrows, emoji, or navigation
card grids.

---

**Maintained here**: `site/DESIGN.md`. Token implementation:
`src/app/globals.css`. Update the relevant rule when its implementation changes.