---
title: "Themes"
description: "Das Erscheinungsbild der ganzen Plattform anpassen: Aufbau eines Themes, theme.json, Beispiel zum Herunterladen, Kopie als Startpunkt"
---

Ein **Theme** legt fest, wie die gesamte Plattform aussieht: Farben, Schriften, Rundungen, Logo, Favicon und App-Icons – auf allen Seiten, in allen Communities, im hellen und im dunklen Modus. Es besteht nur aus statischen Dateien (JSON, CSS, Bilder, Schriften) und kommt ohne Programmcode aus. Eigene Themes laden Sie als ZIP-Datei im Plattform-Admin hoch; sie liegen dann im Speicher Ihrer Installation. Updates der Plattform lassen ein Theme unberührt, solange es sich an die hier beschriebenen Schnittstellen hält.

In der Oberfläche und in den Umgebungsvariablen heißt ein Theme **Template** (Plattform-Admin → **Darstellung**, `APP_TEMPLATE`). Gemeint ist dasselbe.

| Seite | Inhalt |
| --- | --- |
| Diese Seite | Aufbau, `theme.json`, Startpunkte, Testen |
| [Theme-Editor](/anpassen/theme-editor) | Ein Theme ohne CSS-Kenntnisse im Plattform-Admin gestalten: Farben, Rundungen, Schriften, Logo, Vorschau, Kontrastprüfung |
| [Theme gestalten](/anpassen/theme-gestalten) | Design-Tokens, hell/dunkel, Schriften, Logo, `data-ui`-Haken, Rezepte, Kontrast |
| [Theme installieren](/anpassen/theme-installieren) | Ein eigenes Theme als ZIP-Datei im Plattform-Admin hochladen oder per Konsole einspielen (`app:theme:validate`, `app:theme:import`, `app:theme:list`, `app:theme:export`), neue Fassung, vorige Fassung, löschen |

## Mitgelieferte Themes

| Theme | Aussehen |
| --- | --- |
| `quicktribe` | Standard: ruhiges Grau, Systemschrift, hell oder dunkel nach Systemeinstellung |
| `mitternacht` | Beispiel: dunkles Nachtblau mit Indigo-Akzent und runden Knöpfen; startet dunkel |
| `arena` | Gaming/E-Sport: fast schwarzes Violett mit Neon-Cyan und Magenta, Glas-Kopfleiste mit fließender Leuchtlinie, Hero als Arena mit Rasterboden, Schriften Oxanium und Exo 2; startet dunkel |
| `verein` | Sportverein: Vereinsgrün mit Weiß und Gold, Trikotstreifen in der Kopfleiste, Hero als Spielfeld, Schriften Oswald und Atkinson Hyperlegible Next; startet hell |
| `schuetzen` | Schützenverein: Schützengrün mit Messing auf hellem Leinen, ruhige grüne Kante mit Messinglinie in der Kopfleiste, Hero mit Schießscheibe, Emblem Schießscheibe mit gelbgrünem Rand, Schriften Oswald und Atkinson Hyperlegible Next; startet hell |
| `reiterhof` | Reitverein und Reiterhof: Sattelleder und Creme, Kopfleiste mit Steppnaht wie an einem Sattelblatt, Hero mit Hufeisen, Emblem Hufeisen, Schriften Newsreader und Atkinson Hyperlegible Next; startet hell |
| `parcours` | Turniersportlicher Reitverein: Bordeaux mit Schleifengold, Kopfleiste mit rot-weißer Hindernisstange, Hero mit Turnierschleife, Emblem Turnierschleife, Schriften Oswald und Atkinson Hyperlegible Next; startet hell |
| `business` | Unternehmen: Dunkelblau, Anthrazit und dezentes Kupfer, viel Weißraum, zurückhaltende Rundungen, unterstrichene Navigation, Schriften Newsreader und Public Sans; startet hell |

Alle haben eine helle und eine dunkle Variante mit WCAG-AA-Kontrasten. `arena`, `verein`, `schuetzen`, `reiterhof`, `parcours` und `business` sind vollständige Beispiele für die Gestaltung über [`data-ui`-Haken](/anpassen/theme-gestalten): eigene Schriften (variabel, SIL Open Font License, Lizenz unter `fonts/OFL.txt`), SVG-Emblem, App-Icons, umgefärbte Palette je Modus, Hero-Flächen als „Inseln“ mit eigener Palette, Animationen nur ohne `prefers-reduced-motion`. Ihre `theme.css` ist kommentiert, die Kontrastwerte stehen dabei.

Die mitgelieferten Themes stehen auf jeder Installation immer zur Auswahl, dazu die dort hochgeladenen und im [Theme-Editor](/anpassen/theme-editor) gestalteten. Gewählt wird das Theme vom Plattform-Admin unter **Darstellung** (`/admin/appearance`, siehe [Darstellung](/handbuch/plattform-admin/darstellung)) oder fest über die Umgebungsvariable `APP_TEMPLATE` (siehe [Konfiguration](/konfiguration#grundlagen)). Es gilt für die ganze Installation. Communities können darin nur ein eigenes Logo und eine eigene Primärfarbe festlegen (ab 2.1, siehe [Communities mit eigener Farbe und eigenem Logo](/anpassen/theme-gestalten#communities-mit-eigener-farbe-und-eigenem-logo)); Schriften, Flächen und Rundungen kommen immer aus dem Theme. Mitglieder können weiterhin selbst zwischen hell und dunkel umschalten.

## Beispiel-Theme herunterladen

<Tip>
Am schnellsten geht ein eigenes Theme mit dem [Theme-Editor](/anpassen/theme-editor): Farben, Rundungen, Schriften und Logo wählen, Vorschau ansehen, speichern. Das Ergebnis lässt sich als ZIP-Datei herunterladen und mit eigenem CSS weiter verfeinern.
</Tip>

Ausgangspunkt für ein eigenes Theme ist das ausführlich kommentierte Beispiel:

**[beispiel-theme.zip herunterladen](/downloads/beispiel-theme.zip)** (Theme-Schlüssel `beispiel`, frei verwendbar)

Es zeigt alle wichtigen Bausteine: Farben für hell und dunkel, eine eigene Überschriften-Schrift ohne Schriftdateien, weichere Rundungen, Logo für hell und dunkel, Favicon, dezente Gestaltung über `data-ui`-Haken und auskommentierte Rezepte zum Ausprobieren. Die ZIP-Datei lässt sich unverändert im Plattform-Admin hochladen (siehe [Theme installieren](/anpassen/theme-installieren)).

Aus dem Beispiel ein eigenes Theme machen:

1. ZIP-Datei entpacken und das Verzeichnis umbenennen, z. B. in `meine-marke` (nur Kleinbuchstaben, Ziffern und Bindestrich, höchstens 40 Zeichen).
2. In `theme.json` den Wert `key` auf denselben Namen setzen, `name` und `description` anpassen.
3. Farben und Rundungen in `theme.css` ändern, `logo.svg`, `logo-dark.svg` und `favicon.svg` ersetzen.
4. Das Verzeichnis wieder als ZIP-Datei packen (z. B. Rechtsklick → „Komprimieren“ bzw. `zip -r meine-marke.zip meine-marke`), im Plattform-Admin hochladen, wählen und prüfen (siehe [Testen](#testen)).

## Kopie eines vorhandenen Themes als Startpunkt

Im Plattform-Admin unter **Darstellung** hat jedes Theme eine Schaltfläche zum Herunterladen:

- **Kopie herunterladen** bei den mitgelieferten Themes (`quicktribe`, `mitternacht`, `arena`, `verein`, `schuetzen`, `reiterhof`, `parcours`, `business`): Die ZIP-Datei trägt bereits einen eigenen Schlüssel (`mein-quicktribe`, `mein-arena` …) und den Namen mit „(Kopie)“ – sie lässt sich sofort als eigenes Theme wieder hochladen und dann anpassen. `mitternacht/theme.css` ist ausführlich kommentiert und ein guter Ausgangspunkt für ein dunkles Theme; `arena`, `verein`, `schuetzen` und `business` zeigen, wie weit die Gestaltung mit Schriften, Emblem und `data-ui`-Haken gehen kann.
- **Herunterladen** bei hochgeladenen Themes: genau die Dateien der aktuellen Fassung, etwa um sie zu bearbeiten oder auf eine andere Installation zu übertragen.

Für einen anderen Schlüssel genügt beim Hochladen das Feld **Schlüssel** – `theme.json` wird dann angepasst.

## Aufbau

```text
meine-marke/
  theme.json          Pflicht – Beschreibung des Themes (siehe unten)
  theme.css           optional – Design-Tokens und Gestaltung der data-ui-Haken
  fonts/*.woff2       optional – selbst gehostete Schriften, dazu die Lizenzdatei (z. B. fonts/OFL.txt)
  logo.svg            optional – Logo (SVG, PNG oder WebP)
  logo-dark.svg       optional – Logo für den dunklen Modus
  favicon.svg         optional – Favicon (SVG oder PNG)
  icon-192.png        optional – App-Icon 192 × 192 (PWA, Apple-Touch-Icon)
  icon-512.png        optional – App-Icon 512 × 512 (PWA)
  preview.png         optional – Vorschaubild für die Auswahl im Plattform-Admin
```

Als ZIP-Datei dürfen die Dateien direkt in der ZIP-Datei oder in genau einem Ordner liegen. Hochgeladen liegt das Theme im Speicher der Installation und wird unter `/themes/_u/<key>/<version>/…` ausgeliefert; die mitgelieferten Themes liegen im Image unter `public/themes/<key>/` (Adresse `/themes/<key>/…`).

Regeln:

- `key` in `theme.json` ist der **Schlüssel** des Themes: Kleinbuchstaben, Ziffern, Bindestrich, höchstens 40 Zeichen, am Anfang ein Buchstabe oder eine Ziffer. Er muss eindeutig sein; die Schlüssel der mitgelieferten Themes sind vergeben. Der Ordnername in der ZIP-Datei spielt keine Rolle, sollte aber zur Übersicht gleich heißen.
- Alle Dateiangaben in `theme.json` sind relativ zum Theme-Verzeichnis, höchstens ein Unterverzeichnis tief (`fonts/datei.woff2`), ohne `..`.
- Ein Theme enthält kein JavaScript. Schriften, Bilder und CSS kommen ausschließlich aus dem Theme-Verzeichnis (siehe [Sicherheitsregeln](/anpassen/theme-gestalten#sicherheitsregeln-csp)).

## theme.json

Vollständiges Beispiel mit allen Feldern:

```json
{
  "key": "meine-marke",
  "name": "Meine Marke",
  "description": "Hausfarben Petrol und Sand, runde Knöpfe, startet hell.",
  "defaultMode": "system",
  "stylesheet": "theme.css",
  "logo": "logo.svg",
  "logoDark": "logo-dark.svg",
  "showName": true,
  "favicon": "favicon.svg",
  "icons": { "192": "icon-192.png", "512": "icon-512.png" },
  "themeColor": "#0f766e",
  "backgroundColor": "#f6f5f2",
  "fonts": [
    { "family": "Inter", "preload": "fonts/inter-latin-400.woff2" }
  ],
  "preview": "preview.png",
  "swatches": ["#0f766e", "#2dd4bf", "#f6f5f2", "#ffffff"]
}
```

| Feld | Typ | Standard | Bedeutung |
| --- | --- | --- | --- |
| `key` | Text | – | **Pflicht**, Schlüssel des Themes (siehe oben) |
| `name` | Text, ≤ 60 Zeichen | – | **Pflicht**, Anzeigename in der Auswahl |
| `description` | Text, ≤ 300 Zeichen | leer | Kurzbeschreibung in der Auswahl |
| `defaultMode` | `light`, `dark` oder `system` | `system` | Modus für alle, die nicht selbst hell oder dunkel gewählt haben |
| `stylesheet` | Datei `.css` | `theme.css`, falls vorhanden | wird **nach** dem CSS der Anwendung geladen und gewinnt immer |
| `logo` | Datei `.svg`, `.png`, `.webp` | – | Logo in der Kopfleiste (Höhe 2 rem, Breite automatisch) |
| `logoDark` | Datei `.svg`, `.png`, `.webp` | Wert von `logo` | Logo im dunklen Modus |
| `showName` | `true` / `false` | `true` | Plattformname neben dem Logo anzeigen; ohne Logo erscheint der Name immer |
| `favicon` | Datei `.svg`, `.png` | eingebautes Favicon | Symbol im Browser-Tab |
| `icons` | `{"192": png, "512": png}` | eingebaute Icons | App-Icons für die installierte App (PWA) und Apple-Touch-Icon |
| `themeColor` | Farbe `#rrggbb` | `#0f172a` | Farbe der Browserleiste auf Mobilgeräten und im App-Manifest |
| `backgroundColor` | Farbe `#rrggbb` | `#f8fafc` | Hintergrund des Startbildschirms der installierten App |
| `fonts` | Liste `{family, preload?}` | leer | `preload`: eine `.woff2`-Datei, die früh geladen wird. Die `@font-face`-Regeln selbst stehen in `theme.css` |
| `preview` | Datei `.png`, `.webp`, `.jpg`, `.svg` | – | Vorschaubild in der Auswahl im Plattform-Admin |
| `swatches` | Liste `#rrggbb` | leer | Farbmuster in der Auswahl, wenn es kein Vorschaubild gibt |

Weitere Felder in `theme.json` werden ignoriert – etwa `private` aus älteren Versionen.

Ein **hochgeladenes Logo** (Plattform-Admin → Darstellung) hat Vorrang vor Logo, Favicon und App-Icons des Themes. Der **Plattformname** aus dem Plattform-Admin bzw. `APP_NAME` erscheint neben dem Logo, im Seitentitel und als Name der installierten App.

## Testen

1. Theme hochladen (siehe [Theme installieren](/anpassen/theme-installieren)) – Fehler im Paket zeigt der Plattform-Admin sofort beim Hochladen.
2. Im Plattform-Admin unter **Darstellung** das Theme mit **Verwenden** aktivieren. Ist `APP_TEMPLATE` gesetzt, ist die Auswahl gesperrt – dann `APP_TEMPLATE=<key>` setzen und die Anwendung neu starten.
3. Hell und dunkel ansehen (Schalter in der Kopfleiste) und dabei mindestens diese Seiten aufrufen: Startseite, Anmeldung, Landingpage einer Community, Feed, Beitrag, Kurs mit Lektion, Kalender, Mitglieder, Nachrichten, Einstellungen, Plattform-Admin. Auch die Wartungsseite (Zugangsseite) und die Zertifikatsseite eines Kurses nutzen das Theme; Zertifikate drucken immer hell.
4. In den Entwicklerwerkzeugen des Browsers (Konsole und Netzwerk) dürfen keine CSP-Verstöße und keine Fehler 404 auf `/themes/…` erscheinen.
5. Auf dem Smartphone prüfen: Kopfleiste, Navigation, Knöpfe und Dialoge bei schmaler Breite.

Ein fehlerhaftes Paket wird beim Hochladen abgelehnt; der Plattform-Admin listet alle gefundenen Fehler. Häufige Meldungen:

| Meldung | Ursache |
| --- | --- |
| theme.json fehlt (weder direkt in der ZIP-Datei noch in genau einem Wurzelverzeichnis) | Datei fehlt oder liegt eine Ebene zu tief (beim Packen entsteht leicht `meine-marke/meine-marke/theme.json`) |
| theme.json ist kein gültiges JSON | Komma am Ende einer Liste, fehlende Anführungszeichen, Kommentare (JSON kennt keine) |
| „key“ in theme.json fehlt oder ist ungültig | Großbuchstaben, Unterstrich, Leerzeichen oder mehr als 40 Zeichen |
| Der Schlüssel … gehört zu einem mitgelieferten Template | `quicktribe`, `mitternacht`, `arena`, `verein`, `schuetzen`, `reiterhof`, `parcours` oder `business` als Schlüssel – einen eigenen wählen |
| …: Endung nicht erlaubt / Pfad nicht erlaubt | Datei mit fremder Endung (z. B. `.js`, `.html`, `.gif`), Großbuchstaben in der Endung, mehr als ein Unterverzeichnis, versteckte Datei |
| theme.css, Zeile …: url(…) verweist auf eine fremde oder absolute Adresse | Schrift oder Bild von einem fremden Server bzw. mit `/` am Anfang – Datei ins Theme legen und relativ einbinden |
| theme.css, Zeile …: url(…) verweist auf eine Datei, die im Template fehlt | Tippfehler im Dateinamen, Groß- und Kleinschreibung, Datei nicht mitgepackt |
| theme.css, Zeile …: @import ist nicht erlaubt | alle Regeln gehören in die CSS-Datei des Themes |
| …: SVG enthält nicht erlaubte Inhalte | Skript, `onload`-Attribut, eingebettetes HTML oder Verweis auf fremde Adresse in einer SVG-Datei |
| „name“ fehlt / muss Text mit höchstens … Zeichen sein | `name` leer oder zu lang, `description` länger als 300 Zeichen |
| „defaultMode“ muss light, dark oder system sein | Tippfehler, z. B. `Dark` |
| „themeColor“ muss eine Farbe im Format #rrggbb sein | Kurzform `#fff`, Farbname oder `rgb(…)` statt sechsstelligem Hex-Wert |
| „logo“: Dateiname ungültig / Datei … fehlt | falsche Endung, mehr als ein Unterverzeichnis, Datei nicht vorhanden (Groß- und Kleinschreibung beachten) |

Eine neue Fassung wirkt beim nächsten Seitenaufruf. Die Adressen aller Dateien eines hochgeladenen Themes enthalten eine Version, die sich aus dem Inhalt ergibt – Browser laden nach jeder Änderung die neue Fassung, auch Schriften und Bilder, die `theme.css` relativ einbindet. Bis dahin dürfen sie die Dateien dauerhaft zwischenspeichern.

## Eigene Themes auf mehreren Installationen

Eigene Themes kommen per Upload (siehe [Theme installieren](/anpassen/theme-installieren)) oder aus dem [Theme-Editor](/anpassen/theme-editor) auf eine Installation. Sie liegen im Speicher dieser Installation – jede Installation hat ihre eigenen und zeigt in der Auswahl nur diese und die mitgelieferten. Soll dasselbe Theme auf mehreren Installationen laufen, laden Sie dieselbe ZIP-Datei auf jeder hoch (oder laden es auf der ersten herunter und auf den anderen hoch).

Wer ein eigenes Image baut, kann Themes auch unter `public/themes/` ins Image legen (siehe [Hinweis für Entwickler](/anpassen/theme-installieren#hinweis-für-entwickler-theme-im-image)). Solche Themes erscheinen auf jeder Installation mit diesem Image immer in der Auswahl.

<Note>
Frühere Versionen kannten das Feld `"private": true` und die Umgebungsvariable `APP_TEMPLATES`, um Themes im Image erst nach Freischaltung anzuzeigen. Beides gibt es nicht mehr: Das Feld wird ignoriert (ältere Pakete lassen sich unverändert hochladen), die Variable ebenfalls.
</Note>
