Components

Colour theme

Tokens switch on document.documentElement[data-theme] (dark default, light optional). Call wckdThemeToggle() so #theme-toggle and [data-wckd-theme-toggle] stay in sync with localStorage (wckd-theme). Override colours in theme.css, not in kit files.

Jump to:

Download & setup

Download WCKD UI Style guide

Load the kit from Get Started; use the style guide for utilities and tokens while wiring this component.

Default implementation

Theme control

Hook id="theme-toggle" or [data-wckd-theme-toggle]; wckdThemeToggle() syncs data-theme on html with localStorage key wckd-theme.

Markup

<script>
  (function () {
    try {
      var theme = localStorage.getItem("wckd-theme");
      if (theme === "light" || theme === "dark") {
        document.documentElement.setAttribute("data-theme", theme);
      }
    } catch (e) {}
  })();
</script>

<button type="button" class="outline size-xs" id="theme-toggle" aria-label="Toggle colour theme" aria-pressed="false">Theme: Dark</button>

<!-- extra controls on the same page: -->
<button type="button" class="outline size-xs" data-wckd-theme-toggle aria-label="Toggle colour theme">Theme: Dark</button>

Configuration options

Each variant keeps the same markup contract as the default; add only the classes or attributes named in the heading.

Theme output: buttons and surface levels

Reference swatches only: the same surface utilities and buttons rendered once per palette so you can eyeball contrast.

Default (:root)

Surface: fade
Surface: light
Surface: dark

Light override

Surface: fade
Surface: light
Surface: dark

Markup

<!-- output uses the same button + surface utility classes -->
<div class="columns count-2 gap-s">...</div>

Root theme tokens in CSS

These values mirror wckd-ui.css: dark defaults in :root, with [data-theme="light"] as the override layer.

:root (default)

--background-color: #24292E

--text-color: #f0f4f8

--line-color: rgb(255 255 255 / 0.12)

--primary-color: #4dabf7

Light tokens

--background-color: #f0f4f8

--text-color: #1a1f26

--line-color: rgb(26 31 38 / 0.14)

--primary-color: #05578a

Markup

:root{
  --text-color:#f0f4f8;
  --text-color-secondary:rgba(240, 244, 248, 0.92);
  --primary-color:#4dabf7;
  --background-color:#24292E;
  --background-color-light:#2f363d;
  --background-color-dark:#1f2227;
  --background-color-fade:rgb(0 0 0 / 20%);
  --line-color:rgb(255 255 255 / 0.12);
}

[data-theme="light"] {
  --text-color:#1a1f26;
  --text-color-secondary:rgba(26, 31, 38, 0.88);
  --background-color:#f0f4f8;
  --background-color-light:#ffffff;
  --background-color-dark:#d8dee4;
  --background-color-fade:rgba(0, 0, 0, 0.04);
  --line-color:rgb(26 31 38 / 0.14);
  --primary-color:#05578a;
}

DESIGN.md-style theme contract

Where state lives (data-theme on html), where overrides go (theme.css), and how localStorage maps to product requirements. See also design.md.

Theme contract

  • Root state lives on <html> by default, with optional data-theme="light".
  • Core defaults stay in wckd-ui.css; project overrides live in theme.css (or a custom override file loaded later).
  • Use token overrides first (--background-color, --text-color, --line-color, --primary-color, --secondary-color), selector overrides second.
  • Theme toggle persistence uses localStorage["wckd-theme"] through wckdThemeToggle().

Markup

# Theme Contract (DESIGN.md excerpt)

## Source of truth
- Root theme: <html> (default from :root), optional <html data-theme="light">
- Core tokens/defaults: wckd-ui.css
- Project overrides: theme.css or custom-theme.css (loaded after core CSS)

## Token-first customisation
- Override tokens before writing component-specific selectors.
- Keep light/dark parity for readability and line contrast.

## Runtime
- wckdThemeToggle() syncs root data-theme with localStorage key "wckd-theme".

theme.css customisation playbook

Load theme.css after core CSS; set tokens in :root, light deltas in [data-theme="light"].

theme.css playbook

  1. Load theme.css (or your custom stylesheet name) after wckd-ui.css and wckd-ui-components.css.
  2. Set global brand + neutral tokens in :root (your default theme).
  3. Override light deltas in [data-theme="light"].
  4. Test key surfaces: cards, borders, muted text, and buttons in both themes.
  5. Avoid direct hex overrides in component markup unless intentionally one-off.

Markup

/* theme.css checklist */
/* 1) load after core css */
/* 2) set global brand tokens */
:root { --primary-color: #5b7cfa; }

/* 3) light tokens */
[data-theme="light"] {
  --background-color: #f6f8fc;
  --text-color: #10131a;
}

/* 4) no dark block needed because :root is the default */

When to use

  • User-chosen light or dark surfaces on marketing and app chrome.
  • A second control in a drawer or settings panel should use data-wckd-theme-toggle on the extras; reserve id="theme-toggle" for one control if you use the id hook at all.

Implementation notes

  • Run an early inline script (see Get Started) so localStorage["wckd-theme"] sets data-theme on html before paint.
  • Icon buttons: put the sun/moon (or similar) inside the button; the toggle script detects svg or img and keeps children intact.
  • To disable the feature in your build, remove the wckdThemeToggle(); call from the BOOTSTRAP block at the end of wckd-ui.js, or ship a bootstrap that does not call it.
  • With dark-first defaults, no data-theme attribute is required for initial dark render. Add data-theme="light" only when you intentionally start in light mode.
  • This pattern is a manual light/dark switch, not automatic prefers-color-scheme by itself. Document any media-query defaults you add in theme.css separately.

Developer checklist

  • Use <html> with no data-theme for dark default, or set data-theme="light" when light should be initial state.
  • Check project colours in theme.css for both theme values if you override tokens.
  • Never duplicate id="theme-toggle" in one document.

← All components