CSS Architecture

The theme uses a three-layer CSS architecture. Each layer has a clear responsibility and loads in a deterministic order.

Summary

Styles are organized into three layers: base (universal resets and utilities), block (structural layout for Nova blocks), and preset (visual identity — colors, shapes, depth, and motion). The theme also generates CSS custom properties from the preset configuration at build time.

Three-Layer Model

Base Layer

Universal styles shared across all presets and components.

File	Purpose
`reset.css`	CSS reset for consistent cross-browser baseline.
`grid.css`	Responsive grid system using CSS custom properties.
`accessibility.css`	Focus styles, screen reader utilities, reduced motion.
`utilities.css`	Shared structural patterns for reusable UI elements.

Block Layer

Structural styles for the 10 Nova blocks. No colors, no shadows, no preset-specific values. Only layout, spacing, and responsive behavior.

Directory	Purpose
`styles/blocks/app-market-download/`	Download button layout.
`styles/blocks/blog-preview/`	Blog preview grid layout.
`styles/blocks/features/`	Feature grid layout.
`styles/blocks/frame/`	Captioned figure layout.
`styles/blocks/hero/`	Hero section layout.
`styles/blocks/install-strip/`	Install strip layout.
`styles/blocks/spotlight/`	Spotlight section layout.
`styles/blocks/stats/`	Stats grid layout.
`styles/blocks/terminology/`	Terminology tooltip layout.
`styles/blocks/typewriter/`	Typewriter animation layout.

Preset Layer

Visual identity for each preset. Each preset directory contains its own preset.css, block overrides, and navbar/footer variant styles.

text

styles/presets/{envoy|foundry|lantern|marshal|sentinel|signal}/
├── preset.css                     (root variables and base overrides)
├── blocks/                        (per-block visual overrides)
│   ├── hero/style.css
│   ├── features/style.css
│   └── ...
└── theme/                         (Docusaurus theme component overrides)
    ├── Navbar/{Bridge|Canopy|Compass|Monolith}/style.css
    ├── Footer/{Commons|Embassy|Launchpad|Ledger}/style.css
    ├── CodeBlock/style.css
    ├── DocSidebar/style.css
    └── ...

CSS Load Order

The theme loads stylesheets in this exact sequence at page mount:

Global resets — reset.css, grid.css, accessibility.css, utilities.css
Generated CSS — nova-generated.css (CSS custom properties from preset config)
Shared block styles — structural layout for all 10 Nova blocks
Shared theme styles — base styles for 70+ Docusaurus theme components
Preset identity CSS — preset.css for the active preset
Preset block overrides — visual overrides per block per preset
Preset navbar variant — styles for the active navbar variant
Preset footer variant — styles for the active footer variant

Load Order Matters

Later stylesheets override earlier ones at the same specificity. The preset layer loads last so it can override block and theme styles without !important.

CSS Custom Properties

The theme generates CSS custom properties from the preset configuration at build time. These properties are written to nova-generated.css and available globally.

Colors

The two brand colors (primary and secondary) each generate 11 shades. The other four categories (text, border, warning, danger) emit a single base token per category plus a small set of derived color-mix tokens.

Property	Example Value	Description
`--nova-color-primary-50`	`#fff7ed`	Lightest shade
`--nova-color-primary-100`	`#ffedd5`
`--nova-color-primary-200`	`#fed7aa`
`--nova-color-primary-300`	`#fdba74`
`--nova-color-primary-400`	`#fb923c`
`--nova-color-primary-500`	`#f97316`
`--nova-color-primary-600`	`#ea580c`	Base color
`--nova-color-primary-700`	`#c2410c`
`--nova-color-primary-800`	`#9a3412`
`--nova-color-primary-900`	`#7c2d12`
`--nova-color-primary-950`	`#431407`	Darkest shade

The same shade pattern applies to --nova-color-accent-* (the secondary brand color is emitted under the accent namespace for backward compatibility with existing preset CSS).

Non-brand category tokens include --nova-color-text (plus -muted, -soft, -inverse), --nova-color-border (plus -subtle), --nova-color-surface-raised, --nova-color-warning-500 (plus -400 and -bg), and --nova-color-danger-500 (plus -400 and -bg). The full list and how each is derived is documented in Color Pipeline.

Fonts

Property	Example Value
`--nova-font-display`	`'Plus Jakarta Sans', sans-serif`
`--nova-font-body`	`'Inter', sans-serif`
`--nova-font-code`	`'Fira Code', monospace`

Shape

Radius is set by the radius config (sharp, rounded, pill):

Property	`sharp`	`rounded`	`pill`
`--nova-shape-radius`	`0`	`0.5rem`	`9999px`

Density is set by the density config (compact, comfortable, spacious):

Property	`compact`	`comfortable`	`spacious`
`--nova-shape-padding`	`0.5rem`	`1rem`	`1.5rem`
`--nova-shape-gap`	`0.25rem`	`0.5rem`	`1rem`

Depth

Property	`flat`	`elevated`	`glass`
`--nova-depth-card-shadow`	`none`	`0 4px 6px …, 0 2px 4px …`	`0 4px 30px …`
`--nova-depth-card-border`	`1px solid var(--nova-color-border)`	`none`	`1px solid rgba(255,255,255,0.18)`
`--nova-depth-card-backdrop`	`none`	`none`	`blur(5px)`

Code block depth follows the same pattern with --nova-depth-code-shadow and --nova-depth-code-border (flat, bordered, elevated).

Motion

Speed is set by the speed config (none, subtle, normal, expressive):

Property	`none`	`subtle`	`normal`	`expressive`
`--nova-motion-duration`	`0ms`	`150ms`	`200ms`	`300ms`

Toggles are CSS numeric booleans (0 or 1):

Property	Description
`--nova-motion-staggered-reveals`	Enable staggered animations.
`--nova-motion-hover-effects`	Enable hover transitions.

Grid

Responsive grid tokens with three breakpoints:

Property	Base	480px+	768px+
`--nova-grid-gutter`	`16px`	`20px`	`24px`
`--nova-grid-padding`	`16px`	`20px`	`24px`

Values shown for comfortable density. compact uses smaller values; spacious uses larger values.