Turns Loam's theme inputs into CSS custom properties. The components read only those variables, so re-theming is a single call — at runtime, per subtree, with no rebuild.

Install

npm install @btndprojects/loam-theme-web @btndprojects/loam-tokens

Usage

Apply a theme at runtime:

import { applyTheme } from '@btndprojects/loam-theme-web';
import { aurora } from '@btndprojects/loam-tokens';

applyTheme(document.documentElement, { ...aurora.input, mode: 'Dark' });

Or generate the CSS ahead of time (SSR, static sites):

import { tokensToCss } from '@btndprojects/loam-theme-web';

const css = tokensToCss(':root', { accent: '#c0563a', radius: 1.2 });

Theme just one part of the page by passing that element to applyTheme instead of <html>.

Using Tailwind v4? Import the preset so utilities like bg-surface and text-muted map onto the tokens:

@import "@btndprojects/loam-theme-web/fonts.css";
@import "tailwindcss";
@import "@btndprojects/loam-theme-web/base.css";
@import "@btndprojects/loam-theme-web/preset.css";

Fonts — always self-hosted

Loam never loads a font from Google Fonts or any other CDN. fonts.css declares the preset typefaces (Newsreader, Manrope, Space Grotesk, Instrument Serif, JetBrains Mono — OFL, latin + latin-ext subsets) against woff2 files that ship in this package; your bundler copies them to your own origin.

Pick a preset with fontFamily: 'Editorial' | 'Grotesk' | 'Humanist' | 'System', or bring your own fonts. Put the files in your app (e.g. public/fonts/) and pass a custom pairing — applyTheme() registers the @font-face rules for you:

applyTheme(document.documentElement, {
  fontFamily: {
    display: "'Brand Serif', Georgia, serif",
    sans: "'Brand Sans', system-ui, sans-serif",
    mono: "'Brand Mono', monospace", // optional
    displayWeight: 600, // optional
    faces: [
      { family: 'Brand Serif', src: '/fonts/brand-serif.woff2', weight: '400 700' },
      { family: 'Brand Sans', src: '/fonts/brand-sans.woff2', weight: '100 900' },
      { family: 'Brand Mono', src: '/fonts/brand-mono.woff2' },
    ],
  },
});

A face whose src is an http(s): or // URL throws: use a relative or root-relative path, or a data:/blob: URL. For static CSS, fontFaceCss(faces) returns the same @font-face rules.

Documentation

Guides, live examples and the full API are on loam.btndprojects.com — start with Theming.

Related packages

• @btndprojects/loam-tokens — the token pipeline
• @btndprojects/loam-ui-web — the components that read these variables

License

MIT © Nuszpl Botond

The bundled font files in fonts/ (Instrument Serif, JetBrains Mono, Manrope, Newsreader, Space Grotesk) are licensed under the SIL Open Font License 1.1 — each family's license ships next to it as fonts/<family>.LICENSE.txt.