Theming

Customize Wilout UI with CSS variables. Support light and dark modes out of the box.

CSS Variables

All design tokens are exposed as CSS custom properties (variables). Override them in your own CSS.

:root {
  /* Colors */
  --ui-color-primary: #3b82f6;
  --ui-color-secondary: #64748b;
  --ui-color-success: #22c55e;
  --ui-color-danger: #ef4444;
  --ui-color-warning: #f59e0b;
  --ui-color-info: #06b6d4;

  /* Background & Text */
  --ui-color-bg: #ffffff;
  --ui-color-text: #111827;

  /* Spacing */
  --ui-spacing-4: 1rem;

  /* Typography */
  --ui-font-family-sans: system-ui, sans-serif;
  --ui-font-size-base: 1rem;

  /* Border radius */
  --ui-border-radius: 0.25rem;
  --ui-border-radius-lg: 0.5rem;
}

Dark Mode

Add data-ui-theme="dark" attribute to enable dark mode.

<!-- On html or body element -->
<html data-ui-theme="dark">

<!-- Or toggle via JavaScript -->
<script>
  // Enable dark mode
  document.documentElement.setAttribute('data-ui-theme', 'dark');

  // Disable dark mode
  document.documentElement.removeAttribute('data-ui-theme');

  // Toggle
  const isDark = document.documentElement.dataset.uiTheme === 'dark';
  document.documentElement.dataset.uiTheme = isDark ? '' : 'dark';
</script>

Dark mode automatically adjusts background, text, border colors, and shadows.

Custom Theme

Create your own theme by overriding CSS variables.

/* Custom brand colors */
:root {
  --ui-color-primary: #8b5cf6;  /* Purple */
  --ui-color-primary-50: #f5f3ff;
  --ui-color-primary-100: #ede9fe;
  --ui-color-primary-600: #7c3aed;
  --ui-color-primary-700: #6d28d9;
}

/* Or create a named theme */
[data-ui-theme="purple"] {
  --ui-color-primary: #8b5cf6;
  --ui-color-bg: #faf5ff;
}

Color Palette

Primary

50
100
300
500
700
900

Semantic Colors

Success
Danger
Warning
Info

Tokens JSON

Import tokens as JSON for use in JavaScript or other tools.

import tokens from '@wilout/ui-tokens';

console.log(tokens.colorPrimary); // '#3b82f6'
console.log(tokens.spacing4);     // '1rem'

Accessibility

Default theme colors meet WCAG 2.1 AA contrast requirements.

  • Text on background: 7:1+ contrast ratio
  • Interactive elements: visible focus states
  • Buttons and badges maintain contrast in all variants

When customizing colors, use a contrast checker to ensure accessibility.