SIRIUS 3 Theme individualisieren

Mit SIRIUS 3 wird die Theme Toolbox 4.2 installiert. Sie bringt zwei Werkzeuge mit, um das Theme an dein Projekt anzupassen:

• den Live-Editor im Frontend – für Farben, Schriften und Abstände, direkt auf der echten Seite
• den Theme Editor im Backend – für alles darüber hinaus: SCSS- und JavaScript-Varianten, Icons, Bilder und Webfonts

Wo liegen die Theme-Dateien?

Mit SIRIUS 3 hat sich die Verzeichnisstruktur geändert:

Ordner	Inhalt
layout/sirius-theme/	Originaldateien des Themes – nicht direkt bearbeiten, werden bei Updates überschrieben
layout/custom/	Eigene Varianten und projektspezifische Anpassungen – bleiben bei Updates erhalten
assets/nutshell/	Nutshell Framework – die Basis aller unserer Themes, wird über Composer installiert und aktualisiert – nicht bearbeiten

Anpassungen werden also nicht in layout/sirius-theme/ vorgenommen, sondern als Variante unter layout/custom/ abgelegt. Sowohl der Live-Editor als auch der Theme Editor übernehmen das Anlegen der Varianten automatisch.

Auch im Ordner assets/nutshell/ solltest du keine Änderungen vornehmen – sie würden beim nächsten Update überschrieben. Werte aus dem Nutshell Framework überschreibst du stattdessen über die _variables.scss und die _config.scss des Themes (siehe Abschnitt Variablen und Konfiguration).

Der Live-Editor

Der Live-Editor bearbeitet die Design-Token des Themes – Farben, Typografie, Abstände und Form – als Overlay direkt auf der echten Seite, mit sofortiger Vorschau.

Einschalten

Der Live-Editor ist ein Werkzeug für die Design-Phase und standardmäßig ausgeschaltet. Du aktivierst ihn in der Contao-Systemwartung über den Schalter „Frontend-Editor anzeigen". Ist die Gestaltung abgeschlossen, schaltest du ihn dort wieder aus.

Solange er aktiviert ist, erscheint für eingeloggte Backend-Benutzer:innen auf jeder Frontend-Seite unten mittig die Dock-Pille „Theme bearbeiten". Für Besucher:innen ohne Login bleibt das Frontend unberührt.

Vorlagen: die SIRIUS-Farbwelten

Am schnellsten kommst du über den Tab Vorlagen zu einem Ergebnis. SIRIUS 3 bringt drei fertige Farbwelten mit:

Vorlage	Beschreibung	Eckenradius
Waldgrün	Sattes Naturgrün, ruhiger als das helle Limettengrün	4px
Terrakotta	Warme Erdtöne für Stein, Terrasse und Wegebau	6px
Schiefer	Anthrazit mit Moosgrün, für moderne Gartenarchitektur	0

Ein Klick setzt Marken- und Sekundärfarbe, die beiden Artikelhintergründe sowie den Eckenradius. Anschließend kannst du in der Maske weiter nachjustieren. Alle drei Farbwelten sind auf ausreichenden Kontrast geprüft, auch im Dark Mode.

Was sich einstellen lässt

Die Maske wird aus einer Token-Registry erzeugt. SIRIUS liefert dazu eine eigene tokens.json mit, die die Basis-Registry der Theme Toolbox ergänzt. Editierbar sind:

• Markenfarbe (--color-brand) – das SIRIUS-Grün
• Sekundärfarbe (--color-brand-secondary) – das Türkis, das Überschriften, Links, Footer, Navigation und Akkordeon trägt
• Text auf Markenfarbe (--color-on-brand) – Schrift auf Buttons und im Highlight-Artikel. Folgt automatisch der dunklen Sekundärfarbe.
• Text auf Overlays (--color-on-overlay) – Schrift auf den Overlays von Card, Kontakt und Galerie sowie im Zitat. Folgt automatisch der Sekundärfarbe mit 70 % Schwarz.
• Getönter Artikelhintergrund (--article-tint-background)
• Dunkler Artikelhintergrund (--article-dark-background)
• Basis-Schrift und Überschriften-Schrift
• Basis-Abstand (--base-spacing-unit, von 1 bis 2 in Schritten von 0,125)
• Eckenradius (--base-border-radius)

Text auf Markenfarbe und Text auf Overlays musst du nur anfassen, wenn die abgeleitete Farbe auf deiner Markenfarbe nicht genug Kontrast hat – etwa bei einer dunklen Markenfarbe, auf der weiße Schrift besser passt. Sobald du einen eigenen Wert setzt, folgt die Farbe der Sekundärfarbe nicht mehr. Welche Kontraste nötig sind, steht unter Barrierefreiheit in SIRIUS 3.

Alles Abgeleitete ist bewusst nicht editierbar:

• --color-brand-dark, --color-brand-secondary-dark und --color-brand-secondary-light entstehen per color-mix() aus ihrer jeweiligen Grundfarbe – änderst du die Markenfarbe, zieht die dunkle Variante automatisch nach. --color-brand-secondary-light färbt im Dark Mode Überschriften, Navigation und Links.
• --color-highlight erbt von der Markenfarbe, --links-color-hover und --button-background-hover folgen der Sekundärfarbe
• --base-overlay-background-brand ist die Markenfarbe mit 85 % Deckkraft

So bleibt das Farbsystem in sich stimmig: Zwei Grundfarben genügen, der Rest folgt.

Speichern

Während des Gestaltens werden die Werte nur zur Laufzeit als CSS Custom Properties ins :root geschrieben – es ist also noch nichts gespeichert. Erst „Übernehmen" schreibt server-seitig.

Dabei ersetzt der Editor die geänderten Variablen direkt an Ort und Stelle in deiner Custom-_variables.scss – genau so, wie du es von Hand tun würdest. Nur tatsächlich geänderte Werte werden geschrieben, unberührte Token behalten ihren Ausdruck. Danach wird das Theme neu kompiliert.

Das hat einen angenehmen Nebeneffekt: Deine Gestaltung ist Teil der Theme-Quelle – sichtbar, reviewbar und deploybar. Rückgängig machen lässt sie sich im Backend über Theme-Toolbox » Theme Editor » Styles (Diff und „Original wiederherstellen").

Eingehende Werte werden gegen die Registry geprüft – unbekannte Properties werden verworfen, Werte auf ihren erlaubten Bereich geklemmt und auf ausreichenden Kontrast abgesichert.

Wichtig bei Theme-Updates: Sobald du im Live-Editor etwas übernommen hast, existiert eine eigene _variables.scss unter layout/custom/. Neue oder geänderte Variablen aus einem Theme-Update erreichen dein Projekt dann nicht automatisch. Öffne nach jedem Update die _variables.scss im Theme Editor und übernimm über Unterschiede anzeigen, was neu hinzugekommen ist.

Schriften im Live-Editor

Der Font-Picker nutzt dieselbe Google-Fonts-Funktion wie der Theme Editor: Die Schrift wird einmalig server-seitig heruntergeladen, self-hosted abgelegt und per @font-face registriert. Der Browser deiner Besucher:innen lädt ausschließlich die lokale Datei – es entsteht kein Google-Request im Frontend und damit kein DSGVO-Problem.

Theme-Anpassungen über den Theme Editor

Alles, was über Design-Token hinausgeht, machst du im Backend unter Theme-Toolbox » Theme Editor.

In der Dateibaum-Ansicht erkennst du sofort, welche Dateien projektspezifisch angepasst sind:

• Fett gedruckt mit Sternchen (*) = Variante – die Datei weicht vom Original ab und wird aus layout/custom/ geladen
• Normale Schrift = unveränderte Originaldatei aus layout/sirius-theme/

Wenn du eine Datei öffnest, kannst du:

• den Inhalt direkt im Editor bearbeiten
• über Unterschiede anzeigen den Diff zwischen Original und Variante einsehen
• über Original wiederherstellen die Variante entfernen, sodass wieder die Originaldatei verwendet wird

Hinweis: Änderungen sind unmittelbar im Frontend sichtbar. Du musst weder den Cache leeren, noch unter Systemwartung die Option „Skript Cache umgehen (im Produktivbetrieb)" aktivieren. Der Compiler der Theme Toolbox erkennt Änderungen an den SCSS-Dateien automatisch.

Eigene SCSS-Dateien hinzufügen

Für eigene Komponenten – z.B. ein Modal – legst du im Theme Editor einfach eine neue SCSS-Datei an, etwa components/_modal.scss. Anschließend ergänzt du sie in der default.scss:

// COMPONENTS
// …
@import 'components/description-list';
@import 'components/modal';

Sowohl deine neue Datei als auch die geänderte default.scss werden unter layout/custom/ gespeichert. Die Theme Toolbox sucht jede importierte Datei zuerst dort und erst danach im Original – deshalb reicht der Pfad relativ zum SCSS-Ordner.

Wichtig: Sobald eine Variante der default.scss existiert, verwendet die Toolbox nur noch diese. Bringt ein Theme-Update neue Dateien mit, die in der Original-default.scss importiert werden, musst du sie in deiner Variante nachtragen. Über Unterschiede anzeigen siehst du nach einem Update schnell, was sich geändert hat.

Alternative: Direkt im Code-Editor

Wenn dir der Theme Editor nicht zusagt, kannst du sämtliche Anpassungen auch direkt auf Dateiebene unter layout/custom/ mit dem Code-Editor deiner Wahl vornehmen. Auch dann sind die Änderungen unmittelbar im Frontend sichtbar.

Variablen und Konfiguration

Das Aussehen von SIRIUS wird im Wesentlichen über zwei Dateien gesteuert:

Datei	Inhalt
_variables.scss	CSS Custom Properties (CSS-Variablen) für Farben, Schriften, Abstände, Größen usw. – inklusive des Dark-Mode-Blocks. Sie wirken zur Laufzeit im Browser – genau diese Werte bearbeitet auch der Live-Editor.
_config.scss	Sass-Variablen, die beim Kompilieren ausgewertet werden, z.B. die maximale Seitenbreite und die Breakpoints

Die _config.scss

In der _config.scss legt SIRIUS unter anderem diese Werte fest:

$wrapper-max: 72em;

$breakpoints: (
  // xs, sm, md …
  lg: (
    min:        58.75em, // 940px
    max:        (75em - $max-diff), // 1199px
  ),
  xl: (
    min:        75em, // 1200px
    max:        'none'
  )
);

$additional_breakpoints: (
  menu: (
    min:        61.25em, // 980
    max:        (61.25em - $max-diff), // 980
  )
);

$nav-mobile-number-of-menu-points:  6;

• $wrapper-max – die maximale Breite des Inhaltsbereichs
• $breakpoints – die Breakpoints für das Grid (xs bis xl). SIRIUS lässt den xl-Bereich erst ab 75em (1200px) beginnen.
• $additional_breakpoints – zusätzliche Breakpoints. SIRIUS definiert hier den Breakpoint menu: Ab 61.25em (980px) wird die Hauptnavigation als Desktop-Navigation dargestellt, darunter als mobiles Menü. Hat dein Menü viele Punkte, kannst du den Wert erhöhen. Für den Breakpoint werden außerdem eigene Grid-Klassen erzeugt.
• $nav-mobile-number-of-menu-points – für so viele Menüpunkte wird im mobilen Menü eine gestaffelte Einblend-Animation erzeugt. Hat deine Hauptnavigation mehr Punkte, erhöhst du den Wert.

Variablen aus dem Nutshell Framework überschreiben

SIRIUS basiert auf dem Nutshell Framework, das viele weitere Variablen definiert. Beide Dateien sind so aufgebaut, dass du jede Nutshell-Variable im Theme überschreiben kannst – ohne assets/nutshell/ anzufassen:

• Sass-Variablen: Die _config.scss setzt zuerst die SIRIUS-Werte und importiert am Ende die Nutshell-Konfiguration. Dort sind alle Werte mit !default definiert und greifen nur, wenn das Theme sie nicht bereits gesetzt hat. Genau so überschreibt SIRIUS z.B. $wrapper-max (in Nutshell 66.625em), die Grenze zwischen lg und xl (in Nutshell 68.75em) und den Breakpoint menu (in Nutshell 48em). Eigene Werte ergänzt du deshalb immer oberhalb des @import am Ende der Datei.
• Custom Properties: Die _variables.scss importiert zuerst die Nutshell-Variablen und überschreibt sie anschließend im :root-Block. Möchtest du eine Nutshell-Variable ändern, die SIRIUS bisher nicht anpasst, ergänzt du sie einfach im :root-Block deiner _variables.scss.

Welche Variablen es gibt, siehst du in assets/nutshell/scss/_config.scss und assets/nutshell/scss/_variables.scss – nur zum Nachschlagen, nicht zum Bearbeiten.

Erste Anpassungen vornehmen

1. Hauptfarben anpassen

Was du im Live-Editor klickst, kannst du genauso gut direkt in der _variables.scss schreiben. Im Abschnitt GENERAL/COLORS findest du die Farbzuweisungen. In SIRIUS sind sie wie folgt definiert:

// GENERAL/COLORS
--color-gray-light: #c6c6c6;
--color-brand: #a7d60f;
--color-brand-dark: color-mix(in srgb, var(--color-brand), black 45%);
--color-brand-secondary: #228080;
--color-brand-secondary-dark: color-mix(
  in srgb,
  var(--color-brand-secondary),
  black 30%
);
--color-brand-secondary-light: color-mix(
  in srgb,
  var(--color-brand-secondary),
  white 60%
);
// Markenfarbe als Schrift auf dem Seitenhintergrund (Zähler, aktive Navigation)
--color-brand-text: var(--color-brand-dark);
// Schrift auf Flächen in der Markenfarbe (Buttons, Highlight-Artikel)
--color-on-brand: var(--color-brand-secondary-dark);
// Schrift auf den halbtransparenten Overlays (Card, Kontakt, Galerie, Zitat):
// fast schwarz, damit der Kontrast auch über dunklen Bildern reicht
--color-on-overlay: color-mix(in srgb, var(--color-brand-secondary), black 70%);
--color-highlight: var(--color-brand);
--color-text: #555;
--color-text-inverted: #fff;
--color-page-background: #fff;

SIRIUS arbeitet mit zwei Grundfarben: --color-brand trägt das Grün, --color-brand-secondary das Türkis. Um die Markenfarbe zu ändern, ersetzt du

--color-brand: #a7d60f;

durch eine eigene Variable:

--color-brand: var(--color-blue);

oder einen Farbwert:

--color-brand: #2283ce;

Die Sekundärfarbe --color-brand-secondary wird an prominenter Stelle verwendet – unter anderem für die Überschriften (--headings-color: var(--color-brand-secondary)), für Links, den Footer, die Navigation und das Akkordeon. Wenn du nur --color-brand änderst, bleiben die Überschriften türkis.

Links stehen seit SIRIUS 3.1 in der Sekundärfarbe, weil das helle Grün auf Weiß nicht genug Kontrast hat. Die Schrift auf grünen Flächen steuern --color-on-brand und --color-on-overlay. Beide folgen automatisch der Sekundärfarbe. Reicht das auf deiner Markenfarbe nicht, setze sie im Live-Editor auf einen eigenen Wert. Mehr dazu unter Barrierefreiheit in SIRIUS 3.

Wichtig: Prüfe deine Farben immer auch im Dark Mode, ob der Kontrast noch ausreicht. Ist im Betriebssystem das dunkle Farbschema aktiv, wechseln Seitenhintergrund und Textfarbe. Überschriften, Navigation und Links nutzen dann automatisch die helle Variante der Sekundärfarbe (--color-brand-secondary-light). Eine sehr helle Sekundärfarbe kann trotzdem auf dunklem Grund abfallen.

2. Artikelhintergründe anpassen

Möchtest du einen Artikelhintergrund unabhängig von den Grundfarben ändern, findest du weiter unten in der _variables.scss den Abschnitt BASE/ARTICLE:

// BASE/ARTICLE
--article-highlight-background: var(--color-highlight);
--article-highlight-text: var(--color-on-brand);
--article-tint-background: #ececec;
--article-tint-accent: var(--color-brand-secondary-dark);
--article-dark-background: #554236;
--article-dark-text: var(--color-text-inverted);

Diese Variablen werden in base/_article.scss verwendet und geben dir die Möglichkeit, Artikel farbig zu hinterlegen. Standardmäßig hat zum Beispiel der Bereich Kontakt in der Demo einen grünen Hintergrund. Das kommt zustande, weil der Artikel die Klasse article--highlight trägt und in der Klasse der Wert der Variable --article-highlight-background verwendet wird.

Die drei Hintergründe verhalten sich unterschiedlich:

• --article-highlight-background folgt der Markenfarbe (über --color-highlight). Wer den Highlight-Bereich unabhängig davon einfärben will, überschreibt die Variable direkt:

  --article-highlight-background: #f94300;
  

• --article-tint-background und --article-dark-background tragen ihre eigenen Farbwerte. Sie verweisen nicht mehr auf Grauwerte, sondern lassen sich direkt setzen – und sind genau deshalb auch im Live-Editor editierbar.

Überschriften, Links und Fokusrahmen passen sich in den drei Artikelvarianten automatisch an: Im Highlight-Artikel tragen sie die Farbe von --article-highlight-text, im getönten Artikel --article-tint-accent, im dunklen Artikel die Textfarbe. Änderst du einen Hintergrund, prüfe den Kontrast zu diesen Farben.

Solltest du mit der Anpassung der Variablen nicht ans Ziel kommen, hast du immer noch die Möglichkeit, in der _article.scss direkt Anpassungen vorzunehmen.

3. Dark Mode berücksichtigen

SIRIUS bringt seit Version 2.1.0 einen Dark Mode mit: Ist im Betriebssystem das dunkle Farbschema gewählt, wird z.B. statt des weißen ein dunkler Hintergrund verwendet.

Die Variablen dafür stehen am Ende der _variables.scss in einem eigenen Block:

// DARK MODE
@media (prefers-color-scheme: dark) {
  :root {
    color-scheme: dark;
    --color-page-background: #111;
    --color-text: #fff;
    --base-border-color: rgba(255, 255, 255, 0.2);
    --headings-color: var(--color-brand-secondary-light);
    --links-color: var(--color-brand-secondary-light);
    // …
  }
}

Je nach Theme-Anpassung kann es notwendig sein, weitere Variablen für den Dark Mode zu ergänzen bzw. bestehende zu überschreiben – etwa wenn deine Markenfarbe auf dunklem Grund zu wenig Kontrast bringt.

4. Schriften anpassen

In der SIRIUS-Demo verwenden wir standardmäßig die Roboto für Fließtexte und die Roboto Slab für Überschriften. Beide werden lokal vom eigenen Server geladen.

Neben dem Font-Picker im Live-Editor bietet auch der Theme Editor einen eigenen Bereich für Webfonts mit zwei Wegen:

Variante A: Aus dem Google-Webfont-Katalog installieren

Im Theme Editor lässt sich der Google-Webfont-Katalog direkt durchsuchen. Mit zwei Klicks wird die gewünschte Schrift installiert – die Theme Toolbox lädt die Font-Dateien automatisch nach layout/custom/fonts und ergänzt die passende @font-face-Deklaration in base/_fonts.scss. Es wird keine Verbindung zu Google-Servern aufgebaut (DSGVO-konform).

Variante B: Eigene Webfonts manuell hochladen

Alternativ lassen sich Schriftdateien (woff2, ttf, woff) manuell hochladen – z.B. lizenzierte Schriften aus deinem Bestand.

Schriftart in den Variablen aktivieren

In beiden Fällen muss die Schrift anschließend noch in der _variables.scss eingetragen werden, damit sie auch verwendet wird:

--base-font-family-serif: 'Roboto Slab', georgia, 'Times New Roman', serif;
--base-font-family-sans-serif: 'Roboto', arial, helvetica, sans-serif;
--base-font-family: var(--base-font-family-sans-serif);

Die Überschriften greifen im Abschnitt BASE/TYPE auf die Serifen-Schrift zurück:

// BASE/TYPE
--headings-font-family: var(--base-font-family-serif);

Ersetze einfach die Schriftnamen durch die deiner installierten Schriftarten. Nicht mehr benötigte Schriften lassen sich im Theme Editor über den Button „Ungenutzte @font-face bereinigen" entfernen.

5. Icons und Bilder ersetzen

Im Theme Editor gibt es einen eigenen Tab Bilder, in dem sämtliche Bilder und Icons aus layout/sirius-theme/img verwaltet werden. Erlaubt sind JPG, JPEG, PNG, GIF, SVG, WebP und AVIF bis 5 MB.

• Ersetzen – z.B. um das mitgelieferte logo.svg durch dein Kundenlogo auszutauschen. Die neue Datei wird unter layout/custom/img abgelegt, das Original bleibt unberührt; in der Vorschau werden beide nebeneinander dargestellt.
• Hinzufügen – neue Bilder und Unterordner lassen sich direkt im Custom-Bereich anlegen.
• Umbenennen & Löschen – beim Löschen einer Überschreibung wird automatisch wieder das Original verwendet.

6. Eigene JavaScript-Varianten

Wie bei den SCSS-Dateien lassen sich auch JavaScript-Dateien als Variante anlegen. SIRIUS liefert animations.js und navigation.js mit; die Theme Toolbox verwendet dann automatisch deine Variante aus layout/custom/js statt der Originaldatei.

Auch hier stehen Diff-Ansicht und Revert-Funktion zur Verfügung. Zusätzlich kannst du eigene Skripte anlegen und im Seitenlayout einbinden.

Templates anpassen mit dem Template Studio

SIRIUS 3 liefert seine Templates als Twig aus dem Theme-Bundle aus. Anpassungen erfolgen nicht mehr über templates/*.html5, sondern über das Template Studio im Contao-Backend (verfügbar ab Contao 5.7).

So gehst du vor:

1. Öffne im Backend Layout » Template Studio.
2. Suche das Template, das du anpassen möchtest.
3. Lege eine projektspezifische Kopie an und passe sie im Template Studio an.

Hinweis zur Übergangszeit: Wenn du aus einem SIRIUS-2-Projekt kommst und noch eigene .html5-Templates im templates/-Ordner hast, funktionieren diese zunächst weiter – Contao 5.7 zieht ein vorhandenes .html5-Template einem gleichnamigen Twig-Template vor. Möchtest du ein neues Twig-Template testen, das den gleichen Namen wie ein altes .html5-Template hat, musst du die alte Datei vorher umbenennen (z.B. in js_nav--mobile.html5.bak). Sonst greift das Twig-Pendant nicht.

Welche Templates SIRIUS selbst mitbringt und was darin geändert ist, steht unter Angepasste Templates. Eine Einführung in Twig-Templates für Contao findest du in der offiziellen Contao-Dokumentation.

Hilfsklassen verwenden

Klassen für Abstände

Standardmäßig haben alle im Theme gestalteten Elemente und Module einen Abstand, der auf der --base-spacing-unit basiert. Auch Artikel (.mod_article) haben standardmäßig einen Abstand nach oben und unten.

Je nach Inhalt und Layout möchtest du Abstände vergrößern oder verkleinern. In SIRIUS 3 sind die Hilfsklassen bereits über die Theme Toolbox definiert, d.h. du kannst sie direkt in den Inhaltselementen auswählen.

Abstände lassen sich über folgende Klassen realisieren:

• m-t-0 bis m-t-5 (Außenabstand oben 0 bis 5)
• m-b-0 bis m-b-5 (Außenabstand unten 0 bis 5)
• p-t-0 bis p-t-5 (Innenabstand oben 0 bis 5)
• p-b-0 bis p-b-5 (Innenabstand unten 0 bis 5)

Die Abstände basieren auf der --base-spacing-unit und werden mit dem jeweiligen Wert multipliziert. Also ist p-t-1 = (--base-spacing-unit * 1) und p-t-5 = (--base-spacing-unit * 5).

Diese Klassen kannst du sowohl für Artikel als auch für Elemente und Module verwenden. Wir empfehlen, Innenabstände vor allem für Artikel und Außenabstände vor allem für Elemente zu verwenden.

Klassen für Artikel

In den Artikeleinstellungen kannst du weitere Klassen hinzufügen und so das Aussehen des Artikels anpassen. Mit folgenden Klassen, die in base/_article.scss definiert und ebenfalls in der Theme Toolbox hinterlegt sind, beeinflusst du Hintergrund, Textfarbe und Breite:

• Artikel Highlightfarbe: .article--highlight
• Artikel hell: .article--tint
• Artikel dunkel: .article--dark
• Artikel volle Breite: .article--full

Mit .article--full bzw. der Klasse .hero entfernst du die standardmäßig vorhandenen Abstände links und rechts, sodass der Inhalt über die komplette Breite geht. Die Klasse .hero entfernt darüber hinaus noch das Padding oben und unten.