IIO Theme Developer Guide

Diese Seite dokumentiert die komplette auswaehlbare Theme-Struktur in iio/theme sowie den internen Ablauf des Theme-Switchings im Manual.

Stand: April 2026, Schema: Family -> Theme -> assets/style.css mit b2b-basierter Vererbung.

Auswaehlbare Gesamtstruktur

Der Theme-Chooser liest alle Top-Level-Ordner unter iio/theme, mappt sie ueber theme-families.json auf Familien und schliesst legacy/families aus der direkten Auswahl aus.

Top Header Control Center (aktuell)

Die Steuerung sitzt im Shell-Header (iio/theme/_shell.js). Der fruehere Standalone-Picker wird nicht mehr separat unterhalb der Navigation gemountet.

Preset-Profile (aktueller Stand)

• CTO Focus: EN, technical, compact, 100%, expanded, Family core, Theme b2b.
• Ops Daily: DE, technical, compact, 100%, expanded, Family intelego, Theme modern.
• Training Enablement: DE, training, detailed, 110%, compact, Family storyworld, Theme magic.
• Custom: automatisch aktiv, sobald Einzelwerte manuell geaendert werden.

URL-Parameter (Deep Links fuer Header-State)

Beim Teilen einer Ansicht werden diese Query-Parameter gesetzt und beim Laden ausgewertet:

• preset = custom|cto|ops|training
• lang = de|en
• style = technical|business|training
• density = compact|normal|detailed
• size = 90|100|110|120
• nav = compact|expanded
• sync = off|on
• family = Theme-Family-ID
• theme = Theme-ID

Top-Level Directory Status (Cleanup)

Diese Tabelle zeigt alle vorhandenen Top-Level-Ordner in iio/theme mit aktuellem Status und empfohlener Aufraeum-Aktion.

Interner Aufbau

1. Discovery

• theme-switcher.js liest per Directory Listing die Unterordner von iio/theme.
• Ordner legacy und versteckte Ordner werden bewusst gefiltert.
• Jeder verbleibende Ordner wird als Theme-ID behandelt.

2. CSS-Aufloesung

• Resolver-Prio pro Theme: assets/style.css → style.css → theme.css → theme-*.css.
• Durch die Migration ist fuer alle aktiven Themes bereits assets/style.css vorhanden.

3. Aktivierung

• Der aktive Link wird als #iio-active-theme-link in den Head gesetzt.
• Andere Theme-Stylesheet-Links werden deaktiviert, damit nur ein Theme gleichzeitig aktiv ist.
• Zusatzfarben werden via CSS-Variablen auf :root gesetzt.

4. Persistenz

• Storage-Key: iio-theme-preference
• Gespeichert wird die Theme-ID, nicht der Dateipfad.

Wie es im Manual verdrahtet ist

• manual/*.html laden ../theme/_shell.js.
• _shell.js setzt Navigation plus Header-Control-Center und laedt theme-switcher.js.
• theme-switcher.js liefert Discovery/Resolver/Persistenz; die eigentliche Steuer-UI wird im Header gehostet.

Kernpfade: iio/theme/_shell.js, iio/theme/theme-switcher.js, iio/theme/*/assets/style.css

Operator Branding im Header

Manual-Seiten zeigen links neben IIO nicht das aktive Tenant-Logo, sondern das Branding des Tenants, der den Space aktuell betreibt.

• Quelle der Wahrheit: specs/root/SPACE-OPERATOR-CONFIG.yaml
• Der Sync iio/specs/scripts/sync-public-state.sh schreibt daraus public/data/workspace-state.js.
• _shell.js laedt diesen State zur Laufzeit und setzt daraus Favicon und Label-Fallbacks fail-closed.
• Tenant-Seiten bleiben davon getrennt und nutzen weiter ihr eigenes Theme-Logo.

space_operator:
  tenant: intelego
  brand_label: Intelego
  favicon_rel: families/intelego/classic/assets/brand/favicon-32.png

Developer Checkliste fuer neue Themes

1. Neuen Ordner unter iio/theme/THEME_ID anlegen.
2. iio/theme/THEME_ID/assets/style.css erstellen.
3. Inhalt mit @import url('../../b2b/solution-provider/assets/style.css'); starten.
4. Eigene Variablen in :root setzen (navy, blue-dark, blue-mid, blue-light, info).
5. Seite neu laden und Theme im Chooser auswaehlen.

Baukasten-Prinzip fuer Entwickler

Der IIO-Ansatz ist ein Baukasten mit klaren Schichten. Statt jede Seite neu zu bauen, werden stabile Bausteine kombiniert: Shell, Switcher, Basis-CSS und Theme-Overrides.

Wo was hingehoert (Ablage-Regeln)

• Globale Theming-Logik nur in theme-switcher.js. Keine Duplikate pro Seite.
• Globale Manual-Navigation nur in _shell.js. Seiten selbst sollen keine eigene fixe Nav-Struktur pflegen.
• Theme-spezifische Farbe und Akzent in THEME_ID/assets/style.css.
• Komponenten-Styles fuer alle Themes in der b2b-Basisdatei.
• Seitenlokale Spezialfaelle in der jeweiligen Manual-Seite, aber nur wenn wirklich seitengebunden.

Faustregel: Verhalten zentral, Erscheinung pro Theme, Inhalt pro Seite.

Wie man mit dem Baukasten programmiert

Use Case A: Neue Manual-Seite bauen

1. Neue Seite unter iio/manual/ anlegen.
2. Basis-CSS-Link setzen: ../../../iio/theme/families/b2b/solution-provider/assets/style.css.
3. Am Ende <script src="../../../iio/theme/_shell.js"></script> einbinden.
4. Seiteninhalt als Cards/Tabellen/Panel schreiben, keine eigene Theme-Auswahl implementieren.
5. Seite in iio/manual/index.html verlinken.

Use Case B: Neues Theme hinzufuegen

1. Ordner anlegen: iio/theme/mein-theme/.
2. Datei anlegen: iio/theme/mein-theme/assets/style.css.
3. Startinhalt: Import der b2b-Basis plus eigene :root-Variablen.
4. Reload im Browser: Theme erscheint automatisch im Dropdown (Discovery ueber Ordnername).
5. Theme auswaehlen, visuell pruefen, danach feinjustieren.

Use Case C: Systemweites UI-Verhalten aendern

1. Komponenten-Style global: b2b-Basisdatei anpassen.
2. Theme-spezifische Abweichungen: nur in den Adapter-Dateien je Theme.
3. Resolver/Persistenz/Dropdown: theme-switcher.js.
4. Navigation/Seitenliste: _shell.js.

Use Case D: Betreiber des Space wechseln

1. specs/root/SPACE-OPERATOR-CONFIG.yaml anpassen.
2. bash iio/specs/scripts/sync-public-state.sh /home/zolo/space ausfuehren.
3. Manual neu laden und Header-Favicon gegen Betreiber-Brand pruefen.
4. Tenant-Seiten separat pruefen, damit deren Theme-Logo unveraendert bleibt.

Konkretes Starttemplate fuer ein neues Theme

/* iio/theme/mein-theme/assets/style.css */
@import url('../../b2b/solution-provider/assets/style.css');

:root {
  --color-navy: #1a2742;
  --color-blue-dark: #2a4876;
  --color-blue-mid: #3c6aa8;
  --color-blue-light: #5f90d2;
  --color-info: #2f6fa8;
}

Damit nutzt das Theme alle Basis-Komponenten sofort und ueberschreibt nur die Identitaetsfarben.

Technischer Ablauf beim Laden (intern)

1. Manual-Seite laedt _shell.js.
2. _shell.js stellt Navigation sicher und laedt theme-switcher.js.
3. Switcher liest Theme-Ordner unter iio/theme.
4. Pro Theme wird CSS nach Prioritaet aufgeloest (normalerweise direkt assets/style.css).
5. Aktives Theme wird in #iio-active-theme-link geladen.
6. Nicht aktive Theme-Stylesheets werden deaktiviert.
7. Theme-ID wird in LocalStorage gespeichert und beim naechsten Laden wiederhergestellt.

Debugging-Guide (wenn etwas nicht funktioniert)

Release-Checkliste fuer menschliche Developer

1. Jedes aktive Theme hat assets/style.css.
2. Jede Manual-Seite bindet _shell.js ein.
3. Theme-Wechsel funktioniert auf Desktop und Mobile.
4. Kontrast fuer Text/Links ist lesbar.
5. Keine inline Hotfixes in einzelnen Seiten, die globale Regeln brechen.
6. Neue Seite ist in Hub und Shell-Navigation verlinkt.