Docs

Migrating from Fluid Theme 1.x to 2.0

Fluid Theme 2.0.0 replaces the soft, rounded 1.x default with Base v2: an editorial typographic base (Newsreader display over Schibsted Grotesk body, deep oxblood accent on warm paper, square corners, zero shadows, fluid section rhythm, and an inverted navigation bar by default).

Every 1.x CSS custom property name survives, so existing sites can either keep their 1.x visual look on the 2.0 engine or adopt the Base v2 look.

Path A: Keep the 1.x look on 2.0 core (drop-in upgrade)

  1. Single-stylesheet sites: copy dist/fluid-1x.min.css (package export @fluid-theme/core/1x) into your site under its existing fluid.min.css filename.
    • It bundles fluid.min.css + fluid-legacy-1x.css in one file and keeps the /* @fluid-theme/core v2.x.x ... */ banner expected by /status and /version.json.
  2. Multi-stylesheet sites: link dist/fluid.min.css followed by dist/fluid-legacy-1x.css (@fluid-theme/core/legacy-1x).
  3. Navigation bar colour: in 2.0, .nav uses the opposite colour scheme by default (dark bar on a light site, light bar on a dark site), and legacy-1x.css intentionally does not override it. To keep a page-coloured 1.x bar, add data-bg="plain" to <nav class="nav" data-bg="plain">.

Pre-1.0 sites (0.9.x using data-preset or data-palette): presets and palettes were removed in 1.0.0. Map the site's old preset and palette to :root knobs in a child theme before upgrading to 2.0, and verify with node scripts/axe-check.mjs.

Path B: Adopt Base v2 (recommended for new sites and redesigns)

  1. Core base (required): link dist/fluid.min.css (@fluid-theme/core). System serif and sans stacks render immediately with zero external requests.
  2. Self-hosted web fonts (opt-in):
    • Base v2 pairing (Newsreader + Schibsted Grotesk, with metric-matched fallback faces): link dist/fluid-fonts.min.css (@fluid-theme/core/fonts) and serve dist/fonts/*.woff2 + OFL-*.txt beside fonts/ under your CSS directory.
    • Swiss child theme (themes/swiss.css, @fluid-theme/core/themes/swiss): link after core, paired with dist/fluid-fonts-archivo.min.css (@fluid-theme/core/fonts-archivo) or themes/fonts/archivo.css.
    • Gallery child theme (themes/gallery.css, @fluid-theme/core/themes/gallery): link after core, paired with dist/fluid-fonts-bodoni.min.css (@fluid-theme/core/fonts-bodoni) or themes/fonts/bodoni.css.
  3. Opt-in modules (link after core only on pages/sites that use them):
    • Article TOC (dist/fluid-toc.min.css + assets/js/toc.js + build helper assets/js/toc-build.mjs): inline, sticky rail, and bottom mobile dock (data-toc="rail dock").
    • Extra nav modes (dist/fluid-nav.min.css): compact "+" popover (data-nav="compact"), drop panel (data-nav="compact drop"), icon collapse (data-nav="icon"), and sticky-links mode (data-sticky="links"). Core includes the default one-line squeeze and balanced-row wrap without this file.
  4. Fluid Zero (dist/fluid-zero.min.css, @fluid-theme/core/zero): standalone ~2.4 KB gzip reset + native-element base sharing the same @layer order and :root knob names for utility pages or custom-from-scratch builds.

Summary of breaking & visual changes from 1.x

Area 1.x default 2.0 default How to customise or restore
Body & scale 16→18px, fixed steps 17→20px (--text-min / --text-max), pow(var(--type-ratio), n) generator Set --type-ratio, --text-min, --text-max, or --h1-size..--h3-size on :root
Typefaces System sans Newsreader display/headings + Schibsted Grotesk body (system fallbacks without font CSS) Link fluid-fonts.min.css, or set --font-heading, --font-display, --font-body
Accent & paper Blue accent, cool neutral Deep oxblood oklch(42% 0.15 22), warm paper --neutral-tint, ink --color-border-strong Set --accent and --neutral-tint on :root
Corners, shadows, motion 16px card / 10px control radius, shadow style 1, 467ms motion --radius-card: 0, --radius-control: 0, --shadow-style: 0, --motion-base: 320ms Set --radius-card, --radius-control, --shadow-style (0 | 1), --motion-base
Cards & badges Boxed card with hover lift; pill badges Open hairlined layout with no lift; square badges; duotone/greyscale opt-in Override in @layer themes or link fluid-legacy-1x.css
Section & gutter space Smaller fixed section padding --space-section fluid 72→160px; --space-gutter keeps its 1.x meaning (both sides combined, 3vi per-side floor) Set --space-section and --space-gutter
Display headlines --hero-headline-size had a :root default No :root default on --hero-headline-size (still honoured when set); .display / .hero__headline support data-fit (assets/js/fit-text.js) Set --display-max or --hero-headline-size
Navigation bar Page-coloured bar with bottom border Inverted bar by default (dark on light, light on dark); hairline only with [data-sticky] Add data-bg="plain" on .nav for page-coloured bar
  • --font-display
  • --type-ratio
  • --weight-display
  • --weight-heading
  • --display-max
  • --measure
  • --text-min
  • --text-max
  • --h1-size
  • --h2-size
  • --h3-size
  • --hero-headline-size (where a look sets an explicit cap)

Automatic updates

Sites with @fluid-theme/core in package.json copy starters/workflows/dependabot.yml; sites that vendor the CSS copy starters/workflows/update-fluid-theme.yml. Either way, 2.x minor and patch releases open automatic update pull requests, and major upgrades stay held (see starters/workflows/README.md).