Zum Inhalt springen
NativeCSS
Handbuch-Inhalt

Eigenes Theme erstellen

Diese Seite ist der praktische Weg von einem leeren Projekt zu einer fertig eingefärbten Seite - Schritt für Schritt, mit einer fertigen theme.css zum Kopieren. Die technische Erklärung DAHINTER (Cascade Layers, Seed-Werte vs. abgeleitete Skala) steht separat unter Theme anpassen.

Schritt 1 - Dateien ins eigene Projekt kopieren

ncss braucht keinen Build-Schritt und kein npm-Paket - der ganze dist/-Ordner ist bereits fertig ausgeliefertes CSS/JS. Einfach kopieren:

# dist/ komplett ins eigene Projekt kopieren, z.B. nach assets/ncss/
cp -r dist/ mein-projekt/assets/ncss/

Im HTML-Head zwei Zeilen - ncss.css zuerst, die eigene theme.css direkt danach (die gibt es erst nach Schritt 2, das Grundgerüst funktioniert aber schon jetzt ohne sie):

<link rel="stylesheet" href="assets/ncss/ncss.css">
<link rel="stylesheet" href="assets/ncss/theme.css">

Web Awesome/Font Awesome nur bei Bedarf ergänzen - siehe Web Awesome Bridge, für die meisten Projekte reicht natives CSS/HTML völlig aus.

Schritt 2 - Die eigene theme.css anlegen

Die mitgelieferte dist/theme.css enthält NativeCSS' eigene Markenwerte (das kräftige Blau dieser Seite) - als Startpunkt für ein eigenes Projekt lieber diesen Block nehmen und die markierten Stellen ersetzen. Alles, was hier NICHT überschrieben wird, bleibt beim ncss-Standard:

/* theme.css - eigene Markenwerte, nach ncss.css laden */
:root, :host {
  /* Hauptmarke (Buttons, Links, Fokus-Ring) - HELL, DUNKEL */
  --ncss-color-brand: light-dark(#4f46e5, #a5b4fc);
  --ncss-color-brand-contrast: light-dark(#ffffff, #1a1533);

  /* Zweitfarbe (Akzente, sekundäre Buttons) */
  --ncss-color-brand-2: light-dark(#0f766e, #5eead4);
  --ncss-color-brand-2-contrast: light-dark(#ffffff, #04211d);

  /* Seitenhintergrund und Textfarben - Defaults sind neutral/weiß, hier nur bei Bedarf ändern */
  --ncss-color-bg: light-dark(#ffffff, #0f1115);
  --ncss-color-surface: light-dark(#ffffff, #1a1d24);
  --ncss-color-text: light-dark(#1a1a1a, #eef2f8);

  /* Schriftart - system-ui braucht keine Ladezeit, eigene Web-Font hier eintragen */
  --ncss-font-family-base: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;

  /* Ecken - 0 für eckig, größere Werte für runder */
  --ncss-radius-sm: 0.25rem;
  --ncss-radius-md: 0.5rem;
  --ncss-radius-lg: 1rem;
}

Das reicht bereits: Buttons, Badges, Karten-Rahmen, Fokus-Ring und die komplette Farbskala (100/300/700/900, -on-soft) übernehmen die neue Marke automatisch - ncss berechnet die Skala aus genau diesen wenigen Werten per color-mix(), siehe Nur Seed-Werte, keine Ableitungen. Alle weiteren Werte (Statusfarben, Schatten, Bewegung, Layout-Breiten) stehen in der vollständigen Referenz in dist/theme.css - nur bei konkretem Bedarf ergänzen, nicht vorsorglich alles kopieren.

Schritt 3 - Dark Mode gratis testen

Jeder light-dark(...)-Wert oben deckt automatisch beide Farbschemata ab - kein zweites Stylesheet, kein prefers-color-scheme-Media-Query von Hand nötig. Zum Testen einfach im Betriebssystem oder in den Browser-DevTools zwischen Hell/Dunkel umschalten (Chrome: DevTools → Rendering → "Emulate CSS media feature prefers-color-scheme") und prüfen, ob beide Werte in jedem light-dark()-Paar zueinander passen - hell genug Kontrast, keine grelle Fläche im Dark Mode.

Schritt 4 - Kontrast prüfen

Eine neue Markenfarbe verschiebt automatisch Buttons, Links, Badges und die komplette Web-Awesome-Bridge - lohnt sich, das kurz mit echtem Lighthouse zu prüfen (Chrome DevTools → Lighthouse → Accessibility), nicht nur mit bloßem Auge:

  • Weißer/heller Text auf --ncss-color-brand (Button-Beschriftung) braucht mindestens 4.5:1 Kontrast für Fließtext, 3:1 für große Schrift.
  • Passt der Kontrast knapp nicht, eher die Marke selbst dunkler/kräftiger sättigen als nachträglich einzelne Textfarben zu patchen - siehe Barrierefreiheit.

Schritt 5 - Schriften wechseln (optional)

Eigene Web-Font einbinden (z.B. selbst gehostetes @font-face oder ein Font-Provider), dann in theme.css nur den Namen eintragen - die komplette fluide Größen-Skala (clamp()-basiert, siehe Typografie) bleibt unverändert bestehen:

--ncss-font-family-base: "Inter", system-ui, sans-serif;
--ncss-font-family-heading: "Fraunces", serif;

Überschriften-Gewicht und Fließtext-Gewicht sind zwei eigene, semantische Tokens (--ncss-font-weight-heading/-body) statt fest auf die Skalenstufen (-normal/-medium/-semibold/-bold) verdrahtet zu sein - nützlich, wenn eine gewählte Schrift nur bestimmte Gewichte anbietet (z.B. eine Variable Font mit nur 300/600):

--ncss-font-weight-heading: var(--ncss-font-weight-semibold); /* statt -bold */
--ncss-font-weight-body: var(--ncss-font-weight-normal);

<strong>/<b> bleiben davon unberührt (referenzieren weiterhin direkt --ncss-font-weight-bold) - "fett hervorgehoben" soll unabhängig davon bleiben, welches Gewicht eine Überschrift gerade nutzt.

Schritt 6 - Mehrere Themes (optional)

Für mehrere Marken/Domains auf derselben Codebasis: denselben Aufbau in einer weiteren Datei wiederholen (z.B. theme-projekt-b.css) und je nach Domain statt theme.css laden - Details und die attributgesteuerte [data-palette]-Alternative unter Mehrere Themes parallel.

Schritt 7 - Einzelne Komponenten nach eigenem Geschmack anpassen

theme.css ändert Seed-Werte GLOBAL - jede Karte, jeder Button, jedes Badge zieht automatisch mit. Manchmal reicht das nicht: nur die Badges sollen eckiger sein, nur der Button-Schatten soll kräftiger wirken, ohne den Rest der Seite anzufassen. Dafür braucht es keine Kopie der ncss-Datei und kein !important - eine einzige Regel in der eigenen, UNLAYERED CSS-Datei (derselbe Trick wie theme.css selbst, siehe Theme anpassen) reicht, weil unlayered CSS in der Spec immer gegen jede Layer-Regel gewinnt:

/* eigene.css - nach theme.css laden */
.ncss-badge {
  border-radius: var(--ncss-radius-sm); /* statt der vollen Pille */
}
.ncss-card {
  box-shadow: var(--ncss-shadow-lg); /* kräftigerer Schatten als der Default */
}

Welche Eigenschaften eine Komponente überhaupt hat und welche Modifier-Klassen (--primary, --horizontal, ...) es schon gibt, steht in der Komponenten-Referenz - dort auch nachsehen, BEVOR eine Eigenschaft hart überschrieben wird: oft gibt es bereits eine vorgesehene Variante oder ein Token dafür (z.B. --ncss-radius-* statt eines festen px-Werts), das automatisch mit theme.css mitzieht, statt bei der nächsten Marken-Anpassung erneut von Hand nachgezogen werden zu müssen.

Reicht das noch nicht - ein komplett neues, eigenes Bauteil, das es in ncss gar nicht gibt: Eigene Komponenten erstellen.

Checkliste

  • dist/ ins Projekt kopiert, ncss.css eingebunden
  • Eigene theme.css nach ncss.css geladen, Marke/Zweitfarbe gesetzt
  • Dark Mode geprüft (DevTools-Emulation oder System umschalten)
  • Kontrast mit echtem Lighthouse geprüft
  • Bei Bedarf: eigene Schriftart, mehrere Themes, einzelne Komponenten-Eigenschaften