docs/specs/web-redesign/design.md

@@ -0,0 +1,42 @@
+# Web redesign: design
+
+## Themes
+
+The design's themes are CSS custom properties (`--bg`, `--surface`, `--ink`, `--accent`, board and pit shadows, …)
+under a class per theme (`t-ceviz`, `t-gece`, `t-yesim`), set on `<html>` so that menus and dialogs outside the React
+root get them too.
+
+The web app still uses core's `ThemeManager`, because `PitAnimator` listens to it. `ThemeManager` takes the list of
+themes (the default stays the three themes the mobile app uses); the web app passes its own three, which are core
+`Theme` objects with colours taken from the design, and maps the theme id to the CSS class.
+
+Reason: one source of truth for the chosen theme, no change for the mobile app.
+
+## Board highlights
+
+`PitAnimator` marks animated pits by changing `pitColor`, which the new board does not use. `PitViewModel` gets an
+optional `highlight` (`"sow" | "capture" | "store" | "selected"`) that `PitAnimator` sets next to the colour; the web
+board turns it into rings. The mobile app ignores it.
+
+## Move preview
+
+`getSowingPath(stones, pitIndex)` in core returns the pits a move drops stones into, in order, following
+`Board.move` (one stone goes to the next pit; more stones start with the played pit; every pit and store is passed,
+including the opponent's store). The board counts the stones per pit for the "+n" chips; the last index is where the
+last stone lands.
+
+## Styles
+
+The design's styles are plain CSS files next to the components (`*.css`, imported from the component), not
+styled-jsx: they use container queries (`@container`) and `cqw` units, which Parcel's CSS transformer supports and
+styled-jsx 5.0 does not. Class names follow the design.
+
+## Popular games
+
+`GET /games/popular?kind=finished` always returns finished games, so the home page can show live and popular games
+at once. Without the parameter the endpoint behaves as before, which the mobile app relies on.
+
+## Not done
+
+- The design's "Rematch" button: there is no rematch; the game-over card offers "New Game".
+- The mobile app.

docs/specs/web-redesign/requirements.md

@@ -0,0 +1,52 @@
+# Web redesign: requirements
+
+Status: in progress on branch `feature/web-redesign` (based on `feature/game-clock`).
+Scope: web app, with small additions to core and the backend. The mobile app keeps its current look.
+
+The design is the canvas "Köçürme Board Tasarımı" (claude.ai artifact `8AnZr74jA68LGDBfwA1vyd`): home ("Lobi"),
+game ("Oyun") and watch/replay ("İzle / Tekrar") screens, each at desktop (1440 px) and phone (390 px) width. The
+phone screens are the same pages at a narrow width, not a separate app.
+
+## Requirements
+
+### R1. Look
+- R1.1 Three themes: Ceviz (walnut, dark), Gece (night, dark) and Yeşim (jade, light). The header shows them as
+  swatches; the choice is kept in the browser. Themes saved by older versions fall back to Ceviz.
+- R1.2 The typeface is Bricolage Grotesque; icons are inline SVG.
+- R1.3 Every page has the same sticky header: logo and name (links home), theme swatches, account menu on the home
+  page, and one main action ("New Game", or "Leave" during a game). On phones the action shows its icon only.
+- R1.4 Pages work from 320 px wide: no horizontal scrolling, touch targets at least 44 px.
+
+### R2. Board
+- R2.1 Pits and stores are wells on a board; stones are drawn as coloured stones scattered in the well, with the count
+  in a badge. The viewer's store is on the right and its badge uses the accent colour.
+- R2.2 Below 600 px of board width the board stands upright: the top player's store at the top, the viewer's at
+  the bottom, the viewer's pits in the left column.
+- R2.3 On the viewer's turn, the pits they can play are buttons; hovering one previews the move: a "+n" chip on each
+  pit that receives stones and a ring on the pit where the last stone lands.
+- R2.4 While a move is animated, pits receiving stones are ringed; captures and stones landing in the store are
+  marked too. The pit the last move was played from has a dashed ring.
+
+### R3. Game page
+- R3.1 The top player is shown on the left, the bottom player on the right, and the turn between them ("Your turn",
+  "Opponent's turn", or what ended the game). On phones the bottom player is shown below the board.
+- R3.2 Each player shows an avatar with initials, name, role ("You" / "Opponent"), store count, clock and whether
+  they are online. The player to move is ringed.
+- R3.3 When the game ends a card over the board shows the result, the score, "New Game" and "Home"; it can be
+  closed to see the board.
+- R3.4 The move list shows the newest move first, with tags for extra turns, captures and stones added to the store.
+  Selecting a move still shows that position (the review banner offers to go back to live).
+
+### R4. Replay page
+- R4.1 A summary card shows the result, date, duration, move count, both players with the score, and "Watch from
+  start".
+- R4.2 Below the board a controls card has first/previous/play/next/last buttons, the speed (1x, 2x, 4x), a timeline
+  and a line describing the shown move with its tags.
+- R4.3 The move list shows the oldest move first, starting with "Start"; the shown move is highlighted.
+
+### R5. Home page
+- R5.1 A user with a game in progress sees it first: opponent, whose turn, move number, both store counts, a large
+  mini board and "Continue".
+- R5.2 "Live games", "Popular games" and "My recent games" are grids of cards: both players with the score, a mini
+  board with the stone counts and a status pill (live, result, abandoned) with details. "Live games" is hidden when
+  nothing is being played; "Popular games" always lists finished games.

docs/specs/web-redesign/tasks.md

@@ -0,0 +1,15 @@
+# Web redesign: tasks
+
+Work through the tasks in order; each ends with its checks passing and a commit. Tick a task when it is committed.
+
+- [ ] 1. **Core**: `ThemeManager` takes its themes; `PitViewModel.highlight` set by `PitAnimator`; `getSowingPath`
+      with unit tests; new texts (en, tr).
+- [ ] 2. **Backend**: `GET /games/popular?kind=finished`; test.
+- [ ] 3. **Web app shell**: the three themes, font, base styles, `AppHeader` (logo, theme swatches, account menu,
+      action) on every page; restyle the lobby, privacy page, loading and connection panels.
+- [ ] 4. **Web app board**: `BoardView`, `PitView`, `StoreView`, stones, upright layout, highlights and move preview.
+- [ ] 5. **Web app game page**: players, turn, clocks, game-over card, move list and review banner.
+- [ ] 6. **Web app replay page**: summary card, controls card, move list.
+- [ ] 7. **Web app home page**: game-in-progress hero, mini boards, live / popular / recent game cards.
+- [ ] 8. **Checks and docs**: build, Chrome check of every page at desktop and phone width in all three themes;
+      `AGENTS.md` and `TODO.md`.