Technische Seite · Aufbau & Stellschrauben

Für Entwickler: wie das Theme aufgebaut ist

Diese Seite erklärt den technischen Unterbau: die Design-Variablen („Tokens“), wie sie zusammenwirken, die @layer-Kaskade und die Reihenfolge, in der du das Theme anpasst – von „nur beim Framework-Fork“ bis „an einem einzelnen Element“. Zum Schluss: warum sich dieser Aufbau gut für KI-gestützte Design-Automatisierung eignet.

Ein Wert, an einer Stelle

Alle --av-*-Vorgaben stehen einmal in bundle/public/theme/tokens.css, im Layer av.tokens auf :root. Regeln im Theme greifen nie auf Rohwerte zu, immer auf ein Token. Das ist der Grund, warum eine Farbänderung überall konsistent durchschlägt – und der Grund für den Namen Advanced Variable Environment.

Werte, die sich gegenseitig ergeben

Viele Tokens sind nicht gesetzt, sondern berechnet:

/* Sekundärfarbe: aus der Primärfarbe, über zwei Dials */
--av-color-secondary:
  oklch(from var(--av-color-primary)
        l calc(c * var(--av-sec-chroma))
        calc(h + var(--av-sec-hue-shift)));

/* Gedämpfter Text: Mischung aus Textfarbe und Fläche */
--av-color-text-muted:
  color-mix(in oklch, var(--av-color-text) var(--av-muted-fraction),
            var(--av-color-surface));

/* Hell/Dunkel: color-scheme + light-dark(), Umschalten html.light / html.dark */
--av-color-primary-light: light-dark(var(--blue-3), var(--blue-9));

Wer die Primärfarbe ändert, bekommt Sekundärfarbe, Hover-Varianten, gedämpften Text und die Dunkelmodus-Werte automatisch mit.

Skalen-Faktor oder absolute Stufe

Größen kommen als Rampe plus ein Faktor. Der Faktor bewegt die ganze Rampe; bei 1 kollabiert calc() exakt auf den Ausgangswert (pixelgleich – deshalb ist „mit Defaults speichern“ wirkungslos).

--av-radius-scale: 1;
--av-radius-sm: calc(var(--radius-2) * var(--av-radius-scale));
--av-radius-md: calc(var(--radius-3) * var(--av-radius-scale));
/* … */

/* ganze Rampe bewegen: */   :root { --av-radius-scale: 1.4; }
/* eine Stufe hart setzen: */ .promo { --av-radius-lg: 8px; }

Weitere Faktoren: --av-text-scale, --av-heading-scale, --av-space-scale (Dichte), --av-layout-gap-scale, --av-shadow-scale, --av-glow-scale, --av-duration-scale, --av-bg-overlay-scale.

Die @layer-Kaskade

Die Reihenfolge wird einmal in tokens.css deklariert. Frühe Layer haben die niedrigste Priorität. Kunden-CSS in custom.css ist ohne Layer und gewinnt damit gegen alles Layer-CSS – unabhängig von Selektor-Spezifität.

Die Stellschrauben – von global nach lokal

Das Design Studio (ave-editor) ist eines von mehreren gleichwertigen Mitteln, nicht das einzige. Es ist ein optionales Zusatz-Bundle; das Theme-Framework (bundle) läuft auch ohne. Beim Speichern schreibt es lediglich files/theme/CSS/theme-vars.css (ein :root { … }-Block). Ein Projekt ohne Studio setzt dieselben --av-*-Werte von Hand – in theme-vars.css, in custom.css oder als geänderte Vorgaben in tokens.css (Fork + Build). Fehlt theme-vars.css, kommt alles aus tokens.css.

Logo-SVG für logo-tint vorbereiten

Mit der Klasse logo-tint setzt das Theme eine SVG als Code in die Seite statt als Bild und färbt ihre benannten Teile. Benannt wird mit einer CSS-Klasse an einer Gruppe:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1017 170">
  <g class="logo-mark" fill="#1c7ed6"> … Zeichen … </g>
  <g class="logo-word" fill="#808080"> … Schriftzug … </g>
</svg>

• Zwei Namen, zwei Farben: logo-mark bekommt die Akzentfarbe der Umgebung, logo-word ihre Textfarbe. Ein einfarbiges Logo braucht nur logo-word. Alles ohne Namen behält seine Farbe – eine SVG ganz ohne Namen bleibt also unverändert.
• Die fill-Werte sind die Originalfarben. Sie gelten überall, wo die Klasse fehlt (E-Mail, PDF, Backend). Farben an einzelnen Pfaden innerhalb der Gruppe stören nicht, sie werden mit überschrieben.
• Text in Pfade umwandeln. Ein Schriftzug als <text> erschiene in einer Ersatzschrift, sobald die Website seine Schrift nicht selbst lädt – und als gewöhnliches Bild (ohne die Klasse) ohnehin.
• Export aus Grafikprogrammen: Affinity und Illustrator schreiben Ebenennamen als id, nicht als class. Die zwei Klassen also nach dem Export in einem Texteditor an die Gruppen setzen.
• Sicherheit: Die Datei wird vor dem Einbetten bereinigt (dieselbe Bibliothek wie Contaos Upload). Skripte, Ereignis-Attribute und Verweise auf fremde Server fallen weg; gelesen werden nur Dateien im Projekt.

Kopfzeile anordnen

Die Kopfzeile verteilt ihre Teile über die volle Breite: der erste steht ganz links, der letzte ganz rechts, alle übrigen mit gleichem Abstand dazwischen. Ein Teil ist jeder Eintrag, der im Seitenlayout (Themes → Seitenlayouts → Eingebundene Elemente) in der Spalte header steht.

Eine Elementgruppe mit dem Layout layout-row hält ihre Kinder in einer Zeile zusammen und zählt für die Kopfzeile als ein Teil. Bei drei Teilen steht die Navigation mittig zwischen Logo und Knopf – genau in der Seitenmitte nur, wenn Logo und Knopf gleich breit sind.

Build & Betrieb

• CSS-Build: bin/console ave:css:build verkettet die Quelldateien aus bundle/public/theme/ zu bundle/public/dist/theme.min.css und zusammen mit Open Props, Reset und den Starter-Dateien zu dist/ave.min.css. Das Layout bindet ave.min.css als einziges Stylesheet ein, solange unter files/theme/CSS/ keine eigene theme.css oder view-transitions.css liegt – sonst theme.min.css plus die Einzeldateien. --check prüft die Aktualität (CI).
• Schriften: Beim Speichern im Studio wird die gewählte Google-Variable-Font heruntergeladen und unter files/theme/fonts/<slug>/variable.woff2 selbst gehostet (kein externer Font-Dienst).
• Studio-Zustand: Quelle der Wahrheit ist var/ave-editor/theme-settings.json, Versionshistorie var/ave-editor/history.json (max. 20). Nach einer Formeländerung im Theme: bin/console ave:theme:rebuild.

Stolperstein: zusammengesetzte Tokens

Eine Custom Property wird dort aufgelöst, wo sie deklariert ist. Tokens wie --av-card-border, --av-card-bg oder die Glow-Ketten werden deshalb zusätzlich auf den Klassen selbst gesetzt. Wer eine Sektion baut, die --av-color-border oder --av-color-surface-2 umstellt, muss das jeweilige Karten-Token im selben Block mitziehen – sonst bekommt die Karte darin weiter den Wurzelwert. Ebenso lösen relative URLs in --icon-src am Verwendungsort auf; eigene Icons brauchen einen absoluten Pfad.

Gut geeignet für agentische Workflows

Derselbe Aufbau, der das Theme wartbar macht, macht es auch für KI-Agenten berechenbar. Wer Design-Änderungen automatisiert, profitiert von:

• Kleiner, benannter Aktionsraum. Das ganze Aussehen hängt an einem endlichen, dokumentierten Satz --av-*-Tokens (bundle/cheat-sheet.md listet jeden mit Default) plus rund 150 Utility-Klassen mit klar umrissener Wirkung. Ein Agent wählt aus einem Vokabular, statt beliebiges CSS zu erfinden – das senkt Halluzinationen und macht jede Änderung prüfbar.
• Deltas statt Vollzustand. Ein kompletter Marken-Look sind rund zwanzig Zahlen in einem :root { … }-Block. Das Modell muss nur wenige Werte ausgeben; die Ableitungsformeln (Sekundärfarbe, gedämpfter Text, Hell/Dunkel, Skalen-Rampen) machen daraus ein stimmiges Ganzes. Kleine Ausgabe, große Wirkung, geringe Fehlerfläche.
• Deterministisch und diff-bar. Gleiche Tokens ergeben pixelgleiche Ausgabe (bei Faktor 1 identisch mit den Defaults). Ergebnisse sind vorhersagbar und lassen sich gegen einen Baseline-Stand vergleichen.
• Kein Build in der Schleife. custom.css oder theme-vars.css schreiben genügt, der Browser löst zur Laufzeit auf – kein Kompilieren, kein Cache-Tanz zu orchestrieren, kurzer Edit-Prüf-Zyklus.
• Eingebaute Prüfsignale. Der Kontraste-Scan (WCAG AA), die automatische Marken-Text-Kontrastierung, prefers-reduced-motion und Hell/Dunkel sind Teil des Systems. Kontraste lassen sich nach jeder Änderung schnell nachmessen. Der Scan deckt nur den sichtbaren Text der geöffneten Seite im aktiven Farbschema ab, keine Hover- und Fokus-Zustände; eine vollständige Barrierefreiheitsprüfung ersetzt er nicht.
• Guard-Rails im Repo. bundle/ai-instructions.md hält die Regeln fest (nur Open Props, natives HTML5, keine CDNs, das Utility-Schema); die Consistency-Tests (CheatSheetTest, ave:css:build --check, Token-Regel-Wächter) fangen Drift automatisch ab.
• Fertige Werkzeuge zum Selbst-Verifizieren. bin/theme-shots nimmt abhängigkeitsfrei über CDP Baseline-/Vergleichs-Screenshots auf – ein Harness, das ein Agent fahren kann. Und ave-editor bringt „Prompt → Persona“ bereits mit: die Architektur ist darauf ausgelegt, dass ein Sprachmodell nur --av-*-Werte emittieren muss.