theme editor

<tosi-theme-editor> edits a theme as data (see theme data): the base colours at the top, then each variable you declare, for one mode at a time. What you change applies to the page as you change it, and value is the theme, ready to save as JSON.

In an app, import it from tosijs-ui/theme-editor: as of 1.19.0 it is not in the root barrel, so an app that does not use it ships none of it. (The examples here import from tosijs-ui because doc pages run against the full bundle.)

import { tosiThemeEditor } from 'tosijs-ui'

const editor = tosiThemeEditor({
  applyId: 'theme-editor-demo',
  selectors: {
    light: '.theme-editor-demo',
    dark: '.darkmode .theme-editor-demo',
    highContrast: '.high-contrast:not(.darkmode) .theme-editor-demo',
    darkHighContrast: '.darkmode.high-contrast .theme-editor-demo',
  },
  variables: [
    { name: 'tosi-border-radius', kind: 'length', label: 'Corners', group: 'Shape' },
    { name: 'tosi-spacing', kind: 'length', label: 'Spacing', group: 'Shape' },
    { name: 'tosi-font-family', kind: 'font-family', label: 'Font', group: 'Type' },
    { name: 'tosi-font-size', kind: 'length', label: 'Size', group: 'Type' },
  ],
  presets: [
    { name: 'plain', label: 'Plain', theme: null },
    {
      name: 'rounded',
      label: 'Rounded',
      theme: {
        base: { accent: '#7a3cc4' },
        modes: { light: { 'tosi-border-radius': '16px', 'tosi-spacing': '16px' } },
      },
    },
  ],
})
const sample = document.createElement('div')
sample.className = 'theme-editor-demo'
sample.innerHTML = '<p>Themed sample</p><button>Accent button</button>'
editor.addEventListener('change', () => {
  console.log(JSON.stringify(editor.value))
})
preview.append(editor, sample)
.preview {
  display: flex;
  gap: 16px;
  align-items: flex-start;
  flex-wrap: wrap;
}
.theme-editor-demo {
  flex: 1 1 160px;
  padding: var(--tosi-spacing);
  border-radius: var(--tosi-border-radius);
  background: var(--tosi-bg);
  color: var(--tosi-text);
  font-family: var(--tosi-font-family);
  font-size: var(--tosi-font-size);
}
.theme-editor-demo button {
  border: none;
  padding: var(--tosi-spacing-sm) var(--tosi-spacing);
  border-radius: var(--tosi-border-radius);
  background: var(--tosi-accent);
  color: var(--tosi-accent-text);
}
import { deriveTheme } from 'tosijs-ui'

test('editing a base colour or a variable applies it, and a tuned value can be reset', async () => {
  const editor = preview.querySelector('tosi-theme-editor')
  // The fields exist once the editor has rendered, and so do their listeners.
  while (!editor.shadowRoot?.querySelector('[data-name="accent"]')) {
    await new Promise((resolve) => requestAnimationFrame(resolve))
  }
  const sample = preview.querySelector('.theme-editor-demo button')
  // A base colour is a text field; a variable is a <tosi-css-value>, whose value is its CSS.
  const edit = (name, value) => {
    const control = editor.shadowRoot.querySelector(
      `[data-name="${name}"] :is(tosi-css-value, input[type="text"])`
    )
    control.value = value
    control.dispatchEvent(new Event('change', { bubbles: true }))
  }
  // The editor starts on the mode the page is in, so a dark page edits dark mode.
  const { mode } = editor
  edit('accent', '#0064d2')
  // The variable, not the button's colour, which is mid-transition at this instant.
  const accent = deriveTheme(editor.value, editor.generator, { modes: editor.modes })[mode]['tosi-accent']
  if (mode === 'light') expect(accent).toBe('#0064d2')
  expect(getComputedStyle(sample).getPropertyValue('--tosi-accent')).toBe(accent)
  const radius = () => getComputedStyle(sample).getPropertyValue('--tosi-border-radius')
  edit('tosi-border-radius', '12px')
  expect(radius()).toBe('12px')
  expect(editor.value.modes[mode]['tosi-border-radius']).toBe('12px')
  editor.shadowRoot.querySelector('[data-name="tosi-border-radius"] .reset').click()
  expect(editor.value.modes[mode]['tosi-border-radius']).toBe(undefined)
  expect(radius()).toBe('4px')
})

Modes

The mode menu and the High contrast checkbox choose which mode you are editing. Light and dark are the menu, and high contrast goes with either, so the four default modes (light, dark, high contrast, dark high contrast) are two choices rather than four buttons. Each of the four keeps its own tuned values.

Pass modes (a ThemeModeSpec[], see theme data) for a theme's own, such as a tinted or monochrome mode: a mode joins the menu, unless its variant says it is a variation on another mode, which makes it a checkbox. With only selectors, the editor offers the modes those name. Every mode but the first starts out generated or derived; a value you change there is tuned for that mode only, marked with a dot, and stays put when the base colours change. The ↺ button puts it back to the generated value.

The editor starts on the mode the page is in, so a reader in dark mode edits dark mode, unless you set mode. Choosing a mode previews it: the editor shows the page in that mode while you work, by setting the mode's classes on <html> and <body> (the doc system's darkmode and high-contrast for the default modes), and puts them back when it is removed. Set previewModes to false to leave the page alone.

Presets

Pass presets (ThemePreset[]: a name, a label and a theme) and a Load preset… menu appears at the top, as in the example above. Loading one replaces the theme being edited with a copy of the preset's, which you then tune like any other; a preset whose theme is null loads an empty theme. The doc site's theme editor offers its Original, Glass and Material presets this way.

Declaring variables

variables lists what may be edited, beyond the base colours, each with a kind that picks its control:

kind control
color a colour well and the value as text (any CSS colour)
length, text text (16px, 1.5rem, calc(…))
number a number
font-family text, suggesting the families the page already uses
enum a menu of options

group puts variables under a heading. The base colours come from the generator (componentThemeGenerator unless you pass another).

Properties and events

The editor is styled with fixed colours in its shadow DOM, so no theme you make can make it unreadable.