@k8ordo/ui

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

Gray
50
100
200
300
400
500
600
700
800
900
950
Red
50
100
200
300
400
500
600
700
800
900
950
Pink
50
100
200
300
400
500
600
700
800
900
950
Purple
50
100
200
300
400
500
600
700
800
900
950
Cyan
50
100
200
300
400
500
600
700
800
900
950
Blue
50
100
200
300
400
500
600
700
800
900
950
Teal
50
100
200
300
400
500
600
700
800
900
950
Green
50
100
200
300
400
500
600
700
800
900
950
Yellow
50
100
200
300
400
500
600
700
800
900
950
Orange
50
100
200
300
400
500
600
700
800
900
950

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.333
smk8ordo0.875rem / 1.429
mdk8ordo1rem / 1.5
lgk8ordo1.125rem / 1.556
xlk8ordo1.25rem / 1.4
2xlk8ordo1.5rem / 1.333
3xlk8ordo1.875rem / 1.2
emphasizek8ordo3rem / 1
highlightk8ordo6rem / 1

Font weights

mediumk8ordo450
boldk8ordo700

There are two weight tokens, --font-weight-medium and --font-weight-bold. --font-weight-medium is 450, lighter than the usual 500.

Letter spacing

nonek8ordo0
normalk8ordo0.025em

Line height

none
The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.
1
tight
The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.
1.25
snug
The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.
1.375
normal
The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.
1.5
relaxed
The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.
1.625
loose
The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog.
2

Corner radius

xs0.125rem
sm0.375rem
md0.5rem
lg0.75rem
xl1rem
2xl1.25rem

The radius follows the element’s role: --radius-full for buttons, --radius-xl for inputs and cards, --radius-md for checkboxes.

Shadows

2xs0 1px 0 0 rgb(0 0 0 / 0.05)
xs0 1px 2px 0 rgb(0 0 0 / 0.05)
sm0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)
md0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)
lg0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)
xl0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)
2xl0 25px 50px -12px rgb(0 0 0 / 0.25)

Shadows 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.5
0.125rem (2px)
1
0.25rem (4px)
2
0.5rem (8px)
3
0.75rem (12px)
4
1rem (16px)
5
1.25rem (20px)
6
1.5rem (24px)
8
2rem (32px)
10
2.5rem (40px)
12
3rem (48px)
16
4rem (64px)
20
5rem (80px)
24
6rem (96px)

The 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

sm≥ 640px (40rem)
md≥ 768px (48rem)
lg≥ 1024px (64rem)
xl≥ 1280px (80rem)
2xl≥ 1536px (96rem)

The 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, RangeSlider10
z-overlayPopover, DropdownMenu, ListBox, Tooltip1000
z-modalModal, Drawer1300
z-toastToast1500

Every 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

ts
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.

Warning

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.

k8ordo

React libraries that use Baseline features without holding back.