Live Quiz Platform — Client app
Combined app document — Client app
| Status | Draft |
| App | Client app |
| Generated | 2026-06-05 |
| Source of truth | .claude/context/apps/client.md |
The team device app — runs on each team's phone or tablet during a quiz session. Discovers a Host on the local network, joins as a team, receives the slide content the Host pushes, and submits answers. Runs on iPhone, Android phones, iPad, and Android tablets.
Overview
The Client renders the Client canvas of each slide using a responsive layout (anchors, regions, stack) so it adapts across phone, tablet, portrait, and landscape orientations. Each Client device represents one team, with no per-individual identity in v1. On join, the Client receives an eager push of every Client-canvas slide + its resources for the whole quiz, so live-play continues even on flaky Wi-Fi.
For the cross-cutting requirements, scope, and platform list, see the project PRD.
User flows
Per-flow diagrams (lifecycle, discover, join + customisation, session) live on the dedicated flow page, each linked to its relevant UI mockups.
- Full flow diagrams — App lifecycle · Discover · Join + customisation · Session. Each flow links to the mockups it touches.
- Surface inventory matrix — Every screen / element input / notification with
leads-totargets, phase tags, FR references. - Mockup launcher → — Browse every static mockup in one browser tab.
Architecture
A Unity project, sibling to Quiz.Host, Quiz.Remote, and Quiz.Preview. Two top-level scenes — MainMenu (discovery + join: list visible Hosts, enter team name, join) and Play (render the current slide's Client canvas, dispatch input elements, show score). References com.quiz.shared-assets, com.quiz.runtime, com.quiz.core via UPM. See Per-App Scaffolding — Client for the on-disk shape. Cross-cutting:
- Architecture overview for the platform-level diagram.
- Networking for Bonjour/mDNS discovery, the join handshake, the eager push, and reconnect semantics.
- Object-Type Architecture for the input-element plugin contract on the Client side.
Design notes
The brand identity, palette, typography, and motion language are project-wide and live in the Design Specification. The Client phone runs the full Showtime palette throughout play. Client-specific design notes are tagged *{client}*.
Build plan
The Client's items are part of the single project Build Plan. Filter visually for client — Client-tagged work is concentrated in Load-bearing prototype, MVP object-type cohort (Client side), Client team-play features, Crash recovery (Client side).
User flows — detail
Surface-to-surface navigation for the Client. Each diagram shows the happy path forward only — same-screen actions (refresh, edit answer, swipe between panels, back-to-menu) are listed in prose under the diagram rather than drawn as self-loops. Authoring conventions and theme tokens live in .claude/skills/mermaid-diagrams/SKILL.md.
Surfaces referenced here are defined in Client surfaces. Functional requirements are in Functional Requirements — Client.
2. Discover
Mockups: Discover · Code entry
Bonjour host list] -->|tap live host| JO[Join] DIS -->|Have a code? — Stretch| CE[Code-entry] -->|valid| JO classDef terminal fill:#E8F5EC,stroke:#36D17B,stroke-width:2px,color:#1F1933,rx:14,ry:14 class JO terminal
On-screen actions (no navigation): pull-to-refresh, app-menu (Settings / About), tap idle host card → "no quiz loaded" inline notice. Code-entry resolve failure shows an inline "Code didn't match" hint and stays on the code-entry screen.
3. Join and team customisation
Mockups: Team join · Photo capture · Buzzer picker
photo · avatar · buzzer · colour] CUST --> SUBMIT[Join ▸] SUBMIT --> EP[Eager-push] EP --> SE[Session] classDef terminal fill:#E8F5EC,stroke:#36D17B,stroke-width:2px,color:#1F1933,rx:14,ry:14 class SE terminal
Customisation steps (each returns to the Join screen with the choice applied — modal sub-flows, not navigation): camera capture → crop-to-square; premade-avatar picker; buzzer-jingle picker (preview + select); team-colour picker (Beta).
Failure branches (each surfaces as an inline banner on the Join screen, no navigation): team name taken; host rejected join → Discover; fatal object-type mismatch → Discover; rejoin-as-previous-team dialog on reconnect.
4. Session
Mockups: Session · Session ended
slide canvas + HUD] -->|host locks input| LOCK[Locked banner] LOCK -->|host advances| SE SE -->|host ends quiz| END[Final standings] END -->|Stay for next / Leave| DIS[Discover] classDef terminal fill:#E8F5EC,stroke:#36D17B,stroke-width:2px,color:#1F1933,rx:14,ry:14 class END,DIS terminal
On-screen actions (no navigation): tap answer, edit until lock, tap score chip → standings panel (swipe to dismiss), tap team chip → session menu (Change team name / Leave / Report issue). Connection drop: Reconnecting banner overlays the session; auto-retry restores Session on reconnect, falls back to "Host gone" → Discover after timeout.
See also: Client surfaces · Functional Requirements — Client.
Design specification — cross-cutting brand
Shared brand language across all four apps (see Applications). Source of truth for cross-cutting requirement F-X-3. Brand-true treatment lands at Beta; MVP and Alpha are visually utilitarian. Operator-chrome rules for Designer / Host operator / Remote live in Design Specification — Studio.
Final product / brand name deferred to Beta — see open questions. This spec refers to apps by engineering project names (Quiz.Designer, Quiz.Host, Quiz.Client, Quiz.Remote).
Brand identity
| Asset | Treatment |
|---|---|
| Wordmark | Bold, slightly condensed uppercase display face, white fill with heavy black drop shadow. Final wording locked at Beta. |
| Tagline | Clean uppercase sans, lighter weight, white on dark, neon underline accent. Final wording locked at Beta. |
| Logomark | Stylised Q with a checkmark tucked inside it in hot magenta with a black drop shadow. Iconographic, not an initialism. |
| Mascot | Friendly cartoon smartphone — pink/magenta body, big cartoon eyes, white-gloved waving hand, white shoes. Rigged once, reused across all four apps with context-appropriate poses. Rig lands at Beta. |
Tone: live quiz on a Saturday night, televised. High contrast, vibrant gradients, neon edges. Mascot keeps warmth and humour under the energy.
Colour palette
Core hues
| Token | Hex | Usage |
|---|---|---|
color.magenta |
#FF009F |
Primary brand accent; logomark; key CTAs; big-reveal highlights. |
color.electric-blue |
#16B2EB |
Secondary brand accent; live-state indicators; secondary CTAs. |
color.deep-purple |
#961EEF |
Transitional gradient stop; high-energy backgrounds; big-reveal stages. |
color.white |
#FFFFFF |
Wordmark fill; primary text on dark. |
color.near-black |
#0F0B1A |
Primary text on light; neutral surfaces. Slight purple tint reads brand-consistent. |
Gradients + glow
- Brand gradient — linear, left→right:
magenta → deep-purple → electric-blue. Reserved for hero surfaces. - Subtle backdrop — brand gradient with low-opacity low-poly facet overlay. For content-heavy surfaces.
- Neon glow — outer glow (high blur, brand-coloured, additive blend) on framed surfaces, big-reveal headings, active leaderboard rows. Use sparingly.
Theming
Two independent theme layers, both Beta:
- Studio operator-chrome theme designer host remote — calm low-chroma chrome for Designer, the Host operator window, and Remote. Each ships light + dark. See Design Specification — Studio. Only the Client phone and the Host audience window render full Showtime.
- Per-quiz theme on Host / Client / Remote hostclientremote — quiz manifest declares a theme (enum:
dark,light, brand presets). Default is dark brand theme. Richer custom palettes are Stretch.
Studio chrome theme and per-quiz theme are independent — an author might author in light Studio chrome but ship a dark-themed quiz.
Typography
| Role | Family |
|---|---|
| Display / headings / numerals (scores, timers, countdowns) | Bebas Neue — tall condensed uppercase, tight tracking, drop shadow on dark. |
| Body / UI | Inter — geometric sans, sentence case, generous line-height. |
| Mono (codes, timestamps, debug, metadata labels) | JetBrains Mono. |
Rules
- Headings uppercase, bold, tight letter-spacing, drop shadow on dark.
- No more than two type families visible at once.
- Numbers (scores, timers) use the display face for impact.
Samples
| Family | Sample |
|---|---|
| Bebas Neue · headline | QUIZ NIGHT TONIGHT |
| Bebas Neue · score | 42 |
| Inter · body | A quick brown fox jumps over the lazy dog. |
| JetBrains Mono · metadata | core.multiple-choice-input v1.0.0 |
Visual motifs
- Neon glow borders on hero panels, leaderboards, big-reveal stages.
- Low-poly facet textures as subtle overlays on gradients.
- Gradient backdrops — full saturation for hero only; tone down for content-heavy.
- Cartoon mascot on launch, empty states, loading, end-of-quiz. Pose matches context.
Iconography
- Bold and chunky, geometric, weight matches the display typography. No hairlines.
- External imagery (photos, screenshots) sits inside framed cards with neon-glow borders.
Motion
- Confident and snappy. Spring-driven transitions with slight overshoot. Avoid lazy ease-in/out.
- Big reveals — combined scale + glow pulse + branded audio sting. Reserve for genuine reveals.
- Idle states — mascot in subtle motion (idle bob, blink) over abstract spinners.
Implementation details, performance budgets, and engine-side mechanics live in Architecture — Tech Stack and Non-Functional Requirements.
Sound design
Full audio language lands at Beta:
- Stings — correct, incorrect, time-up, lock, big reveal, end of round, end of quiz.
- Transitions — slide-advance whoosh, leaderboard reveal swell, round-change motif.
- Big-reveal audio — branded sting paired with the visual reveal motif.
- Ambient music bed (light) — optional between rounds; muted during questions.
- Buzzer jingles (Alpha — earlier than the rest). Teams pick at join (F-CL-15); Host plays on first-press win (F-HO-27). Author-supplied; small built-in default library (F-DE-29). Mixed at the same loudness band as branded stings.
Mix for venue noise: stings cut through pub ambient without being intrusive.
Team identity client host
Each team bundles name, colour (Beta), avatar (premade or photo, Alpha), buzzer jingle (Alpha) at join. Identity carries through every Host moment featuring the team: leaderboard rows, big-reveal callouts, correct-answer pings, buzzer-win playback. Team photos render at a fixed circular crop at leaderboard scale and a larger square crop on the join-screen roster. Premade avatars use the same crop so the leaderboard reads consistently regardless of source.
Layout and spacing
Spacing scale — 8 px base: 4, 8, 16, 24, 32, 48, 64, 96. No other values.
Client canvas client
Responsive — anchored regions and stacks. Adapts across phone / tablet / portrait / landscape. Primary actions in the thumb-reachable lower half. Tap targets ≥ 44×44 pt.
Voice and tone
- Friendly and confident — host who knows the room and is having fun.
- Concise — pub-quiz rhythm; copy that drags kills the energy.
- Playful, not silly — wit and mild theatre.
- Inclusive — no in-jokes, no jargon.