theme data

A theme as plain data: a few base values (the brand colours) that a generator turns into every variable a page needs, plus values tuned by hand for each mode. It serialises to JSON, so a project or a customer can save one and load it back, and applying it is one stylesheet: no editor code, which lives apart on tosijs-ui/theme-editor.

import { applyThemeData, componentThemeGenerator } from 'tosijs-ui'

const theme = {
  base: { accent: '#0b7a5c', background: '#fbfaf7', text: '#1d1d1b' },
  modes: { light: { 'tosi-border-radius': '12px' } },
}
// Scoped to the demo; a page's own theme would leave out `selectors`.
const resolved = applyThemeData(theme, componentThemeGenerator, {
  id: 'theme-data-demo',
  selectors: {
    light: '.theme-data-demo',
    dark: '.darkmode .theme-data-demo',
    highContrast: '.high-contrast:not(.darkmode) .theme-data-demo',
    darkHighContrast: '.darkmode.high-contrast .theme-data-demo',
  },
})

preview.append(
  Object.assign(document.createElement('div'), {
    className: 'theme-data-demo',
    textContent: `accent ${resolved.light['tosi-accent']}, radius ${resolved.light['tosi-border-radius']}`,
  })
)
.theme-data-demo {
  padding: var(--tosi-spacing);
  border-radius: var(--tosi-border-radius);
  background: var(--tosi-accent);
  color: var(--tosi-accent-text);
}
test('base values generate the palette, and a hand-tuned value wins', () => {
  const box = preview.querySelector('.theme-data-demo')
  const style = getComputedStyle(box)
  // The radius tuned in light holds in every mode; the accent is light's only in light.
  expect(style.borderRadius).toBe('12px')
  const light = !document.body.matches('.darkmode, .high-contrast')
  if (light) expect(style.backgroundColor).toBe('rgb(11, 122, 92)')
  else expect(style.backgroundColor).not.toBe('rgb(11, 122, 92)')
})

Modes

A theme's modes are a list (ThemeModeSpec[]), and THEME_MODE_SPECS is the one used unless you pass modes: light, dark, highContrast and darkHighContrast. Each mode names the selector its values are written under, the classes that put a page in it (for the editor's preview), the mode it is made from (light unless it says otherwise) and how it is made from it (derive):

Only colour literals are transformed. A value derived from others (color-mix(in oklab, var(--accent) 20%, white)) is left as written, and the browser derives it again from the transformed roots. So a mode needs to change only the few colours everything else hangs from.

A theme declares modes of its own by passing a list, such as a tinted mode under .tinted:

const modes = [
  ...THEME_MODE_SPECS,
  {
    name: 'tinted',
    label: 'Tinted',
    selector: '.tinted',
    classes: ['tinted'],
    derive: [{ tint: '#3355dd' }],
  },
]
applyThemeData(theme, null, { modes, page })

A value tuned by hand in a mode (theme.modes.dark) wins over the derived one, and survives regeneration: change the accent, and every generated value follows while your tuned ones stay put.

A mode other than the first writes only what differs from what the page would show anyway (so a font or a size you set once applies in every mode unless a mode tunes it), plus whatever another mode writes, since mode selectors can match together. Pass selectors to write a mode somewhere else, such as a scoped part of the page.

No generator. A design system whose CSS derives its own variables (most do) needs no generator: pass null, and pass page, what its CSS declares in each mode, so a derived mode has roots to transform. A mode with no derive, or one the page's CSS declares itself, is then just what the page declares, plus what you tune: the page's own dark mode is not second-guessed. discoverThemeVariables finds the page's variables and declaredValues turns them into page; both come from tosijs-ui/theme-discovery, not the package root:

import { applyThemeData, THEME_MODE_SELECTORS } from 'tosijs-ui'
import { declaredValues, discoverThemeVariables } from 'tosijs-ui/theme-discovery'

const found = discoverThemeVariables('md-sys-*', { selectors: THEME_MODE_SELECTORS })
applyThemeData(theme, null, { page: declaredValues(found) })

Web fonts

fonts lists stylesheets to link, such as a Google Fonts URL; applyThemeData links them (and unlinks ones the theme no longer names), and the doc site's build links them from each page's <head>. Only fonts.googleapis.com and fonts.bunny.net are accepted, since linking a stylesheet injects CSS. parseFontImport takes whatever Google Fonts offers you to copy (a <link>, an @import line, or the URL) and returns the URL and its families.

Values are checked too: a theme is data, never CSS of its own. A variable name is letters, digits, - and _, and a value that could close its rule (a brace, a comment, a ; outside brackets or quotes, unbalanced brackets or quotes) is left out of the stylesheet; the doc site's build fails on one in a saved theme file. Treat a theme from someone you do not trust as you would their images: it can still change how your page looks.

Generators

A generator says which base values there are, and turns them into each mode's variables:

Variable names are CSS custom properties without the leading dashes: tosi-accent, not --tosi-accent or tosiAccent.