@wentools/theme

Design tokens for color theming, shadows, transitions, and accessibility. Light and dark themes out of the box, customizable through palette primitives. Pairs with @wentools/css-base.

Install

npm install @wentools/theme

Usage

Full import

@import '@wentools/theme';

Cherry-pick modules

@import '@wentools/theme/colors.css';
@import '@wentools/theme/themes.css';
@import '@wentools/theme/shadows.css';
@import '@wentools/theme/transitions.css';
@import '@wentools/theme/accessibility.css';
@import '@wentools/theme/layers.css';
@import '@wentools/theme/semantic.css';

Modules

Colors (colors.css)

Palette primitives and semantic color tokens for the light theme. Sets body { background; color }.

Palette primitives — override these to set your brand identity:

:root {
  --theme-gray-hue: 327.1;
  --theme-gray-chroma: 0.004;
  --theme-red-hue: 29.23;
  --theme-red-chroma: 0.15;
  --theme-yellow-hue: 86.29;
  --theme-yellow-chroma: 0.165;
  --theme-blue-hue: 265.79;
  --theme-blue-chroma: 0.111;
  --theme-green-hue: 141.32;
  --theme-green-chroma: 0.123;
}

Semantic tokens: --color-text-*, --color-bg-*, --color-surface-*, --color-border-*, --color-overlay-*, --color-accent*, --color-success*, --color-danger*, --color-warning*, --color-info*, --gradient-primary*, --color-palette-*.

Themes (themes.css)

Dark theme overrides in [data-theme='dark']. Same token names, adjusted values for dark mode.

Shadows (shadows.css)

Composed shadow system derived from @wentools/css-base --space-* tokens.

Tokens: --shadow-xs through --shadow-xl, --shadow-layer-1/2/3, --shadow-glow-s/m/l, --shadow-text. Includes dark theme overrides.

Transitions (transitions.css)

Animation timing, interactive state offsets, overlay opacity, saturation multipliers, and transform scales.

Tokens: --transition-fast/default/slow/spring, --hover-lightness-offset, --scale-*, --saturation-*, --overlay-opacity-*. Includes prefers-reduced-motion support.

Accessibility (accessibility.css)

Focus ring system and touch target minimums.

Tokens: --focus-offset, --focus-width, --focus-color, --focus-ring, --touch-target-min (44px), --touch-target-comfortable (48px).

Layers (layers.css)

Z-index scale: --layer-base (0), --layer-elevated (100), --layer-overlay (200), --layer-modal (300), --layer-tooltip (400), --layer-max (999).

Semantic (semantic.css)

Non-color design tokens: --radius-s/m/full, --border-thickness-s/m/l, --input-padding-*, --input-border-*.

Svelte integration

Theme store

import { createThemeStore } from '@wentools/theme/svelte/theme_store'

const theme = createThemeStore({ storageKey: 'my-app-theme' })

// Read current theme
$theme // 'light' | 'dark'

// Set theme
theme.setTheme('dark')

// Reset to default
theme.reset()

Flash prevention

Add an inline script to app.html to prevent a flash of the wrong theme on load:

import { flashPreventionScript } from '@wentools/theme/svelte/flash_prevention'

const script = flashPreventionScript('my-app-theme')

Then in app.html:

<script>
  %flash_prevention_script%
</script>

Or paste the generated script directly.

Relationship to @wentools/css-base

This package depends on --space-* tokens from @wentools/css-base for shadow offsets/blurs, radius, and border thickness calculations. Import css-base first:

@import '@wentools/css-base';
@import '@wentools/theme';

CSS Layers

@layer wentools.theme.colors,
       wentools.theme.shadows,
       wentools.theme.transitions,
       wentools.theme.accessibility,
       wentools.theme.layers,
       wentools.theme.semantic;

Un-layered CSS always wins over layered CSS, so your project styles override the library naturally.

License

MIT