System Requirements Document for snake-game

1. Introduction

snake-game is a classic Snake game delivered as a single, self-contained browser experience. The product intent is narrow and complete: a person opens the game, starts a run, steers a snake around a grid, eats food to grow longer and score points, and sees the run end when the snake collides with a wall or with itself. The player can then start a new run and try to beat their previous score.

The audience is anyone who wants a five-minute arcade classic — people who remember Snake on a Nokia phone or grew up on modern browser games. The register is playful, nostalgic, and unpretentious: a game you open in a tab, play for a few minutes, and smile at. It must feel instantly legible (you know what is food, what is the snake, what is the score) and warmly crafted rather than slick or corporate.

There is no account, no sign-in, no backend service, and no marketing page. The game itself is the first and only screen.

2. System Overview

snake-game is a single-page, client-side browser game. The entire product is one playable surface — the Game page — which is also the public entry surface. The player lands directly on the game board, presses START, and plays.

The game runs entirely in the browser. The snake advances in discrete grid steps on a fixed square board; the player changes the snake's direction with the arrow keys (or the on-screen arrow legend on touch devices); eating the coral apple grows the snake by one tile and increments the score; the run ends on collision with a wall or with the snake's own body. The score and the best score achieved in the session are shown in a compact status bar above the board.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The product is a first-party, browser-delivered game with no server-side component and no external provider. All game logic, rendering, input handling, and score tracking happen in the client. There is no headless delivery, no provider-owned surface, and no external destination.

Access ownership. The Game page is publicly reachable with no identity requirement. There is no account, no login, no session continuity across visits, and no persisted profile. The high score is a session-scoped value shown in the status bar; it is not bound to any identity and does not require one.

Current vs. future boundary. Everything described in this document is current. No future capabilities have been accepted by the source. There is no leaderboard, no multiplayer, no level editor, no sound system, no difficulty selector, and no persistence layer in the current scope.

Exclusions. The following are explicitly out of scope for the current product: any blue or indigo in the palette; rounded corners, soft shadows, or glassmorphism; gradient blobs, glowing effects, or particle fields behind the board; photography or 3D renders; bouncy or springy easing; and a marketing landing page above the game.

2c. Page Content and Component Coverage

Game

The Game page is the single page of the product and the public entry surface. It is a single-column, centred composition on a warm paper ground. The game board is the hero; the title, status bar, controls, and legend support it.

Information and state

• Current score, displayed as SCORE 0000 with leading zeros preserved, in tabular Space Mono Bold.
• High score for the session, displayed as HIGH 0000 with leading zeros preserved, in tabular Space Mono Bold.
• Game state: idle (board empty, ready to start), running (snake moving, food present), paused (snake frozen, board visible), and game over (collision occurred, overlay shown).
• Snake position and length, food position, and the current tick interval (which shortens as the snake grows).

Primary actions

• START — begins a new run from the idle state. Chunky pixel button, 2px ink border, 3px offset shadow.
• PAUSE — freezes the running snake and resumes it. Same button treatment.
• RESTART — ends the current run and begins a fresh one. Same button treatment.
• Direction input — arrow keys on keyboard; the on-screen arrow-key legend indicates the mapping. Direction changes take effect on the next grid tick.

Supporting actions

• Reading the arrow-key legend to learn the controls.
• Reading the status bar to track score and high score during play.

Domain entities

• Snake — an ordered chain of 16×16 pixel tiles with a distinct head (two eyes and a tongue) and a body of green tiles.
• Food — a single 16×16 pixel coral apple placed on a grid cell not occupied by the snake.
• Board — a strict square grid, white surface with a 2px ink border and a 3px offset shadow, sized min(80vw, 80vh) capped at 640px.
• Score — an integer incremented by one each time the snake eats food.
• High score — the maximum score reached during the session.

Component responsibilities

• Title block — SNAKE in Press Start 2P, uppercase, ink black, centred, with a 4px coral underline spanning exactly the width of the word.
• Pixel-art divider — a row of alternating ink and coral squares separating the title from the game area.
• Status bar — two white panels with ink borders: score on the left, high score on the right, both with small-caps labels and tabular numerals.
• Game board — the primary visual; renders the grid, the snake, and the food.
• Control row — START, PAUSE, and RESTART buttons plus the arrow-key legend.
• Game-over overlay — appears after the board border blinks coral four times; shows the final score and offers a restart.

States

• Loading — not applicable; the game is client-side and renders immediately.
• Empty (idle) — the board shows an empty grid with no snake and no food; START is the available action.
• Success (running) — the snake moves in discrete grid steps, food is present, score and high score are live.
• Paused — the snake is frozen in place; PAUSE toggles back to running.
• Error / game over — the run ends on collision with a wall or with the snake's own body; the board border blinks coral four times, then the overlay appears.
• Recovery — RESTART (or the overlay's restart action) clears the board and begins a fresh run; the high score is retained for the session.

3. Functional Requirements

FR-1 — Start a new run (explicit) As a Player, I should be able to start a new run so that I can begin playing.

• Trigger: the player presses START from the idle state.
• Observable result: the board shows a snake and a piece of food, and the snake begins advancing in discrete grid steps.
• Access state: public, no identity required.
• Failure/recovery: if the game is already running, START does not begin a second run; the player uses RESTART to begin a fresh one.
• Continuation: the player steers the snake with the arrow keys.

FR-2 — Control the snake's direction (explicit) As a Player, I should be able to control the snake's direction so that I can steer it around the board.

• Trigger: the player presses an arrow key (or the corresponding on-screen control).
• Observable result: the snake's direction changes on the next grid tick; the snake does not reverse directly into itself.
• Access state: public, no identity required.
• Failure/recovery: an input that would reverse the snake into its own body is ignored.
• Continuation: the snake continues advancing in the new direction.

FR-3 — Eat food and grow (explicit) As a Player, I should be able to eat food so that the snake grows longer and my score increases.

• Trigger: the snake's head enters the grid cell occupied by the food.
• Observable result: the food icon plays a two-frame pixel pop, the score increments by one with a brief coral flash on the score number, the snake grows by one tile, and a new piece of food appears on an unoccupied cell.
• Access state: public, no identity required.
• Failure/recovery: if no unoccupied cell remains, the run ends as a win state.
• Continuation: the snake continues moving at a slightly shorter tick interval.

FR-4 — See the score (explicit) As a Player, I should be able to see my score so that I know how well I am doing in the current run.

• Trigger: the score changes when the snake eats food.
• Observable result: the status bar shows SCORE 0000 with leading zeros preserved, in tabular Space Mono Bold, with a coral flash on each point scored.
• Access state: public, no identity required.
• Failure/recovery: not applicable.
• Continuation: the score remains visible throughout the run.

FR-5 — See the high score (explicit) As a Player, I should be able to see the high score so that I know the best result of my session.

• Trigger: the current score exceeds the stored high score.
• Observable result: the status bar shows HIGH 0000 with leading zeros preserved, updated to the new best value.
• Access state: public, no identity required; the high score is session-scoped.
• Failure/recovery: not applicable.
• Continuation: the high score persists for the remainder of the session.

FR-6 — End the run on collision (explicit) As a Player, I should have the run end when the snake collides so that the game has a clear outcome.

• Trigger: the snake's head enters a wall cell or a cell occupied by the snake's own body.
• Observable result: the board border blinks coral four times, then the game-over overlay appears showing the final score.
• Access state: public, no identity required.
• Failure/recovery: the overlay offers a restart action.
• Continuation: the player restarts to begin a new run.

FR-7 — Pause and resume (required_inference) As a Player, I should be able to pause and resume so that I can step away without losing my run.

• Trigger: the player presses PAUSE while the game is running, or presses it again while paused.
• Observable result: the snake freezes in place while paused and resumes advancing when unpaused.
• Access state: public, no identity required.
• Failure/recovery: pausing is unavailable in the idle and game-over states.
• Continuation: the run continues from the same board state.

FR-8 — Restart a run (required_inference) As a Player, I should be able to restart so that I can begin a fresh run after a game over or mid-run.

• Trigger: the player presses RESTART, or uses the restart action on the game-over overlay.
• Observable result: the board clears, the score resets to zero, the snake and food are placed anew, and the run begins.
• Access state: public, no identity required.
• Failure/recovery: not applicable.
• Continuation: the high score is retained for the session.

4. User Personas

Player

Product context. The Player is the single active human role in snake-game. They arrive at the game directly — there is no sign-in, no onboarding, and no marketing page between them and the board. They may be on a desktop with a keyboard or on a touch device, and they expect to understand the game within seconds of it loading.

Primary goal. To steer the snake, eat food, grow longer, and achieve a high score in a run — then start a new run to try to beat it.

Distinct accepted responsibilities.

• Starting a new run from the idle state.
• Steering the snake with the arrow keys, reacting to its increasing length and the shortening tick interval.
• Reading the score and high score in the status bar during play.
• Pausing and resuming when they need to step away.
• Restarting after a collision to begin a fresh run.

Relevant inputs or decisions.

• Which direction to turn the snake on each grid tick.
• When to pause and when to resume.
• When to restart versus continue the current run.

Interactions with other accepted participants. None. The Player is the only accepted human participant; there is no opponent, no spectator, and no external service in the loop.

Observable success. The Player completes a run, sees a final score on the game-over overlay, and can immediately restart to try to beat their session high score.

What makes this role distinct. The Player's work is entirely reactive and continuous: they do not configure, submit, or manage anything — they steer a moving object in real time and respond to the consequences of their own prior inputs. Their success is measured by a single number that they are trying to beat.

5. Core User Flows

Flow 1 — Play a run from start to game over

1. The Player opens snake-game in a browser tab. The Game page loads directly: the title SNAKE sits above a pixel-art divider, the status bar reads SCORE 0000 and HIGH 0000, and the board shows an empty grid. Owner: Game page.
2. The Player presses START. The board places a snake and a coral apple, and the snake begins advancing in discrete grid steps. Owner: Game page.
3. The Player presses an arrow key to steer. The snake's direction changes on the next grid tick. Owner: Game page.
4. The snake's head enters the apple's cell. The apple plays a two-frame pixel pop, the score increments with a coral flash, the snake grows by one tile, and a new apple appears on an unoccupied cell. The tick interval shortens slightly. Owner: Game page.
5. The Player continues steering, reacting to the snake's increasing length and speed, and the score continues to rise. Owner: Game page.
6. The snake's head enters a wall cell or its own body. The board border blinks coral four times, then the game-over overlay appears showing the final score. Owner: Game page.
7. The Player presses the overlay's restart action. The board clears, the score resets to zero, the high score is retained, and a new run begins. Owner: Game page.

Failure and recovery. If the Player makes a wrong turn and collides, the run ends cleanly with the game-over overlay and a restart action — no state is lost beyond the current run's score, and the session high score is preserved.

Continuation. The Player can restart repeatedly within the same session, each time trying to beat the high score shown in the status bar.

Flow 2 — Pause and resume mid-run

1. The Player is mid-run with the snake moving. Owner: Game page.
2. The Player presses PAUSE. The snake freezes in place; the board remains visible with the current snake and food positions. Owner: Game page.
3. The Player steps away and returns. Owner: Game page.
4. The Player presses PAUSE again. The snake resumes advancing from the same board state. Owner: Game page.

Failure and recovery. If the Player presses PAUSE while the game is idle or over, nothing happens; the control is unavailable in those states.

Continuation. The run continues from exactly where it was paused.

Flow 3 — Restart mid-run

1. The Player is mid-run and decides to start over. Owner: Game page.
2. The Player presses RESTART. The board clears, the score resets to zero, the snake and food are placed anew, and the run begins. Owner: Game page.

Failure and recovery. Not applicable; restart is always available during a run.

Continuation. The high score is retained, and the Player continues playing the new run.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. The muse is Susan Kare, and the headline is "Charming clarity, one pixel at a time — a snake game with the warmth of the original Macintosh." The direction is translated into concrete tokens below.

Color tokens (light mode)

No blue anywhere. Colours are flat and unshaded, like a 1-bit palette extended by exactly two hues.

Typography

• Headings: Press Start 2P, used at display sizes only, uppercase, tight leading, generous letter-spacing. Headlines are short (one to four words) and treated as objects, not sentences.
• Body: Space Mono.
• Scale: 1.25 modular — 64 / 48 / 32 / 20 / 16 px.
• Title: Press Start 2P at 64px mobile → 96px desktop.
• Body, labels, score numbers: Space Mono at 16px.
• Score numerals: Space Mono Bold at 32–48px, tabular.

Shape language

Hard pixel edges everywhere — no border-radius. The game board is a strict square grid. Buttons are chunky rectangles with a 2px ink border and a 3px offset shadow (like a pressed key). Panels are white rectangles with 2px ink borders. The only softness is the warm off-white ground. Pixel icons are drawn on an 8×8 or 16×16 grid: apple, snake head, trophy, arrow keys.

Layout

Single-column, centred composition on a warm paper ground. The game board is the hero: a large square (min(80vw, 80vh) capped at 640px) centred on the page, with a 2px ink border and a 3px offset shadow. Above it, a compact status bar: score on the left (label in small caps, number in tabular mono), high score on the right, both in white panels with ink borders. Below it, a row of chunky pixel buttons: START / PAUSE / RESTART, plus a small arrow-key legend.

• Mobile (375px): the board scales to fit width with 16px margins; the status bar stacks into two rows; buttons wrap into two columns.
• Tablet (768px): keep single column, just larger — board and status bar do not sit side by side.
• Desktop (1280px): the board is capped at 640px with generous whitespace; the title sits above it in a single line.

Imagery

Pixel icons and simple pictograms only — no photography, no illustration for its own sake. The snake is a chain of 16×16 pixel tiles with a distinct head (two eyes, a tongue). The food is a single 16×16 pixel apple in coral. The trophy for high score is a 16×16 pixel cup. Decorative elements are limited to a small pixel-art divider (a row of alternating ink and coral squares) between sections. The game board itself is the primary visual.

7. Signature Design Concept

The board is the hero. The first screen is the game itself, not a marketing page. A warm off-white ground (#F4F1E8) fills the viewport. At the top, the game title SNAKE is set in Press Start 2P at 64px mobile → 96px desktop, ink black, uppercase, centred, with a 4px coral underline that spans exactly the width of the word. Directly below, a thin ink rule and a pixel-art divider — a row of alternating ink and coral squares — separate the title from the game area.

The game board — a large white square with a 2px ink border and a 3px offset shadow — dominates the centre, showing the snake (green tiles), the food (coral apple), and an empty grid ready to play. Above the board, a compact status bar with two white panels: SCORE 0000 on the left, HIGH 0000 on the right, both in Space Mono with small-caps labels. Below the board, three chunky pixel buttons (START, PAUSE, RESTART) in a row, each with a 2px ink border and 3px offset shadow. To the right of the status bar, a small pixel-art legend shows the arrow keys.

The composition is centred, symmetrical, and feels like a beautifully crafted little machine — not a SaaS hero. The signature moves are: the board as hero; pixel-art snake and food drawn on the same grid as the play area; chunky pressed-key buttons whose offset shadow collapses and which shift 3px down-right on press; score as ornament with leading zeros preserved and a coral flash on every point; and the pixel-art divider echoing the original Macintosh's love of small, legible symbols.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

Focal subject. The game board itself — a large white square with a 2px ink border and a 3px offset shadow, centred on the warm paper ground, showing the snake (green tiles), the food (coral apple), and an empty grid ready to play.

Input → transformation → outcome thesis. The player presses START → the board places a snake and a coral apple and the snake begins advancing in discrete grid steps → the player steers, eats food, grows, and scores until a collision ends the run and the game-over overlay appears. The hero is not an animation; it is the playable board, and its motion is the game's motion.

Motion vocabulary. Frame-by-frame, mechanical, no easing theatrics. The snake moves in discrete grid steps (a tick every ~120ms, accelerating as it grows). Eating food triggers a two-frame pixel pop on the food icon and a brief score-number flash. Game over is a four-frame blink of the board border in coral, then the overlay appears. Buttons have a press-down effect: the offset shadow collapses to 0 and the button shifts 3px down-right. No fades, no springs, no particles.

Composed first frame. The viewport is filled with #F4F1E8. The title SNAKE sits centred at the top in Press Start 2P with a 4px coral underline. A thin ink rule and a pixel-art divider separate it from the game area. The board — white, 2px ink border, 3px offset shadow — dominates the centre with an empty grid. The status bar reads SCORE 0000 and HIGH 0000. The START, PAUSE, and RESTART buttons sit below the board, and the arrow-key legend sits to the right of the status bar.

Reduced-motion state. With prefers-reduced-motion, the border blink and score flash are removed; only the discrete grid movement remains. The board, status bar, buttons, and legend are unchanged and fully usable.

9. Non-Functional Requirements

NFR-1 — Client-side delivery (explicit) The game runs entirely in the browser with no server-side component, no backend service, and no external provider. All game logic, rendering, input handling, and score tracking happen in the client.

NFR-2 — Public access (explicit) The Game page is publicly reachable with no identity requirement. There is no account, no login, and no session continuity across visits.

NFR-3 — Responsive legibility (explicit) Readable text and controls stay whole at every viewport. Headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them.

NFR-4 — Reduced motion (explicit) With prefers-reduced-motion, the border blink and score flash are removed, keeping only the discrete grid movement. A usable static arrangement is provided.

NFR-5 — Palette constraint (explicit) No blue or indigo anywhere in the palette. The palette is green and coral on warm paper.

NFR-6 — Shape constraint (explicit) No rounded corners, soft shadows, or glassmorphism. Everything is hard-edged and flat.

NFR-7 — Typography constraint (explicit) No Inter, Roboto, Arial, Helvetica, or system-ui. The pixel and mono faces are the voice.

NFR-8 — Imagery constraint (explicit) No photography or 3D renders. The imagery is pixel icons only.

NFR-9 — Motion constraint (explicit) No bouncy or springy easing. Motion is discrete and mechanical.

NFR-10 — No marketing page (explicit) There is no marketing landing page above the game. The game is the first screen.

10. Tech Stack

• Frontend: React (single-page application).
• Styling: CSS with the palette, typography, and shape tokens defined in Section 6.
• Game logic: Client-side JavaScript/TypeScript running in the browser; no backend service.
• Storage: None. The high score is session-scoped and held in memory.
• Deployment: Static hosting of the built frontend. No Docker, no Kubernetes, and no server-side runtime are required for the current product.

11. Assumptions and Constraints

Assumptions

• The game is played in a modern browser with keyboard input available; touch devices use the on-screen arrow-key legend.
• The high score is session-scoped and is not persisted across page reloads or visits.
• The board is a fixed square grid; the grid dimensions are not user-configurable.
• The tick interval starts at approximately 120ms and shortens as the snake grows.

Constraints

• The palette, typography, shape language, layout, motion, and imagery constraints in Sections 6 and 9 are binding.
• The Game page is the only page; no additional pages, routes, or destinations are in scope.
• No account, login, or identity system is in scope.
• No backend service, database, or external provider is in scope.

12. Glossary

• Board — the square grid on which the snake moves, rendered as a white square with a 2px ink border and a 3px offset shadow.
• Food — a single 16×16 pixel coral apple placed on a grid cell not occupied by the snake; eating it grows the snake and increments the score.
• Game over — the state reached when the snake's head collides with a wall or with the snake's own body.
• High score — the maximum score reached during the current session, shown in the status bar as HIGH 0000.
• Run — a single play session from START to game over.
• Score — an integer incremented by one each time the snake eats food, shown in the status bar as SCORE 0000.
• Snake — the player-controlled chain of 16×16 pixel tiles with a distinct head (two eyes and a tongue) and a body of green tiles.
• Tick — one discrete grid step of the snake's movement, occurring at a fixed interval that shortens as the snake grows.