System Requirements Document for html-game

1. Introduction

html-game is a small, fast HTML game that runs in the browser. The product intent is a lightweight, instantly playable arcade/reflex experience that loads quickly, runs smoothly, and gives a casual anonymous visitor something delightful to poke within seconds. The specific game type was left open by the user ("just random one"), so the builder has chosen a simple arcade/reflex-style browser game — a pickup/collect arcade game titled PICKUP — where the player moves a chunky coral capsule around a cream playfield to collect mint targets while avoiding hazards.

The audience is a single active human role: the Player — a casual, anonymous visitor who arrives with zero context, wants to be playing within about two seconds, and measures success in "one more go" rather than in comprehension. There is no account, no setup, no onboarding flow, and no marketing surface. The game is the page.

2. System Overview

html-game is delivered as a single-page browser experience built from HTML, CSS, and JavaScript. It has two cohesive destinations:

• Landing — the anonymous first-impression surface: a full-viewport playfield already animating behind a translucent overlay card that names the game, states the rules in one sentence, and offers a single PLAY capsule.
• Game — the cohesive play workspace: starting a session, responsive play, immediate physical feedback, game-over/end-of-round state, and restarting.

Both destinations are owned by the application and require no identity, no login, and no persistence. The Player is anonymous throughout. There is no backend, no database, no provider-owned surface, and no external destination required for current scope.

Actors:

• Player (active human, sole persona) — opens the game in a browser and plays.
• Browser runtime (non-persona system actor) — renders the canvas/DOM, runs the game loop, and handles input events.

Accepted behavior: a small, fast, browser-playable arcade game with a landing overlay that dissolves into an already-running playfield, responsive physics-driven play, immediate score feedback, a game-over state, and restart.

Narrow exclusions: no accounts, no login, no persistence, no leaderboards, no multiplayer, no separate "how to play" page, no multi-step onboarding, no loading spinners or asset preloaders before play, no photographic or stock imagery, no marketing hero/feature grid/footer.

2a. Product Interpretation and Delivery Boundary

The product is a self-contained, first-party browser game. Delivery is headless of any server: the entire experience is client-side HTML/CSS/JavaScript, so there is no provider-owned surface, no external destination, and no backend responsibility in current scope. Access is anonymous and public — the Player never establishes identity, and no durable actor-specific state is created or resumed, so application-owned identity is neither required nor inferred.

The current horizon covers the Landing and Game destinations and the play lifecycle they support. Future ideas (for example, persistent best-score storage across sessions, additional game modes, or shareable results) are explicitly out of current scope and are listed only in the future section; they must not appear in current pages or acceptance criteria.

2b. Source Content Inventory

Not applicable — no reference directive in this project declares content_source.

2c. Page Content and Component Coverage

Landing

• Information / state: the game title PICKUP, a one-sentence rules statement, and a single PLAY call to action, presented over a full-viewport playfield that is already animating behind the overlay. The HUD rail (score left, best right, mute far right) is visible in the world beneath the overlay.
• Primary action: press the PLAY capsule.
• Supporting actions: toggle mute via the HUD mute control; observe the idle floating loop of the playfield.
• Domain entities: Playfield, Player object (chunky coral capsule), Target cluster (mint), Hazard, Score, Best score, Mute state.
• Component responsibilities:
  • Playfield panel — full-viewport cream field with a hard-edged coral ground band along the bottom third; hosts the already-running scene.
  • Title object — "PICKUP" set at 72px Fredoka SemiBold with a 3px ink outline and a 6px coral offset shadow, overlapping the top-left corner of the playfield and partially cropped by the viewport edge.
  • Overlay card — translucent card holding the title, one sentence of rules, and the PLAY capsule; dissolves on press rather than navigating.
  • PLAY capsule — capsule button cut into the coral ground band as a physical hole; depresses 4px on press with a shadow that shortens in the same frame.
  • HUD rail — thin top rail with score (left), best (right), and mute (far right).
  • Floating label card — lower-left card naming the game.
• States:
  • Loading: none — no spinner or preloader; the scene renders immediately.
  • Empty: not applicable — the playfield is always populated with the idle floating loop.
  • Success: pressing PLAY dissolves the overlay and the world is already running underneath; the Player is in the Game state with zero load-to-play gap.
  • Error / recovery: if the browser cannot run the game loop, the overlay remains and the PLAY capsule stays available for retry; no error page is introduced.

Game

• Information / state: live score, best score for the session, mute state, current player position, active targets, active hazards, and game-over/end-of-round state.
• Primary actions: move the player object to collect targets; avoid hazards; restart after game over.
• Supporting actions: toggle mute; observe floating "+1" score feedback; observe screen-shake and desaturating flash on misses.
• Domain entities: Player object, Target, Hazard, Score, Best score, Round, Mute state.
• Component responsibilities:
  • Playfield — the game world; flat colour-blocked zones with hard edges and soft offset shadows.
  • Player object — chunky coral capsule with ink outline and visible contact shadow, roughly 1/12 of viewport width; accelerates and eases with real damping.
  • Target cluster — mint low-poly shapes that squash on pickup and pop with a 120ms scale-overshoot.
  • Hazard — mint-marked hazard states that trigger a 4px/90ms screen-shake and a desaturating flash on miss.
  • Score readout — Fredoka Medium with tabular figures at 32px so the score does not jitter; each pickup spawns a floating "+1" numeral in Fredoka that arcs up and fades.
  • HUD rail — score left, best right, mute far right.
  • Restart control — capsule button that depresses 4px on press, available in the game-over state.
• States:
  • Loading: none — the game loop starts immediately.
  • Empty: not applicable — targets and hazards are always present during a round.
  • Success: target collected → squash, pop with 120ms scale-overshoot, floating "+1" arcs up and fades, score increments, best score updates if exceeded.
  • Error / recovery: miss → 4px/90ms screen-shake and desaturating flash; round ends → game-over state with final score and a restart capsule; pressing restart begins a new round immediately.
  • Continuation: after restart, the Player is back in active play with the same controls and feedback.

3. Functional Requirements

FR-1 — Small, fast HTML game (explicit) As a Player, I should be able to open a small, fast HTML game in my browser and be playing within about two seconds, so that I get immediate lightweight play with no setup.

• Actor: Player
• Trigger / input: opening the game URL in a browser.
• Observable result: the playfield renders and animates immediately; no spinner, preloader, or onboarding step appears.
• Access state: anonymous, public.
• Failure / recovery: if the browser cannot run the game loop, the Landing overlay remains with the PLAY capsule available for retry.
• Continuation: the Player proceeds to press PLAY and enter active play.

FR-2 — Randomly chosen arcade/reflex game (explicit) As a Player, I should be able to play a simple arcade/reflex-style browser game (the specific type left to the builder's choice), so that I get a delightful, momentum-driven toy rather than a product to evaluate.

• Actor: Player
• Trigger / input: pressing PLAY on the Landing overlay.
• Observable result: the overlay dissolves and the already-running playfield becomes the active game.
• Access state: anonymous, public.
• Failure / recovery: if the overlay does not dissolve, the PLAY capsule remains pressable.
• Continuation: the Player is in active play with responsive controls.

FR-3 — Start a session from the Landing overlay (required_inference) As a Player, I should be able to press a single PLAY capsule on the Landing overlay to start a session, so that the CTA never navigates and there is zero load-to-play gap.

• Actor: Player
• Trigger / input: pressing the PLAY capsule.
• Observable result: the overlay card dissolves; the world is already running underneath.
• Access state: anonymous, public.
• Failure / recovery: if the press is not registered, the capsule remains available.
• Continuation: the Player is in the Game state.

FR-4 — Responsive physics-driven play (required_inference) As a Player, I should be able to move the player object around the playfield with responsive, physics-driven motion, so that every interaction has a springy, physical answer.

• Actor: Player
• Trigger / input: keyboard or pointer input.
• Observable result: the player object accelerates and eases with real damping; hover states scale 1.04 with a 140ms spring; nothing uses linear easing.
• Access state: anonymous, public.
• Failure / recovery: if input is lost, the idle floating loop keeps the scene from looking frozen.
• Continuation: the Player continues collecting targets and avoiding hazards.

FR-5 — Collect targets with immediate feedback (required_inference) As a Player, I should be able to collect mint targets and see immediate physical feedback, so that the score readout lives in the world and the feedback is physical.

• Actor: Player
• Trigger / input: moving the player object into a target.
• Observable result: the target squashes on pickup and pops with a 120ms scale-overshoot; a floating "+1" numeral in Fredoka arcs up and fades; the score increments; the best score updates if exceeded.
• Access state: anonymous, public.
• Failure / recovery: if a target is missed, the miss feedback (screen-shake and desaturating flash) plays instead.
• Continuation: the Player continues play with the updated score.

FR-6 — Miss feedback and recovery (required_inference) As a Player, I should be able to see a short screen-shake and a desaturating flash when I miss, so that misses are legible and the round continues.

• Actor: Player
• Trigger / input: missing a target or hitting a hazard.
• Observable result: a 4px, 90ms screen-shake and a desaturating flash.
• Access state: anonymous, public.
• Failure / recovery: the round continues unless the miss ends the round.
• Continuation: the Player keeps playing or reaches the game-over state.

FR-7 — Game-over / end-of-round state and restart (required_inference) As a Player, I should be able to see a game-over/end-of-round state with my final score and restart with a single capsule press, so that I can go again immediately.

• Actor: Player
• Trigger / input: the round ending; pressing the restart capsule.
• Observable result: the game-over state shows the final score; pressing restart begins a new round immediately with the same controls and feedback.
• Access state: anonymous, public.
• Failure / recovery: if restart is not registered, the restart capsule remains available.
• Continuation: the Player is back in active play.

FR-8 — Mute control (required_inference) As a Player, I should be able to toggle mute from the HUD rail, so that I can control the game's audio without leaving the playfield.

• Actor: Player
• Trigger / input: pressing the mute control in the HUD rail (far right).
• Observable result: the mute state toggles and is reflected in the HUD.
• Access state: anonymous, public.
• Failure / recovery: if the toggle fails, the previous mute state remains.
• Continuation: the Player continues play with the chosen mute state.

4. User Personas

Player

• Product context: a casual, anonymous visitor who arrives at html-game with zero context. They did not search for a specific game; they were handed a small, fast HTML game and want to be playing within about two seconds. They are on a browser, likely on a desktop or laptop, and they will leave immediately if anything asks them to set up, sign in, or wait.
• Primary goal: immediate, lightweight play — a quick, responsive session that starts fast and runs smoothly, with a bit of silliness and momentum.
• Distinct accepted responsibilities: pressing PLAY on the Landing overlay; moving the player object to collect targets; avoiding hazards; reading the in-world score feedback; toggling mute; restarting after game over.
• Relevant inputs or decisions: whether to press PLAY; how to move the player object; whether to keep going after a miss; whether to restart after game over; whether to mute.
• Interactions with other accepted participants: none — the Player is the sole active human role. The browser runtime is a non-persona system actor that renders the scene and runs the game loop.
• Observable success: the playfield is already animating on arrival; pressing PLAY dissolves the overlay with zero load-to-play gap; targets squash and pop with a floating "+1"; misses produce a short screen-shake and desaturating flash; the game-over state shows the final score and a restart capsule; the Player goes again.

What makes the Player's work different from a generic "user": there is no account, no setup, no comprehension task, and no evaluation. The Player's entire relationship with the product is tactile — they poke the toy, learn the rules by touching things, and measure success in "one more go."

5. Core User Flows

Flow 1 — First arrival and immediate play

1. The Player opens the html-game URL in a browser.
2. The Landing page renders: a full-viewport cream playfield with a hard-edged coral ground band along the bottom third, a mint target cluster floating above it, and the player object (a chunky coral capsule) positioned left-of-centre. The scene is already animating behind a translucent overlay card.
3. The overlay card shows the title PICKUP (72px Fredoka SemiBold, 3px ink outline, 6px coral offset shadow, overlapping the top-left corner and partially cropped by the viewport edge), one sentence of rules, and a single PLAY capsule cut into the coral ground band as a physical hole.
4. The Player presses the PLAY capsule. The capsule depresses 4px with a shadow that shortens in the same frame.
5. The overlay card dissolves; the world is already running underneath. There is zero load-to-play gap.
6. The Player is now in the Game page in active play.

Flow 2 — Active play, collection, and miss recovery

1. From the Game page, the Player moves the player object around the playfield using keyboard or pointer input.
2. The player object accelerates and eases with real damping; hover states scale 1.04 with a 140ms spring; nothing uses linear easing.
3. The Player moves the player object into a mint target. The target squashes on pickup and pops with a 120ms scale-overshoot; a floating "+1" numeral in Fredoka arcs up and fades; the score increments; the best score updates if exceeded.
4. The Player misses a target or hits a hazard. A 4px, 90ms screen-shake and a desaturating flash play.
5. The round continues unless the miss ends the round. The Player keeps playing with the updated score.
6. If the Player wants to silence the game, they press the mute control in the HUD rail (far right); the mute state toggles and is reflected in the HUD.

Flow 3 — Game over and restart

1. The round ends on the Game page.
2. The game-over/end-of-round state appears with the Player's final score.
3. A restart capsule is available; the Player presses it. The capsule depresses 4px with a shadow that shortens in the same frame.
4. A new round begins immediately with the same controls and feedback.
5. The Player is back in active play, going again.

6. Visuals Colors and Theme

The creative direction is authoritative for this section. The muse is Bruno Simon; the headline is "Playable toy-box physics" — a tiny, instant-load browser arcade game whose first screen is already the toy.

Colour tokens (light mode):

Colour blocking, not gradients: each zone of the playfield is a flat field with a hard edge and a soft drop shadow.

Typography:

• Headings: Fredoka — Fredoka SemiBold at very large sizes, tight tracking (-0.02em), sentence case, never all-caps. The game title is set as a physical object with a 3px ink outline and a 6px coral offset shadow rather than as plain text.
• Body: Nunito.
• Numeric HUD readouts: Fredoka Medium with tabular figures so the score does not jitter.
• Scale: 1.333 modular — 72 / 48 / 32 / 24 / 18 / 16. HUD numerals at 32; body never below 16 for readability on the cream ground.

Shape language: Toy-box geometry — low-poly forms with 2–3 visible facets, capsules and rounded blocks with 20–28px radii, every element wrapped in a 3px ink outline, and soft offset shadows (0 6px 0 rgba(32,33,58,.18)) that make pieces look like they can be picked up. Buttons are capsules that physically depress 4px on press, not fade on hover.

Layout: The game IS the page — a full-viewport playfield panel with a thin HUD rail across the top (score left, best right, mute far right) and a single floating label card in the lower-left naming the game. No marketing hero, no feature grid, no footer. The landing state is the same viewport with a translucent overlay card holding the title, one sentence of rules, and a single PLAY capsule — pressing it dissolves the card and the world is already running underneath.

Imagery: No photography, no stock art. Everything is drawn in code: flat low-poly shapes with two-tone facet shading, a soft circular ground shadow under each object, and a few procedural confetti particles on score events. The "art" is the geometry and the colour blocking itself.

Avoid: centred headline + subtext + button stacked in the middle of the viewport; any blue/indigo primary or gradient-blob background; Inter, Roboto, Arial, Poppins, or system-ui for any text; a grid of identical hover-lift feature cards; loading spinners or asset preloaders before play can begin; photographic or stock imagery of any kind; soft blurred shadows and glassmorphism panels; a separate "how to play" page or multi-step onboarding. The generic indigo/blue-on-white SaaS template is forbidden for this project.

7. Signature Design Concept

The hero is the game, not a picture of the game.

The public entry (Landing) is a full-bleed cream playfield with a hard-edged coral ground band along the bottom third and a mint target cluster floating above it. The player object is a chunky coral capsule with an ink outline and a visible contact shadow, roughly 1/12 of the viewport width, positioned left-of-centre so the composition reads as "something is about to happen moving right." The title PICKUP is set at 72px Fredoka with an ink outline and coral offset shadow, overlapping the top-left corner of the playfield and partially cropped by the viewport edge — a poster gesture, not a centred SaaS headline. A single capsule PLAY button is cut into the coral ground band as a physical hole rather than sitting on top of it. The scene is already animating behind the overlay, so the hero is the game, not a picture of the game.

Signature moves:

• Landing overlay dissolves into an already-running playfield — the CTA never navigates, it just gets out of the way, so there is zero load-to-play gap.
• Every shape is wrapped in a 3px ink outline with a hard offset shadow, giving the whole game a printed-sticker feel that survives at any viewport size.
• The score readout lives in the world: each pickup spawns a floating "+1" numeral in Fredoka that arcs up and fades, so the HUD is decoration and the feedback is physical.
• Buttons depress 4px on press with a shadow that shortens in the same frame — a tactile, non-fading interaction that no template ships.
• The title is cropped by the viewport edge and overlaps the playfield band, so the first screen reads as a poster rather than a centred hero.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the chunky coral player capsule positioned left-of-centre on the cream playfield, with the mint target cluster floating above the coral ground band.
• Input → transformation → outcome thesis: the Player presses the PLAY capsule → the capsule depresses 4px with a shadow that shortens in the same frame, and the translucent overlay card dissolves → the already-running playfield becomes the active game with zero load-to-play gap.
• Motion vocabulary: physics-driven and springy — the player object accelerates and eases with real damping; collectibles squash on pickup and pop with a 120ms scale-overshoot; misses send a short screen-shake (4px, 90ms) and a desaturating flash; hover states scale 1.04 with a 140ms spring; nothing uses linear easing; the idle state keeps one gentle floating loop so the scene never looks frozen.
• Composed first frame: full-bleed cream playfield; hard-edged coral ground band along the bottom third; mint target cluster floating above it; chunky coral capsule player object left-of-centre with an ink outline and visible contact shadow; title PICKUP at 72px Fredoka with ink outline and coral offset shadow, overlapping the top-left corner and partially cropped by the viewport edge; a single capsule PLAY button cut into the coral ground band as a physical hole; the scene already animating behind the overlay.
• Reduced-motion state: when the Player has requested reduced motion, the idle floating loop and the springy hover scale are suppressed; the overlay still dissolves on PLAY, the score still increments, and the "+1" feedback still appears, but without the scale-overshoot, screen-shake, or desaturating flash. The playfield remains fully playable and legible.

9. Non-Functional Requirements

NFR-1 — Small and fast (explicit) The game must be small and fast: lightweight, quick to load, and quick to run. Rationale: explicit hard constraint in the authoritative user evidence. Acceptance: the playfield renders and animates immediately on arrival; no spinner, preloader, or onboarding step appears before play.

NFR-2 — Browser-playable HTML delivery (explicit) The game must be delivered as HTML playable in a browser. Rationale: explicit hard constraint in the authoritative user evidence. Acceptance: the game runs in a standard browser with no install step.

NFR-3 — Responsive input latency (required_inference) Player input must produce visible motion within the same frame or the next, so that the game feels responsive. Rationale: indispensable to the accepted "responsive play" and "immediate feedback" behavior. Acceptance: the player object responds to input without perceptible lag.

NFR-4 — Readability on the cream ground (required_inference) Body text must never fall below 16px, and HUD numerals must use tabular figures at 32px so the score does not jitter. Rationale: indispensable to the accepted visual direction and to legibility on the warm pastel-cream ground. Acceptance: all body text is at least 16px; the score readout does not shift horizontally as digits change.

NFR-5 — No pre-play loading (explicit) No loading spinners or asset preloaders may appear before play can begin. Rationale: explicit exclusion in the creative direction. Acceptance: the playfield is animating on first paint.

10. Tech Stack

• HTML, CSS, and JavaScript — the game is delivered as HTML playable in a browser (explicit constraint). The playfield, player object, targets, hazards, and confetti are drawn in code; no photographic or stock assets are used.
• Canvas or DOM rendering — the game loop and physics-driven motion run client-side. No backend, database, or server-side rendering is required for current scope.
• Fredoka and Nunito — loaded as web fonts for headings and body respectively, per the creative direction.
• No framework requirement — the game is small and fast; a lightweight vanilla implementation is sufficient and consistent with the explicit "small and fast" constraint.

11. Assumptions and Constraints

Assumptions:

• The Player is anonymous and public; no account, login, or persistence is required or inferred. (required_inference — no durable actor-specific state is created or resumed.)
• The specific game type is left to the builder's choice ("just random one"); a simple arcade/reflex-style browser game is acceptable. (explicit)
• The Player has a standard browser with keyboard or pointer input available. (required_inference)
• The game is a single-page experience with two cohesive destinations (Landing and Game) and no separate "how to play" page or multi-step onboarding. (explicit exclusion)

Constraints:

• The game must be small and fast — lightweight, quick to load and run. (explicit)
• The game must be delivered as HTML playable in a browser. (explicit)
• No loading spinners or asset preloaders before play can begin. (explicit)
• No photographic or stock imagery of any kind. (explicit)
• No blue/indigo primary or gradient-blob background; the generic indigo/blue-on-white SaaS template is forbidden. (explicit)
• No Inter, Roboto, Arial, Poppins, or system-ui for any text. (explicit)
• No centred headline + subtext + button stacked in the middle of the viewport. (explicit)
• No grid of identical hover-lift feature cards. (explicit)
• No soft blurred shadows or glassmorphism panels. (explicit)
• No separate "how to play" page or multi-step onboarding. (explicit)

Future (not in current scope):

• Persistent best-score storage across sessions.
• Additional game modes or game types.
• Shareable results or leaderboards.
• Multiplayer or social features.

12. Glossary

• Player — the sole active human persona; an anonymous casual visitor who plays the game in a browser.
• Playfield — the full-viewport game world; a cream field with a hard-edged coral ground band along the bottom third.
• Player object — the chunky coral capsule the Player moves around the playfield; roughly 1/12 of the viewport width, with an ink outline and a visible contact shadow.
• Target — a mint low-poly collectible that squashes on pickup and pops with a 120ms scale-overshoot.
• Hazard — a mint-marked element that triggers a 4px/90ms screen-shake and a desaturating flash on miss.
• HUD rail — the thin top rail with score (left), best (right), and mute (far right).
• Round — a single play session from PLAY to game over.
• Game-over state — the end-of-round state showing the final score and a restart capsule.
• Overlay card — the translucent Landing card holding the title, one sentence of rules, and the PLAY capsule; it dissolves on press rather than navigating.
• Ink outline — the 3px #20213A outline wrapped around every shape.
• Offset shadow — the soft 0 6px 0 rgba(32,33,58,.18) shadow that makes pieces look like they can be picked up.