building-react-frontend

name	building-react-frontend
description	Builds the React and Vite frontend for the motion-comic experience and is used when the project needs the user-facing story UI, choices, voice input, and graceful fallbacks.

Builds the cinematic frontend that makes the story feel like a product instead of a prototype.

Use this skill when

• The React/Vite app needs to be built or refined.
• The team needs the emotional intake screen, story scene screen, and choice UI.
• The motion-comic experience needs panel animation, narration display, and fallback states.
• The PM needs plain-language explanations for UI decisions.

Capabilities

• Creates a dark, immersive React UI with simple state management.
• Renders 3–5 panels per scene.
• Renders AI-generated GIFs with real motion per panel; falls back to Ken Burns-style CSS/JS motion on static images.
• Supports voice input when available, with text fallback.
• Displays narration, captions, and meaningful choice buttons.
• Handles loading, error, and degraded-media states gracefully.
• Keeps the interface mobile responsive and low-chrome.

Recommended simple frontend structure

• frontend/src/pages/
  • IntakePage
  • StoryPage
  • EndingPage
• frontend/src/components/
  • ComicPanel
  • PanelSequence
  • ChoiceButtons
  • NarrationBar
  • VoiceInput
  • LoadingOverlay
• frontend/src/lib/ or frontend/src/services/
  • API client
  • session helpers

Workflow

1. Explain the UX simply. Example: "The UI should disappear behind the story. Most of what the user feels should come from panels, sound, and choices."
2. Build the intake screen first.
   • atmospheric opening (darkness, mist, mysterious narrator GIF)
   • voice input as primary (with text fallback)
   • mood detection from voice quality where possible
   • clear CTA
3. Build the scene screen.
   • panel sequence
   • caption/narration layer
   • choice area
   • conversational voice input at choice points (encourage users to talk, not just click)
   • choices displayed as text AND narrated — selectable via voice or tap
   • background audio controls if needed
4. Add motion. Play AI-generated GIF assets for primary panel motion. Use CSS keyframes or lightweight JS for fallback Ken Burns on static images only.
5. Add graceful fallbacks.
   • if motion metadata missing → show static image
   • if image missing → show text-first panel
   • if narration audio missing → show captions
6. Connect to backend API.
7. Test on mobile and slow network conditions.
8. Polish only the core demo path.

Example component tree

StoryPage
├─ NarrationBar
├─ PanelSequence
│  ├─ ComicPanel
│  ├─ ComicPanel
│  └─ ComicPanel
├─ ChoiceButtons
└─ LoadingOverlay

Frontend guardrails

• No Redux for MVP.
• No complex design system unless it speeds you up.
• Keep buttons readable and choice text emotionally clear.
• Story quality beats UI feature count.
• Voice is the primary input method — design for voice-first, text as fallback.
• Choices must be visible as text even when narrated aloud.
• No photorealistic imagery. Keep art style consistent per story.

Project references

• AGENTS.md — frontend rules, dark theme, voice input, fallback chain, React conventions.
• docs/PRD.md — key screens, motion-comic behavior, captions, comic panel requirements.
• docs/roadmap.md — MVP frontend scope and what not to build yet.