From 35c2f904a0a8e55e41b64f85ddb8f942c4a35a8c Mon Sep 17 00:00:00 2001 From: Halit Aksoy Date: Sat, 17 Oct 2026 02:28:40 +0300 Subject: [PATCH] docs(theme-polish): add the spec The login pages in the app's three themes, chosen through a cookie, and the web app's messages in the theme's colors at the top centre. --- docs/specs/theme-polish/design.md | 35 +++++++++++++++++++++++++ docs/specs/theme-polish/requirements.md | 28 ++++++++++++++++++++ docs/specs/theme-polish/tasks.md | 10 +++++++ 3 files changed, 73 insertions(+) create mode 100644 docs/specs/theme-polish/design.md create mode 100644 docs/specs/theme-polish/requirements.md create mode 100644 docs/specs/theme-polish/tasks.md diff --git a/docs/specs/theme-polish/design.md b/docs/specs/theme-polish/design.md new file mode 100644 index 0000000..111bede --- /dev/null +++ b/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 `` | 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 ``, 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-` and, + for Ceviz and Gece, `pf-v5-theme-dark` to ``. +- `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. diff --git a/docs/specs/theme-polish/requirements.md b/docs/specs/theme-polish/requirements.md new file mode 100644 index 0000000..9b637c1 --- /dev/null +++ b/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). diff --git a/docs/specs/theme-polish/tasks.md b/docs/specs/theme-polish/tasks.md new file mode 100644 index 0000000..2c6c9e7 --- /dev/null +++ b/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`.