A Persian, pass-the-phone implementation of the Spy party game, modeled on the Figma design.
- Vite + React 19 + TypeScript
- CSS, inline SVG, and imported artwork; no UI framework or runtime game service.
- Playwright browser tests and axe accessibility checks.
- Installable offline PWA (
vite-plugin-pwa) with a self-hosted Vazirmatn font. - Capacitor 8 shells for Android and iOS built from the same web bundle.
npm install
npm run dev # start dev server
npm run build # type-check + production build
npm run preview # preview the build
npx playwright install chromium firefox webkit # one-time browser setup for tests
npm test # builds and tests the production app in Chromium, Firefox, and WebKit
npm run test:ui # interactive test runner (`npm test -- --project=chromium` for one engine)
npm run cap:sync # build and copy the web bundle into android/ and ios/
npm run android # sync, then open Android Studio
npm run ios # sync, then open Xcode (macOS only)
npm run native:assets # regenerate native icons and splash screens from assets/The same dist/ build runs on every platform. Capacitor.isNativePlatform()
(exposed as isNative in src/platform/native.ts) selects the few behaviors
that differ.
| Web / installed PWA | Android and iOS apps (Capacitor) | |
|---|---|---|
| Offline | Service worker precaches the app, artwork, and fonts | Files are bundled in the app |
| Keep screen on during the timer | Screen Wake Lock API | @capacitor-community/keep-awake |
| Back | Browser or system back, through a same-page history entry kept while a screen handles back | Android back button and gesture |
| Status bar | theme-color, black-translucent on iOS |
Light icons on the dark background |
Back behaves the same everywhere: it closes the open dialog, the timer's tools
panel, the guide, or the player names; during a round it asks before cancelling;
on the result screen it returns home; and from home it leaves the app. Screens
register their back action with useBackButton in src/platform/native.ts.
- PWA updates use a waiting service worker that never reloads a running round. A new version takes over the next time the app is opened after every window has been closed.
- Logo and icons.
src/assets/logo.svgis the spy badge: thespy-hero.svghead cropped into the orange circle.public/favicon.svgis the same badge on a square canvas and the source for the favicon and PWA icons (pwa-assets.config.ts, generated at build time). The native sources inassets/(icon-only.png,icon-foreground.png,icon-background.png,splash.png,splash-dark.png) are renders of the badge on the app background; after replacing them, runnpm run native:assetsand commit the generated files. - Native projects.
android/andios/are committed. Change native settings there (app labelجاسوس, portrait orientation), and keep app-wide options incapacitor.config.ts. Runnpm run cap:syncafter every web change and after adding a Capacitor plugin. - Android builds need Android Studio (JDK 21 and the Android SDK). iOS builds need macOS with Xcode; plugins are resolved with Swift Package Manager, so CocoaPods is not required.
- The app id
games.bazimazi.spybecomes permanent once published to a store.
Ignore system and browser reduced-motion settings throughout this project.
Animations, transitions, and scrolling behavior keep their designed settings
regardless of prefers-reduced-motion. Do not add CSS media queries, JavaScript
preference checks, alternate effects, or shorter durations based on that setting.
This is an explicit project design decision and applies to future features too.
Playwright does not globally force reduced motion. A browser regression test
emulates both reduce and no-preference to verify that the same animations
and transitions remain enabled. Future contributors should also follow
AGENTS.md.
Home → (optional) Guide / Names → Reveal × N → Ready → Countdown 3-2-1 → Timer → Vote → Verdict → (Spy's guess) → End
A spy can also stop the timer to guess early: Timer → Spy's guess → End.
The vote can be skipped with “نمایش کلمه و نقشها”. A confirmation explains
that this ends the round without points, then reveals the secrets and leaves
the result to the group.
- Home - choose 3-30 players, 1-8 spies (fewer than players), 1-30 minutes, a word category, the optional spy hint, and classic or challenge guessing. The three main settings use compact − value + steppers (hold to repeat, arrow keys on the value); category, hint, guessing mode, player names, and vibration are under “تنظیمات بیشتر”, and sound is a top-corner toggle. Valid preferences survive reloads.
- Names - optional names by seat (16 characters). Blank seats stay «بازیکن N». Names appear on cards, the vote, the verdict, and the scoreboard.
- Reveal - a large layered deck follows the original card artboards: player number and a faint spy illustration on the back, a centered word or spy portrait on the front, and an explicit hide-and-pass action inside the card. A tap turns the card over in 3D; hiding removes the secret at once and deals the concealed card off the deck toward the next player. The deck shows one evenly spaced card per player still waiting (exact up to 9 players, capped at 9 cards above that) and thins from the back as cards go out. Progress dots (or a bar above 12 players) stay below the deck. Spy and citizen faces share every animation, sound, and vibration so nothing but the card's content can reveal a role across the table. The guide can be opened without losing the current player; opening it or hiding the page conceals revealed cards.
- Ready - everyone gets time to settle in. A slot-machine strip spins through the names and lands on the randomly chosen first questioner. The timer starts only when the group chooses to begin.
- Countdown / Timer - the original stopwatch layout leads with 3-2-1 and then a Persian MM:SS display. A small pause/resume control sits by the clock; the finish action stays at the bottom beside the spy artwork. Extra minutes and question ideas are folded under “زمان و راهنما”, along with the spy's early-guess action; opening them compacts the clock area and keeps the main action reachable. Red stopwatch artwork and a status message mark the final ten seconds, with a ticking sound, a red pulsing vignette, and a fuse bar that burns down under the time. Home confirmations pause time; cancelling restores the previous running or paused state. Public question help draws from 18 shuffled, category-neutral prompts, with no repeats until the deck is exhausted and no immediate repeat when it resets. Folding the panel keeps the current prompt; requesting another never pauses the clock.
- Vote - both time expiry and early completion leave secrets hidden. The group agrees on as many suspects as there are spies; with a full ballot a new pick replaces the oldest.
- Verdict - a drumroll, then each suspect's card turns over and the result is stamped. Accusing any citizen ends the round for the spies. Catching every spy gives them a last chance to guess the word.
- Spy's guess - classic play offers the word among seven decoys from its own category. Optional “چالش حرفهای” instead asks the spy to write the word without showing any candidates or the category. Persian/Arabic ی and ک, diacritics, tatweel, and spacing differences are accepted; synonyms, partial answers, and multiple guesses are not. Both modes show the chosen answer in a confirmation before the single final submission; cancelling preserves it.
- End - a winner banner with confetti, the reason, the portrait, spies, word, and the spy's guess. The team tally and a scrollable, keyboard-accessible list of roles and points are available on demand. One bottom action starts another round with the same settings and a fresh word.
| Result | Points |
|---|---|
| Every spy caught, last guess wrong | each citizen +1 |
| A spy guessed early and missed | each citizen +1 |
| A citizen was accused | each spy +2 |
| Every spy caught, last guess right | each spy +2 |
| A spy stopped the discussion and guessed right | each spy +3 |
Points follow seats and accumulate for the session until the number of players changes. Rounds settled without the in-app vote are not scored.
src/game/feedback.ts synthesizes every sound with Web Audio, so there are no
audio files and nothing to download. Buttons get a tap cue automatically;
data-cue on an element picks another cue and data-cue="none" leaves the cue
to the screen. Vibration uses @capacitor/haptics in the native apps and
navigator.vibrate where browsers support it; the setting is hidden where
neither exists. Audio starts on the first touch, as browsers require.
The review combined a full source/state-machine audit, baseline browser screenshots, scenario testing, primary design/accessibility guidance, and comparison with related social deduction games. This is an expert review, not an observed study of real players: improvements to enjoyment and balance are hypotheses until tested with groups.
The strongest part of the original game was its quick setup, Persian identity, and card artwork. The implementation keeps those and addresses friction around them. Findings were prioritized by their ability to spoil a round or interrupt the group, followed by replay variety and reading comfort.
| Priority | Observed issue | Implemented response |
|---|---|---|
| High | The timer immediately exposed the word and spies, removing the chance for a final vote or guess. | A separate decision phase before an explicit reveal. The publisher's Spyfall rules also distinguish time expiry from voting; this game's word-based, multiple-spy rules remain its own variant. |
| High | The same card interaction revealed and passed a role, and secrets remained on screen during the outgoing animation. | Separate reveal/hide actions, immediate secret removal, player progress, and concealment on page hiding. This applies Nielsen's error-prevention and system-status guidance to the costliest mistakes. |
| High | The last card automatically started the countdown; players had no pause control. | An untimed ready screen, explicit start, pause/resume, optional extensions, and safe early completion. Xbox's guidance on UI time limits supports time to read setup instructions; its exemption for core gameplay timers is respected. |
| Medium | Only 19 words were drawn with replacement. | 100 familiar Persian words in five categories; no repeats within the selected pool during a session, and no immediate repeat when the pool resets. With the original uniform draw, the calculated chance of at least one repeat in five rounds was about 44%. |
| Medium | The guide explained goals but left the first question and transition to discussion vague. | A random starting player, practical question examples, and a concise guide matching the actual screens. Undercover's own rules offer a useful comparison for private cards and a designated first speaker; its different roles and elimination system were not adopted. |
| Medium | Small steppers, identical accessible names, weak amber-button contrast, and a visually busy background made interaction harder. | 44px controls, contextual labels, valid selection ranges, visible keyboard focus, solid card and option surfaces, and dark primary-button text. Contrast improved from 2.01:1 to 8.21:1. See W3C contrast guidance and the 44px enhanced target-size guidance. This is a design target, not a claim of full WCAG conformance. |
| Medium | Settings reset on reload; countdown updates ran every animation frame and were continuously announced. | Validated preference storage, a deadline-based clock, updates at most four times per second, and announcements for meaningful status changes instead of every tick. |
Browser timing decisions are grounded in MDN's Page Visibility documentation:
background tabs can suspend animation frames and throttle timers. The clock
recalculates from a deadline and catches up when visible; it continues while
the page is hidden unless explicitly paused. It uses Date.now() because
MDN documents cross-platform sleep differences in performance.now().
An optional Screen Wake Lock
keeps the display awake during active discussion when the browser allows it.
Unsupported browsers, insecure contexts, and power-saving rejection fall back
without blocking play.
npm test builds the production app and starts an isolated preview on
127.0.0.1:5191. The tests also cover the vote, verdict, last-chance and
early guesses, scoring, player names, and sound/vibration settings. The
original 22 tests cover supported role counts, two complete word-pool
cycles, category switching, corrupt/denied storage, rapid taps, private
handoffs, keyboard navigation, dialog cancellation/focus, pause/resume,
extensions, delayed timer callbacks, timeout and early-end privacy, rematches,
guide access during a private handoff, citizen and spy cards, home-confirmation
timing, denied wake locks, and unchanged animation behavior under both system
motion preferences. Axe checks the major screens, expanded tools, role lists,
and a confirmation dialog after all finite animations finish.
Screenshots are generated for 320×568, 360×740, 363×692 (the supplied reference
size), 390×844, 430×932, 740×360, and 1280×800; layout checks include horizontal overflow,
reachable start, handoff, and gameplay actions, artwork placement, and card-text
clipping. Gameplay captures include all three countdown digits, the initial
timer, 03:20, the last-ten-seconds warning, final decision, result, and expanded
tools. Shared gameplay framing lives in src/components/GameplayScreen.tsx.
Secrets and word history stay in memory. Reloading resets a live round and its word history; only preferences (including names and sound settings) persist, and the session scoreboard stays in memory. The app records the group's agreed vote; how the group reaches it is up to them. Real iOS/Android screen-lock behavior, screen readers, and social balance still need device and group playtesting. Browsers may deny wake locks. Gameplay needs no server once loaded; the PWA precaches the app and the service worker serves reloads offline once it is ready. Playwright's WebKit cannot route navigations through a service worker, so the offline reload test runs in Chromium and Firefox only.
The next useful research is three Persian-speaking groups (new and experienced players, 3-8 people), playing several rounds each. Record setup time, requests for explanation, accidental reveals, pauses, unclear questions, perceived fairness/enjoyment, and voluntary rematches. Also check whether the scoring values feel fair, whether groups use the early spy guess, and whether sound helps or distracts. Use that evidence to prioritize difficulty-tuned word sets and scoring changes. Large groups are technically supported; their pacing has not been validated with players.
The follow-up review audited the round state, winning conditions, scoring, guess UI, preferences, and public help, and ran the existing 37-test browser suite before making changes. All baseline tests passed. The visual identity, private pass-the-phone cards, random roles, word pools, scoring values, and designed motion remain the foundation.
The publisher's Spyfall overview emphasizes free questions, listening, bluffing, and an early spy guess. These are useful design anchors, rather than a claim that this multiple-spy, word-based variant implements those rules. The Undercover developer's rules also distinguish private words, discussion, and a final guess. The conclusions below come from this app's code and UI; balance and enjoyment still need group playtesting.
| Finding | Update | Why it matters |
|---|---|---|
| Eight candidates give a blind guess a calculated 1-in-8 (12.5%) success chance and expose the word's category, even with spy hints off. | Optional challenge mode removes all candidates and asks for the word. Existing preferences migrate to classic; the choice persists and appears before discussion starts. | Experienced groups can demand stronger deduction while newcomers keep the familiar game. This is a difficulty option, not a proven balance correction. |
| Public help repeats the same three questions. | 18 shuffled prompts, with explicit next-question control and no repeats within a deck. Every prompt is independent of the secret and category. | Helps a stalled conversation without disclosing extra clues or making the phone manage every spoken turn. |
| A single tap can expose all secrets or commit the spy's only guess. | Review the guess before submitting, or confirm ending an unscored round before revealing secrets. Cancellation retains the answer or ballot and restores focus. | Protects the group's investment in the round without adding delays to normal card handoffs. |
| The accusation helper accepts partial or duplicate spy selections as a catch. | Require exactly the configured number of distinct spy seats. | Keeps the game rules valid outside the current UI's constraints too. |
| Repeated outcome callbacks can accumulate points twice. | Guard final scoring once per round, and guard guess submission. | Prevents repeated input from changing a settled score. |
Additional regression coverage exercises preference migration, both challenge outcomes, keyboard-equivalent Persian answers, strict rejection of partial and multiple guesses, blank-input handling, cancellation and focus, secret privacy, non-repeating prompt cycles, running time during help, and repeated submission. The new screens and dialogs receive axe checks and captures at phone, landscape, and desktop sizes. The full suite retains offline, timer, handoff, scoring, and motion-policy checks.
Playtest classic and challenge with at least three Persian-speaking groups, including beginners and experienced players, over several rounds. Record how often guesses are informed versus random, team win rates by group size and mode, time before the first question, repeated requests for help, mistaken reveals, disputed typed answers, and voluntary rematches. In particular, challenge mode changes spy difficulty while keeping scoring unchanged; use the observed results before changing points or recommended role counts. Large groups and physical iOS/Android keyboards still need device testing. Synonyms are intentionally not guessed by the software; the UI explains that the exact word is required. Session scores and live rounds remain in memory.
src/
App.tsx // top-level state machine
components/ // shared UI (Screen frame + icons)
game/ // pure game logic, scoring, feedback, and Persian helpers
platform/ // native shell setup and back handling
screens/ // one component per screen
assets/ // source images for native icons and splash screens
android/, ios/ // Capacitor native projects