AI Implementation feature(886): Admin Area General Settings and Categories 1.04 (#26)
This commit was merged in pull request #26.
This commit is contained in:
+60
-26
@@ -1,50 +1,84 @@
|
||||
---
|
||||
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
|
||||
description: How the canonical themes are loaded, selected by administrators, and applied to the SPA via CSS custom properties.
|
||||
tags: [guide, theming, design, admin]
|
||||
timestamp: 2026-07-22T13:40: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`:
|
||||
HIPCTF ships canonical themes defined as JSON files in `backend/themes/`. The
|
||||
catalog is identified by `THEME_IDS` in
|
||||
`backend/src/common/types/theme-ids.ts`; the default is `classic`.
|
||||
|
||||
`classic`, `midnight`, `sunset`, `forest`, `cyber`, `paper`, `crimson`,
|
||||
`ocean`, `neon`, `monochrome`.
|
||||
Each theme contains an `id`, display `name`, and token set containing colors,
|
||||
font family, radii, and spacing values. The frontend maps the supported visual
|
||||
tokens to CSS custom properties.
|
||||
|
||||
Each theme is a flat map of CSS custom properties (colors, radii, font
|
||||
family) consumed by `frontend/src/styles.css`.
|
||||
# Administrator workflow
|
||||
|
||||
1. Sign in as an administrator and open **Admin area → General**, or navigate
|
||||
to `/admin/general`.
|
||||
2. Wait for the settings and available-theme requests to finish.
|
||||
3. Choose a value from **Global theme** (`data-testid="general-themeKey"`).
|
||||
4. Click **Save** (`data-testid="general-save"`).
|
||||
5. Verify that `Saved.` appears and that the page uses the selected colors,
|
||||
font, and corner radii. Reloading the application should preserve the theme.
|
||||
|
||||
The selector lists themes exposed by `GET /api/v1/admin/general/themes`. Only
|
||||
theme JSON files present in the configured `THEMES_DIR` are listed, while the
|
||||
loader still maintains canonical fallback themes for bootstrap and runtime
|
||||
safety.
|
||||
|
||||
# Backend loading
|
||||
|
||||
`ThemeLoaderService` (`backend/src/common/utils/theme-loader.service.ts`)
|
||||
runs on module init:
|
||||
runs on module initialization:
|
||||
|
||||
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.
|
||||
1. Reads theme JSON files from `THEMES_DIR` (default `./themes`).
|
||||
2. Validates IDs and tokens; malformed files are skipped or reported through
|
||||
the loader's validation path.
|
||||
3. Backfills missing canonical themes so the application always has a valid
|
||||
catalog.
|
||||
4. Validates the configured `SETTINGS_KEYS.THEME_KEY`; an unknown value falls
|
||||
back to `classic` and is persisted as the repaired setting.
|
||||
|
||||
The resolved theme object is sent to the SPA in the
|
||||
`GET /api/v1/bootstrap` payload (see [System Endpoints](/api/system.md)).
|
||||
The selected theme is sent to the SPA in `GET /api/v1/bootstrap` (see
|
||||
[System Endpoints](/api/system.md)). Administrators can read and update the
|
||||
selection through [Admin Endpoints](/api/admin.md). A successful general-settings
|
||||
update emits a `general` SSE event containing the new `themeKey`.
|
||||
|
||||
# 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.
|
||||
fetches `/api/v1/bootstrap` once per application lifecycle, stores the payload
|
||||
in signals, and applies the returned theme before the UI is rendered. The
|
||||
`applyThemeToCss` helper in
|
||||
`frontend/src/app/core/services/bootstrap.types.ts` writes these tokens to
|
||||
`document.documentElement`:
|
||||
|
||||
| Theme token | CSS custom property |
|
||||
|---|---|
|
||||
| `primary`, `secondary`, `accent`, `surface`, `text` | `--color-*` |
|
||||
| `success`, `warning`, `danger` | `--color-*` |
|
||||
| `fontFamily` | `--font-family` |
|
||||
| `radii.sm`, `radii.md`, `radii.lg` | `--radius-sm`, `--radius-md`, `--radius-lg` |
|
||||
|
||||
Reapplying a theme replaces the existing values. `clearThemeCss` removes every
|
||||
property managed by the helper. Components consume the properties through
|
||||
`var(--token)` in the global stylesheet and component styles.
|
||||
|
||||
# Verification
|
||||
|
||||
The frontend theme tests in `tests/frontend/bootstrap-theme.spec.ts` verify
|
||||
that all tokens are written, missing tokens are a no-op, reapplication replaces
|
||||
values, zero-valued radii are preserved, and cleanup removes every managed
|
||||
property.
|
||||
|
||||
# See also
|
||||
|
||||
- [System Endpoints](/api/system.md)
|
||||
- [Admin — General Settings](/guides/admin-general-settings.md)
|
||||
- [Admin Endpoints](/api/admin.md)
|
||||
- [Backend Module Map](/architecture/backend-modules.md)
|
||||
|
||||
Reference in New Issue
Block a user