# Design Language for ppuzzl.org ## Aesthetics and Tone ppuzzl.org is a **celestial puzzle field** — a neomorphic star map where every puzzle piece is a night-sky fragment waiting to be placed. The domain name is a compressed, raw spelling of "puzzle," dropping the vowel-e the way a field note drops formality: *ppuzzl* as scrawl, as urgency, as something a navigator scratches on wet paper in the dark. The site is not a game store, not a product catalog — it is a **living sky puzzle in progress**, and the visitor is both player and cartographer. The aesthetic is **neomorphism weathered by wilderness**: soft extruded panels that look carved from basalt or compressed clay, lit from a single northwest source at 3200 K so they cast warm, directional inner shadows. This is not the clean, sterile soft-UI neomorphism of SaaS apps — it is neomorphism after exposure, neomorphism that has sat in mountain air. The panels carry fingerprint-grain noise at 4% opacity, a reminder that something real was touched here. The aurora-gradient palette — greens folding into deep violets, cold cyan slipping under magenta curtains — is not decorative background wash. It is **the puzzle's atmosphere**: when pieces connect, a ripple of aurora color bleeds outward from the join point, as if the sky itself is responding to correct placement. Stars are the puzzle motif: every piece boundary is traced by a thin `#C8E6C9` hairline constellation edge, 0.5 px, suggesting that the pieces were cut along old star-pattern routes. The tone is raw-authentic: no polish veneer, no startup superlatives. Copy reads like a field log. Layout breathes with real space. Silence is used deliberately. --- ## Layout Motifs and Structure The page is built on a **masonry constellation grid**: a CSS masonry layout (using `columns: 3` at desktop, `columns: 2` at tablet, `columns: 1` at mobile) where each card-column is a puzzle fragment of irregular height. The masonry is not purely random — it obeys a hidden **star-map constraint**: the tallest card in each column aligns vertically with a named constellation point, and thin SVG lines (stroke `#4DD0E1`, opacity 0.12) connect the card top-corners across columns, suggesting Orion's belt, the Southern Cross, Cassiopeia — depending on the page scroll position. **Structural layers (top to bottom):** 1. **Sky Aperture (`100svh` hero).** The viewport opens like a telescope shutter — two neomorphic panels slide apart vertically (0.9 s, `cubic-bezier(0.23, 1, 0.32, 1)`) to reveal the masonry grid beneath. The hero holds only the wordmark `ppuzzl` in monospace, rendered at `18 vw`, and a single aurora smear — a radial `conic-gradient` in shades of `#00BCD4`, `#7C4DFF`, `#00E676` — that pulses at 4 s breath cycle. 2. **Masonry Puzzle Field (main content).** Cards are puzzle pieces. Each card is a neomorphic extruded box (`border-radius: 16px`, background `#1a1f2e`, box-shadow: `inset 6px 6px 12px #0d1016, inset -6px -6px 12px #27304a`). Cards carry: a star-fragment image composed from CSS clip-path polygons (nature shapes — mountain silhouette, tree ridgeline, water reflection — all in monochrome with aurora highlights), a terse field-log label in monospace, and a completion state indicator that ripples aurora color when toggled. 3. **Constellation Connector Layer.** An SVG overlay (position: fixed, pointer-events: none, z-index: 10) draws SVG `` elements between the centroid of each visible card. Lines animate in on scroll via IntersectionObserver, stroke-dashoffset from full to zero over 0.8 s. When a puzzle piece is "solved" (card toggled), its connecting lines shift from `#4DD0E1 0.12` to `#00E676 0.4` with a ripple emission at the card center. 4. **Field Log Footer.** A neomorphic trough at the bottom — inset, not extruded — holding only: a session coordinate pair (latitude/longitude of the current session's approximate star position in the sky), the puzzle completion percentage, and a monospaced timestamp. No social links. No copyright flourish. Just coordinates. **Spatial rhythms:** - Column gap: `clamp(12px, 2vw, 28px)` — tight enough to suggest pieces fitting together - Card padding: `clamp(20px, 3vw, 40px)` — generous internal breathing - The masonry grid has zero horizontal centering margin — it runs edge-to-edge, creating a sense of the puzzle extending beyond the viewport --- ## Typography and Palette **Typography — mono, all from Google Fonts.** Monospace is not used here as a developer aesthetic. It is used as **star-catalog notation**: the precise, fixed-width spacing that astronomical tables require. One face. Two optical roles. - **Display / Wordmark:** [Space Mono](https://fonts.google.com/specimen/Space+Mono), Bold 700, set at `clamp(48px, 18vw, 200px)` for the hero wordmark `ppuzzl`. Letter-spacing: `-0.03em` (tight, like a compressed field notation). The wordmark is rendered as an SVG text path that subtly traces a constellation arc — the letterforms sit on a slight curve, as if placed along Sagittarius's teapot. - **Body / Labels / Field Log:** [Space Mono](https://fonts.google.com/specimen/Space+Mono), Regular 400, at `clamp(11px, 1.1vw, 14px)`. Line-height: 1.75. Used for card labels, coordinates, timestamps, and all status text. All uppercase for category labels, sentence-case for descriptions. - **Accent / State Labels:** [JetBrains Mono](https://fonts.google.com/specimen/JetBrains+Mono), Regular 400, at `12px` for small status badges (SOLVED, OPEN, CONNECTING) in aurora green `#00E676` on dark panels. **Color palette — aurora-gradient:** - `#0D1021` — Deep Space Black (page background, extruded card base) - `#1A1F2E` — Compressed Basalt (card surface, neomorphic panel face) - `#4DD0E1` — Cyan Aurora (primary accent, constellation lines, active states) - `#7C4DFF` — Violet Crown (secondary aurora band, puzzle piece join ripple highlight) - `#00E676` — Boreal Green (solved state, completion indicators, positive feedback glow) - `#FF4081` — Solar Magenta (error ripple, incorrect placement feedback, rare accent) - `#E8F5E9` — Polar Frost (primary text on dark, field-log entries) - `#263238` — Slate Depth (shadow side of neomorphic extrusion, inset trough base) Aurora gradients are rendered as `conic-gradient(from 200deg at 60% 40%, #00BCD4 0%, #7C4DFF 30%, #00E676 60%, #FF4081 80%, #00BCD4 100%)` animated with a 12 s rotation cycle at opacity 0.15 over the background, creating an atmospheric sky drift. --- ## Imagery and Motifs **Nature-elements through monochrome silhouette:** There are no photographs. All nature imagery is built from CSS `clip-path` polygons and SVG paths — mountain ridgelines, tree canopies, horizon water lines — rendered as single-color shapes against the aurora background. The silhouettes are hand-traced and deliberately imperfect (intentional vertex jitter of ±2 px). Each puzzle card holds one silhouette fragment clipped to the card's irregular boundary polygon, so the silhouettes only make sense when all cards are mentally assembled — the puzzle IS the landscape. **Star-celestial motifs:** - **Constellation skeleton:** Each card's clip-path boundary is a polygon derived from an actual constellation — Lyra, Cygnus, Aquila, Hercules — mapped to card-shaped rectangles. The vertex positions are computed from real right-ascension/declination data, scaled to card dimensions. The resulting polygon is slightly irregular but recognizably star-derived. - **Star punctuation:** Individual star points are rendered as tiny CSS `radial-gradient` circles, 2–5 px diameter, placed at the constellation vertex positions within each card. They twinkle via a CSS animation: `opacity 2s ease-in-out infinite alternate` between 0.4 and 1.0, each star offset by a randomized `animation-delay` of 0–4 s. - **Aurora ribbons:** Two absolute-positioned SVG paths per card, rendered as `` elements with a `stroke-dasharray` animation that loops at 8 s, simulating a slow aurora ribbon drifting through the card. Stroke: `conic-gradient`-like simulation using four stacked paths in `#4DD0E1`, `#7C4DFF`, `#00E676`, `#FF4081` at opacity 0.08–0.16. **Ripple pattern on interaction:** Every interactive state change — card hover, card toggle (solve/unsolve), constellation line completion — emits a CSS ripple: `box-shadow` expansion from `0 0 0 0 #4DD0E1` to `0 0 0 40px transparent` over 0.6 s. Correct placements use `#00E676` ripple; incorrect uses `#FF4081`; general hover uses `#4DD0E1`. The ripple is emitted from the cursor's position within the card, not the card center — making each interaction feel physically located. --- ## Prompts for Implementation Build ppuzzl.org as a **single-page star-puzzle field** — a slowly-discovered masonry of neomorphic puzzle fragments that the visitor navigates by scrolling and toggling, assembling a picture of a night-sky landscape without ever being told what it is. There is no tutorial, no onboarding modal, no instructions section. The design itself is the instruction. **Macro structure (top to bottom):** 1. **Telescope Shutter Hero (`100svh`).** Two neomorphic basalt-dark panels cover the screen. On load, after a 300 ms pause, they split apart (top panel translates up, bottom panel translates down) via `transform: translateY(-50vh)` / `translateY(50vh)` over 900 ms, `cubic-bezier(0.23, 1, 0.32, 1)`. Behind them, the masonry grid is already rendered but invisible. The hero wordmark `ppuzzl` in Space Mono 700 at 18 vw sits centered, aurora-gradient text-fill via `-webkit-background-clip: text`, before the shutter opens. After opening, it shrinks (CSS transition) to a 20 px fixed top-left label — the site's only persistent navigation. 2. **Masonry Puzzle Field.** CSS `columns: 3; column-gap: clamp(12px, 2vw, 28px)` layout holding 18–24 puzzle-piece cards. Each card uses `break-inside: avoid`. Card heights vary: small cards are 200–280 px, medium 320–420 px, large 500–600 px. The size variation is the masonry's irregularity — it suggests a jigsaw, not a grid. Cards enter viewport via `IntersectionObserver`: `opacity 0 → 1`, `transform: scale(0.96) → scale(1)` over 500 ms with `animation-delay` based on card index (0 ms, 60 ms, 120 ms...) for a staggered cascade. 3. **Constellation SVG Overlay.** A `position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; pointer-events: none; z-index: 10` SVG element. JavaScript tracks each visible card's centroid (via `getBoundingClientRect`) and draws `` elements between adjacent card centroids in a nearest-neighbor graph limited to 3 connections per card. Lines animate via `stroke-dashoffset` on enter. On scroll, centroid positions update and lines re-route. 4. **Field Log Footer.** `min-height: 120px` inset neomorphic trough. Three monospaced data points: `RA: 18h 29m 14s` / `DEC: +38° 47'` (randomly seeded per session), `SOLVED: 0 / 24`, `UTC: `. No other content. **Animation and interaction specifics:** - Ripple: use a pseudo-element `::after` absolutely positioned at cursor offset via CSS custom property `--x`, `--y` set by JS `mousemove`. `border-radius: 50%`, `transform: scale(0)` → `scale(4)`, `opacity: 0.3 → 0`, `transition: all 0.6s`. Never use a library — pure CSS/JS only. - Aurora background drift: single `` element behind all content, drawing a looping `conic-gradient` via `ctx.createConicGradient`, rotating 1 degree per frame at 0.1 opacity. - Neomorphic extrusion: always two-shadow system. Light source: upper-left. Light shadow: `rgba(39, 48, 74, 0.9)`. Dark shadow: `rgba(13, 16, 22, 0.9)`. On hover, shadows reverse slightly (inset begins to dominate) as if pressing the piece. - No external JS libraries except one: `gsap` is permitted for the shutter-open sequence only. All other animation: CSS transitions and keyframes. **Avoid:** - Pricing blocks, CTA buttons, hero headlines with taglines - Sticky headers with navigation links - Testimonials, stat grids, social proof - Bright white backgrounds anywhere - Any font other than Space Mono and JetBrains Mono - Flat, unshadowed cards (every surface must have neomorphic depth) - Aurora that is decorative only — it must respond to puzzle state --- ## Uniqueness Notes 1. **Neomorphism at 2% frequency, applied to a puzzle mechanic instead of a UI component.** Every other neomorphic design in the registry treats soft-UI as a cosmetic for buttons and cards. ppuzzl.org makes the neomorphic extrusion *the puzzle mechanic itself* — the push-and-click of a physical puzzle piece is simulated by the inset/extrude shadow reversal. The frequency report shows neomorphism at 2%; no other design uses it for game interaction. 2. **Masonry as a constellation map, not a content grid.** Masonry at 8% in the registry is used everywhere as a Pinterest-style photo layout. Here, the masonry column-gap and card heights are mathematically derived from constellation vertex data, and SVG lines connect card centroids to sketch real astronomical patterns. The layout IS the star map. This combination — masonry + star-celestial + SVG overlay as one system — appears nowhere else in the registry. 3. **Mono typography used as star-catalog notation, not developer aesthetic.** Mono sits at 75% in the registry — the single most overused typography category. Every other mono design uses it for terminal/code visual language. ppuzzl.org uses Space Mono as an astronomical field-log typeface, paired with JetBrains Mono for status labels. The cultural reference is the Messier catalog and navigator's star tables, not a terminal window. This is a mono design that reads nothing like any other mono design in the registry. 4. **Aurora-gradient as interactive state language.** Aurora at 3% in the registry. Other aurora designs use it as a decorative background wash. Here, the three aurora colors (`#4DD0E1`, `#7C4DFF`, `#00E676`) are each semantically assigned to interaction states (hover, solving, solved), and the aurora canvas drifts faster when puzzle completion percentage rises — the sky responds to the player's progress. The gradient is functional, not ornamental. 5. **Planned seed documented:** `aesthetic: neomorphism, layout: masonry, typography: mono, palette: aurora-gradient, patterns: ripple, imagery: nature-elements, motifs: star-celestial, tone: raw-authentic`