# PDR — Product Design Requirements

**Product:** Tessra  
**Studio:** Bots & Bones · © 2026  
**Version:** v3.4 Lacuna (game) + landing5 (public site)  
**Last updated:** 2026-07-02

---

## 1. Executive summary

**Tessra** is a calm Penrose-tiling puzzle — no timer, no fail state, focused on tactile pattern discovery. The public landing sells the game as an experience of attention inside an aperiodic mosaic, not as a math lesson.

The landing and the game share one visual language: dark atmospheric UI, Fraunces headlines, JetBrains Mono labels, live Penrose mosaic as the primary asset, and four interchangeable colour moods.

**Design canonical theme for landing and style board:** Quartz (Quiet Bloom).  
**Game production default:** Soft Atlas (Warm Ledger) — documented but secondary for marketing surfaces.

---

## 2. Positioning and voice

### One-line positioning

> *Elegant discovery in an aperiodic mosaic.*

### Approved copy (EN, from product UI)

| Context | Copy |
|---------|------|
| Home / hero | *Elegant discovery in an aperiodic mosaic.* |
| About | *A game of attention inside an aperiodic mosaic.* |
| Daily | *One shared tiling every UTC day. Tap outward — watch the hidden order emerge.* |
| Levels (v3.4) | *Restore the missing tiles. Twenty gentle lessons, then the long mosaic.* |
| Landing hero title | *Reveal the hidden pattern.* |
| Landing hero sub | *Build impossible mosaics inspired by Penrose tilings. Reveal hidden figures, discover infinite patterns and explore a geometric world that never truly repeats.* |

### Voice rules

- Short imperative or a feeling — one per screen.
- Poetic without pomposity; precise without theory.
- English is primary for public surfaces.

### Anti-positioning (never say)

- "Math app", "learn tessellations", "educational geometry"
- Timers, lives, competition, leaderboards
- "Penrose" in the product name (Penrose = mathematical concept, 1974)
- Gradient blob backgrounds, decorative illustrations unrelated to the mosaic
- Mindfulness startup clichés (breathing circles, pastel fog)

---

## 3. Audience

People who enjoy zen puzzles, satisfying interaction, and calm games — Monument Valley, Kami, Patterned. They play to disconnect, touch a living pattern, and enter flow — not to study geometry.

---

## 4. Product scope — game v3.4 Lacuna

| Feature | Requirement |
|---------|-------------|
| Core mechanic | Tray + holes: restore missing thick (72°) and thin (36°) rhombs in a mostly-complete mosaic |
| Tutorial | 20 free levels (Seed → Motif → Thread → Mosaic) |
| Paid chapters | 100 levels (Ember → Zenith) behind mock paywall after L20 |
| Daily | One shared UTC-day seed; tap frontier tiles outward from centre; 3-day archive |
| Colour moods | 4 production themes in SideMenu picker: soft-atlas, lagoon, quartz, folio |
| Onboarding | None in v3.4 — splash goes straight to Home; levels teach the game |
| Progress | `penrose-v34-progress` in localStorage: `{ unlocked, dailyByDate, premium } |
| Paywall | Mock IAP after L20; Unlock / Restore sets `premium: true` |

### Hole strategies (level generation)

`isolated`, `pairs`, `chain`, `cluster`, `figure`

---

## 5. Landing scope

Production landing at repo root (`index.html`). Sight experience: live mosaic backdrop, vertical scroll-snap, frameless content screens.

### Global layer (always on)

| Element | Requirement |
|---------|-------------|
| Boot loader | Animated Tessra logo (~2.6s), then content |
| Live mosaic | Ghost tiles in backdrop; drag-to-pan everywhere |
| Edge fog | `sight__fog` vignette on mosaic |
| Nav | Hidden over hero; glass bar after scroll (`is-scrolled`) |
| Scroll snap | Vertical mandatory between screens; disabled with `prefers-reduced-motion` |
| Mosaic dim | `sight__dim` activates when scrolled past hero |

### Screen inventory

| # | Section ID | Status | Purpose |
|---|------------|--------|---------|
| — | Boot | Done | Brand reveal before content |
| 1 | `#hero` | Done | Primary value prop + CTA + phone screenshot |
| 2 | `#rules` | Done | Teach two rhomb types |
| — | `#stats` | Done | Credibility band: 20 / 365 / ∞ |
| 3 | `#daily` | Done | Daily mosaic feature |
| 4 | `#figures` | Done | Twenty named Penrose figures |
| 5 | `#pattern` | Done (placeholder art) | Penrose facts carousel |
| 6 | `#generator` | Done | Interactive mosaic + theme swatches + PNG export |
| 7 | `#waitlist` | Planned | Email capture; CTAs already link here |
| — | `footer` | Done | Brand, nav, studio credit, legal |

---

## 6. Design principles

1. **Mosaic as hero asset** — never decoration; always implies continuation beyond the viewport.
2. **Frameless screens** — content floats over the live canvas; no card boxes on main sections.
3. **Fog and dim** — atmospheric depth; content readable without opaque panels.
4. **One bright interlude** — `#pattern` is the only opaque accent-wash section.
5. **Generator as playground** — full-bright mosaic (`is-generator` removes fog/dim).
6. **Tactile typography** — Fraunces for emotion, JetBrains Mono for precision labels.
7. **No infinite plane on landing** — generate larger than visible, draw visible only, edge fade.

---

## 7. Theme strategy

| Level | Theme ID | Poetic name | Use |
|-------|----------|-------------|-----|
| **Primary (canonical)** | `quartz` | Quiet Bloom | Landing default, `design.md` YAML tokens, style board default |
| **Secondary** | `soft-atlas` | Warm Ledger | Game production default; alt theme |
| **Secondary** | `lagoon` | Tide Pool | Alt theme |
| **Secondary** | `folio` | Rose Fold | Alt theme |
| **Reference only** | obsidian, lapis, parchment, moss, coral | Lab presets in `themes.js` | Not in production picker; appendix in `design.md` |

### Token parity requirement

Landing `styles/tokens.css` and game `themes.js` must stay aligned on the four production themes. Theme switch on landing must update HTML `data-landing-theme`, CSS variables, and mosaic tile colours without FOUC.

---

## 8. Screen requirements

### `#hero`

| Requirement | Detail |
|-------------|--------|
| Goal | Communicate product promise; drive waitlist CTA |
| Must have | Brand lockup (DynamicLogo + "Tessra"), H1, sub copy, primary CTA, phone screenshot, scroll hint |
| CTA | "Notify me on launch" → `#waitlist` |
| A11y | `aria-live` on rotating word; focusable CTA; reduced-motion skips word rotation |
| Pass | Hero readable over mosaic; phone visible on mobile without cropping critical UI |

### `#rules`

| Requirement | Detail |
|-------------|--------|
| Goal | Explain the two rhomb types without math lecture |
| Must have | Eyebrow, H2, lead, two interactive rhomb illustrations (thick 72°, thin 36°), chips |
| Interaction | Rhomb hover drift; colour fill on hover |
| A11y | SVG decorative; copy is the primary content |
| Pass | Both rhombs visually distinct; chips legible at 375px width |

### `#stats`

| Requirement | Detail |
|-------------|--------|
| Goal | Quick credibility: scope of game |
| Must have | Three numerals: 20 levels, 365 patterns/year, ∞ mosaics |
| Typography | JetBrains Mono numerals, Fraunces labels |
| Pass | Band snaps with adjacent screens; numerals readable at all breakpoints |

### `#daily`

| Requirement | Detail |
|-------------|--------|
| Goal | Sell Daily as shared ritual |
| Must have | Split layout: copy left, phone right; eyebrow, H2, lead, chips |
| Copy anchor | *One shared tiling every UTC day* |
| Mobile | Phone stacks above text (`order: -1`) |
| Pass | Screenshot shows real Daily UI; text does not overlap phone |

### `#figures`

| Requirement | Detail |
|-------------|--------|
| Goal | Show depth of content — twenty named figures |
| Must have | Infinite glyph marquee with real figure outlines |
| Pass | Marquee respects `prefers-reduced-motion` (static or slowed) |

### `#pattern`

| Requirement | Detail |
|-------------|--------|
| Goal | Light education without lecture; bridge to generator |
| Must have | 6-card horizontal carousel, prev/next controls, accent wash background |
| Exception | Only section with opaque background — navy text on accent wash |
| CTA | Link to Wikipedia; optional "Open generator" |
| Pass | Carousel keyboard-navigable; contrast ≥ 4.5:1 on accent wash |

### `#generator`

| Requirement | Detail |
|-------------|--------|
| Goal | Let visitor play with the mosaic; export wallpaper |
| Must have | Zoom, recenter, randomize, spin dial, 4 theme swatches, PNG download |
| State | `is-generator` on `#sight` removes fog and dim |
| Theme swatches | Must switch all four production themes live |
| Pass | PNG exports at 2× viewport; spin works via drag and tap |

### `#waitlist` (planned)

| Requirement | Detail |
|-------------|--------|
| Goal | Capture email for launch notification |
| Must have | Email input, submit, success/error states |
| Integration | `WAITLIST_ENDPOINT` env or form service |
| Pass | Form validates email; accessible labels and error messages |

### Footer

| Requirement | Detail |
|-------------|--------|
| Goal | Close with brand, navigation, studio credit |
| Must have | Opaque `--bg` background (50svh min); Bots & Bones logo; privacy/support links |
| Pass | No mosaic bleed-through; logo readable on dark bg |

---

## 9. Content inventory

### Screenshots (current paths)

| Screen | Asset |
|--------|-------|
| Hero phone | `assets/screenshots/sreen_home_02.png` |
| Daily (quartz) | `landing4/assets/screenshots/v32/quartz/daily.png` (legacy path) |

### DynamicLogo behaviour

Boot logo, nav brand, and hero lockup run the game animation: tiles grow from centre (`easeOutBack`), hold, fade, repeat. Colours read from CSS tokens (`--tile-thick`, `--tile-thin`) and update on theme switch.

### Favicon and meta

- `assets/favicon.svg`
- `theme-color` matches active theme background
- Title: *Tessra — Elegant discovery in an aperiodic mosaic*

---

## 10. Success criteria

| Criterion | Measure |
|-----------|---------|
| Theme switch | All 4 moods apply without page reload or visible flash |
| Contrast | Body text ≥ WCAG AA (4.5:1) on quartz, lagoon, folio backgrounds |
| Scroll experience | Snap works on desktop and mobile; disabled with reduced-motion |
| Token alignment | Landing tokens match game `themes.js` for production picker IDs |
| PDR coverage | Every landing `#section` has measurable requirements (this document) |
| Style board | `design/style-board.html` renders all themes and component specimens |

---

## 11. Out of scope

- Web v5 object/instrument mode
- Hub Nothing-Grid chrome (`assets/hub.css`) as product surface
- Mobile Jaro/Courier palette (separate track in `penrose-mobile/`)
- v4 Story player, Canvas ∞, 8-palette UTC rotation
- Real illustrations for pattern-fact cards (placeholder plates acceptable)
- Wallpaper size/format picker on generator

---

## 12. References

| Document | Path |
|----------|------|
| Design system (canonical) | [`design.md`](design.md) |
| Visual style board | [`design/style-board.html`](design/style-board.html) |
| Legacy cross-track design | [`DESIGN-legacy.md`](DESIGN-legacy.md) (deprecated) |
| Landing brief | [`penrose/versions/v3.4-lacuna/LANDING-BRIEF.md`](penrose/versions/v3.4-lacuna/LANDING-BRIEF.md) |
| Screen build plan | [`LANDING-SCREENS.md`](LANDING-SCREENS.md) |
| Game themes source | [`penrose/versions/v3.4-lacuna/themes.js`](penrose/versions/v3.4-lacuna/themes.js) |
| Landing tokens | [`styles/tokens.css`](styles/tokens.css) |
| Brand platform | [`00 - main docs/01 - BRAND PLATFORM.md`](00%20-%20main%20docs/01%20-%20BRAND%20PLATFORM.md) |

---

## Next Actions

- Ship `#waitlist` section to unblock full scroll flow and CTA completion.
- Replace pattern-carousel placeholder art with Penrose-fact illustrations.
- Capture v3.4 screenshots for Daily and Levels cards on landing.