Entwicklung

Blöcke, Designs, Stile und Variablen – technisch

Wie Blocktyp, Design, Stile und Theme-Variablen zusammenspielen und wie daraus HTML und CSS entstehen.

Ein Block auf einer Seite entsteht aus vier Teilen: dem Blocktyp (was der Block ist und welche Inhalte er hat), dem Design (Markup und eigenes SCSS), den Stilen (Auswahlen wie „Hintergrund: Dunkel“, die CSS-Klassen setzen) und den Theme-Variablen (Farben, Schriftgrößen, Abstände als CSS Custom Properties). Diese Seite zeigt, wo jedes Teil liegt, wie sie sich gegenseitig verwenden und in welcher Reihenfolge das CSS entsteht. Die vollständige Referenz liegt in deiner Installation unter docs/module/.

1. Blocktyp: module.json

Ein Blocktyp liegt in config/modules/<typ>/. Die module.json beschreibt die Bedeutung des Blocks, nie sein Aussehen:

{
    "type": "headline",
    "level": "element",
    "label": "Überschrift",
    "fields":   { "text":  { "type": "rich", "format": "emphasis", "label": "Text" } },
    "settings": { "level": { "type": "select", "label": "Ebene",
                             "options": ["h1", "h2", "h3"], "default": "h2" } }
}

Faustregel: Felder sind Inhalt, Einstellungen haben eine Bedeutung (SEO, Verhalten), reine Optik wie Farbe, Größe oder Ausrichtung ist ein Stil.

2. Design: variants/<id>

Jedes Design eines Blocktyps besteht aus bis zu drei Dateien in config/modules/<typ>/variants/. Im Block-Studio entsprechen sie den Reitern:

Der Renderer hängt an das äußere Element feste Klassen: bloqy-element (bzw. -section, -layout), bloqy-type-<typ> und bei Designs mit SCSS die Scope-Klasse mv-<id>. Seiten speichern nur den Verweis (type, variant) und ihre Werte; eine Änderung am Design wirkt deshalb auf allen Seiten.

3. Wie ein Design Stile einbindet

Ein Stil ist für Redakteure eine Auswahl mit verständlichen Namen, technisch eine Liste von Werten mit CSS-Klassen. Ein Design bietet zentrale Stile über style_sets in seiner JSON-Datei an:

"style_sets": {
    "spacing": "none",
    "size": { "set": "headline_size", "default": "auto" },
    "align": "",
    "text_color": "default"
}

• Schlüssel → Standardwert: legt je Design fest, welcher Wert ohne Auswahl gilt.
• Anderer Name: "size": {"set": "headline_size"} bietet den Stil headline_size unter dem Namen size an.
• Kurzform als Liste: "style_sets": ["background", "spacing"].
• Ein eigener Stil des Designs (style_options) mit gleichem Namen hat Vorrang.

Im Template setzt {{style.<name>}} die Klassen des gewählten Werts ein:

<hgroup class="bloqy-headline-group {{style.align}}">
    <{{setting.level}} class="{{style.size}}" data-cms-field="text">{{field.text}}</{{setting.level}}>
</hgroup>

Verwendet das Template einen angebotenen Stil nicht, hängt bloqy dessen Klassen an das äußere Element. Steht umgekehrt {{style.x}} im Template, ohne dass das Design den Stil anbietet, zeigt der Reiter Aussehen ihn unter Fehlende Stile; dort ordnest du ihm einen zentralen Stil zu.

4. Stilwerte sind CSS-Klassen

Die zentralen Stile pflegst du unter Gestaltung → Blöcke → Reiter Stile. Gespeichert werden sie in config/modules/.style-sets.json:

{
    "version": 46,
    "sets": {
        "background": {
            "label": "Hintergrund",
            "default": "none",
            "values": {
                "none": { "label": "Keiner",  "classes": "" },
                "dark": { "label": "Dunkel",  "classes": "bloqy-bgc-color-dark" },
                "brand": { "label": "Marke",  "classes": "bloqy-bgc-color-brand" }
            }
        }
    }
}

Das CSS zu den Klassen liefert ein Paket je Stil: config/styles/<stil>/style.scss, bearbeitet über den Button CSS am Stil. Mitgelieferte Pakete stammen aus bloqy/resources/styles/; neue Fassungen aus Updates erscheinen als Update verfügbar mit Vergleich, angepasstes CSS wird nie überschrieben. Bekommt ein Stil einen Wert mit einer Klasse ohne CSS, legt bloqy beim Speichern eine leere Regel unter „Eigene Werte“ an.

Redakteure sehen nur die Bezeichnungen der Werte, nie Klassen. Ändert sich ein Wert, wirkt das sofort in allen Designs, die den Stil anbieten.

5. Wie Theme-Variablen entstehen

Vier Seiten unter Gestaltung → Theme erzeugen CSS Custom Properties auf :root (und die gleichnamigen SCSS-Variablen):

Die Liste aller Gruppen mit Beispielen steht unter Variablen.

6. Farbklassen

Aus jeder Farbe des Themes erzeugt bloqy Klassen, die die Stile als Werte verwenden:

<farbe> ist der volle Variablenname, also z. B. bloqy-bgc-color-primary. Ob eine Farbe dunkel ist, ergibt sich aus dem Kontrast oder aus „Schrift darauf“ unter Theme → Farben.

7. Wie Designs die Variablen nutzen

Im SCSS eines Designs verwendest du die Grundfarben direkt als Variable, ohne Ersatzwert. So folgt das Design jeder Änderung unter Theme → Farben:

// Design-SCSS, gekapselt in .mv-<id>
& {
    background: var(--color-surface);
    color: var(--color-text);
    border: 1px solid var(--color-border);
    border-radius: var(--bloqy-radius, var(--bloqy-radius-box, 0.5rem));
}
& .badge { background: var(--color-primary); color: var(--color-primary-on); }
& .hinweis { background: var(--color-warning-100); }

@media (min-width: $breakpoint-md) {
    & { padding: var(--bloqy-space-l, 2rem); }
}

• Farben immer aus Theme → Farben; feste Farbwerte nur für Abdunklungen über Bildern.
• Ecken sind die Ausnahme mit Ersatzwert: zuerst der Stil „Ecken“ (--bloqy-radius), dann der Standard dieser Art aus dem Design-System, dann der eigene Wert.
• In Media Queries funktionieren keine CSS-Variablen; nimm dort die SCSS-Variablen wie $breakpoint-md.

8. Reihenfolge des CSS

Die Website lädt die Stylesheets in dieser Reihenfolge: die Tailwind-Basisdatei (site.json → theme.base), weitere Stylesheets, zuletzt /theme/custom.css. Diese Datei übersetzt bloqy aus /theme/custom.scss:

1. scss/_variables.scss – erzeugt aus den Theme-Variablen und Farben ($name und --name)
2. scss/_fonts.scss – @font-face und --font-<familie> aus der Schriftbibliothek
3. mitgelieferte Teildateien wie _reset.scss
4. scss/_module.scss – erzeugt, siehe unten
5. eigene Teildateien, die du später anlegst (bloqy hängt sie ans Ende)

_module.scss ist in sich so aufgebaut:

1. CSS der Stil-Pakete (in der Reihenfolge der Stile, deaktivierte und ungenutzte entfallen)
2. gemeinsame Regeln des Kerns, Effekt-Pakete, Komponenten
3. Regeln je Breakpoint, Sichtbarkeit je Bildschirmbereich, Schriftklassen bloqy-font-*, Menü, Navigation, Spalten
4. Design-System und Typografie (bei Tailwind mit Cascade Layers im Layer base)
5. Farben: Abstufungen, -on und die Farbklassen
6. zuletzt das SCSS jedes Designs in seiner Klasse .mv-<id>

Bei gleicher Spezifität gewinnt also das Design gegen Stile und Kernregeln, und eigene Teildateien am Ende von custom.scss gewinnen gegen alles davor. _variables.scss, _fonts.scss und _module.scss werden bei jedem Build neu geschrieben, bearbeite sie nie von Hand.

9. Wohin mit eigenem CSS?

• Gehört es zu einem Design? Ins SCSS des Designs (Block-Studio → Code → SCSS).
• Gehört es zu einem Stilwert? Ins CSS-Paket des Stils.
• Alles Übrige (globale Typografie-Feinheiten, Formularfelder außerhalb von Blöcken): eine eigene Teildatei unter Theme → SCSS-Dateien, die custom.scss einbindet.

Mehr dazu unter CSS: Stile, custom.scss und Theme. Nach Änderungen außerhalb des Admins erzeugt Werkzeuge → Theme neu übersetzen das CSS komplett neu.