Theming — Cmssy Documentation

Überblick

cmssy ist headless - deine Next.js-App besitzt das gesamte visuelle Styling (Farben, Typografie, Dark Mode) als normales Tailwind/CSS in deinem eigenen Repo. cmssy steuert nicht, wie deine Site aussieht. Was cmssy pro Workspace speichert, ist Branding: ein Markenname und ein paar geteilte Assets, die du abrufst und anwendest. Die Styling-Referenz weiter unten gilt für dieses CSS, das dir gehört - siehe Erweiterte Block-Funktionen für das Tailwind-v4-Setup.

Branding

Das Branding liegt in der Site-Config des Workspace. Rufe es mit fetchSiteConfig aus @cmssy/react ab:

import { fetchSiteConfig } from "@cmssy/react";
import { cmssy } from "@/cmssy.config";

const { branding } = await fetchSiteConfig(cmssy);
// { brandName, logoUrl, faviconUrl, ogImageUrl } | null

Feld	Bedeutung
`brandName`	Anzeigename der Site / Marke.
`logoUrl`	Logo-Asset - rendere es in deinem Header.
`faviconUrl`	Favicon - binde es in deine Metadata-Icons ein.
`ogImageUrl`	Standard-Bild für Open Graph / Social Sharing.

Jedes Feld ist nullable - rendere nur, was gesetzt ist. buildCmssyMetadata wendet das Branding für SEO bereits an: brandName als Titel-Fallback und ogImageUrl als Standard-Bild für Open Graph / Twitter. Favicon und Logo wendest du selbst an:

import { fetchSiteConfig } from "@cmssy/react";
import { cmssy } from "@/cmssy.config";

export async function generateMetadata() {
  const { branding } = await fetchSiteConfig(cmssy);
  return branding?.faviconUrl ? { icons: { icon: branding.faviconUrl } } : {};
}

Farbsystem

Eine typische cmssy-Site nutzt OKLCH-Farbwerte, die als CSS-Variablen in deiner App definiert sind, aufgeteilt in semantische Tokens, die sich an Light- und Dark-Mode anpassen:

--background / --foreground — Seitenhintergrund und Text
--primary / --primary-foreground — primäre Action-Buttons
--muted / --muted-foreground — dezente Hintergründe und Hilfstext
--card / --card-foreground — Kartenflächen
--border — Standard-Rahmenfarbe
--destructive — Fehler- und Gefahrenzustände

Farben anpassen

Bearbeite den :root-Block in styles/main.css, um deine Farbpalette zu ändern. Nutze OKLCH-Werte für wahrnehmungsgleiche Farben:

Dark Mode

Der Dark Mode wird über die Klasse .dark auf dem Root-Element gesteuert. Überschreibe dieselben Variablen im .dark-Selektor:

Tailwind CSS v4

Das Projekt nutzt Tailwind CSS v4 mit CSS-first-Konfiguration. Wichtige Unterschiede zu v3:

Keine tailwind.config.js — alles lebt im CSS
@theme inline mappt CSS-Variablen auf Tailwind-Utilities
@source-Direktiven sagen Tailwind, welche Dateien nach Klassennamen gescannt werden
Gradient-Klassen nutzen bg-linear-to-r statt bg-gradient-to-r
Schatten-Skala verschoben: shadow-sm in v4 = altes blankes shadow

Border Radius

Der Border Radius nutzt eine Basis-Variable --radius. Alle Radius-Tokens leiten sich davon ab:

rounded-sm = calc(var(--radius) - 4px)
rounded-md = calc(var(--radius) - 2px)
rounded-lg = var(--radius) (Standard 10px)
rounded-xl = calc(var(--radius) + 4px)