docs/UI_UX_SPEC.md

Read-Along AI: UI/UX & Frontend Specification

1. Design Philosophy & Objective

The primary objective of this frontend is to provide a zero-distraction, highly accessible interface for children ages 4 to 7. Standard Gradio interfaces are built for data scientists and are too cluttered for early learners.

To qualify for the Off-Brand Award, this application must aggressively overwrite default Gradio styling using the css parameter in gr.Blocks and custom gr.HTML components.

2. Global Styling Rules (Custom CSS)

Note: As per the Roadmap, aggressive CSS gamification and styling polish should be deferred to Phase 3 (Day 7) after the core Phase 1 backend event loop is proven.

Codex must inject the following CSS rules to override the default Gradio theme:

• Typography: Use a highly legible, rounded sans-serif font (e.g., 'Nunito', 'Quicksand', 'Comic Sans MS', sans-serif).
• Sizing: Text must be massive. Base font size for the target reading block should be at least 4rem to 6rem.
• Colors: Use high-contrast, soft, friendly colors. Avoid stark white backgrounds (use a soft cream or pastel blue: e.g., #F8F9FA or #E3F2FD).
• Chrome Removal: Hide the default Gradio footer, "Built with Gradio" badges, and unnecessary padding around the main container.

3. Component Layout & Structure

The app should utilize a single-column, centered layout (gr.Column(elem_classes="main-container")). The experience is sentence-first; the UI should not expose separate phonics/CVC/sentence level controls during the hackathon MVP.

Header: The Architecture Toggle

• Mode Switch: A small, unobtrusive gr.Radio or gr.Dropdown at the top allowing the user to select between ⚡ Turbo Mode (Modal) and 🏕️ Off the Grid Mode (Local). This controls whether the backend endpoints execute locally or in the cloud.

Top: The Reading Canvas (gr.HTML)

• Do NOT use gr.Textbox for the target words/sentences.
• To allow the child to click individual words for audio assistance, the text must be rendered dynamically via gr.HTML.
• Every word in a sentence must be wrapped in a clickable <span> tag with a specific CSS class (e.g., <span class="clickable-word" onclick="...">Word</span>).
• Hovering over a word should highlight it (e.g., change background to soft yellow) to indicate it is interactive.
• The canvas should display one short sentence at a time from the fixed MVP curriculum.

Middle: The Interaction Zone

• Record Button: Use gr.Audio(sources=["microphone"], type="filepath").
• CSS Override: The default Gradio audio waveform UI is too complex. Use CSS to hide the waveform and editing tools. Style the wrapper to look like a single, massive, colorful "Microphone/Record" button with heavy border-radius (pill or circle shape) and a box-shadow.

Bottom: The Reward & Control Container

• Feedback Display (gr.HTML): A dedicated, hidden container used exclusively for rendering success animations (e.g., CSS keyframe bouncing stars, confetti emojis, or a smiling mascot).
• Navigation Controls: Two simple, oversized buttons: "Next Sentence" and "Listen to Sentence" (triggers full-sentence audio playback). Existing button labels may say "Next Level" during polish, but the product behavior is sentence advancement.

4. Frontend-to-Backend Event Mapping

Codex must wire the Gradio events as follows:

• Event 1 (The Read Attempt): When the gr.Audio component finishes recording (.stop_recording() or .change()), it immediately triggers the Python evaluation function (which routes to local or Modal ASR). The UI should display a simple, child-friendly loading state (like a spinning star) during inference.
• Event 2 (Word Click Assist): Clicking a <span> in the Reading Canvas triggers a frontend helper that plays a cached word clip when available and falls back to browser speech synthesis so word clicks do not block the child.
• Event 3 (Success State): If the evaluation function returns True, update the Feedback Display gr.HTML to show the success animation and auto-load the next sentence after 2.5 seconds.