System Requirements Document for tic-tac-toe

1. Introduction

This document specifies tic-tac-toe, a simple, single-page browser game in which one human player competes against an AI opponent on a classic 3×3 board. The product intent is deliberately narrow: deliver a complete, self-contained tic-tac-toe match experience — choose a move, watch the AI respond, reach a win, loss, or draw, and start another game — without accounts, navigation, or any surrounding application surface.

The audience is a single casual player who wants a low-stakes, coffee-break toy they can pick up and play immediately. The entire experience lives on one page, opens anonymously, and requires no sign-in, no setup, and no prior state.

2. System Overview

tic-tac-toe is a client-delivered, single-page game. The player lands directly on the game surface, sees a 3×3 board and a title, and plays against an AI opponent. The player marks cells with an X; the AI answers with an O. The match resolves to a win, a loss, or a draw, and the player can immediately begin a new game. A running scoreboard tracks the player's wins, draws, and AI wins across games in the session.

The only human actor is the Player. The AI opponent is a system process internal to the page — it is not a persona, not a separate destination, and not a network service. There is no backend account system, no multi-user state, and no persistence beyond the current browser session.

2a. Product Interpretation and Delivery Boundary

The product is delivered as a single first-party page, Tic Tac Toe, that is anonymously reachable. Because the game is a self-contained, single-session toy with no durable identity, no commitments bound to a named participant, and no cross-session state to resume, no application-owned identity is established and no authentication is introduced. The player's scoreboard lives only for the current session and resets on reload; this is consistent with the "simple" scope constraint and does not require accounts.

Everything the player does — selecting a cell, reading the AI's response, reading the outcome, starting a new game, and toggling difficulty — happens on this one page. There are no other pages, routes, or destinations in the current scope. Future ideas (for example, online multiplayer or persistent stats) are explicitly out of scope and are not represented in the current page, requirements, or acceptance.

2b. Source Content Inventory

Not applicable. No reference directive in the authoritative sources declares a content_source, so no source content inventory is included.

2c. Page Content and Component Coverage

Tic Tac Toe

The single page of the product. It is the anonymous public entry surface and hosts the entire game lifecycle: title, board, AI opponent, outcome, scoreboard, and new-game reset.

• Information and state
  • Game title stack: "TIC / TAC / TOE" in Alfa Slab One, with "TOE" reversed out of a burnt-orange block.
  • A small "VS AI" badge stamp in mustard, rotated, indicating the opponent.
  • The 3×3 board state: each of the nine cells is empty, marked with the player's X, or marked with the AI's O.
  • Turn state: whose move it is (player or AI), and whether the board is locked while the AI is thinking.
  • Match outcome state: in progress, player win, AI win, or draw.
  • Scoreboard state: three counters — YOU (player wins), DRAWS, AI (AI wins) — for the current session.
  • Difficulty state: a two-position switch (the two positions are the two difficulty levels offered by the game).
• Primary actions
  • Select an empty cell to place the player's X (only legal on the player's turn and while the game is in progress).
  • Start a new game via the NEW GAME button, which clears the board and resets the in-progress match while preserving the session scoreboard.
  • Toggle difficulty via the two-position switch, which sets the AI's playing strength for subsequent games.
• Supporting actions and controls
  • Read the outcome stamp (WIN / LOSE / DRAW) that appears over the board when the match ends.
  • Read the winning line rule that wipes across the three winning cells on a win or loss.
  • Read the scoreboard counters, which update after each completed match.
• Domain entities
  • Board: a 3×3 grid of nine cells, each empty, X, or O.
  • Mark: X (player, burnt orange) or O (AI, mustard).
  • Match: one game from empty board to a terminal outcome (win, loss, or draw).
  • Outcome: WIN, LOSE, or DRAW, rendered as a rotated rubber stamp.
  • Scoreboard: session counters for player wins, draws, and AI wins.
  • Difficulty: the currently selected AI strength level.
• Component responsibilities
  • Title stack: presents the game identity and the "VS AI" badge; purely presentational.
  • Board panel: renders the ruled 3×3 grid, receives cell selections, and displays X and O marks with stamp-scale animation.
  • AI opponent (system process): computes and plays the AI's move after the player's move, subject to the selected difficulty.
  • Outcome stamp and winning line: render the terminal result and highlight the winning three cells.
  • Scoreboard strip: displays and updates the three session counters.
  • Controls row: hosts the NEW GAME button and the difficulty switch.
• States
  • Loading: not applicable in the conventional sense; the page is a static client bundle with no remote data fetch. The board renders immediately in its empty state.
  • Empty: a fresh board with all nine cells empty, awaiting the player's first move.
  • In progress: the player has moved; the board shows a mix of X and O marks; the turn indicator reflects whose move it is.
  • AI thinking: after the player's move, the board is locked to further player input for the brief AI beat before the AI's O lands.
  • Success (player win): the winning line wipes across the three player cells and the WIN stamp slams down; the YOU counter increments.
  • Failure (AI win): the winning line wipes across the three AI cells and the LOSE stamp slams down; the AI counter increments.
  • Draw: the board fills with no winner; the DRAW stamp slams down; the DRAWS counter increments.
  • Recovery / continuation: after any terminal outcome, the player presses NEW GAME to clear the board and play again; the scoreboard persists for the session.
  • Error: no network or server errors are possible in the current scope; the only invalid interaction is selecting an occupied cell or selecting during the AI's turn, which is rejected by leaving the board unchanged.

3. Functional Requirements

Each requirement below is a distinct, source-bounded story point. Provenance is marked as explicit (stated in the authoritative user requirement thread or Planning Scope), basic_default (an accepted default filling an unspecified detail), or required_inference (an indispensable mechanic needed to make an accepted outcome usable).

FR-1 — Single-page game delivery (explicit) As a Player, I should reach the entire tic-tac-toe game on a single page, so that I can play without navigating anywhere else.

• Trigger/input: opening the product.
• Observable result: the Tic Tac Toe page renders with the title, board, scoreboard, and controls; no other page or route exists.
• Access state: anonymous; no sign-in required.
• Failure/recovery: not applicable.
• Continuation: the player proceeds to play a match.

FR-2 — Play against an AI opponent (explicit) As a Player, I should compete against an AI opponent, so that I can play a full game without another human.

• Trigger/input: the player makes a move; the AI responds.
• Observable result: the AI places an O on the board after the player's move.
• Access state: anonymous.
• Failure/recovery: if the AI has no legal move (board full), the match ends as a draw.
• Continuation: play continues until a terminal outcome.

FR-3 — Place a mark on an empty cell (explicit) As a Player, I should select an empty cell to place my X, so that I can make my move.

• Trigger/input: the player selects one of the nine empty cells on their turn.
• Observable result: an X appears in the selected cell with a stamp-scale animation; the cell becomes occupied.
• Access state: anonymous; only legal while the match is in progress and it is the player's turn.
• Failure/recovery: selecting an occupied cell or selecting during the AI's turn leaves the board unchanged.
• Continuation: the AI then takes its turn.

FR-4 — AI responds with its own mark (required_inference) As a Player, I should see the AI place its O in response to my move, so that the game advances and I can plan my next move.

• Trigger/input: the player's move completes.
• Observable result: after a brief beat, an O appears in a legal empty cell; the turn returns to the player.
• Access state: anonymous.
• Failure/recovery: if no legal cell remains, the match ends as a draw instead.
• Continuation: the player takes the next turn.

FR-5 — Reach a win, loss, or draw outcome (explicit) As a Player, I should reach a clear win, loss, or draw at the end of a match, so that I know how the game resolved.

• Trigger/input: three of the player's marks align (win), three of the AI's marks align (loss), or all nine cells fill with no alignment (draw).
• Observable result: the winning line wipes across the three aligned cells (on a win or loss) and a rotated WIN, LOSE, or DRAW stamp slams down over the board; the board locks to further play.
• Access state: anonymous.
• Failure/recovery: not applicable; every completed match resolves to exactly one of the three outcomes.
• Continuation: the player can start a new game.

FR-6 — Start a new game (explicit) As a Player, I should start a new game after a match ends, so that I can play again.

• Trigger/input: the player presses the NEW GAME button.
• Observable result: the board clears to nine empty cells, the outcome stamp and winning line are removed, and a fresh match begins.
• Access state: anonymous.
• Failure/recovery: pressing NEW GAME mid-match also clears the board and restarts the current match.
• Continuation: the player makes the first move of the new match.

FR-7 — Session scoreboard (required_inference) As a Player, I should see a running tally of my wins, draws, and the AI's wins, so that I can track how I am doing across games in this session.

• Trigger/input: each completed match.
• Observable result: the YOU, DRAWS, or AI counter increments according to the outcome.
• Access state: anonymous; the tally is session-scoped and resets on reload.
• Failure/recovery: not applicable.
• Continuation: the tally persists across NEW GAME resets within the session.

FR-8 — Difficulty selection (required_inference) As a Player, I should be able to set the AI's difficulty with a two-position switch, so that I can choose how hard the opponent plays.

• Trigger/input: the player toggles the two-position difficulty switch.
• Observable result: the switch physically slides between its two ink blocks and the AI's playing strength changes for subsequent games.
• Access state: anonymous.
• Failure/recovery: not applicable.
• Continuation: the selected difficulty applies to the next match.

4. User Personas

Player

Product context. The Player is a single casual person who opens the game for a short, low-stakes break. They are not a power user, not a competitor, and not part of any team or account system. They arrive anonymously, expect the game to be immediately playable, and leave when they are done. There is no second human participant in the product.

Primary goal. Play a complete game of tic-tac-toe against an AI opponent and see a clear result, then be able to play again.

Distinct accepted responsibilities.

• Choosing which empty cell to mark on each of their turns.
• Reading the AI's responses and adapting their play.
• Reaching and reading a win, loss, or draw outcome.
• Starting a new game to continue playing.
• Optionally adjusting the AI's difficulty with the two-position switch.
• Reading the session scoreboard to track their record.

Relevant inputs or decisions.

• Which cell to select on each turn.
• Whether to start a new game after a match ends.
• Which difficulty position to set on the switch.

Interactions with other accepted participants. The Player's only counterparty is the AI opponent, which is a system process inside the page rather than a human persona. The Player acts, the AI responds, and the Player reads the result. There is no human-to-human interaction in the current scope.

Observable success. The Player completes a full match, sees a WIN, LOSE, or DRAW stamp, sees the scoreboard update, and can immediately start another game.

5. Core User Flows

Flow 1 — Play a full match against the AI

1. Starting context. The Player opens the product. The Tic Tac Toe page loads anonymously on the kraft-paper ground, showing the title stack, the empty 3×3 ruled board, the scoreboard strip at zero, and the NEW GAME button and difficulty switch.
2. The Player selects an empty cell. An X lands in that cell with a 90ms stamp-scale animation, and the board locks to further player input.
3. After a brief beat, the AI opponent places an O in a legal empty cell, drawn as a thick two-stroke path. The turn returns to the Player.
4. The Player and the AI alternate moves (steps 2–3) until the match resolves.
5. Outcome. If three of the Player's marks align, the winning line wipes across those cells in orange and the rotated WIN stamp slams down over the board. If three of the AI's marks align, the same wipe occurs on the AI's cells and the LOSE stamp slams down. If all nine cells fill with no alignment, the DRAW stamp slams down. In every case the board locks to further play.
6. Observable result. The Player sees the outcome stamp and the winning line (where applicable), and the corresponding scoreboard counter increments.
7. Continuation. The Player presses NEW GAME to clear the board and begin another match, or leaves the page.

Flow 2 — Start a new game

1. Starting context. A match has just ended, or the Player wants to abandon the current match.
2. The Player presses the NEW GAME button. The button depresses 2px on press.
3. Observable result. The board clears to nine empty cells, the outcome stamp and winning line are removed, and the match resets. The session scoreboard is preserved.
4. Continuation. The Player makes the first move of the new match, returning to Flow 1.

Flow 3 — Adjust the AI's difficulty

1. Starting context. The Player is on the Tic Tac Toe page, before or between matches.
2. The Player toggles the two-position difficulty switch. The switch physically slides between its two ink blocks.
3. Observable result. The AI's playing strength is set for subsequent games.
4. Continuation. The Player starts or continues a match under the new difficulty, returning to Flow 1.

Flow 4 — Track the session record

1. Starting context. The Player has completed one or more matches in the current session.
2. The Player reads the scoreboard strip of three ink-bordered boxes: YOU, DRAWS, AI.
3. Observable result. The counters reflect the outcomes of all matches played in the session.
4. Continuation. The Player continues playing; the tally persists across NEW GAME resets and resets only on page reload.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Aaron Draplin, and the headline concept is "Field-Notes tic-tac-toe: thick strokes, kraft paper, one hot orange X." The register is playful, tactile, low-stakes, and nostalgic — a coffee-break toy, not a productivity tool. The board should feel like a physical object the player can slap a mark onto.

Colour tokens (light mode)

No blue of any kind. No gradients.

Typography

• Headings: Alfa Slab One at 400, all-caps, tight tracking (-0.01em). Used only for the game title, outcome stamps, and the big "TIC / TAC / TOE" stack.
• Body and labels: Oswald at 500/600, uppercase with 0.08em letterspacing, for every label, button, and scoreboard line.
• No lowercase display type anywhere.
• Type scale: 1.5 modular on a 4px baseline — 96 / 64 / 40 / 24 / 16 / 13. Labels 13px Oswald 600, board marks 64px, stamps 40px, title 96px.

Shape language

• Hard rectangles with 3px ink borders and 6px offset solid shadows — no blur, no rounded corners beyond 2px.
• The board is a ruled panel: nine square cells separated by 3px ink rules, the outer frame 3px, the inner grid 2px.
• Buttons are chunky ink-bordered blocks that depress 2px on press.
• Badge/stamp shapes for outcome states, with a 12-degree rotation on the win stamp.

Layout

• Single page, single column, max-width 960px, centred on the kraft ground with a thick ink rule top and bottom.
• Order: badge-style header (small circular "VS AI" stamp + title stack), the 3×3 ruled board as the dominant object, a scoreboard strip of three ruled boxes (YOU / DRAWS / AI) below it, then a row of two chunky buttons (NEW GAME, difficulty toggle as a two-position switch).
• Asymmetric detail: the title stack is left-aligned and overhangs the board's right edge by one column; the scoreboard is flush right.

Imagery

• No photography, no illustration, no 3D. The image is the board itself plus thick-line vector iconography in the Draplin register: a small crossed-hammer badge in the header, halftone-dot texture at 6% opacity on the kraft ground, ruled tick marks along the page edges, and rubber-stamp outcome graphics (WIN / LOSE / DRAW) with distressed edges. Every graphic is one or two ink colours.

7. Signature Design Concept

The public entry is the game itself, and the signature concept is the board as a physical, stamped object on a field-notes page.

• A full-width kraft-paper field with a 3px ink rule at the very top carrying a tiny "TIC TAC TOE — VS AI" ticker in Oswald 13px uppercase.
• Below it, left-aligned, the title is a three-line slab stack in Alfa Slab One at 96px — TIC / TAC / TOE — in ink black, with the word TOE sitting on a burnt-orange block that bleeds off the left edge of the viewport.
• The 3×3 ruled board (cream card, 3px ink frame, 6px offset shadow) overlaps the bottom of the title stack by 40px and is the largest object on screen.
• To its right, a rotated "VS AI" badge stamp in mustard.
• No centred text, no subheading, no blue button, no gradient.

The board reads as a letterpress square: 3px ink outer frame, 2px inner rules, 6px solid offset shadow, halftone dot texture at 6% on the kraft ground behind it. Marks are thick strokes — X as two 8px orange strokes with squared caps, O as a mustard ring with a 3px gap — both landing with a stamp-scale rather than a fade. The outcome is a rotated rubber stamp (WIN / LOSE / DRAW) in Alfa Slab One on a mustard or orange block, rotated -12deg, slamming down over the board after the winning line wipes across in orange. The scoreboard is a ruled strip of three ink-bordered boxes (YOU / DRAWS / AI) with tabular Oswald numerals, flush right, plus a two-position chunky switch for difficulty that physically slides between two ink blocks.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject. The 3×3 ruled board on its cream card, overlapping the bottom of the TIC / TAC / TOE title stack by 40px, with the rotated "VS AI" mustard badge to its right.
• Input → transformation → outcome thesis. The player selects an empty cell → an X lands in that cell with a 90ms scale-in from 1.4 to 1 with a single 2px overshoot → after a 420ms beat the AI's O arrives as a thick two-stroke path; on a terminal outcome the winning line wipes across in 200ms and the rotated stamp slams down with a 120ms scale-down.
• Motion vocabulary. Snap and stamp, never smooth. Marks land with a 90ms scale-in from 1.4 to 1 with a single 2px overshoot. The AI's O arrives after a 420ms beat. The winning line is a 3px orange rule that wipes across in 200ms, then the rotated win stamp slams down with a 120ms scale-down. Buttons depress 2px instantly. No easing theatrics, no particles, no fades longer than 150ms.
• Composed first frame. The kraft ground fills the viewport with a 3px ink rule at the top carrying the "TIC TAC TOE — VS AI" ticker. The title stack sits left-aligned, with TOE reversed out of a burnt-orange block bleeding off the left edge. The empty ruled board overlaps the title's baseline by 40px, its 6px offset shadow grounding it. The "VS AI" badge is rotated to the board's right. The scoreboard strip reads 0 / 0 / 0, flush right, and the NEW GAME button and difficulty switch sit below.
• Reduced-motion state. When the user prefers reduced motion, marks appear instantly in place with no scale-in, the AI's O appears without the 420ms beat, the winning line appears fully drawn, and the outcome stamp appears at its final rotation without the slam. All state changes remain fully legible and the game remains completely playable.

9. Non-Functional Requirements

NFR-1 — Single-page constraint (explicit) The product must consist of exactly one page. No additional routes, pages, or destinations may be introduced.

NFR-2 — Simple scope (explicit) The product must remain a simple tic-tac-toe game against an AI opponent. No adjacent capabilities (accounts, multiplayer, persistence, social features, monetisation) may be added.

NFR-3 — Anonymous access (required_inference) The page must be reachable without sign-in, since the game is a self-contained session toy with no durable identity or cross-session state to protect.

NFR-4 — Session-scoped scoreboard (required_inference) The scoreboard must persist across NEW GAME resets within a session and reset on page reload, consistent with the absence of persistence in the simple scope.

NFR-5 — Responsive single-column layout (basic_default) The page must render as a single centred column with a max-width of 960px, adapting to narrower viewports without breaking the board's square cells.

NFR-6 — Accessible colour contrast (basic_default) Ink black on kraft and cream grounds, and burnt orange and mustard marks on cream, must meet accessible contrast for text and meaningful graphics.

NFR-7 — Reduced-motion support (basic_default) The interface must respect the user's reduced-motion preference, as described in the motion direction.

NFR-8 — No blue, no gradients (explicit) The interface must contain no blue, indigo, or violet, and no gradients, per the creative direction.

10. Tech Stack

• React for the single-page client application.
• Vite as the build tool for the client bundle. [Default — not specified by user]
• CSS (plain stylesheets or CSS modules) for the Draplin-register styling, including the ruled board, offset shadows, and stamp animations. [Default — not specified by user]
• TypeScript for type safety across the board, match, and scoreboard state. [Default — not specified by user]
• No backend, no database, and no containerisation are required, because the game is a self-contained client-side experience with session-only state.

11. Assumptions and Constraints

• Single page only. The product is exactly one page; no navigation, routing, or additional destinations exist. (explicit)
• Simple scope. The game is tic-tac-toe against an AI opponent and nothing more. (explicit)
• Anonymous play. No accounts, sign-in, or identity are introduced, because no durable identity or cross-session state is required. (required_inference)
• Session-only scoreboard. The scoreboard resets on page reload. (required_inference)
• AI is a system process. The AI opponent runs inside the page and is not a persona, a separate destination, or a network service. (required_inference)
• Difficulty switch has two positions. The two positions are the two difficulty levels offered by the game; the specific strength of each level is an implementation detail. (required_inference)
• No persistence, no multiplayer, no monetisation. These are out of scope for the current product. (explicit by omission from the simple-scope constraint)
• **Future ideas are excluded from