System Requirements Document for windy-hey

1. Introduction

windy-hey is a browser-based game centered around Nigeria. It is a warm, story-led, single-player quiz experience about Nigerian people, places, objects and culture — a game that reads like a well-set essay with a deck of cards you can play. The product intent is to give anyone curious about Nigeria an inviting, humane, replayable way to encounter the country one question at a time, with no download and no sign-up.

The audience is casual browsers of all ages who want something warm and literary rather than a neon arcade: people who will land on a public page, understand in a few seconds what the game is, and begin playing immediately.

This document is the System Requirements Document for windy-hey. It specifies the two current destinations (Landing and Play), the single active human persona (Player), the game's lifecycle from public entry through a win or loss outcome to replay, and the visual and interaction direction that governs how the game looks and feels.

2. System Overview

windy-hey is delivered as a first-party web application with two current, anonymously reachable destinations:

• Landing — the public entry surface. It explains the Nigeria-centered game, its audience and how to begin, and offers the Begin action.
• Play — owns starting a game session, presenting Nigeria-themed questions with answer choices, tracking score and streak, reaching a win or loss outcome, and restarting or playing again.

There is exactly one active human actor: the Player. No other human personas participate. There is no account, no sign-in, no download, and no provider-owned or external-destination surface in the current scope. All game state for a session is owned by the application and lives for the duration of that session; nothing durable is required to persist across visits.

The game is centered around Nigeria as an explicit hard constraint: its questions, its imagery (talking drum, kola nut, Lagos danfo bus, baobab silhouette, jollof, Nollywood clapperboard, calabash) and its voice all derive from Nigerian content.

Removed from scope

• Contact-download permission revocation and third-party access management (also: permissions, information access) — this was a general question asked before the game request and is not part of the windy-hey product.
• Credits, credit balances, and live web search (also: web search, credits) — these were questions about the assistant, not product requirements.

2a. Product Interpretation and Delivery Boundary

windy-hey is a self-contained, first-party browser game. Both current destinations are public and anonymous: a visitor can read the Landing page and start playing without establishing any identity, and the Play page never requires a sign-in. Because no accepted behavior creates a durable relationship, entitlement, value transfer or commitment that must remain bound to a returning participant, the product deliberately owns no application identity, no accounts and no cross-visit persistence.

The current delivery boundary is the two pages above and the in-session game loop they contain. Everything a player does — reading the Landing page, beginning a session, answering questions, seeing score and streak, reaching a verdict, and playing again — happens inside that boundary. There is no future-horizon feature set defined by the source; the only forward-looking note is that the game should remain replayable within a visit.

2c. Page Content and Component Coverage

Landing

Information and state

• Full-width cream field carrying the display headline "A game about Nigeria, one question at a time" in Literata, flush-left, spanning a 9-column measure on desktop and stacking to 44px on mobile.
• A rust rule beneath the headline that extends past the text to the right edge.
• A short "what this is" paragraph in Work Sans body text explaining that this is a Nigeria-centered quiz game for the curious, playable in the browser.
• Three card-shaped "what you'll be asked" panels describing the kinds of questions (people, places, culture/objects), each a warm off-white card with a 1px ink hairline and a rust top rule.
• A five-tile illustrated "Nigeria in objects" band running edge-to-edge: talking drum, danfo bus, jollof, baobab, clapperboard — each tile framed by a hairline ink border, reading as a museum vitrine rather than a card grid.
• A hand-drawn zigzag rule separating major sections.
• A small mustard "no download, no sign-up" label beside the Begin button.

Primary action

• Begin — a solid rust pill pinned bottom-left under the headline; starts a game session and moves the player to Play.

Supporting actions

• None beyond Begin; the page is a reading surface with a single call to action.

Domain entities

• Game description content (headline, intro paragraph, three "what you'll be asked" panels, five object tiles).

Component responsibilities

• Hero block: headline, rust rule, Begin pill, no-sign-up label.
• Object band: five illustrated tiles with hairline frames.
• Explainer panels: three bordered cards.
• Zigzag divider.

States

• Loading: static content; no data fetch required.
• Empty: not applicable.
• Success: page renders fully; Begin is available.
• Error: not applicable (no network dependency).
• Recovery: not applicable.

Play

Information and state

• A centered question in Literata 500 at 26px mobile → 40px desktop, within a 68ch reading measure.
• A 120px spot illustration in the top-left of the question card, drawn in a single ink line with rust and mustard fills.
• Answer choices stacked as full-width bordered cards, each with a rust circular badge carrying the letter A/B/C/D on the left and a hairline border; a rust top rule appears only on the hovered/selected card.
• A right-hand score rail on desktop (floating at 1280px, collapsing above the question at 768px and below) reading like a marginal note: "Score 4 / 10" and "Streak ×3" in Literata tabular numerals, with a mustard tick mark per correct answer.
• A results state opened by a hand-drawn zigzag divider, above a Literata verdict line and a single rust "Play again" pill.

Primary actions

• Select an answer choice (A/B/C/D) to commit an answer.
• Play again on the results state to restart a session.

Supporting actions

• Read the current question and its spot illustration.
• Read score, streak and progress in the score rail.

Domain entities

• Session (current question index, score, streak, total questions).
• Question (prompt text, spot illustration, four answer choices, correct answer).
• Answer selection (chosen letter, correctness).
• Result (win or loss verdict, final score).

Component responsibilities

• Question card: spot illustration, question text, rust top rule when active.
• Answer list: four numbered exam-slip cards with rust badges.
• Score rail: score, streak, mustard ticks.
• Results panel: zigzag divider, verdict line, Play again pill.

States

• Loading: session start; question set is prepared before the first question renders.
• Empty: not applicable — a session always begins with a question.
• Success: correct answer triggers a 200ms rust wash and a stamp-like scale from 0.96 to 1; score numeral ticks up over 180ms; streak increments.
• Error: wrong answer triggers a quiet 1px shake; the correct answer is revealed and the session continues.
• Recovery: after the final question, the results state appears with a verdict and a Play again pill; Play again returns to a fresh session at question one.
• Reduced motion: all washes, shakes, scales, count-ups and cross-fades are suppressed; state changes are shown statically.

3. Functional Requirements

FR-1 — Nigeria-centered game (explicit) As a Player, I should play a game whose content is centered around Nigeria, so that the experience is genuinely about the country rather than a generic quiz with Nigerian labels.

• Trigger: the player begins a session.
• Observable result: every question, illustration and verdict references Nigerian people, places, objects or culture (talking drum, kola nut, danfo, baobab, jollof, Nollywood, calabash, and similar).
• Access state: public, anonymous.
• Failure/recovery: not applicable.
• Continuation: the player proceeds through the question set.
• Owner: Play.

FR-2 — Public entry and understanding (required_inference) As an anonymous visitor, I should reach the Landing page and understand what the game is before starting, so that I can decide to play.

• Trigger: the visitor opens the site.
• Input: none.
• Observable result: the Landing page shows the headline, the "what this is" paragraph, the three "what you'll be asked" panels, the five-tile object band and the Begin action.
• Access state: anonymous, no identity required.
• Failure/recovery: not applicable (static content).
• Continuation: the visitor selects Begin.
• Owner: Landing.

FR-3 — Begin a session (required_inference) As a Player, I should begin a session from the public entry, so that I can start playing.

• Trigger: the player selects Begin on Landing.
• Input: Begin selection.
• Observable result: the Play page opens with the first question, an empty score, and a fresh streak.
• Access state: anonymous.
• Failure/recovery: if the session cannot start, the player remains on Landing and can retry Begin.
• Continuation: the player reads and answers the first question.
• Owner: Landing (initiation) → Play (session).

FR-4 — Answer questions to a win or loss outcome (required_inference) As a Player, I should answer Nigeria-themed questions and reach a win or loss outcome, so that the session has a meaningful result.

• Trigger: the player selects an answer choice.
• Input: chosen letter A/B/C/D.
• Observable result: a correct answer produces a rust wash and stamp scale, increments score and streak, and adds a mustard tick; a wrong answer produces a quiet shake and reveals the correct answer. After the final question, a verdict line states win or loss with the final score.
• Access state: anonymous.
• Failure/recovery: a wrong answer is recoverable — the session continues to the next question.
• Continuation: the player proceeds to the next question or to the results state.
• Owner: Play.

FR-5 — Restart or play again (required_inference) As a Player, I should restart or play again after a session ends, so that the game is replayable.

• Trigger: the player selects Play again on the results state.
• Input: Play again selection.
• Observable result: a fresh session begins at question one with score and streak reset.
• Access state: anonymous.
• Failure/recovery: if restart fails, the results state remains and Play again can be retried.
• Continuation: the player plays the new session.
• Owner: Play.

4. User Personas

Player

Product context. The Player is a casual browser of any age who is curious about Nigeria and has arrived at windy-hey through a link or a search. They have not signed up, have not downloaded anything, and expect to understand the game within seconds and to be playing within a few more. They may be Nigerian and testing the game's warmth and accuracy, or they may know little about the country and want an inviting introduction.

Primary goal. To play an engaging, replayable, Nigeria-centered game and reach a satisfying win or loss outcome.

Distinct accepted responsibilities.

• Reading the Landing page to understand what the game is and what kinds of questions to expect.
• Deciding to begin a session via the Begin action.
• Answering each question by selecting one of four lettered choices.
• Reading score, streak and progress as the session advances.
• Reaching and reading the verdict at the end of the session.
• Choosing to play again.

Relevant inputs and decisions. The Player's inputs are the Begin selection, the answer-letter selections, and the Play again selection. Their decisions are whether to start, which answer to commit, and whether to replay.

Interactions with other accepted participants. None. The Player is the only active human actor; the game itself is the counterparty that presents questions, judges answers and issues the verdict.

Observable success. The Player reaches a verdict line with a final score, understands how they did, and can immediately start another session. The experience feels warm, literary and Nigerian rather than arcade-like or generic.

5. Core User Flows

Flow A — Discover the game and begin

1. The Player opens windy-hey and lands on Landing (anonymous; no identity required).
2. The Player reads the display headline "A game about Nigeria, one question at a time" and the short "what this is" paragraph.
3. The Player scans the three "what you'll be asked" panels and the five-tile "Nigeria in objects" band to understand the flavor of the questions.
4. The Player selects Begin (rust pill, bottom-left under the headline).
5. Observable result: the Play page opens with the first question, an empty score and a fresh streak.
6. Next step: the Player answers the first question (Flow B).

Failure/recovery: if the session does not start, the Player remains on Landing and can select Begin again.

Flow B — Play a session to a verdict

1. The Player is on Play with the first question centered in Literata 500 and a 120px spot illustration top-left.
2. The Player reads the four answer cards, each with a rust A/B/C/D badge.
3. The Player hovers or selects a card; a rust top rule appears on that card.
4. The Player commits an answer.
5. Observable result (correct): a 200ms rust wash crosses the card, a stamp-like scale from 0.96 to 1 plays, the score numeral ticks up over 180ms, the streak increments, and a mustard tick appears in the score rail.
6. Observable result (wrong): a quiet 1px shake plays, the correct answer is revealed, and the session continues.
7. The Player repeats steps 2–6 for each remaining question; the score rail updates throughout.
8. After the final question, a hand-drawn zigzag divider opens the results state, above a Literata verdict line stating win or loss with the final score.
9. Next step: the Player chooses Play again (Flow C) or leaves the page.

Failure/recovery: a wrong answer never ends the session prematurely; the Player always reaches the verdict. With reduced motion, all washes, shakes, scales, count-ups and cross-fades are suppressed and state changes appear statically.

Flow C — Play again

1. The Player is on the results state within Play.
2. The Player selects the single rust Play again pill.
3. Observable result: a fresh session begins at question one with score and streak reset.
4. Next step: the Player plays the new session (Flow B).

Failure/recovery: if restart fails, the results state remains and Play again can be retried.

6. Visuals Colors and Theme

The visual direction is Warm editorial play — a Nigeria story told in cream, ink and rust, with Frank Chimero as muse.

Palette (light mode)

• Background: #F5EFE3 (cream paper) — carries ~70% of every screen.
• Surface: #FFFBF3 (warm off-white) — card surfaces with a 1px ink hairline, never a drop shadow.
• Text: #2B241C (ink) — all body and heading text; body text on cream measures above 8:1 contrast.
• Primary: #A8442A (rust) — the action colour: Begin button, correct-answer stamps, current-question rule.
• Accent: #D6A02E (mustard) — secondary highlight used only for streaks and score numerals.
• Muted: #8C7E6B (muted clay) — captions and metadata.

Typography

• Headings: Literata at 600–700 weight, tight -0.02em tracking, generous leading (1.05–1.15).
• Question text: Literata at 500 for a reading feel.
• Body and UI: Work Sans at 400/500 for labels, buttons and score chrome; wide 0.06em letterspacing on all-caps eyebrows.
• Scale (modular 1.333): display clamp(44px, 8vw, 96px); question 26px → 40px; body 16px → 18px; label 12px all-caps; score numerals 32px → 56px Literata tabular.

Shape language

• Soft, paper-like rectangles with a 10px radius at most.
• Hairline 1px ink borders at 20% opacity.
• No heavy shadows; cards sit flat on cream with a single 3px rust rule along their top edge to mark the active one.
• Buttons are gentle pills (8px radius) with solid rust fill and cream text.
• Illustrated spot art sits in soft-cornered wells. Nothing glossy, nothing beveled.

Layout

• Single-column reading measure of 68ch as the spine of every page.
• Right-hand margin rail on desktop for score, streak and progress.
• Landing is a long editorial scroll: illustrated opener, "what this is" paragraph, three card-shaped "what you'll be asked" panels, then the Begin CTA.
• Play keeps the same measure: question centered at Literata 500, answer choices stacked as full-width bordered cards with a rust number badge; score rail floats right at 1280px and collapses above the question at 768px and below.
• Everything fits within 375px with 20px gutters.

Imagery

• Warm flat illustrated spot art drawn in a single ink line with rust and mustard fills: talking drum, kola nut, Lagos danfo bus, baobab silhouette, bowl of jollof, Nollywood clapperboard, calabash.
• Each question carries one 120px spot illustration in the top-left of its card.
• No photography, no stock people, no 3D.
• A repeating hand-drawn zigzag rule separates major sections.

Accessibility of text and controls

• Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit; no other element covers any part of them.
• Imagery and decoration may be cropped, bled, rotated or overlapped as the direction asks, provided they cover no readable text or control.
• With prefers-reduced-motion, a usable static arrangement is provided.

7. Signature Design Concept

The public entry is a museum vitrine on cream paper. The Landing hero is a full-width cream field with a 96px Literata headline — "A game about Nigeria, one question at a time" — set flush-left in a 9-column measure that spans the viewport on desktop and stacks to 44px on mobile. Beneath it, a rust rule extends past the text to the right edge, like a marginal note drawn by hand.

Below the rule, a horizontal band of five illustrated spot-art tiles (talking drum, danfo, jollof, baobab, clapperboard) runs edge-to-edge as a static row on cream, each tile framed by a hairline ink border — reading as a museum vitrine, not a card grid. The Begin button sits pinned bottom-left under the headline as a solid rust pill, with a small mustard "no download, no sign-up" label to its right.

The concept recomposes only accepted Landing content and the Begin control; it introduces no new behavior, page or destination. It deliberately avoids a centred hero with subtext and a blue button, a card grid with hover-lift and soft drop shadows, neon or dark-mode arcade treatment, stock photography, gradient blobs, glassmorphism, Inter/Roboto/Poppins/system-ui fonts, pill-shaped buttons with a bounce animation, and emoji as primary iconography.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the five-tile "Nigeria in objects" band — talking drum, danfo, jollof, baobab, clapperboard — as a static vitrine row on cream.
• Input → transformation → outcome thesis: as the visitor scrolls the Landing page, the vitrine band holds its place as a fixed editorial anchor while the headline and rust rule settle into view; the Begin pill remains pinned bottom-left. The transformation is compositional, not behavioral — the page reads like a well-set essay, and the outcome is that the visitor understands the game and can select Begin.
• Motion vocabulary: gentle and mostly none. Correct answers get a single 200ms rust wash and a stamp-like scale from 0.96 to 1; wrong answers get a quiet 1px shake; question-to-question transitions are a 240ms cross-fade with no slide; score numerals tick up with a 180ms count. No parallax, no floating blobs.
• Composed first frame: cream field, flush-left 96px Literata headline, rust rule extending right, five hairline-framed illustrated tiles in a row, rust Begin pill bottom-left with mustard no-sign-up label.
• Reduced-motion state: all washes, shakes, scales, count-ups and cross-fades are suppressed; the vitrine band wraps into rows or allows horizontal scrolling so each tile can be brought fully into view; the page remains fully usable and readable.

9. Non-Functional Requirements

• Nigeria-centered content (explicit). Every question, illustration and verdict must reference Nigerian people, places, objects or culture. Rationale: the user's explicit hard constraint that the game be centered around Nigeria.
• Anonymous, no-sign-up access (explicit via direction). Both Landing and Play must be reachable without identity, download or account. Rationale: the direction's "no download, no sign-up" label and the accepted anonymous access contract.
• Readability and contrast (explicit via direction). Body text on cream must measure above 8:1 contrast; ink #2B241C on cream #F5EFE3 satisfies this. Rationale: the direction's stated contrast requirement.
• Responsive integrity (explicit via direction). Headlines, labels, numbers, cards' text and controls must stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit; no other element may cover any part of them. Rationale: the direction's readable-text-and-controls rule.
• Reduced motion (explicit via direction). With prefers-reduced-motion, a usable static arrangement must be provided; all motion is suppressed. Rationale: the direction's accessibility requirement.
• Replayability (required_inference). A session must be restartable from the results state without a page reload. Rationale: the accepted "restart or play again" requirement.
• No persistence of identity (required_inference). No account, session token or durable player record is required; game state lives for the duration of a session. Rationale: no accepted behavior creates a durable relationship that must remain bound to a returning participant.

10. Tech Stack

• Frontend: React (single-page application) with the two routes Landing and Play.
• Styling: CSS with the palette, typography and shape tokens above; Literata and Work Sans loaded as web fonts.
• Backend: Python/FastAPI serving the question set and session logic, extended within the existing backend process rather than a new service.
• Storage: in-memory or lightweight storage for the question set; no durable player records required.
• Deployment: Docker/docker-compose for local and single-host deployment; Kubernetes only if deployment requires it.

11. Assumptions and Constraints

• Assumption: The question set is authored content about Nigeria and is bundled with the application; no live web search or external content API is required. (required_inference)
• Assumption: A session consists of a fixed number of questions (the direction's score rail shows "Score 4 / 10", implying ten), and the verdict is a win or loss based on the final score. (required_inference)
• Assumption: The game is single-player and local to the browser session; no multiplayer, leaderboard or sharing is in scope. (required_inference)
• Constraint: The game must be centered around Nigeria. (explicit)
• Constraint: No download, no sign-up, no account. (explicit via direction)
• Constraint: The generic indigo/blue-on-white SaaS template is forbidden. (explicit via direction)
• Constraint: No photography, no stock people, no 3D; imagery is warm flat illustrated spot art in a single ink line with rust and mustard fills. (explicit via direction)
• Constraint: Fonts are Literata (headings, questions) and Work Sans (body, UI); Inter, Roboto, Poppins and system-ui are excluded. (explicit via direction)

12. Glossary

• Player — the single active human persona; an anonymous visitor who plays the game.
• Session — one run of the game from Begin to a win or loss verdict, including score and streak.
• Verdict — the Literata line on the results state stating win or loss with the final score.
• Score rail — the right-hand marginal note on Play showing "Score x / 10" and "Streak ×n" with mustard ticks.
• Vitrine band — the five-tile illustrated "Nigeria in objects" row on Landing.
• Spot illustration — a 120px single-ink-line drawing with rust and mustard fills, one per question.
• Zigzag rule — the hand-drawn divider separating major sections and opening the results state.
• Begin — the rust pill on Landing that starts a session.
• Play again — the rust pill on the results state that restarts a session.