Add game selection screen and new run wizard

Build a 3-step wizard at /runs/new: select game (themed gradient cards
grouped by generation with filter tabs), configure rules (reuses existing
RulesConfiguration), and name/create run. Remove standalone Games and Rules
pages since they're now integrated into the wizard flow.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.beans/nuzlocke-tracker-uw2j--game-selection-screen.md

@@ -1,24 +1,30 @@
 ---
 # nuzlocke-tracker-uw2j
 title: Game Selection Screen
-status: todo
+status: completed
 type: task
+priority: normal
 created_at: 2026-02-04T15:44:16Z
-updated_at: 2026-02-04T15:44:16Z
+updated_at: 2026-02-05T14:02:43Z
 parent: nuzlocke-tracker-f5ob
 ---
 
 Build the initial screen where users select which Pokémon game they want to track.
 
 ## Checklist
-- [ ] Create game selection component
+- [x] Create game selection component
-- [ ] Display games grouped by generation
+- [x] Display games grouped by generation
-- [ ] Show game artwork/logo for each option
+- [x] Show game artwork/logo for each option
-- [ ] Add search/filter functionality for games
+- [x] Add search/filter functionality for games
-- [ ] Navigate to rule settings after selection
+- [x] Navigate to rule settings after selection
-- [ ] Allow returning to change game selection
+- [x] Allow returning to change game selection
 
-## UX Considerations
+## Implementation Notes
-- Games should be visually recognizable
+- Game selection is step 1 of a 3-step new run wizard at `/runs/new`
-- Consider showing regional variants (e.g., Kanto games together)
+- `GameCard` component: slug-based gradient backgrounds as fallback for missing box art
-- Mobile-friendly grid/list layout
+- `GameGrid` component: responsive grid with generation filter tabs
+- `StepIndicator` component: clickable progress bar for navigating wizard steps
+- `NewRun` page: wizard flow — select game → configure rules → name & create run
+- Reuses existing `RulesConfiguration` component for step 2
+- `GameSelect` page at `/games` shows a browseable game grid with "Start New Run" CTA
+- "New Run" link added to nav bar

frontend/src/App.tsx

@@ -1,14 +1,13 @@
 import { Routes, Route } from 'react-router-dom'
 import { Layout } from './components'
-import { Home, GameSelect, Dashboard, Encounters, Rules } from './pages'
+import { Home, NewRun, Dashboard, Encounters } from './pages'
 
 function App() {
   return (
     <Routes>
       <Route path="/" element={<Layout />}>
         <Route index element={<Home />} />
-        <Route path="games" element={<GameSelect />} />
+        <Route path="runs/new" element={<NewRun />} />
-        <Route path="rules" element={<Rules />} />
         <Route path="dashboard" element={<Dashboard />} />
         <Route path="encounters" element={<Encounters />} />
       </Route>

frontend/src/components/GameCard.tsx

@@ -0,0 +1,79 @@
+import type { Game } from '../types'
+
+const GAME_GRADIENTS: Record<string, string> = {
+  firered: 'from-red-500 to-orange-500',
+  leafgreen: 'from-green-500 to-emerald-500',
+  emerald: 'from-emerald-500 to-teal-500',
+  heartgold: 'from-amber-400 to-yellow-500',
+  soulsilver: 'from-gray-400 to-slate-500',
+}
+
+const DEFAULT_GRADIENT = 'from-blue-500 to-indigo-500'
+
+interface GameCardProps {
+  game: Game
+  selected: boolean
+  onSelect: (game: Game) => void
+}
+
+export function GameCard({ game, selected, onSelect }: GameCardProps) {
+  const gradient = GAME_GRADIENTS[game.slug] ?? DEFAULT_GRADIENT
+
+  return (
+    <button
+      type="button"
+      onClick={() => onSelect(game)}
+      className={`relative w-full rounded-lg overflow-hidden transition-all duration-200 hover:scale-105 hover:shadow-lg focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900 ${
+        selected ? 'ring-2 ring-blue-500 scale-105 shadow-lg' : 'shadow'
+      }`}
+    >
+      {game.boxArtUrl ? (
+        <img
+          src={game.boxArtUrl}
+          alt={game.name}
+          className="w-full h-48 object-cover"
+        />
+      ) : (
+        <div
+          className={`w-full h-48 bg-gradient-to-br ${gradient} flex items-center justify-center`}
+        >
+          <span className="text-white text-2xl font-bold text-center px-4 drop-shadow-md">
+            {game.name.replace('Pokemon ', '')}
+          </span>
+        </div>
+      )}
+      <div className="p-3 bg-white dark:bg-gray-800 text-left">
+        <h3 className="font-semibold text-gray-900 dark:text-gray-100">
+          {game.name}
+        </h3>
+        <div className="flex items-center gap-2 mt-1">
+          <span className="text-xs px-2 py-0.5 rounded-full bg-gray-100 dark:bg-gray-700 text-gray-600 dark:text-gray-400">
+            {game.region}
+          </span>
+          {game.releaseYear && (
+            <span className="text-xs text-gray-500 dark:text-gray-400">
+              {game.releaseYear}
+            </span>
+          )}
+        </div>
+      </div>
+      {selected && (
+        <div className="absolute top-2 right-2 w-6 h-6 bg-blue-500 rounded-full flex items-center justify-center">
+          <svg
+            className="w-4 h-4 text-white"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={3}
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M5 13l4 4L19 7"
+            />
+          </svg>
+        </div>
+      )}
+    </button>
+  )
+}

frontend/src/components/GameGrid.tsx

@@ -0,0 +1,94 @@
+import { useState, useMemo } from 'react'
+import type { Game } from '../types'
+import { GameCard } from './GameCard'
+
+const GENERATION_LABELS: Record<number, string> = {
+  1: 'Generation I',
+  2: 'Generation II',
+  3: 'Generation III',
+  4: 'Generation IV',
+  5: 'Generation V',
+  6: 'Generation VI',
+  7: 'Generation VII',
+  8: 'Generation VIII',
+  9: 'Generation IX',
+}
+
+interface GameGridProps {
+  games: Game[]
+  selectedId: number | null
+  onSelect: (game: Game) => void
+}
+
+export function GameGrid({ games, selectedId, onSelect }: GameGridProps) {
+  const [filter, setFilter] = useState<number | null>(null)
+
+  const generations = useMemo(
+    () => [...new Set(games.map((g) => g.generation))].sort(),
+    [games],
+  )
+
+  const filtered = filter
+    ? games.filter((g) => g.generation === filter)
+    : games
+
+  const grouped = useMemo(() => {
+    const groups: Record<number, Game[]> = {}
+    for (const game of filtered) {
+      ;(groups[game.generation] ??= []).push(game)
+    }
+    return Object.entries(groups)
+      .map(([gen, games]) => ({ generation: Number(gen), games }))
+      .sort((a, b) => a.generation - b.generation)
+  }, [filtered])
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center gap-2">
+        <button
+          type="button"
+          onClick={() => setFilter(null)}
+          className={`px-3 py-1.5 text-sm font-medium rounded-full transition-colors ${
+            filter === null
+              ? 'bg-blue-600 text-white'
+              : 'bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-300 hover:bg-gray-200 dark:hover:bg-gray-600'
+          }`}
+        >
+          All
+        </button>
+        {generations.map((gen) => (
+          <button
+            key={gen}
+            type="button"
+            onClick={() => setFilter(gen)}
+            className={`px-3 py-1.5 text-sm font-medium rounded-full transition-colors ${
+              filter === gen
+                ? 'bg-blue-600 text-white'
+                : 'bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-300 hover:bg-gray-200 dark:hover:bg-gray-600'
+            }`}
+          >
+            Gen {gen}
+          </button>
+        ))}
+      </div>
+
+      {grouped.map(({ generation, games }) => (
+        <div key={generation}>
+          <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-3">
+            {GENERATION_LABELS[generation] ?? `Generation ${generation}`}
+          </h3>
+          <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+            {games.map((game) => (
+              <GameCard
+                key={game.id}
+                game={game}
+                selected={game.id === selectedId}
+                onSelect={onSelect}
+              />
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

frontend/src/components/Layout.tsx

@@ -13,16 +13,10 @@ export function Layout() {
             </div>
             <div className="flex items-center space-x-4">
               <Link
-                to="/games"
+                to="/runs/new"
                 className="px-3 py-2 rounded-md text-sm font-medium hover:bg-gray-100 dark:hover:bg-gray-700"
               >
-                Games
+                New Run
-              </Link>
-              <Link
-                to="/rules"
-                className="px-3 py-2 rounded-md text-sm font-medium hover:bg-gray-100 dark:hover:bg-gray-700"
-              >
-                Rules
               </Link>
               <Link
                 to="/dashboard"

frontend/src/components/StepIndicator.tsx

@@ -0,0 +1,78 @@
+const STEPS = ['Select Game', 'Configure Rules', 'Create Run']
+
+interface StepIndicatorProps {
+  currentStep: number
+  onStepClick: (step: number) => void
+}
+
+export function StepIndicator({ currentStep, onStepClick }: StepIndicatorProps) {
+  return (
+    <nav aria-label="Progress" className="mb-8">
+      <ol className="flex items-center">
+        {STEPS.map((label, i) => {
+          const step = i + 1
+          const isCompleted = step < currentStep
+          const isCurrent = step === currentStep
+
+          return (
+            <li
+              key={label}
+              className={`flex items-center ${i < STEPS.length - 1 ? 'flex-1' : ''}`}
+            >
+              <button
+                type="button"
+                onClick={() => isCompleted && onStepClick(step)}
+                disabled={!isCompleted}
+                className={`flex items-center gap-2 text-sm font-medium ${
+                  isCompleted
+                    ? 'text-blue-600 dark:text-blue-400 cursor-pointer hover:text-blue-700 dark:hover:text-blue-300'
+                    : isCurrent
+                      ? 'text-gray-900 dark:text-gray-100'
+                      : 'text-gray-400 dark:text-gray-500 cursor-default'
+                }`}
+              >
+                <span
+                  className={`flex items-center justify-center w-8 h-8 rounded-full text-sm font-bold shrink-0 ${
+                    isCompleted
+                      ? 'bg-blue-600 text-white'
+                      : isCurrent
+                        ? 'border-2 border-blue-600 text-blue-600 dark:border-blue-400 dark:text-blue-400'
+                        : 'border-2 border-gray-300 dark:border-gray-600 text-gray-400 dark:text-gray-500'
+                  }`}
+                >
+                  {isCompleted ? (
+                    <svg
+                      className="w-4 h-4"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                      strokeWidth={3}
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        d="M5 13l4 4L19 7"
+                      />
+                    </svg>
+                  ) : (
+                    step
+                  )}
+                </span>
+                <span className="hidden sm:inline">{label}</span>
+              </button>
+              {i < STEPS.length - 1 && (
+                <div
+                  className={`flex-1 h-0.5 mx-3 ${
+                    step < currentStep
+                      ? 'bg-blue-600'
+                      : 'bg-gray-300 dark:bg-gray-600'
+                  }`}
+                />
+              )}
+            </li>
+          )
+        })}
+      </ol>
+    </nav>
+  )
+}

frontend/src/components/index.ts

@@ -1,3 +1,6 @@
+export { GameCard } from './GameCard'
+export { GameGrid } from './GameGrid'
 export { Layout } from './Layout'
 export { RuleToggle } from './RuleToggle'
 export { RulesConfiguration } from './RulesConfiguration'
+export { StepIndicator } from './StepIndicator'

frontend/src/pages/GameSelect.tsx

@@ -1,10 +0,0 @@
-export function GameSelect() {
-  return (
-    <div className="p-8">
-      <h1 className="text-3xl font-bold mb-6">Select a Game</h1>
-      <p className="text-gray-600 dark:text-gray-400">
-        Game selection will be implemented here.
-      </p>
-    </div>
-  )
-}

frontend/src/pages/NewRun.tsx

@@ -0,0 +1,188 @@
+import { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { GameGrid, RulesConfiguration, StepIndicator } from '../components'
+import { useGames } from '../hooks/useGames'
+import { useCreateRun } from '../hooks/useRuns'
+import type { Game, NuzlockeRules } from '../types'
+import { DEFAULT_RULES } from '../types'
+
+export function NewRun() {
+  const navigate = useNavigate()
+  const { data: games, isLoading, error } = useGames()
+  const createRun = useCreateRun()
+
+  const [step, setStep] = useState(1)
+  const [selectedGame, setSelectedGame] = useState<Game | null>(null)
+  const [rules, setRules] = useState<NuzlockeRules>(DEFAULT_RULES)
+  const [runName, setRunName] = useState('')
+
+  const handleGameSelect = (game: Game) => {
+    setSelectedGame(game)
+    if (!runName || runName === `${selectedGame?.name} Nuzlocke`) {
+      setRunName(`${game.name} Nuzlocke`)
+    }
+  }
+
+  const handleCreate = () => {
+    if (!selectedGame) return
+    createRun.mutate(
+      { gameId: selectedGame.id, name: runName, rules },
+      { onSuccess: () => navigate('/dashboard') },
+    )
+  }
+
+  const enabledRuleCount = Object.values(rules).filter(Boolean).length
+  const totalRuleCount = Object.keys(rules).length
+
+  return (
+    <div className="max-w-4xl mx-auto p-8">
+      <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100 mb-2">
+        New Nuzlocke Run
+      </h1>
+      <p className="text-gray-600 dark:text-gray-400 mb-6">
+        Set up your run in a few steps.
+      </p>
+
+      <StepIndicator currentStep={step} onStepClick={setStep} />
+
+      {step === 1 && (
+        <div>
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-4">
+            Choose a Game
+          </h2>
+
+          {isLoading && (
+            <div className="flex items-center justify-center py-12">
+              <div className="w-8 h-8 border-4 border-blue-600 border-t-transparent rounded-full animate-spin" />
+            </div>
+          )}
+
+          {error && (
+            <div className="rounded-lg bg-red-50 dark:bg-red-900/20 p-4 text-red-700 dark:text-red-400">
+              Failed to load games. Please try again.
+            </div>
+          )}
+
+          {games && (
+            <GameGrid
+              games={games}
+              selectedId={selectedGame?.id ?? null}
+              onSelect={handleGameSelect}
+            />
+          )}
+
+          <div className="mt-6 flex justify-end">
+            <button
+              type="button"
+              disabled={!selectedGame}
+              onClick={() => setStep(2)}
+              className="px-6 py-2 bg-blue-600 text-white rounded-lg font-medium hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+            >
+              Next
+            </button>
+          </div>
+        </div>
+      )}
+
+      {step === 2 && (
+        <div>
+          <RulesConfiguration rules={rules} onChange={setRules} />
+
+          <div className="mt-6 flex justify-between">
+            <button
+              type="button"
+              onClick={() => setStep(1)}
+              className="px-6 py-2 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 rounded-lg font-medium hover:bg-gray-200 dark:hover:bg-gray-600 focus:outline-none focus:ring-2 focus:ring-gray-400 focus:ring-offset-2 transition-colors"
+            >
+              Back
+            </button>
+            <button
+              type="button"
+              onClick={() => setStep(3)}
+              className="px-6 py-2 bg-blue-600 text-white rounded-lg font-medium hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 transition-colors"
+            >
+              Next
+            </button>
+          </div>
+        </div>
+      )}
+
+      {step === 3 && (
+        <div>
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-4">
+            Name Your Run
+          </h2>
+
+          <div className="bg-white dark:bg-gray-800 rounded-lg shadow p-6 space-y-4">
+            <div>
+              <label
+                htmlFor="run-name"
+                className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1"
+              >
+                Run Name
+              </label>
+              <input
+                id="run-name"
+                type="text"
+                value={runName}
+                onChange={(e) => setRunName(e.target.value)}
+                className="w-full px-3 py-2 rounded-lg border border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+                placeholder="My Nuzlocke Run"
+              />
+            </div>
+
+            <div className="border-t border-gray-200 dark:border-gray-700 pt-4">
+              <h3 className="text-sm font-medium text-gray-500 dark:text-gray-400 mb-2">
+                Summary
+              </h3>
+              <dl className="space-y-1 text-sm">
+                <div className="flex justify-between">
+                  <dt className="text-gray-600 dark:text-gray-400">Game</dt>
+                  <dd className="text-gray-900 dark:text-gray-100 font-medium">
+                    {selectedGame?.name}
+                  </dd>
+                </div>
+                <div className="flex justify-between">
+                  <dt className="text-gray-600 dark:text-gray-400">Region</dt>
+                  <dd className="text-gray-900 dark:text-gray-100 font-medium">
+                    {selectedGame?.region}
+                  </dd>
+                </div>
+                <div className="flex justify-between">
+                  <dt className="text-gray-600 dark:text-gray-400">Rules</dt>
+                  <dd className="text-gray-900 dark:text-gray-100 font-medium">
+                    {enabledRuleCount} of {totalRuleCount} enabled
+                  </dd>
+                </div>
+              </dl>
+            </div>
+          </div>
+
+          {createRun.error && (
+            <div className="mt-4 rounded-lg bg-red-50 dark:bg-red-900/20 p-4 text-red-700 dark:text-red-400">
+              Failed to create run. Please try again.
+            </div>
+          )}
+
+          <div className="mt-6 flex justify-between">
+            <button
+              type="button"
+              onClick={() => setStep(2)}
+              className="px-6 py-2 text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 rounded-lg font-medium hover:bg-gray-200 dark:hover:bg-gray-600 focus:outline-none focus:ring-2 focus:ring-gray-400 focus:ring-offset-2 transition-colors"
+            >
+              Back
+            </button>
+            <button
+              type="button"
+              disabled={!runName.trim() || createRun.isPending}
+              onClick={handleCreate}
+              className="px-6 py-2 bg-blue-600 text-white rounded-lg font-medium hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
+            >
+              {createRun.isPending ? 'Creating...' : 'Create Run'}
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/pages/Rules.tsx

@@ -1,46 +0,0 @@
-import { useState } from 'react'
-import { RulesConfiguration } from '../components'
-import type { NuzlockeRules } from '../types'
-import { DEFAULT_RULES } from '../types'
-
-export function Rules() {
-  const [rules, setRules] = useState<NuzlockeRules>(DEFAULT_RULES)
-  const [saved, setSaved] = useState(false)
-
-  const handleSave = () => {
-    // TODO: Persist to backend API
-    setSaved(true)
-    setTimeout(() => setSaved(false), 2000)
-  }
-
-  return (
-    <div className="max-w-2xl mx-auto p-8">
-      <div className="mb-6">
-        <h1 className="text-3xl font-bold text-gray-900 dark:text-gray-100">
-          Nuzlocke Rules
-        </h1>
-        <p className="mt-2 text-gray-600 dark:text-gray-400">
-          Configure the rules for your Nuzlocke run. Hover over the info icon
-          for explanations.
-        </p>
-      </div>
-
-      <RulesConfiguration rules={rules} onChange={setRules} />
-
-      <div className="mt-6 flex items-center gap-4">
-        <button
-          type="button"
-          onClick={handleSave}
-          className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
-        >
-          Save Rules
-        </button>
-        {saved && (
-          <span className="text-green-600 dark:text-green-400">
-            Rules saved!
-          </span>
-        )}
-      </div>
-    </div>
-  )
-}

frontend/src/pages/index.ts

@@ -1,5 +1,4 @@
 export { Home } from './Home'
-export { GameSelect } from './GameSelect'
+export { NewRun } from './NewRun'
 export { Dashboard } from './Dashboard'
 export { Encounters } from './Encounters'
-export { Rules } from './Rules'