# Design Language for ppuzzle.org ## Aesthetics and Tone ppuzzle.org is a **topographic puzzle engine disguised as a mountaineer's field notebook** — where each puzzle is a summit to be solved, each solved piece reveals new elevation, and the entire surface of the page breathes with the restless energy of a climber halfway up an exposed ridge. The aesthetic is pure **avant-garde**: no affordances telegraphed, no friendly rounded buttons, no grid of testimonials. The interface is terrain. The user reads it the way a climber reads rock: by texture, by shadow angle, by the logic of what must come next. The palette is built around the absolute darkness of high-altitude night: `#050508` (void-black, the sky at 4am above the treeline), `#0d0d1a` (deep indigo-black, the underside of a storm cell), `#12ff7a` (electric chartreuse-green, the neon of a headlamp bouncing off fresh ice), `#ff2d6e` (neon magenta-pink, the emergency flare cut), `#00c3ff` (electric glacier-blue, bioluminescent crevasse glow), and `#f0f0f0` (near-white, the chalk dust on a fingerhold). No warm hues. No softness. This is above-treeline territory. The tone is **bold-confident without being aggressive**: the site does not explain itself to you. It trusts that you — the puzzle-solver, the pattern-recognizer — will understand the language. Like a topographic map given to someone who knows how to read one, the design assumes competence. Directions are implied by form, not labeled. Inspiration: Olafur Eliasson's glacier-light installations. Ryoji Ikeda's data-terrain audio-visual work. Erik Demaine's mathematical paper-folding sculptures. The design sits precisely at the intersection of mathematics, mountaineering, and signal-art. ## Layout Motifs and Structure The layout is **hero-dominant** in a way the corpus has never attempted: the hero is not a banner with text on it — the hero is the puzzle itself, rendered live, occupying the full viewport with no chrome. The puzzle surface IS the hero. Navigation, branding, and secondary content exist only as **edge annotations**: hairline text labels printed at the absolute perimeter of the screen like the legend on a topo map, never intruding on the central terrain. **Macro structure:** 1. **Full-Viewport Puzzle Terrain (`100svh`, `100svw`):** A dark field on which the active puzzle is rendered. No padding. No card borders. No drop shadows. The puzzle tiles are the only visual element that matters. The mountain-landscape motif lives here: each puzzle's background gradient-mesh represents a topographic slice — ridgelines as lines, elevation as color depth, solutions as summits achieved. 2. **Edge-Annotation Navigation:** All navigation is compressed into four edge strips — 32px tall on top and bottom, 24px wide on left and right. Top edge: domain wordmark left-aligned, puzzle-counter right-aligned. Bottom edge: current puzzle name left-aligned, solve-streak indicator right-aligned. Left edge: difficulty scale (a tiny topo line running vertically, the current puzzle's difficulty marked as a red pin). Right edge: minimized legend. All set in mono at 9px, color `#f0f0f0` at 50% opacity. They disappear on hover of the puzzle field. 3. **Elastic Panel Reveal:** Secondary content — puzzle library, leaderboard, settings — lives in **elastic panels** that spring in from the edges with genuine physics. Left panel snaps in from the left edge when the user swipes or presses `[` . Right panel for stats. These panels are dark-on-dark: `#0d0d1a` background with `#12ff7a` hairline borders. They have spring overshoot (goes 8px past target, bounces back in ~180ms, cubic-bezier(0.34, 1.56, 0.64, 1)). 4. **Gradient-Mesh Depth Field:** Behind the puzzle tiles, a full-bleed mesh gradient shifts slowly (12-second loop, no repeat) representing altitude. At low difficulty: deep navy. At medium: indigo-to-black with glacier-blue midtones. At high: black with chartreuse ghost-lines. The mesh is built from 9 anchor points with smooth interpolation, rendered as an SVG `feDisplacementMap` filter on a `feMerge` composed layer — not a CSS gradient. 5. **Puzzle-tile Grid (the non-grid grid):** Tiles are not on a conventional grid. They use a **broken-grid elastic layout**: rows are offset by a randomized but seeded amount (tied to puzzle ID) so the grid looks as though it was stretched and released — the topographic distortion of a paper map that got wet and dried. Tile gaps use `#12ff7a` at 8% opacity as a hairline. Solved tiles shift to `#00c3ff` hairline. Unsolved tiles breathe with a 4-second pulse at 6% opacity. ## Typography and Palette **Typography — mono only, all from Google Fonts, used with precision:** The site is set entirely in monospace, but mono used at the frontier of its expressiveness — not as code-aesthetic, but as **instrument-panel precision**. Three weights, two faces: - **Primary Display:** [`Space Mono`](https://fonts.google.com/specimen/Space+Mono) — Regular (400) and Bold (700). Used for the wordmark `ppuzzle.org` at `clamp(3.5rem, 8vw, 9rem)`, tracking `0.18em`, all-lowercase. Also used for all puzzle-tile labels at `9px`, `letter-spacing: 0.06em`. Space Mono has the correct angularity — its terminals are sheared, its bowl shapes are asymmetric — it reads as a high-altitude instrument font rather than a programmer's convenience font. - **Secondary / Edge Annotations:** [`JetBrains Mono`](https://fonts.google.com/specimen/JetBrains+Mono) — Light (300) for edge-strip annotations, all numerals and single-letter labels. At `9px` / `10px`, JetBrains Mono's slightly narrower letterforms pack cleanly into the 24–32px edge strips without crowding. - **Tertiary / Panel Labels:** [`Fira Code`](https://fonts.google.com/specimen/Fira+Code) — Regular (400) for panel-interior content only. Fira Code is the most neutral of the three — it disappears behind the content, which is what panel labels should do. **Scale:** - Wordmark: `clamp(3.5rem, 8vw, 9rem)`, `font-weight: 700`, tracking `0.18em`, color `#f0f0f0` - Edge strips: `9px` / `10px`, `font-weight: 300`, color `#f0f0f0` at `50%` opacity - Panel headings: `14px`, `font-weight: 700`, color `#12ff7a` - Panel body: `12px`, `font-weight: 400`, color `#f0f0f0` at `80%` opacity - Puzzle tile numerals: `9px` centered in tile, `font-weight: 400`, color determined by tile state **Palette (all named, all hex, functional roles):** | Token | Hex | Role | |-------|-----|------| | `--void` | `#050508` | Page background, deepest black | | `--deep` | `#0d0d1a` | Panel backgrounds, secondary layers | | `--peak` | `#12ff7a` | Primary accent — solved states, borders, headings | | `--flare` | `#ff2d6e` | Error states, high-difficulty markers, emergency accent | | `--glacier` | `#00c3ff` | Active selection, mid-solve state, glacier-blue accent | | `--chalk` | `#f0f0f0` | Primary text, tile numerals, wordmark | | `--mid` | `#1a1a2e` | Mesh gradient midpoint, tile hover state | | `--ridge` | `#0a2a1a` | Subtle green-tinted dark for topographic depth | ## Imagery and Motifs **All imagery is generative and mathematical — zero photography, zero stock, zero icons.** The visual language is built from three overlapping systems: **1. Topographic Gradient-Mesh (primary):** The background of every puzzle view is a unique gradient-mesh computed from the puzzle's seed value. The mesh has 9 control points arranged in a 3×3 grid, each with a color value derived from the puzzle's properties (difficulty, category, puzzle-ID). The interpolation is done via SVG `feMerge + feColorMatrix` to produce smooth, non-CSS gradients that look like elevation maps shot from space on a false-color infrared sensor. Each puzzle has a unique "terrain" that cannot be replicated with CSS `radial-gradient`. Colors used: `--void`, `--deep`, `--mid`, `--ridge`, with trace amounts of `--glacier` at high-elevation zones. **2. Mountain-Landscape Silhouette System:** A procedurally-generated mountain ridgeline runs across the bottom of the hero view — always behind puzzle tiles, always at 8–12% opacity in `--chalk`. The ridgeline is an SVG `polyline` generated from a seeded noise function (sine wave + harmonic overtones at 1/3 amplitude, 1/5 amplitude, 1/7 amplitude) — mathematically the same harmonic series used in Fourier synthesis, rendering a ridgeline that looks natural but is strictly deterministic per puzzle ID. Peak positions correspond to the hardest puzzle clusters. Each mountain silhouette is unique per puzzle but consistently uses 5–9 peaks across the full viewport width. The leftmost peak is always 15–20% viewport height, giving the skyline an asymmetric tension. **3. Elastic Puzzle Tiles (micro-motif):** Each tile is a square with a `1px` border at `--peak` (8% opacity when unsolved, 100% when solved). The corners are clipped at `2px` — not rounded, clipped with `clip-path: polygon()`, giving a subtly faceted, crystal-face feel. This micro-motif echoes the mountain silhouette: the puzzle field IS the mountain, the individual tiles are its rock faces. Hover on a tile produces a `1px` expansion of the `--glacier` border ring (spring animation, `cubic-bezier(0.34, 1.56, 0.64, 1)`, 140ms). A fully solved puzzle triggers the border to pulse `--peak` → `--glacier` → `--peak` at 1.6s intervals, like a summit beacon. **No photography** (corpus uses it at 87% — we abstain entirely). No icon fonts. No decorative type beyond the mono faces already defined. The only decorative elements are mathematical: the ridgeline, the mesh, the clipped tile corners. ## Prompts for Implementation **The story.** A solver arrives at ppuzzle.org the way a climber arrives at basecamp before dawn: the world is dark, the terrain is above them, and the objective is clear. The puzzle is already rendered — it doesn't load, it doesn't animate in, it's simply there, immovable, waiting. The solver begins to move tiles. Each correct placement brightens a hairline on the mountain silhouette, adds one more solved-tile border glow to the mesh. When the final tile snaps into place, the ridgeline brightens to 100% opacity and the gradient-mesh transitions to a full-summit palette (glacier-blue dominant) over 800ms. No confetti. No modal. Just the mountain, completed. **Implementation specifics:** 1. **Root layout:** `body { background: #050508; overflow: hidden; position: relative; }` — the page never scrolls. All content lives within `100svh × 100svw`. The puzzle field is `position: absolute; inset: 32px 24px;` (leaving edge strips). 2. **Edge strip implementation:** Four `position: fixed` bars, `z-index: 100`, `background: transparent`. Typography renders directly on the puzzle's mesh gradient, leveraging contrast. On puzzle-field hover, edge strips fade to `opacity: 0` over `200ms ease-out`, restore on mouse-leave. 3. **Elastic panel physics:** Panels use `transform: translateX()` with `transition: transform 280ms cubic-bezier(0.34, 1.56, 0.64, 1)`. The overshoot is built into the easing function — no JS spring library required. Panel toggle binds to `[` and `]` keys, plus swipe gestures (Touch Events API, minimum 40px horizontal swipe). 4. **SVG gradient-mesh:** Render as an `` element behind puzzle tiles. Use `` with multiple `` + `` nodes to build a multi-point mesh gradient. Each puzzle ID seeds a simple LCG RNG that determines the 9 control-point colors within the defined palette range. Animate with `` tag on the `feColorMatrix values` attribute — no JS animation loop needed. 5. **Mountain ridgeline:** SVG `` generated at puzzle-load. X points evenly distributed across viewport width, Y points from seeded harmonic series. Rendered at the bottom 15% of the puzzle field, `z-index: 1` (below tiles, above mesh). On puzzle completion: `stroke-opacity` transitions from 0.1 to 1.0 over 1200ms, `stroke` transitions from `#f0f0f0` to `#12ff7a` over 1200ms. 6. **Tile grid:** CSS Grid with `column-gap` and `row-gap` set to `2px`, but column widths use a JS-computed offset array (seeded per puzzle ID) that shifts each row left/right by `-8px` to `+8px`, breaking the strict grid alignment. This is the "topo-distortion" effect. The offset array is deterministic per puzzle so two solvers always see the same terrain. 7. **AVOID:** Any modal/dialog for puzzle completion. Any CTA buttons. Any pricing section. Any stats counter. Any testimonial. The page narrates through the puzzle itself, not through marketing copy. 8. **AVOID animation patterns that are overused in the corpus:** No parallax, no stagger reveals, no scroll-triggered animations (the page doesn't scroll). The only permitted animation is elastic spring (panel open/close), pulse (unsolved tiles), and gradient-mesh slow-drift. ## Uniqueness Notes **Differentiators from every other design in the registry:** 1. **The hero IS the product.** In 98% of registered designs, the hero is marketing space — a headline, a background image, a CTA. Here, the hero is a live, interactive puzzle. There is no marketing layer. The user engages with the actual product from frame-zero. No registered design uses the hero zone as an active interactive canvas. 2. **Edge-annotation navigation at 0% opacity-on-hover.** Navigation that deliberately hides itself when the user is engaged is structurally opposite to all registered navigation patterns. The convention is to make navigation permanent. ppuzzle.org makes navigation ghost-level peripheral — it knows its own place relative to the puzzle. 3. **Seeded SVG gradient-mesh as unique puzzle "terrain" per puzzle ID.** The corpus uses `gradient-mesh` at 8%, always as a static decorative background. This design makes the gradient-mesh functionally tied to puzzle data — each puzzle has a unique landscape derived from its mathematical properties. The visual and the interactive are causally linked, not decorative. 4. **Broken-grid tile layout with seeded topo-distortion.** Standard puzzle implementations use perfectly regular grids. ppuzzle.org's tile grid is offset-per-row using a seeded deterministic function, making each puzzle's visual field feel like a geological survey of its own difficulty terrain. The grid *is* the motif. 5. **Mountain ridgeline as completion meter.** The procedurally generated SVG ridgeline brightens and shifts color as the puzzle is solved — functioning as a non-linear, non-numeric progress indicator. This replaces conventional progress bars, percentage counters, and completion modals entirely. No registered design uses a landscape silhouette as a real-time game-state display. **Seed documented:** `aesthetic: avant-garde, layout: hero-dominant, typography: mono, palette: dark-neon, patterns: elastic, imagery: gradient-mesh, motifs: mountain-landscape, tone: bold-confident`