---
title: "Wordle Clone"
status: final
created: 2026-07-07
updated: 2026-07-07
---

# PRD: Wordle Clone

## 0. Document Purpose

This PRD defines the v1 requirements for a Wordle-clone word-guessing game. It is written for the builder (Helg) and serves as the input to architecture, epics/stories, and implementation workflows. The document builds on the product brief (`briefs/brief-wordle-2026-07-07/brief.md`) and brainstorming session. Structure: Glossary-anchored vocabulary, features with nested FRs, user journeys as the organizing spine. Assumptions are tagged inline and indexed in §9.

## 1. Vision

A browser-playable Wordle clone — 5 letters, 6 attempts, green/yellow/gray positional feedback — with a computer solver engine under the hood that pre-computes every word to rank difficulty. V1 delivers the core game, multiple solver algorithms, word ranking, and Play Again with skill-based word selection. One daily word is shared by all players. Works on mobile and desktop via web browser. Post-v1 features are prioritized by friend feedback.

This is a learning project first: the codebase is built with the BMad method end-to-end and stands as a reference for future work.

## 2. Target User

### 2.1 Jobs To Be Done

- As a word-puzzle fan, I want a quick, satisfying daily challenge that tests my vocabulary and deduction skills
- As a player, I want clear, immediate feedback on every guess so I can refine my strategy
- As a returning player, I want to jump straight into the game without friction
- As a builder, I want a clean codebase I understand and can extend

### 2.2 Non-Users (v1)

- Players expecting multiplayer or social features
- Players wanting variable word lengths or alternative game modes

### 2.3 Key User Journeys

- **UJ-1. First-time player learns the rules and plays.**
  - **Persona + context:** A friend of Helg's, heard about the game, opens it for the first time on their phone.
  - **Entry state:** Browser, no prior visit cookie.
  - **Path:** Screen 1 displays the rules — 5-letter words, 6 attempts, green/yellow/gray meaning. Taps **Play**. Lands on Screen 2 — empty 5×6 grid, keyboard below in light gray (all keys unused). Types a 5-letter guess. Grid fills, keyboard updates with per-key colors. Repeats until solved or out of attempts.
  - **Climax:** Solves in 4 attempts — the row confirms green, a brief celebration.
  - **Resolution:** Screen 3 — "Congratulations!", attempt count, updated statistics, **Play Again** button.
  - **Edge case:** Types a word not in the dictionary → "Unknown word" message, backspace all letters on that row, retry. Attempt is not burned.

- **UJ-2. Returning player jumps straight in.**
  - **Entry state:** Prior visit cookie detected.
  - **Path:** Skips Screen 1, lands directly on Screen 2 — empty grid, fresh keyboard.
  - **Climax + Resolution:** Same as UJ-1.

- **UJ-3. Player types an invalid word.**
  - **Path:** Submits 5 letters not in the word bank → "Unknown word" message shown on Screen 2 → player backspaces all letters on that row → retries. Attempt not consumed.

- **UJ-4. Player exhausts all 6 attempts and fails.**
  - **Path:** Six guesses, none correct. Screen 3 shows: the correct word revealed, "Better luck next time," statistics updated (streak broken, fail recorded), **Play Again** button.

- **UJ-5. Player hits Play Again.**
  - **Path:** From Screen 3 results, taps **Play Again** → new word generated, randomly picked based on player skill level → Screen 2 with empty grid → plays again.

## 3. Glossary

- **Word** — the target 5-letter word the player tries to guess.
- **Guess** — a 5-letter string submitted by the player on one attempt.
- **Attempt** — one row of the 6-row grid; a single guess consumes one attempt.
- **Grid** — the 5-column × 6-row visual layout displaying all guesses and their feedback.
- **Feedback** — per-letter color: green (correct letter, correct position), yellow (letter in word, wrong position), gray (letter not in word or excess instance).
- **Feedback Scoring Rule** — greens are assigned first (exact-position matches). Yellows are then allocated up to the remaining count of that letter in the word (total count minus greens already assigned). Any guess letter instances exceeding the word's count are gray. Example: word `style`, guess `hello` → gray, yellow, gray, green, gray.
- **Keyboard** — on-screen QWERTY layout. Each key shows the best feedback achieved for that letter across all guesses so far (green > yellow > dark gray). Unused letters remain light gray.
- **Daily Word** — the single word shared by all players each day. Same for every player.
- **Play Again** — post-result action; generates a new word randomly, weighted by player skill level.
- **Player Skill** — performance metric derived from past games, used to bias Play Again word selection.
- **Solver** — computer algorithm that pre-computes attempt counts for every word in the bank using an optimal or heuristic strategy.
- **Word Ranking** — difficulty score per word, derived from solver attempt data.
- **Word Bank** — the curated set of valid 5-letter words: both guessable words (dictionary for validation) and target words (eligible as daily/play-again words). Curated by recent internet usage frequency.
- **Screen 1 / Rules** — rules display shown on first visit; skipped on subsequent visits (cookie).
- **Screen 2 / Game** — the grid + keyboard play surface.
- **Screen 3 / Results** — post-game screen showing outcome, statistics, and the Play Again button.
- **Statistics** — lifetime stats: games played, win rate, attempt-count histogram, current/max streak.

## 4. Features

### 4.1 Rules Screen

**Description:** On first visit (no cookie), display the game rules. Returning players skip directly to the game. Realizes UJ-1, UJ-2.

**Functional Requirements:**

#### FR-1: First-visit detection
The system can detect whether the player has previously visited and show or skip the rules screen accordingly.

**Consequences (testable):**
- Player with no cookie sees Screen 1 (Rules).
- Player with a prior-visit cookie lands directly on Screen 2 (Game).

#### FR-2: Rules display
The system can display the game rules: 5-letter words, 6 attempts allowed, green/yellow/gray feedback meaning, and a Play button to proceed.

**Consequences (testable):**
- Rules text is rendered on Screen 1.
- Tapping Play navigates to Screen 2.

### 4.2 Core Gameplay

**Description:** The main game surface — grid, keyboard, guess entry, and feedback. Realizes UJ-1, UJ-2, UJ-3, UJ-4.

**Functional Requirements:**

#### FR-3: Grid rendering
The system can render a 5-column × 6-row grid. Each cell displays one guessed letter with its feedback color (green, yellow, or dark gray background) after submission.

**Consequences (testable):**
- Empty grid renders with 6 rows × 5 columns.
- After a guess, the active row fills with letters and each cell shows the correct feedback color.

#### FR-4: Keyboard rendering and highlighting
The system can render an on-screen QWERTY keyboard. After each guess, keys update to reflect the best feedback for that letter across all guesses: green (correct position in any guess), yellow (present but wrong position), dark gray (used and absent), light gray (unused).

**Consequences (testable):**
- All keys start light gray.
- A letter guessed in the correct position turns that key green and stays green.
- A letter guessed in the wrong position turns yellow, unless it later becomes green.
- A letter guessed and confirmed absent turns dark gray.

#### FR-5: Guess submission
The player can type a 5-letter word via physical keyboard or on-screen keyboard and submit it (Enter key or on-screen submit).

**Consequences (testable):**
- 5 letters accepted per guess.
- Submission requires exactly 5 letters.
- Letters appear in the active grid row as typed.

#### FR-6: Invalid word rejection
The system can validate the guess against the word bank. If the guess is not in the bank, display "Unknown word," allow backspace to clear the row, and do not consume the attempt.

**Consequences (testable):**
- Guess "XXXXX" (not in bank) → "Unknown word" message shown.
- Player can backspace all letters and retry.
- Attempt counter does not increment.

#### FR-7: Feedback scoring
The system can apply the Feedback Scoring Rule to each guess: greens first (exact position matches), then yellows allocated to remaining letter count in the word, excess instances gray.

**Consequences (testable):**
- Word `large`, guess `hello` → positions: h=gray, e=gray, l=yellow, l=gray, o=gray (one 'l' in word, second 'l' is excess).
- Word `style`, guess `hello` → gray, yellow, gray, green, gray.

#### FR-8: Win detection
The system can detect when all 5 letters are green (correct guess) and transition to Screen 3 with a congratulations message.

**Consequences (testable):**
- All-green row → Screen 3 shows "Congratulations!" and attempt count.
- Statistics updated: win recorded, streak incremented.

#### FR-9: Loss detection
The system can detect when the 6th attempt is exhausted without a correct guess and transition to Screen 3 with the correct word revealed.

**Consequences (testable):**
- 6th wrong guess → Screen 3 shows "Better luck next time" and the correct word.
- Statistics updated: loss recorded, streak reset.

### 4.3 Daily Word

**Description:** A single word shared by all players each day. Realizes UJ-1, UJ-2, UJ-4.

**Functional Requirements:**

#### FR-10: Daily word selection
The system can select and serve the same target word to all players for a given calendar day. Word changes at midnight EST/EDT (America/New_York).

**Consequences (testable):**
- Two players opening the game on the same day get the same target word.
- Word changes at the daily boundary.

### 4.4 Play Again

**Description:** After completing or failing the daily word, the player may play additional rounds with words selected based on their skill level. Realizes UJ-5. [ASSUMPTION: skill is measured as average attempts-to-solve across past games.]

**Functional Requirements:**

#### FR-11: Play Again word selection
The system can generate a new word after the daily word is completed, selected randomly from the word bank with weighting based on the player's skill level.

**Consequences (testable):**
- Tapping Play Again on Screen 3 loads a new word.
- Word difficulty correlates with player skill (better players get harder words on average).
- Player returns to Screen 2 with an empty grid.

#### FR-12: Player skill tracking
The system can compute and store a player skill metric derived from past game performance.

**Consequences (testable):**
- Skill metric updates after each completed game.
- Metric persists across sessions (browser storage).

### 4.5 Results Screen

**Description:** Post-game display showing outcome, statistics, and the Play Again action. Realizes UJ-1, UJ-4, UJ-5.

**Functional Requirements:**

#### FR-13: Results display
The system can show the game outcome: congratulations with attempt count (win) or correct word revealed (loss).

**Consequences (testable):**
- Win → "Congratulations!" + "Solved in N attempts."
- Loss → "Better luck next time" + "The word was: XXXXX."

#### FR-14: Statistics display
The system can show lifetime statistics: games played, win rate (%), attempt-count histogram (1-6 + fail), current streak, max streak.

**Consequences (testable):**
- Stats update after every game and persist across sessions.
- Histogram bars reflect actual attempt distribution.

#### FR-15: Play Again button
The system can display a Play Again button on Screen 3 that triggers a new game.

**Consequences (testable):**
- Button is visible and tappable on Screen 3.
- Triggers FR-11 (word selection) and navigates to Screen 2.

### 4.6 Solver Engine

**Description:** Computer solver that pre-computes attempt counts for every word in the bank using multiple algorithms. Produces word ranking data. Runs as a standalone pre-compute script (not in-browser, not during gameplay); output is a static data file consumed by the game at build time or server start.

**Functional Requirements:**

#### FR-16: Multi-algorithm solver
The system can run at least two distinct solving algorithms against every word in the target word bank and record the number of attempts each algorithm required.

**Consequences (testable):**
- Solver output includes: word, algorithm name, attempt count.
- At least two algorithms implemented (e.g., entropy-based, minimax, frequency-based).

#### FR-17: Word ranking output
The system can produce a difficulty score for each word derived from solver attempt data, stored in a format consumable by the game.

**Consequences (testable):**
- Every word in the target bank has a difficulty score.
- Play Again word selection (FR-11) uses these scores.

### 4.7 Word Bank

**Description:** Curated set of valid 5-letter words. [ASSUMPTION: a suitable public-domain 5-letter word list with frequency data exists and is licensable.]

**Functional Requirements:**

#### FR-18: Word bank curation
The system can load a word bank of valid 5-letter English words, filtered for recent internet usage frequency (last ~5 years). The bank distinguishes guessable words (all valid 5-letter strings the player might type) from target words (subset eligible as daily/play-again words).

**Consequences (testable):**
- Invalid guess "ABCDE" is rejected (FR-6).
- Target words are a curated subset of guessable words.
- No obscure/archaic words in the target set.

### 4.8 Browser Persistence

**Description:** All player state survives browser close and session restart. Covers first-visit cookie, statistics, and skill metric.

**Functional Requirements:**

#### FR-19: Browser storage
The system can persist player state (rules-seen cookie, lifetime statistics, skill metric) to browser storage and restore it on subsequent visits.

**Consequences (testable):**
- Close browser tab, reopen → rules screen skipped if previously seen.
- Statistics and histogram persist across sessions.
- Skill metric survives browser restart.
- Clearing browser storage resets all state to first-visit defaults.

## 5. Non-Goals (Explicit)

- Multiplayer or real-time 2-player mode
- Variable word length (3-7 letters)
- Position-blind or alternative game modes
- User-submitted words
- Post-solve learning layer (definition, etymology, pictures)
- Standardized hints on attempts 5-6
- Percentile ranking or leaderboards
- Daily word notification/reminder system
- Native mobile app

## 6. MVP Scope

### 6.1 In Scope

- Three-screen web application (Rules, Game, Results)
- Core gameplay: 5 letters, 6 attempts, green/yellow/gray feedback with correct letter-counting rule
- On-screen QWERTY keyboard with per-key color highlighting
- Physical keyboard support
- Daily word — same for all players
- Play Again with skill-based word selection
- Invalid word rejection with retry (attempt not burned)
- Lifetime statistics with attempt-count histogram and streaks
- Computer solver engine (≥2 algorithms, pre-computed word ranking)
- Curated word bank (recent-usage filtering)
- Works on mobile and desktop via web browser

### 6.2 Out of Scope for MVP

- Adaptive difficulty system (full) — partial via Play Again skill weighting
- Percentile ranking — post-v1
- Streak quality weighting — post-v1
- Standardized hints — post-v1
- Post-solve learning layer — post-v1
- Infinite after-play (beyond Play Again from daily) — post-v1 [ASSUMPTION: Play Again from daily provides enough "more to do"; true freeplay/infinite mode is deferred.] [NOTE FOR PM: Play Again from daily is in; freeplay/infinite mode is out]
- Computer-guess subgame — post-v1
- Real-time 2-player mode — post-v1
- Variable word length — post-v1
- Position-blind hard mode — post-v1

## 7. Success Metrics

*Scaled for a hobby/learning project.*

**Primary**
- **SM-1**: I can play a complete game from browser — rules → guess → feedback → result → play again. Validates all FRs.
- **SM-2**: The solver engine produces word rankings for the full word bank. Validates FR-16, FR-17.
- **SM-3**: I complete the full BMad workflow (brief → PRD → architecture → epics → implementation) with this project.

**Secondary**
- **SM-4**: A friend can open the game on their phone and play without explanation. Validates UJ-1.
- **SM-5**: Session-to-session persistence works — stats, rules cookie, and skill metric survive browser close. Validates FR-19.

**Counter-metrics (do not optimize)**
- **SM-C1**: Codebase complexity — do not over-engineer for a learning project. Counterbalances SM-2.

## 8. Open Questions

1. **Word bank source?** Which public domain / licensed word list? Frequency data from which corpus?
2. **Solver algorithms?** Which two (or more) specific algorithms to implement?
3. **Skill metric formula?** Simple average attempts, weighted recent, or another model?
4. **Cookie/privacy banner needed?** Depends on jurisdiction and whether we use any tracking beyond a first-visit cookie.

## 9. Assumptions Index

- §4.4 — Skill metric is average attempts-to-solve across past games. Confirm formula during implementation.
- §4.7 — A suitable public-domain 5-letter word list with frequency data exists and is licensable.
- §6.2 — Play Again provides enough "more to do" after the daily word; true freeplay/infinite mode is deferred.