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):
'invert'inverts luminance; with a generator, its own dark adjustments follow. Dark is light inverted, and a value you tuned in light is carried over, inverted.'contrast'pushes values apart; with a generator, the base background goes to white, the text to black, and the accent darkens until it reaches 7:1 (WCAG AAA) against it. Dark high contrast is high contrast, inverted.'monochrome'takes the colour out, and{ tint: '#3355dd', amount }takes it out and tints toward a hue.- A function of the values does anything else.
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:
componentThemeGeneratoris the tosijs-ui component theme (createTheme), with base valuesaccent,backgroundandtext;- the doc system has its own,
docSystemThemeGenerator(fromtosijs-ui/doc-system/doc-system-styles), which its theme editor uses.
Variable names are CSS custom properties without the leading dashes: tosi-accent, not
--tosi-accent or tosiAccent.