docs(themes): theme authoring guide with hellion forge branding

README.md

@@ -62,6 +62,13 @@ Hellion Chat baut auf [Chat 2](https://github.com/Infiziert90/ChatTwo) von **Inf
 - **Mitgelieferte Hellion-Schrift** (Exo 2, OFL-1.1) als optionaler Default statt System-Font.
 - **Hellion-Logo** im Plugin-Bundle und in der Dalamud-Plugin-Liste.
 
+#### Custom Themes (v1.1.0)
+
+HellionChat 1.1.0 bringt eine Theme-Engine mit fünf eingebauten Themes
+(Hellion Arctic, Chat 2 Klassik, Event Horizon, Moonlit Bloom, Mint Grove)
+und ein JSON-basiertes Authoring-Format für eigene Themes. Schema und
+Schritt-für-Schritt-Anleitung in [`docs/THEME-AUTHORING.md`](docs/THEME-AUTHORING.md).
+
 ### Pop-Out Convenience (v0.6.0)
 
 - **Eingabe-Bar in Pop-Out-Fenstern** als globaler Opt-In in Settings → Fenster → Fenster-Rahmen. Wenn aktiv hat jedes Pop-Out-Window unten einen kompakten Input mit kanal-farbigem Icon-Button und Text-Eingabe — kein Wechsel mehr ins Hauptfenster für eine schnelle Antwort.
@@ -302,6 +309,7 @@ Dokumentation lebt unter [`docs/`](docs/).
 | [`docs/CONTRIBUTORS.md`](docs/CONTRIBUTORS.md) | Tester, Übersetzer und Code-Beiträger der Hellion-Seite. |
 | [`docs/LEARNING-JOURNEY.md`](docs/LEARNING-JOURNEY.md) | Entwicklungsgeschichte, vom Web-Stack zu C# / Dalamud, was ich aus dem Fork gelernt habe. |
 | [`docs/IPC.md`](docs/IPC.md) | IPC-Kanal-Reference, Tuple-Payload-Felder, Migrations-Diff für Drittplugins. |
+| [`docs/THEME-AUTHORING.md`](docs/THEME-AUTHORING.md) | Theme-Engine-Authoring-Guide (EN): JSON-Schema, Color-/Layout-Slots, Channel-Identity-Regeln, Validierung. |
 | [`docs/UPSTREAM_SYNC.md`](docs/UPSTREAM_SYNC.md) | Cherry-Pick-Policy gegenüber Chat 2. |
 | [`docs/THIRD_PARTY_NOTICES.md`](docs/THIRD_PARTY_NOTICES.md) | NuGet-Dependencies mit Lizenzen, Bundled Assets, Network-Status pro Komponente. |
 | [`docs/AI_DISCLOSURE.md`](docs/AI_DISCLOSURE.md) | Offenlegung der KI-Unterstützung im Entwicklungsprozess. |

docs/THEME-AUTHORING.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <img src="images/hellion-forge.png" alt="Hellion Forge" width="180" />
+</p>
+
+# Theme Authoring Guide
+
+> Built by **Hellion Forge** — the plugin workshop arm of [Hellion Online Media](https://hellion-media.de). HellionChat ships with five built-in themes; this guide walks you through writing your own.
+
+## TL;DR
+
+1. Open Settings → Themes → **Open themes folder**
+2. Copy `example-theme.json` to `<your-name>.json` in the same folder
+3. Edit the file with any text editor
+4. Reload the plugin (toggle off/on in `/xlplugins`)
+5. Your theme appears in the Custom-Themes section in Settings → Themes
+
+That's the whole loop. The rest of this document is reference.
+
+## File location
+
+```
+%APPDATA%\XIVLauncher\pluginConfigs\HellionChat\themes\
+```
+
+(or the equivalent path on Linux/macOS — Settings → Themes → "Open themes folder" opens it directly).
+
+Each `*.json` file in this folder is loaded as one theme. The `example-theme.json` that HellionChat seeds on first launch is your starting template.
+
+## File format
+
+Theme JSON has four blocks:
+
+```json
+{
+  "schemaVersion": 1,
+  "slug": "your-slug",
+  "name": "Your Theme Name",
+  "author": "You",
+  "description": "One-line description shown under the theme name.",
+  "colors":   { ... 21 color slots ... },
+  "layout":   { ...  9 layout values ... },
+  "chatChannels": { ... optional, channel-name → hex ... }
+}
+```
+
+### Top-level fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `schemaVersion` | int | yes | Always `1` for HellionChat 1.1.0. The plugin warns and skips themes with a different number. |
+| `slug` | string | yes | Lowercase, hyphenated. Must be unique across all themes (built-in slugs are reserved). |
+| `name` | string | yes | Display name in the picker. |
+| `author` | string | yes | Shown small under the theme name. |
+| `description` | string | yes | One short sentence. |
+| `colors` | object | yes | All 21 slots required (see below). |
+| `layout` | object | yes | All 9 slots required (see below). |
+| `chatChannels` | object | no | Optional channel-name → hex map (see below). |
+
+### Color slots
+
+All values are 6-digit `#RRGGBB` or 8-digit `#RRGGBBAA` hex strings. Six-digit values get an implicit `FF` alpha.
+
+| Slot | Role |
+|---|---|
+| `primary` | Brand color — used on buttons, sliders, check marks, highlighted separators. |
+| `primaryDark` | Pressed-button stage. |
+| `primaryLight` | Hovered-button / link-text stage. |
+| `primaryGlow` | Glow / subtle accent (typically primary with ~60% alpha). |
+| `accent` | Counter-accent — scrollbar grab on hover/active, resize grip, optional CTA. |
+| `accentDark` / `accentLight` | Dark/light siblings of accent. |
+| `identity` | Title-bar active color and active-tab color. Often equals `primaryDark`. |
+| `windowBg` | Outermost window background. |
+| `childBg` | Inner panel / popup background. |
+| `frameBg` | Input fields, sliders, combos. |
+| `surface` | Card surfaces, headers, selectables. |
+| `surfaceHover` | Hovered card / header step. |
+| `border` | Panel borders. Typically primary with ~40% alpha for a brand-tinted edge. |
+| `textPrimary` | Body text. Soft off-white reads better than pure `#FFFFFF` on dark backgrounds. |
+| `textMuted` | Captions, secondary lines. |
+| `textDim` | Disabled / hint text, separators. |
+| `statusSuccess` | Green-ish for success notifications. |
+| `statusDanger` | Red for errors. |
+| `statusWarning` | Amber for warnings. |
+| `statusInfo` | Cyan-ish info. Often equals primary. |
+
+### Layout slots
+
+All values are floats in pixels. `BorderSize` is 0 or 1 (no thicker borders look right with ImGui's edge anti-aliasing).
+
+| Slot | Typical range | Notes |
+|---|---|---|
+| `windowRounding` | 0–8 | 0 = sharp upstream look; 4–6 = softer "app" feel. |
+| `childRounding` | 0–6 | Usually 1 less than `windowRounding`. |
+| `popupRounding` | 0–6 | Same as `childRounding`. |
+| `frameRounding` | 0–4 | For inputs, sliders. |
+| `grabRounding` | 0–4 | Slider grab dot. |
+| `tabRounding` | 0–4 | Tab corners. |
+| `scrollbarRounding` | 0–4 | Scrollbar grab. |
+| `windowBorderSize` | 0 or 1 | 1 reads better in dark themes. |
+| `frameBorderSize` | 0 or 1 | Usually matches windowBorderSize. |
+
+### Optional `chatChannels`
+
+If present, your theme proposes its own chat-channel colors. Property names are `ChatType` enum values (case-insensitive). Unknown names are skipped silently — safe for forward-compat.
+
+```json
+"chatChannels": {
+  "Say":             "#FFFFFF",
+  "Yell":            "#FFE066",
+  "Shout":           "#FFA040",
+  "TellIncoming":    "#FF99CC",
+  "TellOutgoing":    "#FF99CC",
+  "Party":           "#80C0E8",
+  "FreeCompany":     "#4DD9E8",
+  "NoviceNetwork":   "#A8E060",
+  "Linkshell1":      "#A8E060"
+}
+```
+
+The user is asked **once per theme switch** whether to apply these colors — never auto-overwriting existing picks. The banner shows up only if your suggested colors differ from the user's current `Configuration.ChatColours`.
+
+#### Channel-identity rule
+
+**Don't break FFXIV channel identity.** Players have used these conventions for over a decade:
+
+| Channel | Convention | Why |
+|---|---|---|
+| Say | white / off-white | Default-readable speech. |
+| Yell | yellow | Urgent broadcast. |
+| Shout | orange | Local urgent. |
+| Tell | pink-magenta | Whisper, must stand out. |
+| Party | light blue | Group ops. |
+| FreeCompany | cyan-teal | Guild ops. |
+| NoviceNetwork | lime-green | Mentor channel. |
+
+A theme can tint these toward its brand family (e.g., a purple theme can shift Tell from `#FF99CC` to `#E090FF`), but **don't** flip them (Tell suddenly green, Yell suddenly cyan). RP groups and combat-spec setups depend on the visual hierarchy.
+
+The four colored built-in themes (Hellion Arctic, Event Horizon, Moonlit Bloom, Mint Grove) all follow this rule — read their JSON for reference. Chat 2 Klassik intentionally ships without `chatChannels` so the user keeps their existing picks.
+
+## Theme families
+
+Naming convention `<color>-<modifier>` is recommended for theme families. The first member of a family is the lightest/brightest:
+
+- `mint-grove` (current built-in, light mint)
+- `forest-grove` (planned, dark emerald)
+- `moss-grove` (planned, mid muted)
+
+Code-wise families have no special handling — only the slug naming hints at the relationship. The picker may group families later, but that's not required.
+
+## Validation and errors
+
+When HellionChat loads your theme:
+
+- **Schema mismatch** (`schemaVersion != 1`): theme is skipped, warning written to `/xllog`.
+- **Missing required field** (e.g., no `slug`): theme is skipped, warning written.
+- **Invalid hex** (e.g., `#GGHHII`): theme is skipped, warning written.
+- **Unknown channel name** in `chatChannels`: that one channel is skipped silently, the rest of the theme loads normally.
+
+Check `/xllog` after a plugin reload to see what loaded and what didn't.
+
+## Testing your theme
+
+1. Edit the JSON, save the file.
+2. Reload the plugin: `/xlplugins` → toggle HellionChat off, then on.
+3. Settings → Themes → click your theme card.
+4. Watch every plugin window (chat, settings, pop-out) and pick something to fix.
+5. Tweak. Reload. Repeat.
+
+Tip: the **Settings → Themes** picker shows a mini-mockup per theme — your colors are visible before you switch.
+
+## Sharing themes
+
+Themes are JSON, so sharing is just a file. Drop it into someone's `pluginConfigs/HellionChat/themes/` folder and their plugin picks it up on next reload.
+
+A community theme repository is on the Hellion Forge roadmap. Until then: share via Discord or any pastebin.
+
+## Reference
+
+- `docs/example-theme.json` (seeded automatically on first launch into `pluginConfigs/HellionChat/themes/`) — minimal valid theme.
+- The five built-in themes live in source under `HellionChat/Themes/Builtin/`. They are a good reference for Color choices that work.
+- [Hellion Online Media branding](https://hellion-media.de) — the Arctic Cyan + Ember Glow palette that drives the default Hellion Arctic theme.
+
+---
+
+<p align="center"><sub>HellionChat is a privacy-focused fork of <a href="https://github.com/Infiziert90/ChatTwo">Chat 2</a>, distributed under the EUPL-1.2.<br/>Theme engine and authoring guide are part of <strong>Hellion Forge</strong>.</sub></p>