# Design Language for ppuzzle.dev

## Aesthetics and Tone

ppuzzle.dev is a puzzle game platform imagined as if a brutalist concrete archive had been left open in the rain during golden hour — the raw structural bones of a 1970s Eastern European cultural ministry building, slowly being colonised by warm amber light pooling in its crevices. The aesthetic refuses the cheerful pop-art playfulness that defines most puzzle games: no cartoon mascots, no rainbow leaderboards, no gamified badges. Instead, the site treats puzzles as a serious sculptural problem — the act of solving as meditative, almost geological. Every screen has the weight of a heavy stone door sliding open to reveal a chamber lit by a single narrow window at sunset.

The mood is **dreamy-brutalist** — a paradox held taut. The structural grammar is pure brutalism: raw, unornamented, load-bearing, exposed. But the light that pours through the exposed structure is molten rose-amber, the kind of sunset that turns concrete gold and makes shadows feel warm rather than cold. The brutalism provides bones; the sunset-warm palette provides blood.

The inspiration touchstones are: the unrealised Soviet Metabolist architecture of Yona Friedman rendered in Wim Wenders' amber-toned cinematography, combined with the tactile pull of a freshly broken piece of white Carrara marble. The site should make a user feel they have entered a ruin that is still alive — cool stone, warm light, quiet movement.

**Tone: dreamy-ethereal but never decorative. Structural but never sterile. Warm but never cozy.**


## Layout Motifs and Structure

The layout is a single **immersive-scroll** canvas — one unbroken vertical descent through the architecture. There are no page transitions, no modal overlays, no sidebar navigation. The user falls through the building. Each section is a **full-viewport chamber** — a room in the archive — and the transition between chambers uses the **layered-depth** motif: the current chamber's marble-textured floor appears to sink as the next chamber's ceiling descends from above, creating a parallax crush that evokes passing between floors of an elevator without walls.

**Chamber sequence (seven full-screen rooms):**

1. **The Vault Door** — Entry. Full-black with a single centered puzzle-fragment silhouette in warm amber (#E8824A) that assembles itself on load via bounce-enter. Headline at 18vw, weight 800, flush-left against a 12-column brutalist grid. The word "ppuzzle" is treated as a typographic puzzle — each letter arrives independently.
2. **The Specimen Hall** — Featured puzzle grid. Raw concrete-texture background (#2B2520) with eight puzzle cards arranged on an asymmetric brutalist grid: six columns, cards spanning 1, 2, or 3 columns. Card faces are marble-texture surfaces with inset puzzle imagery. No hover effects — cards respond only to scroll position, tilting 2° as they enter the viewport.
3. **The Cartography Room** — Puzzle categories displayed as architectural floor-plan fragments. SVG-drawn room outlines in #E8824A on #1A1510 background. Category labels in slab-serif at 11px letterspaced uppercase. Each floor-plan fragment is a navigable zone.
4. **The Workshop** — How-to section. Split-screen: left half is a live marble-texture puzzle solving demo (CSS grid animation), right half is instructional text in tight brutalist columns. The split ratio is 55/45, not 50/50.
5. **The Observatory** — Leaderboard and stats. High-ceilinged feeling — extra vertical padding (20vh top and bottom). Monospaced numbers in #F2C59A against dark concrete (#1A1510). Rankings displayed as architectural elevations, not a table.
6. **The Archive** — Recent completions / activity feed. Horizontal rows of completion cards, each a marble slab with embedded text. Warm amber light bleeds from the right edge of each row.
7. **The Threshold** — Footer / call to action. The structure opens back to sky — warm gradient ceiling above a single CTA. Minimal. The CTA is a single line of type: "Enter the archive." No button — the entire text is the link.

**Grid system:** 12-column brutalist grid, 24px gutters, maximum content width 1440px. Margins are asymmetric on desktop: 120px left, 80px right — deliberately off-centre like a brutalist facade with an entrance not at the midpoint. Mobile collapses to a single full-bleed column, gutters 16px.


## Typography and Palette

**Typography (Google Fonts only):**

- **Display — [Barlow Condensed](https://fonts.google.com/specimen/Barlow+Condensed)**, weight 800, italic. Used for all section titles, puzzle titles, and the primary headline. Set very large: 12–22vw for hero, 5–8vw for section heads. The condensed italic creates a leaning-forward urgency that suits the brutalist aesthetic — it feels like structural steel, not calligraphy. Letter-spacing: -0.03em at display sizes.
- **Body — [DM Sans](https://fonts.google.com/specimen/DM+Sans)**, weights 300 and 400. Clean, humanist, slightly warm. The contrast between the brutalist display font and the humanist body creates the core typographic tension of the design — architecture versus human. Body measure: 600px max, 1.7 line-height, 16–18px size.
- **Data / Numbers — [DM Mono](https://fonts.google.com/specimen/DM+Mono)**, weight 400. Used exclusively for timers, scores, puzzle piece counts, leaderboard ranks. The monospace font signals precision, measurement, the mechanical — appropriate for puzzle data.
- **Labels / Category Tags — [Barlow](https://fonts.google.com/specimen/Barlow)**, weight 400, all-caps, letterspaced 0.2em at 10–11px. Used for UI labels, breadcrumbs, metadata.

**Palette — sunset-warm against brutalist concrete:**

- `--concrete-void` `#0F0C0A` — near-black with a trace of warm brown. Primary background for deep chambers. Not a cold black — it reads as shadow cast by warm light.
- `--concrete-raw` `#2B2520` — mid-dark concrete. Card backgrounds, section alternating background. The texture of a brutalist slab in shade.
- `--stone-warm` `#4A3F35` — warm medium grey-brown. Border colour, subtle dividers, the colour of stone in diffuse light.
- `--amber-glaze` `#E8824A` — the primary accent. Sunset amber-orange. Used for interactive states, key icons, the puzzle fragment in the hero. Not bright orange — it is the specific colour of late afternoon light hitting a west-facing concrete wall.
- `--amber-pale` `#F2C59A` — soft amber cream. Used for body text on dark backgrounds, leaderboard numbers, secondary accents. The colour of sunlit marble dust.
- `--marble-white` `#F5F0EA` — warm off-white. Used for card faces with marble texture, light foreground elements, the CTA text. Warmer than pure white — it reads as stone, not paper.
- `--rose-dusk` `#C4634F` — deep rose-red. Used sparingly for error states, difficulty indicators (hardest tier), and the left border-accent on active puzzle cards. The colour of the horizon at the exact moment before the sun disappears.

**Texture layer:** A subtle CSS noise filter (`filter: url(#grain)` via inline SVG) applied at 3% opacity over the entire background creates the paper/stone tactility without obscuring content.


## Imagery and Motifs

**Marble texture is the primary imagery system.** Puzzle cards are rendered as slabs of white Carrara marble — the crack-vein pattern is drawn in SVG using Perlin noise-seeded cubic Bézier curves, so every card has a unique marble pattern generated at runtime. No two cards look the same. The marble palette is warm-toned: veins in `--rose-dusk` (#C4634F) and `--stone-warm` (#4A3F35) on `--marble-white` (#F5F0EA) grounds.

**The puzzle-fragment silhouette** is the master motif: an SVG outline of an irregular jigsaw piece, used as:
- The hero centrepiece (large, amber-filled, assembles on bounce-enter)
- A background watermark on chamber walls (scaled to 120vh, opacity 0.04, rotated 15°, positioned asymmetrically)
- The favicon and loading indicator
- The cursor replacement on puzzle-interactive surfaces (an SVG cursor shaped like a puzzle tab)

**Architectural structural lines** appear as decorative elements throughout: horizontal concrete-beam rules (3px, `--stone-warm`, full-width minus 120px left margin) between sections, vertical column lines (1px, `--stone-warm`, 6% opacity) running the full page height aligned to the 12-column grid.

**Amber light bleeds** are CSS radial gradients positioned as if a light source exists just off-screen right: `radial-gradient(ellipse 800px 400px at 110% 50%, rgba(232,130,74,0.12), transparent)`. Each chamber has its own light-bleed origin, creating depth continuity as the user scrolls — the light source appears to be stationary while the architecture moves past it.

**No photography.** No illustrations. No icons except a minimal set of SVG puzzle pieces for category indicators (6 shapes, each a different irregular polygon, each filled with its category's marble texture via SVG pattern fill).


## Prompts for Implementation

Treat ppuzzle.dev as a **single architectural descent** — seven chambers of a brutalist archive, each rendered as a full-viewport scene in warm concrete and amber. The user is not browsing a website; they are walking through a building that happens to contain puzzles. The scroll behaviour is the narrative.

**Bounce-enter animation system (primary animation vocabulary):**
Every significant element enters the viewport with a **bounce-enter** — not a cheerful bouncy-ball bounce, but a heavy, deliberate settle, as if a stone block has been lowered into place and found its seating with a single gentle rebound. CSS timing: `cubic-bezier(0.34, 1.56, 0.64, 1)` for the bounce overshoot, duration 0.6s, delay staggered 80ms between siblings. Elements should feel substantial when they land, not airy. The bounce amplitude is small (8px vertical) — it is the weight of stone finding rest, not a toy springing.

**Layered-depth scroll transitions (chamber transitions):**
Between chambers, implement a CSS scroll-driven animation using `animation-timeline: scroll()`. As the user scrolls from Chamber N to Chamber N+1: Chamber N's marble floor texture scales from `scale(1)` to `scale(1.08)` while its opacity drops from 1 to 0; simultaneously Chamber N+1's concrete ceiling descends from `translateY(-40px)` to `translateY(0)`. The layered-depth effect is achieved by `z-index` stacking with `perspective: 1200px` on the scroll container. No JavaScript scroll listeners — pure CSS scroll-driven animations.

**Marble texture generation (CSS + SVG):**
Each puzzle card's marble surface is an SVG `<pattern>` with three overlapping `<path>` elements using `stroke-dasharray` and `stroke-dashoffset` animated via CSS. The paths are generated server-side (or statically pre-generated for 20 variants) using a seeded random walk algorithm. Pattern tile size: 400×400px. Each path: 2px stroke, semi-transparent (`--rose-dusk` at 40% opacity for primary veins, `--stone-warm` at 25% for secondary veins).

**Typography scale — Barlow Condensed Italic:**
- Hero title: `clamp(12vw, 18vw, 22vw)`, weight 800, italic, `--marble-white`, letter-spacing -0.03em
- Chamber headings: `clamp(5vw, 8vw, 11vw)`, weight 800, italic, `--amber-glaze`
- Card titles: `clamp(1.2rem, 2vw, 2.4rem)`, weight 800, not italic (structural, not expressive)
- Body: `clamp(0.9rem, 1.1vw, 1.125rem)`, DM Sans 300/400, `--amber-pale`, line-height 1.7

**Puzzle-assembly hero sequence:**
On page load, the hero puzzle-fragment silhouette assembles from five separate SVG `<path>` fragments. Each fragment starts at `opacity: 0`, `transform: translate(random(-30px,30px), random(-20px,20px)) rotate(random(-8deg,8deg))`. They animate in sequence (80ms stagger) using bounce-enter timing. The assembled piece glows briefly (`filter: drop-shadow(0 0 24px rgba(232,130,74,0.6))`) for 400ms before the glow fades. Total sequence: 1.2s from first load.

**Leaderboard / Observatory typography:**
Ranks and scores display in DM Mono at `6vw` for rank number, `2.4rem` for username, `1rem` for score. The rank number is rendered in `--amber-glaze` at 8% opacity as a background behind each row — enormous, behind the text, as if it were carved into the chamber wall. Rows have 1px bottom borders in `--stone-warm` at 30% opacity.

**AVOID:**
- Rounded corners on cards (brutalist: 0px border-radius on all containers)
- Drop shadows as elevation signals (use border and colour to create depth, not shadows)
- Animated gradient backgrounds (the amber glow is static/CSS-only)
- Scroll-snap that feels instant (all scroll-driven transitions should have 0.4s minimum perceived duration)
- Any use of pure `#000000` or `#FFFFFF` (the palette uses warm near-black and warm off-white only)
- Hover tooltips, floating labels, modal overlays
- CTA buttons — the only interactive affordance is the single threshold-line text link


## Uniqueness Notes

**Three or more differentiators relative to the existing corpus:**

1. **Brutalist puzzle platform — an unoccupied design territory.** The corpus contains 7% brutalist designs but none applied to a puzzle/game context. Every puzzle platform in the design vocabulary defaults to playful-rounded, candy-bright, or gamified-badge aesthetics. ppuzzle.dev is the first brutalist puzzle site: it treats puzzle-solving as a serious, meditative, architectural act, not a dopamine loop. The concrete-and-amber palette combination (brutalist structure + sunset-warm light) is a zero-occurrence pairing in the frequency data.

2. **Marble texture as interactive surface, not decorative background.** The corpus uses `marble-texture` (3%) as atmospheric background dressing. ppuzzle.dev makes marble the primary UI surface: puzzle cards are marble slabs with SVG-generated Perlin-noise vein patterns, unique per card. The marble is functional — it signals "this is a puzzle face, touch it" — rather than merely atmospheric. Combined with the CSS scroll-driven marble-floor-sinking transition between chambers, the marble becomes a structural, navigational, and narrative element simultaneously.

3. **Bounce-enter as heavy stone landing, not playful bounce.** Bounce-enter appears at only 2% corpus frequency, and every existing use treats it as a cheerful, springy, lightweight animation. ppuzzle.dev reinterprets bounce-enter through the brutalist lens: `cubic-bezier(0.34, 1.56, 0.64, 1)` with small amplitude (8px), heavy perceived weight, 0.6s duration. The animation vocabulary is consistent with the architectural metaphor — stones being lowered into place, not toys being thrown. This is a new semantic register for a documented pattern.

4. **Zero photography, zero illustration, zero icon libraries.** The corpus overwhelmingly uses photography (duotone, vintage, or editorial) or illustration as the primary imagery mode. ppuzzle.dev uses only: SVG-generated marble textures, CSS amber light-bleeds, architectural structural lines, and the master puzzle-fragment silhouette motif. The entire visual language is built from code — no asset pipeline for imagery. This aligns with the puzzle domain (puzzles are structural problems) and keeps the brutalist aesthetic free of the softness that photography introduces.

**Chosen seed:** aesthetic: brutalist, layout: immersive-scroll, typography: humanist, palette: sunset-warm, patterns: bounce-enter, imagery: marble-texture, motifs: layered-depth, tone: dreamy-ethereal

**Patterns avoided per frequency analysis:**
- parallax (76% corpus frequency) — replaced by CSS scroll-driven chamber transitions
- stagger (51%) — replaced by bounce-enter with 80ms delay offset (different semantic)
- scroll-triggered (34%) — avoided; using scroll-driven CSS animations (declarative, not JS-triggered)
- warm palette generic (88%) — avoided; sunset-warm used as specific amber-concrete pairing, not as a generic warmth signal
- gradient backgrounds animated (common) — replaced by static CSS amber light-bleeds
- humanist typography as default (31%) — humanist (DM Sans) used in deliberate tension against brutalist display (Barlow Condensed), not as the dominant voice
<!-- DESIGN STAMP
  timestamp: 2026-05-10T13:00:36
  domain: ppuzzle.dev
  seed: seed:
  aesthetic: ppuzzle.dev is a puzzle game platform imagined as if a brutalist concrete archiv...
  content_hash: 0a6621b2231d
-->