Overview
Reveillark is a Wordle-inspired daily guessing game where players identify a hidden legendary creature from Magic: The Gathering. Each wrong guess progressively unmasks a region of the card — from color identity through mana cost, type line, stats, and finally the full art and name. Every player worldwide sees the same puzzle each day.
- Data-driven gameplay: All card attributes are sourced from Scryfall — no manual puzzle authoring needed
- Progressive reveal: SVG-masked card images uncover regions in a thematic sequence across up to 6 guesses
- Shareable results: Emoji-grid summaries (like Wordle) for social sharing without spoilers
- Zero backend: Entirely client-side with localStorage persistence — no accounts, no server
Problem
Daily puzzle games thrive on simplicity and social sharing, but building one for a domain as rich as Magic: The Gathering presents unique challenges around content scale, visual design, and long-term sustainability.
Content at scale
- Thousands of cards to choose from
- Hand-authoring daily puzzles doesn't scale
- Need variety without repeating cards
Visual reveal design
- Text-only clues lose the card game identity
- Showing the full card is an instant spoiler
- Need graduated difficulty within a single puzzle
Global consistency
- All players must see the same daily puzzle
- No backend means no server-side state
- Timezone handling across the globe
Solution
A stateless, data-driven architecture where Scryfall provides the card pool, a seeded RNG selects the daily puzzle deterministically, and SVG masks progressively reveal the card image — no backend, no content team, infinite variety.
Core design decisions
- Scryfall as source of truth: 2,841 legendary creatures pre-filtered and embedded as static JSON — no runtime API calls
- Deterministic selection: Date-seeded Mulberry32 PRNG ensures every player gets the same card globally per UTC day
- Visual masking: SVG overlays on real card art — not custom graphics — with pixel-calibrated regions for Scryfall's 488×680px images
- Client-only: localStorage for game state; no backend, no database, no accounts
Visual masking system
The signature mechanic: real card art is progressively unmasked using SVG overlays with pixel-perfect region coordinates. Each reveal level exposes a thematically meaningful part of the card.
| Reveal level | What's unmasked |
|---|---|
| 0 — Card back | Nothing visible; player starts with only the knowledge that it's a legendary creature |
| 1 — Frame color | Card border/frame reveals color identity (white, blue, black, red, green, multi, colorless) |
| 2 — Mana cost | Top-right corner shows casting cost — narrows candidates by CMC and color pips |
| 3 — Type line | Creature types and supertypes revealed (e.g., “Legendary Creature — Human Wizard”) |
| 4 — Power/toughness | Bottom-right stat box unmasked |
| 5 — Set info | Set symbol and collector number visible |
| 6 — Full card | Art, name, and rules text — game over (loss) |
Technical implementation
- SVG clip paths: 8 distinct mask regions with precise coordinates calibrated to Scryfall's 488×680px card images
- CSS transitions: Smooth dissolve animations as regions are revealed
- Color-based glow: Card border radiates a color matching the card's color identity for thematic immersion
Design rationale
- Thematic ordering: Reveals follow how MTG players evaluate cards — color first, then cost, type, stats
- Real art: Using actual card images creates authentic recognition moments
- No custom assets: Masks work on any card automatically — no per-card graphics needed
Puzzle generation
Every player worldwide sees the same card each day — without a server. A seeded pseudo-random number generator maps each UTC date to a specific card deterministically.
How it works
- Date seed: Current UTC date is hashed into a 32-bit integer
- Mulberry32 PRNG: Deterministic algorithm produces the same sequence for any given seed
- Card selection: PRNG output maps to an index in the 2,841-card pool
- Curated overrides: First 10+ days use hand-picked cards to ensure a strong launch experience
Search & UX
A custom autocomplete engine searches 2,841 card names instantly with relevance scoring, accent-insensitive matching, and full keyboard navigation.
Search engine
- Normalized index: Pre-computed at startup; handles accents, special characters, and case insensitivity
- Relevance scoring: Exact match (100) → starts-with (80) → word-starts-with (60) → contains (40)
- Top 8 results: Sorted by score, rendered as keyboard-navigable dropdown
Polish
- Confetti celebration on win (gold-themed particles)
- Color glow effects matching the card's identity
- Staggered victory text animation
- Progress orbs showing current reveal level
- Countdown timer to the next daily puzzle
- Guess history with visual feedback
Architecture
A clean separation of game logic, state management, and UI components — fully typed, thoroughly tested, and deployed as a static bundle with no server dependencies.
Code organization
- game/: Pure logic — puzzle selection, state reducer, storage, search, share formatting
- components/: React UI — masked card, autocomplete, guess history, result screen, header
- types/: Shared TypeScript interfaces for cards and game state
- data/: Static 2,841-card JSON pool pre-processed from Scryfall
Quality & testing
- Vitest: Unit tests for all game logic (puzzle, state, storage, search, share)
- React Testing Library: Component tests for autocomplete, card display, and masking
- TypeScript strict: No implicit any; full type safety across the codebase
- CI/CD: GitHub Actions runs lint, test, build on every push; auto-deploys to Pages
Outcomes
Delivered capabilities
- Deterministic daily puzzle generation via seeded PRNG
- SVG visual masking system with pixel-calibrated regions
- Instant autocomplete across 2,841 cards with relevance scoring
- Spoiler-free emoji-grid sharing for social platforms
- localStorage persistence with automatic state serialization
- Confetti, color glows, and victory animations for polish
- WCAG-compliant accessibility with ARIA labels and keyboard navigation
- Comprehensive test suite covering logic and components
Building engaging web experiences?
Reveillark demonstrates creative problem-solving, polished UX, and clean architecture — from deterministic puzzle algorithms to pixel-perfect SVG masking. If you need someone who can ship delightful, technically sound products, let's talk.