Theming
The design tokens behind the colors, spacing and type of @k8ordo/ui. Each token is a CSS variable, so redefining it fits the library to your application.
On this page
Colors by purpose
Colors named for their purpose: text, backgrounds and borders. Each has a light and a dark value, and the dark class switches between them.
Text
color-fg-base
Light gray-900 · Dark gray-50
Body text
color-fg-subtle
Light gray-600 · Dark gray-400
The faintest text, such as placeholders
color-fg-mute
Light gray-700 · Dark gray-300
Supporting text, such as descriptions and captions
color-fg-inverse
Light gray-50 · Dark gray-900
Text on bg-inverse
color-fg-info
Light blue-800 · Dark blue-200
Informational message text
color-fg-success
Light green-800 · Dark green-200
Success message text
color-fg-warning
Light yellow-800 · Dark yellow-200
Warning message text
color-fg-error
Light red-800 · Dark red-200
Error message text
Backgrounds
color-bg-base
Light white · Dark gray-800
Card background
color-bg-raised
Light white · Dark gray-800
Background of overlays such as modals and menus
color-bg-surface
Light gray-50 · Dark gray-950
The outermost background: lighter than bg-subtle in light mode, darker in dark mode
color-bg-subtle
Light gray-100 · Dark gray-900
Page background
color-bg-mute
Light gray-200 · Dark gray-700
Hover-state background
color-bg-emphasize
Light gray-300 · Dark gray-600
Active-state background
color-bg-inverse
Light gray-900 · Dark white
Inverted background, paired with fg-inverse
color-bg-info
Light blue-100 · Dark blue-900
Informational message background
color-bg-success
Light green-100 · Dark green-900
Success message background
color-bg-warning
Light yellow-100 · Dark yellow-900
Warning message background
color-bg-error
Light red-100 · Dark red-900
Error message background
Borders
color-border-base
Light gray-400 · Dark gray-600
Standard borders, such as form fields
color-border-subtle
Light gray-100 · Dark gray-700
The faintest borders
color-border-mute
Light gray-200 · Dark gray-600
Restrained borders, such as separators
color-border-emphasize
Light gray-500 · Dark gray-500
Emphasized borders, as on hover
color-border-inverse
Light gray-700 · Dark gray-300
Borders on bg-inverse
color-border-info
Light blue-500 · Dark blue-400
Information borders, also the focus ring
color-border-success
Light green-500 · Dark green-400
Success-state borders
color-border-warning
Light yellow-500 · Dark yellow-400
Warning-state borders
color-border-error
Light red-500 · Dark red-400
Error-state borders
Brand colors
primary is teal and secondary is cyan. The four group colors tell data series apart, as in a chart.
primary
color-primary-fg
Light teal-800 · Dark teal-300
Primary text and icons
color-primary-bg
Light teal-200 · Dark teal-900
Primary fill, as in a solid button
color-primary-bg-subtle
Light teal-50 · Dark teal-950
The faintest primary background, as in a selected state
color-primary-bg-mute
Light teal-100 · Dark teal-900
Restrained primary background
color-primary-bg-emphasize
Light teal-300 · Dark teal-800
Emphasized primary background, as on hover
color-primary-border
Light teal-500 · Dark teal-500
Primary borders
secondary
color-secondary-fg
Light cyan-800 · Dark cyan-300
Secondary text and icons
color-secondary-bg
Light cyan-200 · Dark cyan-900
Secondary fill
color-secondary-bg-subtle
Light cyan-50 · Dark cyan-950
The faintest secondary background
color-secondary-bg-mute
Light cyan-100 · Dark cyan-900
Restrained secondary background
color-secondary-bg-emphasize
Light cyan-300 · Dark cyan-800
Emphasized secondary background, as on hover
color-secondary-border
Light cyan-500 · Dark cyan-500
Secondary borders
group
color-group-primary
Light teal-800 · Dark teal-200
First data series
color-group-secondary
Light cyan-800 · Dark cyan-200
Second data series
color-group-tertiary
Light pink-800 · Dark pink-200
Third data series
color-group-quaternary
Light purple-800 · Dark purple-200
Fourth data series
Base palette
Ten hues, each in eleven shades from 50 to 950. The hues other than gray share one lightness scale, so the same shade gives close to the same contrast.
Components never use these colors directly. They go through the colors by purpose above.
Overriding tokens
app.css:root {
--color-primary-fg: var(--purple-800);
--color-primary-bg: var(--purple-200);
--color-primary-bg-subtle: var(--purple-50);
--color-primary-bg-mute: var(--purple-100);
--color-primary-bg-emphasize: var(--purple-300);
--color-primary-border: var(--purple-500);
}
.dark {
--color-primary-fg: var(--purple-300);
--color-primary-bg: var(--purple-800);
--color-primary-bg-subtle: var(--purple-950);
--color-primary-bg-mute: var(--purple-900);
--color-primary-bg-emphasize: var(--purple-700);
--color-primary-border: var(--purple-500);
}app.css:root {
--color-primary-border: oklch(0.55 0.15 300);
}Tokens are declared on :root and .dark, outside any layer. Redefine a name in CSS loaded after the @k8ordo/ui stylesheet to override it.
The tokens point at the base palette, named like --purple-200. Point them at another hue and the brand color changes as a whole. A literal value works as well as a reference.
High-contrast values are redefined on :root and .dark inside @media (prefers-contrast: more).
Typography
Text sizes
xsk8ordo0.75rem / 1.333smk8ordo0.875rem / 1.429mdk8ordo1rem / 1.5lgk8ordo1.125rem / 1.556xlk8ordo1.25rem / 1.42xlk8ordo1.5rem / 1.3333xlk8ordo1.875rem / 1.2emphasizek8ordo3rem / 1highlightk8ordo6rem / 1Font weights
mediumk8ordo450boldk8ordo700There are two weight tokens, --font-weight-medium and --font-weight-bold. --font-weight-medium is 450, lighter than the usual 500.
Letter spacing
nonek8ordo0normalk8ordo0.025emLine height
nonetightsnugnormalrelaxedlooseCorner radius
xssmmdlgxl2xlThe radius follows the element’s role: --radius-full for buttons, --radius-xl for inputs and cards, --radius-md for checkboxes.
Shadows
2xsxssmmdlgxl2xlShadows for cards and popovers. Cards use --shadow-sm, and modals and menus use --shadow-md. --shadow-xl and anything heavier are never used.
Spacing
0.512345681012162024The spacing unit is --spacing, 0.25rem (4px). Multiply it by the step you want, as in calc(var(--spacing) * 4). With tailwind.css, a class such as p-4 or gap-6 is that number times 0.25rem.
Breakpoints
smmdlgxl2xlThe widths at which a layout changes. A media query cannot read a variable, so write the value, as in @media (width >= 40rem). With tailwind.css they are variants such as sm:.
Stacking order
z-raisedAutocomplete, Combobox, RangeSlider10z-overlayPopover, DropdownMenu, ListBox, Tooltip1000z-modalModal, Drawer1300z-toastToast1500Every component in the overlay and modal rows of the table opens in the browser’s top layer. There, elements stack in the order they opened, so those two values have no effect.
toast only orders toasts within the page.
Dark mode
document.documentElement.classList.add('dark');Add the dark class to <html> to switch the whole page to the dark values.
The CSS color-scheme property becomes dark under .dark too, so scrollbars and form controls are drawn dark. With tailwind.css, the dark: variant applies under .dark.
@k8ordo/ui never adds the class itself. In a k8ordo application, @k8ordo/color-scheme adds it before the first paint.
Printing
deck.module.css.deck {
print-color-adjust: exact;
}deck.tsx<div className={clsx(styles.deck, 'print-as-shown')}>{slides}</div>When printing, the color tokens and color-scheme go back to the light values even under .dark. Browsers leave backgrounds out by default, so the dark values would print light text on white paper. The dark: and light: variants of tailwind.css switch the same way.
To print in the scheme on screen, such as a slide deck printed with its backgrounds, add an element with the print-as-shown class. A .dark that contains it keeps the dark values in print. With dark on <html>, that is the whole page, so hide what you do not print. To print the backgrounds, set print-color-adjust: exact as well.
High contrast
toggle-button.module.css.button[aria-pressed='true'] {
background-color: var(--color-primary-bg-emphasize);
@media (forced-colors: active) {
background-color: var(--color-system-highlight);
color: var(--color-system-highlight-text);
}
}In your own UI, write the two cases as @media (prefers-contrast: more) and @media (forced-colors: active). Under forced colors only system colors apply, so paint a selected state with a system color token such as --color-system-highlight. With tailwind.css, they are the contrast-more: and forced-colors: variants.
The component stylesheet follows the OS settings. Under prefers-contrast: more, text and border colors gain contrast against their background, and cards and modals that relied on a shadow gain a border. Under forced-colors: active, borders, focus rings and selected states use system colors.
Pitfall
Do not draw a border or a focus ring with box-shadow alone, since forced colors remove shadows. To hide an element, use visibility: hidden, not a transparent text color. Under forced colors, a transparent color is painted too and shows.