System Requirements Document for cosmic-tic

1. Introduction

cosmic-tic is a single-page tic tac toe game. A visitor opens the page and immediately plays a complete round of tic tac toe on a 3×3 grid: two players alternate placing marks, the app shows whose turn it is, prevents play on occupied cells, and detects and displays a win or a draw. The entire product is that one page — there is no navigation, no account, and no second screen.

The audience is anyone who wants a 60-second mental duel: a casual, anonymous player who expects something instantly playable that also feels like a small cosmic launch rather than a utility form. The product's register is dark, glowing, motion-first and HUD-like, while the grid itself stays dead simple to read and tap.

2. System Overview

cosmic-tic is delivered as a single public page, Tic Tac Toe, reachable anonymously with no sign-in. The page hosts the whole game: the oversized COSMIC-TIC wordmark, the 3×3 board, the turn/status HUD strip, and the win/draw announcement. A single active human persona, the Player, plays both marks in turn on the same device.

The game logic — turn alternation, occupied-cell prevention, win detection across rows, columns and diagonals, and draw detection when all nine cells are filled without a winner — runs in the application. The provisioned scaffold consists of a React frontend serving the page, a shared FastAPI backend for application APIs and domain modules, and a MariaDB database for application-owned persistent data. Because the accepted product has no accounts, no saved history, and no cross-session state, the database is provisioned infrastructure only; it does not by itself justify domain entities, authentication, or persistence requirements.

Removed from scope

• Multiplayer networking or remote opponents
• Computer/AI opponent
• Score tracking, match history, or leaderboards
• User accounts, profiles, or sign-in
• Additional pages, routes, or navigation menus

2a. Product Interpretation and Delivery Boundary

The requester asked for a single-page tic tac toe app, and that is the whole current delivery: one first-party page that is both the entry point and the game. Access is anonymous and public — no identity is established, because no accepted behavior requires durable actor-specific state, a commitment bound to a participant, or resumption across sessions. Both marks are played by people at the same device in alternating turns.

Everything the game needs to be usable lives on that page: the board, the turn indicator, the occupied-cell rule, the win/draw outcome, and a way to start a new round. Nothing beyond the single page is current. Future ideas (for example an AI opponent or score history) are not part of this delivery and are not represented in the page.

2c. Page Content and Component Coverage

Tic Tac Toe

Information and state

• Game phase: in progress, won by X, won by O, or drawn.
• Whose turn it is (X or O), shown in the HUD strip.
• The 3×3 board state: each cell empty, marked X, or marked O.
• Mono coordinate readout for the board (A1–C3) beneath the grid.
• Move count in JetBrains Mono within the HUD strip.

Primary actions

• Select an empty cell to place the current player's mark.
• Start a new round via the top-right ghost NEW ROUND chip, available at any time.

Supporting actions and controls

• Fixed top-left COSMIC-TIC micro-mark (identity only, not navigation).
• HUD status line that crossfades colour with the active player and switches to a single mono status line on win or draw.

Domain entities

• Round: the current game instance with its board state, active mark, move count, and outcome.
• Cell: one of nine positions identified by coordinate (A1–C3), holding empty, X, or O.
• Mark: X (electric cyan) or O (magenta), the two player identities expressed as colour.

Component responsibilities

• Wordmark block: oversized COSMIC-TIC display type with the hyphen rendered as a glowing cyan rule that pulses on game start.
• Board panel: floating glass instrument panel with corner HUD brackets, 1px luminous borders, radial under-glow, and two slow-orbiting hairline rings; renders nine cells and their marks.
• Cell: accepts a placement only when empty and the round is in progress; renders the volumetric X or O with a 220ms spring scale-in, light sweep and glow bloom.
• HUD strip: turn indicator, move counter, and status line; becomes a single mono status line on completion.
• Win overlay: pulses the three winning cells once and draws a luminous line across them in 500ms.
• Ambient layer: generative starfield of ~120 faint particles at 20% opacity and concentric orbital rings behind the board.

States

• Loading: the page renders its static cosmic stage immediately; no data fetch is required to play.
• Empty: a fresh round shows nine empty cells, X to move, move count 0.
• Success: a placement fills the cell, the turn indicator crossfades to the other mark, and the move count increments.
• Win: the winning three cells pulse once, a luminous line draws across them, and the HUD shows the winning mark as a single mono status line.
• Draw: all nine cells filled with no winner; the HUD shows a draw status line.
• Error/recovery: selecting an occupied cell or any cell after the round ends is rejected with no state change; the player continues by choosing an empty cell or pressing NEW ROUND.
• Reduced motion: static marks, no orbit, no sweep, instant state changes; the board remains fully usable.

3. Functional Requirements

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

• Trigger: the Player opens the app.
• Observable result: the Tic Tac Toe page renders the wordmark, the 3×3 board, and the HUD strip; there is no nav bar or second route.
• Access: anonymous, no sign-in.
• Failure/recovery: not applicable; the page is self-contained.
• Continuation: the Player proceeds to place a mark.

FR-2 — Alternating marks on a 3×3 grid (explicit) As a Player, I should place X and O alternately on a 3×3 grid, so that two players can take turns in a standard game.

• Trigger: the Player selects an empty cell during an in-progress round.
• Observable result: the cell shows the active mark (X in cyan, O in magenta), the turn indicator crossfades to the other mark, and the move count increments.
• Access: anonymous.
• Failure/recovery: selecting an occupied cell is rejected with no state change; the Player chooses another cell.
• Continuation: the other mark moves next.

FR-3 — Occupied-cell prevention (required_inference) As a Player, I should be unable to place a mark on a cell that already holds one, so that the board state stays valid.

• Trigger: the Player selects a cell that is already marked.
• Observable result: nothing changes — the mark, turn, and move count stay as they were.
• Access: anonymous.
• Failure/recovery: the rejection is the recovery; the Player selects an empty cell instead.
• Continuation: play continues with the same active mark.

FR-4 — Win detection and display (explicit) As a Player, I should see when a player has won, so that the round has a clear outcome.

• Trigger: a placement completes three matching marks in a row, column, or diagonal.
• Observable result: the three winning cells pulse once, a luminous line draws across them in 500ms, and the HUD strip switches to a single mono status line naming the winning mark.
• Access: anonymous.
• Failure/recovery: further cell selections are rejected until a new round starts.
• Continuation: the Player presses NEW ROUND to play again.

FR-5 — Draw detection and display (explicit) As a Player, I should see when the round ends in a draw, so that a full board without a winner is clearly resolved.

• Trigger: the ninth mark is placed with no winning line.
• Observable result: the HUD strip shows a draw status line; no winning line is drawn.
• Access: anonymous.
• Failure/recovery: further cell selections are rejected until a new round starts.
• Continuation: the Player presses NEW ROUND to play again.

FR-6 — New round (required_inference) As a Player, I should be able to start a fresh round at any time, so that I can replay after a win, a draw, or mid-game.

• Trigger: the Player presses the top-right NEW ROUND ghost chip.
• Observable result: the board clears to nine empty cells, X moves first, the move count resets to 0, and the wordmark hyphen pulses on game start.
• Access: anonymous.
• Failure/recovery: not applicable; the action is always available.
• Continuation: the Player places the first mark of the new round.

FR-7 — Turn and status visibility (required_inference) As a Player, I should always see whose turn it is and the current status, so that I know when to act.

• Trigger: any state change (placement, win, draw, new round).
• Observable result: the HUD strip shows the active mark with a colour crossfade during play, and a single mono status line on completion; the mono coordinate readout (A1–C3) and move count remain visible.
• Access: anonymous.
• Failure/recovery: not applicable.
• Continuation: the Player acts on the displayed state.

4. User Personas

Player

Product context. The Player is a casual visitor who opens cosmic-tic for a short, self-contained mental duel. They arrive anonymously on the single Tic Tac Toe page with no account, no history, and no expectation of anything beyond one round at a time. The same person typically plays both marks in alternating turns on one device.

Primary goal. Play a complete round of tic tac toe quickly — place marks, always know whose turn it is, and reach a clear win or draw — then start another round if they want.

Distinct accepted responsibilities.

• Choosing an empty cell and placing the active mark.
• Reading the turn indicator to know which mark moves next.
• Respecting occupied cells (the app enforces this; the Player simply picks another cell).
• Recognizing the win or draw outcome when it is announced.
• Starting a new round via NEW ROUND.

Relevant inputs and decisions. Which empty cell to select; when to start a new round. The Player makes no configuration choices — there are no settings, names, or modes.

Interactions with other accepted participants. The only other participant is the second mark played by the same person at the same device; there is no remote opponent, no system opponent, and no other persona. The app itself acts as referee: it alternates turns, blocks occupied cells, and declares the outcome.

Observable success. The board reflects each placement with a glowing mark, the turn indicator flips correctly, occupied cells reject input, and a win or draw is announced clearly with the winning line drawn or the draw status shown.

5. Core User Flows

Flow 1 — Play a round to a win

1. The Player opens cosmic-tic and lands on the Tic Tac Toe page (anonymous, no sign-in). The cosmic stage renders: oversized COSMIC-TIC wordmark, the floating glass 3×3 board, and the HUD strip showing X to move and move count 0.
2. The Player selects an empty cell. The cell fills with a cyan X that scales in with a light sweep and glow bloom; the turn indicator crossfades to magenta O; the move count increments to 1.
3. The Player selects another empty cell for O. A magenta O appears; the turn indicator crossfades back to X; the move count increments.
4. Steps 2–3 repeat with alternating marks. If the Player selects an occupied cell, nothing changes and they choose an empty cell instead.
5. On the placement that completes three matching marks in a row, column, or diagonal, the three winning cells pulse once and a luminous line draws across them in 500ms; the HUD strip switches to a single mono status line naming the winning mark.
6. Further cell selections are rejected. The Player presses NEW ROUND to continue, and the board clears with X to move.

Flow 2 — Play a round to a draw

1. The Player opens the Tic Tac Toe page and begins placing alternating marks as in Flow 1.
2. The Player fills cells until eight are marked with no winning line.
3. The Player places the ninth mark in the final empty cell. No winning line exists, so the HUD strip shows a draw status line and no luminous line is drawn.
4. Further cell selections are rejected. The Player presses NEW ROUND to play again.

Flow 3 — Start a new round mid-game

1. During an in-progress round on the Tic Tac Toe page, the Player decides to restart.
2. The Player presses the top-right NEW ROUND ghost chip.
3. The board clears to nine empty cells, X moves first, the move count resets to 0, and the wordmark hyphen pulses on game start.
4. The Player places the first mark of the new round.

6. Visuals Colors and Theme

Muse and headline. Gleb Kuznetsov — a luminous 3×3 constellation played in the void. Cinematic future-tech: dark, glowing, motion-first, HUD-like, with the grid kept dead simple to read and tap.

Mode. Dark mode only.

Colour tokens (exact hex by role)

• Background / void: #05060E (covers ~70% of the frame)
• Surface / glass panel: #0D1126
• Text (body and headings): #EAF2FF
• Primary (Player X, luminous strokes): #34E4FF
• Accent (Player O, luminous strokes): #FF3DCB
• Muted (uppercase micro-labels at 12px+ only, never paragraph text): #7C89B8
• Cell border: #34E4FF at 18% opacity, 1px

The two hot accents are the only saturated colour, used at mark scale and as thin luminous strokes. No violet-on-white or blue-on-white ground.

Typography

• Headings: Space Grotesk, 500–700 weight; uppercase for HUD labels with +0.18em tracking.
• Wordmark: COSMIC-TIC set very large and tight (-0.03em) with the hyphen as a glowing cyan rule.
• Body: Space Grotesk.
• Numerals, move counters, coordinates: JetBrains Mono.
• Scale: 1.25 modular with a display jump — wordmark clamp(48px, 9vw, 128px); headings and UI 40/28/20/16/14; 13px uppercase micro-labels at +0.18em; 12px mono for coordinates and move count.
• Forbidden for headings or body: Inter, Roboto, Arial, Helvetica, system-ui.

Shape language. Full-bleed void with floating glass panels: 20px radii, 1px luminous borders, thin radial glow behind the board, concentric orbit rings as hairline strokes. Marks are volumetric: X built from two beveled cyan strokes, O a glowing magenta torus. Hard-edged HUD tick marks and corner brackets frame the board like an instrument display.

Layout. Single page, one centred board column on desktop (board ~min(78vw, 520px)) with the title block stacked above and a HUD strip below showing turn/status in mono. On mobile the wordmark stacks to two lines above the board, the board fills width minus 24px gutters, and the HUD strip becomes a single row of two chips. No nav bar — a fixed top-left COSMIC-TIC micro-mark and a top-right NEW ROUND ghost button are the only chrome.

Imagery style. No photography. The imagery is the interface itself: a generative starfield of ~120 faint particles behind the board at 20% opacity, concentric orbital rings, a soft volumetric glow under the board, and glowing 3D-ish marks rendered in CSS with layered gradients and box-shadows (not WebGL).

Readability rule. Headlines, wordmarks, labels, numbers and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit; decoration and motion may bleed or overlap but never cover readable text or controls.

7. Signature Design Concept

The first screen is a dark cosmic stage, not a SaaS hero. The oversized COSMIC-TIC wordmark spans nearly the full viewport width in the upper third at clamp(48px, 9vw, 128px), its hyphen replaced by a glowing cyan rule that pulses on game start. Beneath it, offset slightly left, the 3×3 board floats as a 520px glass instrument panel lit from below by a cyan-to-magenta radial glow, ringed by two hairline orbit circles that slowly rotate. There is no subtitle paragraph, no solid CTA button, and no gradient blob — the board is the hero, and the only call to action is the small ghost NEW ROUND chip pinned top-right.

Signature moves, all recomposing accepted content only:

• The wordmark's glowing hyphen rule pulses on game start.
• The board carries corner HUD brackets and a mono coordinate readout (A1–C3) beneath it.
• Player identity is colour: X in electric cyan, O in magenta, each mark scaling in with a light sweep and bloom across its cell.
• The win state draws a luminous line across the three winning cells and pulses them once while the HUD strip switches to a single mono status line.
• Slow orbiting hairline rings and a faint particle field are the only ambient decoration, disabled under prefers-reduced-motion.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject. The 3×3 glass instrument panel floating in the void, lit from below by a cyan-to-magenta radial glow, ringed by two hairline orbit circles, beneath the oversized COSMIC-TIC wordmark.
• Input → transformation → outcome thesis. A cell selection (input) triggers a 220ms spring scale-in of the volumetric mark with a light sweep and glow bloom across the glass (transformation), and the turn indicator crossfades colour while the move count increments (outcome). A winning placement (input) pulses the three winning cells once and draws a luminous line across them in 500ms (transformation), and the HUD strip becomes a single mono status line (outcome).
• Motion vocabulary. Ambient slow orbit of the hairline rings; faint particle drift; light sweep across glass on each placement; 220ms spring mark scale-in with glow bloom; 500ms luminous win-line draw; colour crossfade on the turn indicator; hyphen rule pulse on game start. Motion stays precise and luminous — no bouncy or playful cartoon easing.
• Composed first frame. Void ground #05060E; wordmark spanning the upper third with its glowing cyan hyphen; board centred and offset slightly left as a #0D1126 glass panel with 1px #34E4FF-at-18% borders and corner brackets; two hairline orbit rings mid-rotation; starfield at 20% opacity; HUD strip below showing X to move and move count 0; ghost NEW ROUND chip top-right.
• Reduced-motion state. Static marks, no orbit, no sweep, no particle drift, instant state changes; the board, HUD, and NEW ROUND control remain fully usable and readable.

9. Non-Functional Requirements

• Single-page constraint (explicit): the product is delivered as exactly one page; no additional routes, navigation, or screens.
• Anonymous access (explicit via planning scope): the page is publicly reachable with no sign-in, account, or identity establishment.
• Responsive readability (explicit via creative direction): headlines, wordmarks, labels, numbers and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px; no element covers readable text or controls.
• Reduced motion (explicit via creative direction): under prefers-reduced-motion, all ambient and placement motion is disabled and state changes are instant, with a fully usable static arrangement.
• No WebGL dependency (explicit via creative direction): marks and glow are rendered in CSS with layered gradients and box-shadows; no heavy WebGL scene or shader dependency for a 9-cell game.
• Immediate playability (required_inference): the page requires no data fetch to begin a round; the board is interactive on first render.
• Input integrity (required_inference): occupied cells and post-completion cells reject placement without altering board state, turn, or move count.

10. Tech Stack

• Frontend: React application UI rendering the single Tic Tac Toe page, with CSS-rendered volumetric marks, glow, starfield and orbit rings.
• Backend: shared FastAPI process for application APIs and domain modules, hosting the game logic (turn alternation, occupied-cell prevention, win/draw detection).
• Database: MariaDB, provisioned as application-owned persistent storage. The accepted product has no accounts, saved history, or cross-session state, so no domain entities or persistence requirements are derived from its presence.
• Orchestration: docker-compose with the frontend, backend, and database services; the frontend depends on the backend gateway, and the backend depends on the database.

11. Assumptions and Constraints

• Assumption (required_inference): both marks (X and O) are played by people at the same device in alternating turns; there is no remote or computer opponent.
• Assumption (required_inference): X always moves first in a fresh round.
• Assumption (required_inference): the game state lives in the page session; refreshing the page starts a fresh round.
• Constraint (explicit): the app must be a single page.
• Constraint (explicit): no accounts, sign-in, or identity establishment.
• Constraint (explicit via creative direction): dark mode only; the forbidden indigo/blue-on-white SaaS template must not be used.
• Constraint (explicit via creative direction): Inter, Roboto, Arial, Helvetica and system-ui are forbidden for headings and body.

12. Glossary

• Round: one complete game of tic tac toe from empty board to win, draw, or restart.
• Cell: one of the nine positions on the 3×3 board, identified by coordinate A1–C3.
• Mark: a player's symbol on the board — X (electric cyan) or O (magenta).
• HUD strip: the mono status area below the board showing turn, move count, and outcome.
• Winning line: the luminous stroke drawn across three matching cells in a row, column, or diagonal.
• NEW ROUND: the top-right ghost chip that clears the board and starts a fresh round.
• Wordmark: the oversized COSMIC-TIC display type whose hyphen is a glowing cyan rule.