docs: update documentation to OKF v0.1 format

2026-07-22 09:37:07 +00:00
parent d134a56abe
commit 4e463de65c
5 changed files with 136 additions and 14 deletions
@@ -0,0 +1,86 @@
+---
+type: guide
+title: Event LED Color Mapping
+description: Single source of truth mapping each event window state to the themed background color painted on the authenticated shell's status LED.
+tags: [guide, shell, led, theming, event-window, tester]
+timestamp: 2026-07-22T09:35:00Z
+---
+
+# Purpose
+
+The 10×10 status dot in the authenticated shell LED
+(`[data-testid="shell-led"]` in
+[`ShellHeaderComponent`](/architecture/frontend-structure.md)) reflects the
+current event window state. Its background color is driven by a single pure
+helper so the dot is **never transparent** and the active theme token always
+resolves at runtime.
+
+# Mapping
+
+Defined in
+`frontend/src/app/core/services/event-status.pure.ts` and re-exported via
+`frontend/src/app/core/services/event-status.store.ts`:
+
+| `EventState` | `ledBackgroundColor(state)` | Theme CSS variable     |
+|--------------|------------------------------|------------------------|
+| `countdown`  | `var(--color-warning)`       | `--color-warning`      |
+| `running`    | `var(--color-success)`       | `--color-success`      |
+| `stopped`    | `var(--color-danger)`        | `--color-danger`       |
+| `unconfigured` | `var(--color-secondary)`   | `--color-secondary`    |
+
+Backing constant: `LED_COLOR_BY_STATE: Readonly<Record<EventState, string>>`.
+The accessor function `ledBackgroundColor(state)` returns the same string for
+each state.
+
+# How it reaches the DOM
+
+1. `HomeComponent` forwards the `state` signal from
+   [`EventStatusStore`](/architecture/frontend-structure.md) to
+   `ShellHeaderComponent` via its `eventState` input.
+2. `ShellHeaderComponent.ledColor` is a `computed` signal defined as
+   `computed(() => ledBackgroundColor(this.eventState()))`.
+3. The template binds it directly:
+   `[style.background-color]="ledColor()"`.
+4. The LED's base `.led` rule is shape-only (`inline-block`, 10×10, circular,
+   `vertical-align: middle`); no `transparent` fallback is applied, so the
+   author background color is always visible.
+5. The legacy `.led-running`, `.led-countdown`, `.led-stopped`,
+   `.led-unconfigured` CSS selectors remain on the element and continue to be
+   useful hooks for selectors and tests, but they no longer declare the color.
+
+# Examples
+
+## Programmatic lookup
+
+```ts
+import { ledBackgroundColor, LED_COLOR_BY_STATE } from
+  './frontend/src/app/core/services/event-status.pure';
+
+ledBackgroundColor('running');   // 'var(--color-success)'
+ledBackgroundColor('stopped');   // 'var(--color-danger)'
+LED_COLOR_BY_STATE.unconfigured; // 'var(--color-secondary)'
+```
+
+## Verifying in the DOM
+
+```ts
+const dot = document.querySelector('[data-testid="shell-led"]') as HTMLElement;
+dot.style.backgroundColor; // resolves to the current theme token, never empty
+dot.getAttribute('aria-label'); // 'Event status: running'
+```
+
+# Tester checklist
+
+* The LED is **visible** in every state (no transparent or missing dot).
+* The LED color matches the mapping table when the event window is forced
+  into each state via the [event window settings](/guides/event-window.md).
+* Switching states live updates both the dot color and the
+  `aria-label="Event status: <state>"` attribute.
+* The four `led-<state>` classes are still applied to the element.
+
+# See also
+
+- [Authenticated Shell](/guides/authenticated-shell.md)
+- [Event Window](/guides/event-window.md)
+- [Frontend Structure](/architecture/frontend-structure.md)
+- [Theming](/guides/theming.md)