Architecture

Load order runs through a single global @layer declaration in ncss.css - layer order is page-global, independent of the order <link> tags appear in the <head>.

Layer Order

wa-native, wa-base, wa-utilities, wa-color-palette, wa-color-variant, wa-theme,
wa-theme-dimension, wa-theme-overrides,   ← Web Awesome's own layers (if included)
tokens, reset, base, helpers, components, ← NativeCSS itself
webawesome-bridge,                        ← position for integrations/webawesome-bridge.css
                                             (opt-in, see below - the layer stays reserved)
browser-fixes                             ← isolated browser/engine workarounds, last

@layer controls priority EXPLICITLY instead of via selector specificity/!important. A rule in a LATER layer always wins over a rule in an earlier layer - regardless of selector specificity. Unlayered CSS (e.g. theme.css, inline styles) ALWAYS beats every layered rule.

File Structure

dist/
  ncss.css                  Import manifest (layer order + all @import)
  tokens.css                Design tokens: typography, spacing, radius, shadow, motion
  colors.css                Color tokens (light-dark(), graded scales)
  reset.css                 Minimal reset
  base.css                  Unstyled native elements get sensible defaults
  browser-fixes.css         Isolated browser/engine-specific workarounds
  theme.css                 Included example theme
  page-transitions.css      Opt-in page transitions
  helpers/                  Utility classes (layout, typography, forms, media, ...)
  components/               Ready-made component CSS (nav, card, modal, badge, ...)
  js/                       Component JS, collected in one place - only include what a
                             component you actually use needs (see components.html for
                             the component ↔ file mapping)
  integrations/             Opt-in bridges to external libraries, NOT part of ncss.css -
                             webawesome-bridge.css, fontawesome-font-display-fix.css
demo/                     All demo/documentation pages
vendor/                   Self-hosted Web Awesome + Font Awesome (optional)

Why theming runs unlayered

Theming runs through theme.css (load after ncss.css) - a single, deliberately UNLAYERED file with all the important seed values (brand colors, base surfaces, fonts, radii, shadows, motion). Unlayered CSS always wins against any layered rule, no !important needed. Details: Theming, step-by-step walkthrough: Build Your Own Theme.

Cherry-picking instead of all-or-nothing

Every component is its own small file (components/card.css, components/modal.css, ...) - include only what's needed by copying ncss.css into your own project as a starting point and removing the @import lines you don't need. That copied, project-owned file IS the project's manifest - no bundler that has to purge unused CSS after the fact, the file is only ever as large as intended from the start.

integrations/ takes the same idea one step further: webawesome-bridge.css and fontawesome-font-display-fix.css are NOT in ncss.css's import manifest - a project without Web Awesome/Font Awesome ships none of it. Only projects that actually load the respective library add the matching integration file themselves (see Web Awesome Bridge).