docs/specs/theme-polish/design.md

@@ -0,0 +1,35 @@
+# Theme polish: design
+
+See `requirements.md`; requirement ids (R1.1, …) are referenced below.
+
+## Decisions
+
+| Decision | Reason |
+|---|---|
+| The web app writes the theme's id to a `mancala_theme` cookie; a small script in the login theme reads it and puts the theme's class on `<html>` | Keycloak's pages are on another origin (`localhost:8080`, `auth.playmancala.app`), so they cannot read the app's `localStorage`. Cookies are shared: host-only cookies across the ports of `localhost`, and a cookie for `playmancala.app` with its subdomains (R1.2). |
+| The script runs in `<head>`, before the page is drawn | No flash of another theme. |
+| Without the cookie, the script picks Ceviz or Yeşim from `prefers-color-scheme` (R1.3) | The app's default theme is Ceviz (dark); Yeşim is its only light theme. |
+| `darkMode=false` in the theme; the script adds PatternFly's `pf-v5-theme-dark` itself for the dark themes | Keycloak's own dark mode follows the system and would fight the chosen theme. |
+| The theme stays a stylesheet on top of `keycloak.v2`, now with the three themes' tokens copied from `apps/frontend/src/styles/app.css` | Templates stay Keycloak's, so upgrades need no template changes. |
+| The logo and the small board on the card are masks filled with the theme's colors | One image each for all three themes. |
+| The app's name comes from CSS by the page's language | The realm's display name is one string; the header shows "Köçürme" for Turkish and "Mancala" otherwise, like the web app. |
+| Notyf stays for messages, configured for the top centre and restyled with the theme's variables (R2) | It is used from plain functions (`Util.checkConnectionAndMaybeAlert`), not only components; a React toast would need a context everywhere. |
+
+## Login theme (`apps/keycloak/themes/mancala/login`)
+
+- `theme.properties`: `darkMode=false`, `scripts=js/theme.js`, styles `css/styles.css css/mancala.css`.
+- `js/theme.js`: reads `mancala_theme` (`ceviz`, `gece`, `yesim`), falls back to the color scheme, adds `t-<id>` and,
+  for Ceviz and Gece, `pf-v5-theme-dark` to `<html>`.
+- `css/mancala.css`: the Bricolage Grotesque font; the tokens of `.t-ceviz`, `.t-gece`, `.t-yesim`; PatternFly's
+  variables mapped to them; the header like the app's (logo, name), the card on `--surface`, inputs on `--surface2`,
+  primary buttons in `--accent`, secondary ones outlined, links in `--ink`, errors in `--live`.
+- `img/logo-mask.svg`, `img/board-mask.svg`: alpha masks.
+
+## Web app
+
+- `theme/themes.ts`: `saveThemeCookie(theme)`, called with `applyThemeClass` at start and on every theme change. The
+  cookie lasts a year, `SameSite=Lax`, `Secure` on https, and on a real domain is set for the last two labels of the
+  host (`playmancala.app`).
+- `util/Notyf.ts`: `position: { x: "center", y: "top" }`, a shorter duration, no icons, dismissible by click.
+- `styles/app.css`: Notyf's container below the header; the toast in `--ink` on `--bg` (an inverted chip, readable on
+  every theme), the app's font, rounded.

docs/specs/theme-polish/requirements.md

@@ -0,0 +1,28 @@
+# Theme polish: requirements
+
+Status: in progress, on branch `feature/theme-polish` (based on `develop`).
+Scope: the Keycloak login theme and the web app's short messages. Follows `web-redesign`.
+
+## Goals
+
+The login pages and the web app's messages look like the rest of the app in each of its three themes (Ceviz, Gece,
+Yeşim), and messages appear where they are noticed without covering the game.
+
+## Requirements
+
+### R1. Login pages
+- R1.1 The login, registration, password reset and other Keycloak login pages use the web redesign's look: its colors,
+  font, logo, rounded cards, pill buttons and the app's name ("Mancala", in Turkish "Köçürme").
+- R1.2 They use the theme the player chose in the web app on the same device, also right after changing it.
+- R1.3 Without a chosen theme (e.g. a first visit straight to the login page), they follow the system's color scheme:
+  Ceviz when it is dark, Yeşim when it is light.
+- R1.4 Errors, info messages and the language select stay readable in every theme; the pages work at phone width
+  without horizontal scrolling.
+
+### R2. Messages in the web app
+- R2.1 Short messages (e.g. "Opponent's turn", "Connection lost") use the theme's colors and font.
+- R2.2 They appear at the top centre, just below the header, not in the bottom right corner.
+- R2.3 Several messages stack without covering the header; each goes away by itself or when clicked.
+
+## Out of scope (TODO)
+- Keycloak's email theme (password reset emails).

docs/specs/theme-polish/tasks.md

@@ -0,0 +1,10 @@
+# Theme polish: tasks
+
+Work through the tasks in order; each ends with its checks passing and a commit. Tick a task when it is committed.
+
+- [x] 1. **Spec**: requirements, design and tasks.
+- [ ] 2. **Web app messages**: Notyf at the top centre in the theme's colors.
+- [ ] 3. **Theme cookie**: the web app saves the chosen theme for the login pages.
+- [ ] 4. **Login theme**: the script, the three themes' styles, logo and board masks; checked in Chrome in all three
+      themes, at desktop and phone width, with and without the cookie.
+- [ ] 5. **Docs**: `AGENTS.md` (specs list, the cookie), `apps/keycloak/README.md`, `TODO.md`.