Skip to content

Theming

You define a few color seeds, in hex or oklch, and the engine generates the full scales, dark mode, and the text for each color. Every step is calculated from contrast, not eyeballed.

How it works

Each color family starts from a seed, either a hex (#3b82f6) or an OKLCH color (oklch(0.62 0.19 259)). The engine builds 10 steps (100–1000) and gives each one a specific contrast against the background. The 100 is barely distinguishable from it, and the 1000 is almost black in light mode and almost white in dark mode. That’s why the 500 step behaves much the same with any color, whether it’s a blue, a lime, or a red.

The hue holds across the scale, and the saturation never exceeds your seed’s, so a muted seed gives you a muted scale. The exception is yellows, which lean orange as they get darker instead of turning greenish. Dark mode isn’t a mirror of light mode. It’s recalculated against the dark background with the same criteria, so --color-brand-500 “does the right thing” in light and dark mode. See the Tokens page for every resulting scale.

Here’s what the engine calculates for #3b82f6. “Background” is the step’s WCAG contrast with the page background; “text” is the contrast of the text that goes on top (that step’s -contrast), in WCAG and in APCA (Lc).

Step Light · background Light · text Dark · background Dark · text
1001.1:118.2 · Lc 1001.0:118.4 · Lc 103
2001.2:116.1 · Lc 921.1:117.1 · Lc 102
3001.5:113.1 · Lc 801.3:114.7 · Lc 101
4002.1:19.4 · Lc 631.8:110.6 · Lc 95
5003.7:1 · your color5.3 · Lc 403.4:15.6 · Lc 80
6006.0:15.3 · Lc 765.5:1 · your color5.1 · Lc 39
7008.5:17.6 · Lc 847.8:17.2 · Lc 53
80012.0:110.7 · Lc 9211.0:110.2 · Lc 69
90016.0:114.2 · Lc 9615.0:113.9 · Lc 86
100019.0:116.9 · Lc 9818.0:116.7 · Lc 97

Your color stays exact

The seed isn’t a suggestion. It shows up as is on the step its lightness calls for. With #3b82f6, your blue lands on step 500 in light mode and on 600 in dark mode; the rest of the scale is calculated around it.

There’s a band of mid lightness where no text, light or dark, reaches AA contrast on the color. If your seed falls right there, it shifts to the nearest edge (by 3 lightness points at most), and the Theme editor tells you by how much and why. Legibility wins.

That scale is your brand’s palette. The fill of buttons and controls doesn’t come from whichever step the seed lands on, but from the “solid” (next section): there, a black or very dark brand stays as you wrote it.


Text on each color

Every step comes with its text color. --color-brand-600-contrast is the system gray (the lightest or darkest one in the mode) that reads best on --color-brand-600. On every step and with any seed, that text reaches AA contrast for normal text (4.5:1 or higher). It’s a property of the calculation, not something checked by hand.

Besides WCAG 2 contrast, which is the required criterion, APCA is measured too (Lc; higher means more legible). APCA doesn’t decide anything. The Theme editor shows it so you can see where the two methods disagree, especially in the mid tones.


Your brand’s fill

The primary button and the checked checkbox, radio, and toggle are painted with the theme’s primary; if you don’t set one, with your brand (brand). Set brand: '#7c3aed' and the button is violet; for black buttons with that violet brand, add primary: 'oklch(0.15 0 0)' to the theme (next to colors, like focusRing). That’s what this documentation’s theme does: blue brand, black buttons. Everything else that carries the brand (badges, avatars, progress bars, variant="brand") follows brand.

So it looks right in light and dark mode, the engine picks the scale step that works as the fill, the solid:

  • In light mode: if your brand is darker than the family’s working tone (step 600), your exact color is used. If it’s lighter, step 600 is used, the one that holds white text on top.
  • In dark mode: a neutral brand (black or gray) inverts, like the rest of the grays: black becomes white. A colored brand uses a lighter tone that reads on the dark background.

The status colors (success, danger, info, warning) follow the same rule, and the color variants of those four components (variant-danger, etc.) use their family’s solid.

The primary exposes its own under the same name (--color-primary-solid and the rest; it has no scale, so bg-primary-500 doesn’t exist). Each family exposes the solid as variables, so you can use it in your own components: --color-brand-solid, --color-brand-solid-hover, and --color-brand-solid-active, each with its text color (--color-brand-solid-contrast, -solid-hover-contrast, -solid-active-contrast), which always reaches AA contrast. They exist for brand, for any color you add, and for the status colors.

css

There are utilities too: bg-brand-solid, bg-brand-solid-hover, bg-brand-solid-active, the text color color-brand-solid-contrast (and the hover and active ones), and outline-brand-solid.

html

A white brand can’t be the fill

If the seed is almost white, it doesn’t show on the light background and the solid can’t be white: it comes out gray (step 600). taisho generate warns you, and so does the Theme editor and, in development, createTheme (one console.warn per seed; without a bundler, such as from a CDN, it always warns). For a white button use an outlined variant; for the brand, pick a darker seed.

P3 displays

A P3 display shows more saturated colors than an sRGB one. The engine calculates both scales with the same variable names, and the browser uses the one that fits the display (the color-gamut: p3 media query). No color falls outside what the display can show, so the browser doesn’t have to clip or distort it. In sRGB you see the sRGB scale, and in P3 you get more vivid steps. An oklch seed that only exists in P3 looks exact on those displays and gets as close as possible in sRGB.


Grays

The grays (--color-gray-*) are pure neutrals by default. If you want them to carry a hint of your brand, the theme accepts a tint. c is how much color (0.01 is barely noticeable) and h is the hue in degrees. The tint keeps each gray’s lightness and fades out toward white and black, which stay neutral. The text for each step is measured against the grays the theme actually uses.

ts

In the Theme editor, the “Brand-tinted” option does exactly that with the hue of your brand seed.


Color blindness

Color should never be the only signal. A status also comes across through text, an icon, or a shape. To check what happens to your palette, the Theme editor has a color blindness view that simulates deuteranopia, protanopia, and tritanopia on the scales and the preview.


Three ways to use it

There are three ways to apply a theme, from the shortest to the most custom. Pick the one that’s enough. You don’t need to go through the earlier ones.


1. Use the ready-made theme

This path doesn’t install anything. The first <link> in the Installation guide brings the theme values; the second, the rules that use them. The theme always goes first.

html

The compiled theme is taisho, with a black brand (oklch(0.15 0 0), the same gray 1000, which looks white in dark mode), a lime secondary, and an amber accent. It’s the one these docs use. If you need other colors, go on to the two paths below.


2. Repaint in the browser

With createTheme you pass your seeds and the theme applies instantly, without compiling anything. It sits on top of the theme loaded by the <link>. It only overrides what you define, and calling it again replaces the previous one instead of stacking. Use it, for example, to give each customer of your app their own color.

ts

createTheme takes the same theme keys as the config, except components: colors, scales (fontSizes, shadows, motion…), density, focusRing, and locked. It changes the values of levels that already exist; adding new levels (extend) is compiled.

createTheme is the main export of @taishods/core. Install it with npm i -D @taishods/core, as in path 3. The CDN <script> doesn’t include it. If you’d rather not depend on a package, path 3 gives you the same result, compiled.

3. Compile your own CSS

Your seeds live in a taisho.config.ts in your project, and the CLI compiles them into CSS with your palettes already calculated. Every brand change means editing the config and running the command again (build time, not runtime).

bash

generate writes theme.css with your tokens, fonts.css, and the system. That’s taisho.css with only what your files use if you declare content in the config, or the full taisho.full.css if you don’t. When it’s done, it prints the exact <link> tags to paste. Your theme replaces the first <link> from path 1.

Where the command comes from

The CLI ships in @taishods/core. With npm i -D @taishods/core you get the taisho command. It needs Node 22.18 or newer. If you’re going to use icons, also install npm i -D lucide-static, where the names come from.

What goes in the config

A theme is an entry in themes. Its key is the name of the output file, and inside go the brand seeds and, if you want, a few overrides.

ts

The status colors (success, warning, info, danger) come from defaultStates; a theme can override them with its own states field. Each status’s background and border (--ts-color-*-bg, -border) come from steps 100 and 200 of its palette, so they change on their own when you move the seeds.

brand is required in every theme. The fill of primary buttons and of checked checkboxes, radios, and toggles, plus links and accents, come from that seed. Without it, taisho generate stops with an error that says which theme is missing it and what to add, and your editor flags the type before you run anything. The other colors (brand-secondary, accent…) are optional and can have any name you like.

If your brand ends up nearly the same color as a status (a red brand with the default danger, for example), a primary button and a danger button would look the same. In that case taisho generate warns you, without stopping, with the measured distance, and the fix is to define that status separately in defaultStates. The warning fires below a 0.05 distance between colors (ΔE in OKLab), a difference you can barely see with the naked eye.

Besides colors, each theme can override its fonts, radius, spacing, shadows, grays (neutral), and surfaces (material), and also typography, strokes, motion, and density (below). To add new names—a screen, a radius, a font size, your own class—there are extend and utilities. The config declares names and the theme changes values. Every scale is on the Tokens page with its values. The classes it generates follow the Class names grammar.

focusRing sets the color of the focus ring across the whole system (--ts-focus-ring-color) with any CSS value, for example 'var(--color-brand-600)'. If you don’t set it, it comes from your brand.


Focus color

Focus (what you see when navigating with the keyboard) is a thin line against the edge plus a more transparent halo of the same color. The color comes from the theme’s focusRing option, which takes any valid CSS color, including a system variable; if you don’t set it, from your brand. Buttons and fields with a color (danger, success…) use their own. For your own components: focus-ring draws the focus and focus-ring-danger (or any color in your theme) picks the color.

ts

Corner shape

The theme’s cornerShape option picks between round corners ('round', the usual one) and 'squircle', a smoother curve that blends into the side instead of cutting it with an arc. It works the same in createTheme, in the config’s themes, and in the internal config. It comes out as the --ts-corner-shape variable, which every radius-* class and every component with a radius reads. Any value other than those two stops taisho generate with the exact path. In a locked theme (locked) it is ignored, like the other overrides.

corner-shape draws the squircle, today only in Chromium. At the same size, that curve looks tighter than an arc, so with 'squircle' every radius goes up one step: xs takes the value of sm, sm that of md, and so on up to 2xl, which takes the value of 3xl. 3xl stays the same, and none and full don’t move. Radii the theme changes go up with their new value. Names added by extend.radius take the shape but don’t go up. The engine works it out; nothing else needs touching.

Everything sits inside @supports (corner-shape: squircle): in Firefox and Safari the token stays at round and the radii don’t go up, so everything looks round with the usual sizes. With an explicit cornerShape: 'round' in createTheme, a base compiled with squircle can be overridden.

ts

Typography

These are two different things: the CSS stack the tokens use (--font-sans) and which files get downloaded. In the config they’re fonts and fontFaces; the fonts.css that generate outputs is built from the second one.

ts

The @fontsource/* packages have to be in your project’s package.json. Each combination of script and weight is one more file the user downloads. latin covers English, and declaring too few costs nothing, while declaring too many is paid for on every visit.

For <em>, quotes and emphasis with the font’s real italic (otherwise the browser slants the regular), add styles: ['normal', 'italic']. Without styles only the regular is downloaded. Each weight and script adds one italic file, and the font has to ship it: if the package has no italic for that weight, generate stops with an error that names it.

ts

Change and add levels to each scale

Every scale in the system (font sizes, shadows, durations, sizing…) is reached from two places with the same path. In the theme, themes.<theme>.<scale> changes the value of a name that already exists. In extend.<scale> you add new names, which apply to every theme and generate their variable and their classes. extend only adds: overriding a system name is an error, and so is a name the scale doesn’t have, written inside a theme (the message says where to add it).

Scale In the theme: changes the value In extend: adds levels Generates
Font sizesfontSizesfontSizes--ts-fontsize-N · text-N · type-heading-N · type-copy-N
Line heightslineHeightslineHeights--ts-lh-N · leading-N
Letter spacingletterSpacingletterSpacing--ts-ls-* · tracking-*
Font weightsfontWeightsfontWeights--ts-fw-* · weight-*
Stroke widthsborderWidthsborderWidths--ts-border-width-N · border-N · ring-N
Blursblursblurs--ts-blur-* · blur-* · backdrop-blur-*
Opacitiesopacitiesopacities--ts-opacity-N · opacity-N
Shadowsshadowsshadows--ts-shadow-* · shadow-* · surface-* · floating-*
Durations and easingsmotion.durations · motion.easingsmotion.durations · motion.easings--ts-duration-* · duration-* · --ts-ease-* · ease-*
Radiiradiusradius--ts-radius-* · radius-* · --ts-corner-shape (cornerShape option)
Gaps and spacesspacing.gaps · spacing.spacesspacing.gaps · spacing.spaces--ts-gap-* · --ts-space-* · gap-* · p-* · m-*
Screensscreensscreens--ts-screen-* · screen variants
Sizingfixed: not changedsizing: [30, 100]--ts-sizing-N · p-N · w-N · h-N · size-N · gap-N · icon-N…
Layers (z-index) and loopszIndex · motion.loopsnot extendable--ts-z-* · --ts-duration-spin…
ts

The levels you add are used like any other:

html
  • Names. In font sizes, line heights, and stroke widths the name is a whole number from 1 to 999; in opacities, from 0 to 100; in sizing, the list of px. Everything else is lowercase with hyphens.
  • Values. An opacity goes from 0 to 1 (or is a var()), a weight from 1 to 1000, a duration is in ms or s, a z-index is a whole number. A value that could close the CSS declaration (; or braces) is rejected.
  • A font size comes with its line height. Every extend.fontSizes needs a lineHeights with the same name. Sizes from 14 up add type-heading-N and sizes from 12 to 24 add type-copy-N. If you change fontSizes in a theme without touching lineHeights, the line height stays as it was.
  • Sizing. sizing is fixed: you add levels, but no theme changes the value of an existing one. Each new level brings its classes and the icon’s icon-N modifier, which the Icon component uses with a numeric size.
  • Motion. A duration you add also drops to 1 ms with the system’s “reduce motion”. Infinite animations (loops) can’t be extended, and with “reduce motion” the skeleton and the indeterminate bar stand still (motion.iterations).
  • Shadows. A new shadow generates shadow-*, surface-*, and floating-*; it doesn’t reach the material-* surfaces, which carry their own.
  • The focus. Stroke widths 1 and 4 draw the focus line and halo: at 0 they disappear. taisho generate warns, without stopping.
  • Right-to-left languages. In Arabic, Persian, Urdu, and Hebrew, line height and letter spacing follow your theme’s, with a line height of at least 1.35. If you set it with var(), the variable must hold a length, not a bare number.
  • A locked theme ignores the values it defines, but receives everything you add in extend.
  • Autocomplete. If you add levels in extend or declare utilities, taisho generate writes taisho.classes.d.ts with your own classes: keep it inside your tsconfig include and they join TaishoClass.

Theme density

Density is the size of controls (height, padding, checkboxes) in normal mode and in compact mode (class="ts compact"). Each theme can change the px of every family and size with density: the families are control-h, button-px, field-px, select-pr, textarea-px, textarea-py, badge-h, badge-px, tag-h, tag-px, control-box, and radio-dot, and the sizes are sm, md, and lg (xs only in control-h and button-px). compact.spacing changes the gaps and spaces that compact mode shrinks (none, quarter, half, base, section, double); the ones you add in extend aren’t compacted.

ts

Whatever you don’t define keeps the built-in value. When a theme defines density, the density-compact (or density-comfortable) class on a single component, as in class="ts button density-compact", takes its values too; createTheme applies the theme’s density to the page, but doesn’t reach that class.


Dark mode and density (runtime)

Both are controlled with a class on <html>, so you can toggle them in the browser without rebuilding anything, and they work the same with any of the three paths:

ts

Follow the system mode

With darkMode: 'media' in the config, the page follows the visitor’s system preference from the first paint, with no script in the <head>. The dark class on <html> forces dark and the light class forces light: that’s what a theme picker in your app uses. The default is 'class': dark mode turns on only with the class.

ts
The option applies when the CSS is generated. The ready-to-use file from the CDN turns on dark mode with the dark class.

Sections with a fixed mode

A dark footer or side panel in a light SaaS doesn’t change when the page does. scheme-dark and scheme-light fix the mode of an element and everything inside it: colors, components and text color resolve in that mode, whatever the page’s mode is. Paint its background too, because the class fixes the mode and doesn’t paint the element:

html

Fixed colors come from the same scale: scheme-dark bg-background-100 is a near-black background in both modes and scheme-light bg-background-100 a white one. A NavBar inside the section takes that section’s background with no variant.

Menus, dialogs and toasts that open over the page take the page’s mode, not the mode of the section they were opened from.