AI Implementation feature(823): Landing Page and Login/Register Modal (#11)

docs/guides/theming.md

@@ -0,0 +1,50 @@
+---
+type: guide
+title: Theming
+description: How the 10 canonical themes are loaded, validated, and applied to the SPA via CSS custom properties.
+tags: [guide, theming, design]
+timestamp: 2026-07-21T18:28:00Z
+---
+
+# Theme catalog
+
+HIPCTF ships 10 canonical themes defined as JSON files in
+`backend/themes/` (`01-classic.json` … `10-monochrome.json`). The full
+list lives in `backend/src/common/types/theme-ids.ts`:
+
+`classic`, `midnight`, `sunset`, `forest`, `cyber`, `paper`, `crimson`,
+`ocean`, `neon`, `monochrome`.
+
+Each theme is a flat map of CSS custom properties (colors, radii, font
+family) consumed by `frontend/src/styles.css`.
+
+# Backend loading
+
+`ThemeLoaderService` (`backend/src/common/utils/theme-loader.service.ts`)
+runs on module init:
+
+1. Reads every `*.json` file in `backend/themes/`.
+2. Validates each against the `Theme` interface
+   (`backend/src/common/types/theme.ts`) — unknown theme ids, malformed
+   JSON, or missing tokens throw `ApiError(THEME_INVALID)`.
+3. Backfills any of the 10 canonical themes that are missing from disk
+   (safety net so a partial checkout still boots).
+4. Reads `SETTINGS_KEYS.THEME_KEY` (default `'classic'`). If the value is
+   not in `THEME_IDS`, the loader falls back to `classic`, logs a
+   warning, and persists `'classic'` back to settings so the next request
+   is self-healing.
+
+The resolved theme object is sent to the SPA in the
+`GET /api/v1/bootstrap` payload (see [System Endpoints](/api/system.md)).
+
+# Frontend application
+
+`BootstrapService` (`frontend/src/app/core/services/bootstrap.service.ts`)
+writes each theme token onto `document.documentElement` (e.g.
+`--color-primary`, `--radius-md`, `--font-family`). Because `styles.css`
+references the tokens via `var(--token)`, swapping themes is instant.
+
+# See also
+
+- [System Endpoints](/api/system.md)
+- [Backend Module Map](/architecture/backend-modules.md)