Theming

Setup

Import the default theme once at the top of your app — this loads every design token as a CSS custom property on :root.

import '@corndev/ui/theme';

Or from CSS:

@import '@corndev/ui/theme';

Re-theming in one step

Override the brand tokens and every component follows. This is the whole mechanism — there is no theme object, no provider, and no build step.

@import '@corndev/ui/theme';

:root {
  --corn-primary: #0ea5e9;
  --corn-primary-hover: #38bdf8;
  --corn-primary-active: #0284c7;
}

You never need !important or selector overrides: component CSS reads tokens and never hardcodes a colour, so your declaration on :root wins on its own.

A :root override sets the light theme. Dark mode keeps its own values for any token it restates — see Dark mode for how to re-theme that side.

Derived tokens follow automatically

Focus rings, overlays, and thumb shadows are composed from the brand tokens using color-mix(), so they re-tint when you change --corn-primary or --corn-danger. You do not restate them:

/* This alone re-tints every focus ring in the library. */
:root { --corn-primary: #16a34a; }

Override a derived token directly only when you want it to stop tracking its source:

:root {
  /* Thinner ring, still your brand hue */
  --corn-focus-ring-width: 2px;

  /* Opt out of the hue entirely */
  --corn-focus-ring: 0 0 0 2px rgba(0, 0, 0, 0.4);
}

Scoped themes

Tokens are ordinary custom properties, so they cascade. Set them on any element to theme part of a page:

.checkout-panel {
  --corn-primary: #16a34a;
  --corn-radius-md: 2px;
}

Dark mode

Set data-theme="dark" on the document root. The bundled dark theme restates the colour tokens; the derived tokens re-compose from them, so focus rings adapt with no extra work.

document.documentElement.setAttribute('data-theme', 'dark');

Re-theming dark mode

The dark theme ships on :root[data-theme='dark'], which deliberately outranks a plain :root. That is what lets you re-theme the library without dark mode quietly inheriting your light values — but it also means a :root block cannot change a dark colour. Match the same selector:

@import '@corndev/ui/theme';

/* Light */
:root { --corn-primary: #0ea5e9; }

/* Dark — needs the matching selector, not a bare [data-theme='dark'] */
:root[data-theme='dark'] { --corn-primary: #38bdf8; }

A bare [data-theme='dark'] { … } scores lower and will not take effect. This applies to every token the dark theme restates; tokens it leaves alone are derived and follow your :root override on both sides.

Following the OS preference

prefers-color-scheme is not wired up for you — the attribute is the only switch. To track the OS setting, either flip the attribute in JS, or declare your own dark palette in a media query:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme='light']) {
    --corn-bg-primary: #0f172a;
    --corn-text-primary: #ffffff;
    /* …the rest of your dark palette */
  }
}

Note that this second form does not pick up the bundled dark theme — it only applies the tokens you list. Flipping the attribute is the simpler route:

const mq = matchMedia('(prefers-color-scheme: dark)');
const sync = () => document.documentElement.setAttribute('data-theme', mq.matches ? 'dark' : 'light');
sync();
mq.addEventListener('change', sync);

A light/dark toggle

Corn UI ships no toggle component: the part that matters runs before the page paints, which a component cannot do. A toggle is two small pieces, and this site uses exactly these.

1. In <head>, before any stylesheet paints. Without it the page renders light and then flips, which is visible on every load of a dark page:

<script>
  (() => {
    try {
      const saved = localStorage.getItem('theme');
      const theme = saved ?? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
      document.documentElement.setAttribute('data-theme', theme);
    } catch {
      // A private window or blocked site data makes localStorage throw.
      document.documentElement.setAttribute('data-theme', 'light');
    }
  })();
</script>

2. The button. It names the state it switches to, and saves the choice where it can:

<button id="theme-toggle" class="corn-button" data-variant="button" data-level="neutral" data-emphasis="quiet" type="button"></button>
<script>
  const button = document.getElementById('theme-toggle');
  const paint = theme => {
    const next = theme === 'dark' ? 'light' : 'dark';
    button.textContent = `${next[0].toUpperCase()}${next.slice(1)} mode`;
    button.setAttribute('aria-label', `Switch to ${next} mode`);
  };
  paint(document.documentElement.getAttribute('data-theme') ?? 'light');
  button.addEventListener('click', () => {
    const next = document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
    document.documentElement.setAttribute('data-theme', next);
    paint(next);
    try { localStorage.setItem('theme', next); } catch { /* not persisted */ }
  });
</script>

Copy the first piece even if you write the button differently. It is the one that is easy to leave out, and nothing reports it missing until someone loads a dark page on a slow connection.

Browser support

The baseline is modern evergreen: the current and previous versions of Chrome, Edge, Firefox and Safari. Decided deliberately rather than by accident, because the alternative is paying for it in every stylesheet — the question had been open long enough that components were being written around selectors nobody had ruled in or out.

What that admits, and where it is used:

field-sizing is the one that is genuinely new, so anything relying on it must degrade to something usable rather than something broken.

On an older browser the derived tokens fall back to the default purple and red focus rings — still visible, but no longer tracking your brand colour — and everything else themes normally.

Two size ladders, and which is which

data-size means one of two things depending on what it is on, and the two ladders are deliberately different lengths:

A scale mirrors the token ramp behind it, so it has a step for every token — corn-text reaches all five font sizes, and md names the 14px base explicitly rather than leaving it as the value you get by writing nothing.

A control ladder is three steps because a control is sized for a hit area, not for a typographic ramp: sm, the default md, and lg. Adding xs there would mean a control below the 24×24px minimum target size WCAG 2.2 asks for, which is a bug rather than an option.

At each step every single-line control is the same height, from --corn-control-height-sm, -md and -lg: an input, a select, a combobox, a text button and an icon button line up in any row. The tokens are an input’s own geometry by default, so they follow the type scale. Set them to make every control taller or denser at once.

A value outside its ladder does nothing and says nothing — CSS cannot error, so data-size="xs" on a control matches no rule and gives no signal. It renders at the default size, which is the md step: every control repeats md’s geometry in its base class precisely so that an unrecognised value, or no data-size at all, lands somewhere sensible rather than on the browser’s own defaults — where <input class="corn-input"> with no size would measure 23.6px, under the 24px target this page cites above. scripts/size-fallback.test.js fails the build if a base rule and its md rule ever disagree.

The published types name the accepted values for each component, and scripts/option-values.test.js fails the build if a documented value ever loses the rule behind it.

Design tokens

Every token below is overridable.

Colors — Brand

Colors — Status

Colors — Text

Colors — Backgrounds

Colors — Borders

Colors — Chart / Data Viz

Series colours for charts. Unlike every other colour here these are not derived from --corn-primary — they are independently validated steps, and composing them from the brand would break their colour-vision and contrast guarantees. scripts/chart-palette.test.js re-runs those checks against the shipped values.

Assign slots in fixed order and never cycle them. A ninth series folds into “Other”, becomes small multiples, or picks up a second encoding channel.

All eight are validated for adjacent pairs — stacked segments, grouped bars, lines. Only slots 1–3 clear the stricter all-pairs gates that scatter, bubble and choropleth need, where every series can end up beside every other. Past three in those forms, fold to “Other” or facet into small multiples.

On the light surface --corn-chart-3, --corn-chart-4 and --corn-chart-5 sit below 3:1. That is permitted, but it obliges relief: give those series visible direct labels or a table view. Every dark slot clears 3:1.

Status colours are reserved for state and must never be reused as a series colour — --corn-danger on a series tells the reader that series is failing.

Sequential ramp

One hue, low to high, for magnitude — heatmaps, choropleths, intensity. seq-1 always sits nearest the surface, so the ramp reads the same direction in both themes instead of inverting when the user flips the toggle.

There is no diverging ramp yet; it lands with the first component that needs one.

Semantic / derived

Composed from the tokens above. Override the source colour and these follow; override these to break the link. These swatches are live: they show the theme you are viewing, so flip the toggle to see the other.

Breakpoints

Reference values for the responsive rules built into the components. CSS cannot read a custom property inside a media query condition, so changing these tokens will not move the breakpoints — the component stylesheets carry the same numbers as literals. They are published so your own layout code can line up with the library’s, and so the values are stated somewhere rather than implied.

To move a breakpoint, override the rule rather than the token:

@media (max-width: 800px) {
  .corn-layout-body { flex-direction: column; }
}

Spacing

Typography

Border Radius

Shadows

Transitions