Architektur

Ladereihenfolge über eine einzige globale @layer-Deklaration in ncss.css - Layer-Reihenfolge ist seiten-global, unabhängig davon, in welcher Reihenfolge <link>-Tags im <head> stehen.

Layer-Reihenfolge

wa-native, wa-base, wa-utilities, wa-color-palette, wa-color-variant, wa-theme,
wa-theme-dimension, wa-theme-overrides,   ← Web Awesomes eigene Layer (falls eingebunden)
tokens, reset, base, helpers, components, ← NativeCSS selbst
webawesome-bridge,                        ← Position für integrations/webawesome-bridge.css
                                             (opt-in, siehe unten - Layer bleibt reserviert)
browser-fixes                             ← isolierte Browser-/Engine-Workarounds, zuletzt

@layer regelt die Priorität EXPLIZIT statt über Selektor-Spezifität/!important. Eine Regel in einem SPÄTEREN Layer gewinnt immer gegen eine Regel in einem früheren Layer - unabhängig von Selektor-Spezifität. Unlayered CSS (z.B. theme.css, Inline-Styles) schlägt IMMER jede Layer-Regel.

Dateistruktur

dist/
  ncss.css                  Import-Manifest (Layer-Reihenfolge + alle @import)
  tokens.css                Design Tokens: Typografie, Abstand, Radius, Schatten, Bewegung
  colors.css                Farb-Tokens (light-dark(), abgestufte Skalen)
  reset.css                 Minimal-Reset
  base.css                  Ungestylte native Elemente bekommen sinnvolle Defaults
  browser-fixes.css         Isolierte Browser-/Engine-spezifische Workarounds
  theme.css                 Mitgeliefertes Beispiel-Theme
  page-transitions.css      Opt-in Seitenübergänge
  helpers/                  Utility-Klassen (Layout, Typografie, Formulare, Medien, ...)
  components/               Fertige Komponenten-CSS (Nav, Card, Modal, Badge, ...)
  js/                       Komponenten-JS, gesammelt an einem Ort - nur einbinden,
                             was eine genutzte Komponente tatsächlich braucht (siehe
                             components.html für die Zuordnung Komponente ↔ Datei)
  integrations/             Opt-in Brücken zu externen Bibliotheken, NICHT Teil von
                             ncss.css - webawesome-bridge.css, fontawesome-font-display-fix.css
demo/                     Alle Demo-/Dokumentationsseiten
vendor/                   Selbst gehostetes Web Awesome + Font Awesome (optional)

Warum Theme-Anpassung unlayered läuft

Theme-Anpassung läuft über theme.css (nach ncss.css laden) - eine einzige, bewusst UNLAYERED Datei mit allen wichtigen Seed-Werten (Markenfarben, Grundflächen, Schriften, Radien, Schatten, Bewegung). Unlayered CSS gewinnt immer gegen jede Layer-Regel, kein !important nötig. Details dazu: Theme anpassen, Schritt-für-Schritt-Anleitung: Eigenes Theme erstellen.

Cherry-Picking statt Alles-oder-nichts

Jede Komponente ist eine eigene, kleine Datei (components/card.css, components/modal.css, ...) - nur einbinden, was gebraucht wird, indem man ncss.css als Startpunkt in das eigene Projekt kopiert und darin nicht benötigte @import-Zeilen entfernt. Diese kopierte, eigene Datei IST das Projekt-Manifest - kein Bundler, der ungenutztes CSS erst per Purge wieder herausschneiden muss, die Datei ist von Anfang an nur so groß wie gewollt.

integrations/ geht denselben Gedanken einen Schritt weiter: webawesome-bridge.css und fontawesome-font-display-fix.css stehen NICHT im Import-Manifest von ncss.css - ein Projekt ohne Web Awesome/Font Awesome liefert dadurch keine einzige Zeile davon aus. Nur wer die jeweilige Bibliothek tatsächlich lädt, bindet die passende Integrationsdatei selbst zusätzlich ein (siehe Web Awesome Bridge).