@hadoku/themes

中文文档
5.14.4发布于 2026/11/13MITTypeScriptES Module构建来源已验证近 30 天下载 1.3万

16 themes with a symmetric, WCAG-verified token set and a complete Tailwind v4 color mapping - Light, Dark, Ocean, Cyberpunk, Coffee, Lavender, Nature, Pink, Izakaya

原始使用文档
文档目录35 节
  1. Themes
  2. Installation
  3. Usage
  4. Import CSS
  5. Use Theme Utilities
  6. Apply to HTML
  7. Paint in the visitor's theme before the first frame
  8. CSS Variables
  9. Colors — 5 semantic families × 6 tokens
  10. Colors — structural
  11. Typography
  12. Spacing
  13. Layout
  14. Transitions
  15. Usage Example
  16. Tailwind v4 Compatibility
  17. Why Namespacing?
  18. Variable Mapping
  19. Tailwind Integration
  20. Migration from v1.x
  21. React Integration
  22. Using the useTheme Hook (Recommended)
  23. Manual React Integration
  24. Framework Examples
  25. Vue
  26. Vanilla JS
  27. Theme Editor
  28. API Reference
  29. React Utilities (New in v1.1.3+)
  30. Core Functions
  31. Types
  32. Browser Support
  33. License
  34. Author
  35. Related Packages

@wolffm/themes

Beautiful color themes using CSS custom properties. Framework-agnostic and ready to use in any web project.

Themes

8 theme families (16 themes), each with light and dark variants:

  • Light (default) / Dark - Clean blue and white / Sophisticated midnight with purple accents
  • Ocean Light/Dark - Deep sea blues and tropical coral
  • Cyberpunk Light/Dark - Neon dystopia with electric colors
  • Coffee Light/Dark - Rich espresso and cream tones
  • Lavender Light/Dark - Soft purple elegance
  • Nature Light/Dark - Lush leaf greens inspired by forests and earth
  • Pink Light/Dark - Bubblegum pink and neon glows
  • Izakaya Light/Dark - Japanese izakaya-inspired warm tones (Kitsune contest winner)

Installation

npm install @wolffm/themes

Usage

Import CSS

import '@wolffm/themes/style.css'

Use Theme Utilities

import { setTheme, loadTheme, saveTheme, THEMES } from '@wolffm/themes'

// Set theme (applies immediately)
setTheme('dark')
setTheme('cyberpunk-dark')

// Save to sessionStorage and apply
saveTheme('lavender-light')

// Load saved theme on app start
const theme = loadTheme()

// Get all available themes
console.log(THEMES) // ['light', 'dark', 'coffee-light', ...]

Apply to HTML

<!-- Set globally on html element -->
<html data-theme="dark">
  <!-- Or on a specific container -->
  <div data-theme="ocean-light">
    <!-- Your content -->
  </div>
</html>

Paint in the visitor's theme before the first frame

A page that sets data-theme from a bundle paints once untinted and then swaps. @wolffm/themes publishes the one pre-paint script every hadoku page inlines at the top of <head>: it reads the stored choice (or deals a sticky random dark theme to someone who never picked one), sets data-theme before anything paints, and publishes the decision as window.__hadokuTheme. The header of src/theme-bootstrap.js documents what it resolves and exposes.

It must be inline text. A <script src>, a module, or a bundled script all run after first paint, which defeats the point. Take it one of two ways:

// As a string, for a build tool. Astro:
import { THEME_BOOTSTRAP } from '@wolffm/themes/theme-bootstrap'
// <script is:inline set:html={THEME_BOOTSTRAP} />
// As the file's text, for a sync script that writes it between markers:
import { readFileSync } from 'node:fs'
import { createRequire } from 'node:module'
const path = createRequire(import.meta.url).resolve('@wolffm/themes/theme-bootstrap.js')
const source = readFileSync(path, 'utf8')

The text holds no closing script tag and no <!--, so it can go inside a <script> element unescaped (test/theme-bootstrap.test.mjs enforces it). It calls /session/whoami and /prefs/api/v1/portfolio by relative URL, so its cross-device half (remember(), adopt()) only works on hadoku.me's origin. Never copy it into a repo: import it, so a new theme reaches every page with a version bump.

CSS Variables

Each theme defines 47 variables (41 color + 6 shadow). Color variables use the --color-* namespace — which is also Tailwind v4's — so they map straight to utilities. Everything else is namespaced --hdk-* to avoid colliding with Tailwind internals.

Which token do I use for X? → THEME_USAGE_GUIDE.md. That is the doc to read (and to point agents at) before writing any styles.

Colors — 5 semantic families × 6 tokens

Every family carries an identical set. The rectangle is the point: the symmetric guess is always correct.

fillgradient/pressedtinthover overlaytext on filltext on tint
primary--color-primary-dark-bg-hover--color-on-primary--color-on-primary-bg
success--color-success-dark-bg-hover--color-on-success--color-on-success-bg
warning--color-warning-dark-bg-hover--color-on-warning--color-on-warning-bg
danger--color-danger-dark-bg-hover--color-on-danger--color-on-danger-bg
neutral--color-neutral-dark-bg-hover--color-on-neutral--color-on-neutral-bg

Colors — structural

  • --color-text (+ -secondary, -tertiary, -muted)
  • --color-border (+ -light)
  • --color-bg (+ -card, -alt, -hover, -overlay)

Every on-* pair is verified ≥4.5:1 against its surface in every theme by scripts/check-contrast.mjs.

Typography

  • --font-family
  • --hdk-text-* (xs, sm, md, base, lg) - font sizes
  • --font-weight-* (normal, semibold, bold)
  • --line-height-* (normal, relaxed)

Spacing

  • --hdk-space-* (xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl)

Layout

  • --hdk-radius (+ sm, lg variants) - border radius
  • --hdk-shadow-* (sm, md, lg, focus, focus-sm, focus-alt)

Transitions

  • --transition-fast
  • --transition-smooth

Usage Example

.my-button {
  background: var(--color-primary);
  color: var(--color-on-primary);
  padding: var(--hdk-space-md) var(--hdk-space-xl);
  border-radius: var(--hdk-radius);
  font-size: var(--hdk-text-base);
  box-shadow: var(--hdk-shadow-sm);
  transition: var(--transition-fast);
}

.my-button:hover {
  background: var(--color-primary-dark);
  box-shadow: var(--hdk-shadow-md);
}

Tailwind v4 Compatibility

This package uses namespaced CSS variables (--hdk-*) to avoid collisions with Tailwind v4's internal variables.

Why Namespacing?

Tailwind v4 uses CSS custom properties internally:

  • --spacing-* powers max-w-md, p-4, gap-*, etc.
  • --radius-* powers rounded-md, rounded-lg, etc.
  • --font-size-* powers text-sm, text-base, etc.
  • --shadow-* powers shadow-sm, shadow-md, etc.

Without namespacing, a theme variable like --spacing-md: 8px would break max-w-md (changing it from 28rem to 8px).

Variable Mapping

Old Name (v1.x)New Name (v2.x)
--spacing-md--hdk-space-md
--font-size-sm--hdk-text-sm
--border-radius--hdk-radius
--shadow-sm--hdk-shadow-sm
--shadow-modal--hdk-shadow-lg

Tailwind Integration

Three imports, no hand-written @theme block:

@import '@wolffm/themes/style.css'; /* 1. tokens — MUST be unlayered */
@import 'tailwindcss'; /* 2. Tailwind */
@import '@wolffm/themes/tailwind-colors.css'; /* 3. all 41 colours */
@import '@wolffm/themes/tailwind-integration.css'; /* 4. radius/shadow/type (optional) */

You now get bg-primary, text-on-primary, bg-success-bg, text-on-danger-bg, border-border, bg-bg-card — every token, as a utility.

Never hand-roll a @theme colour block. A local copy is exactly the drift this package exists to prevent; tailwind-colors.css is generated from style.css and CI fails if the two disagree.

Step 1 must stay unlayered. Tailwind emits each @theme entry into @layer theme as :root { --x: var(--x) }, which is self-referential and invalid on its own. It resolves only because style.css declares the same properties outside any cascade layer, and unlayered wins. Import it with layer(...) and all 41 colours silently become transparent.

tailwind-integration.css (step 4) is separate and optional — it maps --hdk-* radius/shadow/type onto rounded-*, shadow-*, text-*.

Migration from v1.x

Search and replace in your CSS:

var(--spacing-       →  var(--hdk-space-
var(--font-size-     →  var(--hdk-text-
var(--border-radius  →  var(--hdk-radius
var(--shadow-        →  var(--hdk-shadow-
var(--shadow-modal)  →  var(--hdk-shadow-lg)

React Integration

import { useTheme, THEME_FAMILIES, THEME_ICON_MAP } from '@wolffm/themes'
import { ConnectedThemePicker } from '@wolffm/task-ui-components'
import '@wolffm/themes/style.css'
import '@wolffm/task-ui-components/theme-picker.css'

function App() {
  const { theme, setTheme } = useTheme()

  return (
    <ConnectedThemePicker
      themeFamilies={THEME_FAMILIES}
      currentTheme={theme}
      onThemeChange={setTheme}
      getThemeIcon={theme => {
        const Icon = THEME_ICON_MAP[theme]
        return Icon ? <Icon /> : null
      }}
    />
  )
}

Manual React Integration

import { useEffect, useState } from 'react'
import { loadTheme, setTheme, THEMES, type Theme } from '@wolffm/themes'
import '@wolffm/themes/style.css'

function App() {
  const [theme, setThemeState] = useState<Theme>('light')

  useEffect(() => {
    const savedTheme = loadTheme()
    setThemeState(savedTheme)
  }, [])

  const handleThemeChange = (newTheme: Theme) => {
    setTheme(newTheme)
    setThemeState(newTheme)
  }

  return (
    <select value={theme} onChange={e => handleThemeChange(e.target.value as Theme)}>
      {THEMES.map(t => (
        <option key={t} value={t}>
          {t}
        </option>
      ))}
    </select>
  )
}

Framework Examples

Vue

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { loadTheme, setTheme, THEMES, type Theme } from '@wolffm/themes'
import '@wolffm/themes/style.css'

const theme = ref<Theme>('light')

onMounted(() => {
  theme.value = loadTheme()
})

const handleThemeChange = (newTheme: Theme) => {
  setTheme(newTheme)
  theme.value = newTheme
}
</script>

<template>
  <select v-model="theme" @change="handleThemeChange(theme)">
    <option v-for="t in THEMES" :key="t" :value="t">{{ t }}</option>
  </select>
</template>

Vanilla JS

import { loadTheme, setTheme, THEMES } from '@wolffm/themes'
import '@wolffm/themes/style.css'

// Load saved theme on page load
document.addEventListener('DOMContentLoaded', () => {
  loadTheme()

  // Theme switcher
  const select = document.getElementById('theme-select')
  THEMES.forEach(theme => {
    const option = document.createElement('option')
    option.value = theme
    option.textContent = theme
    select.appendChild(option)
  })

  select.addEventListener('change', e => {
    setTheme(e.target.value)
  })
})

Theme Editor

Hosted at https://hadoku.me/task/editor** (service tier and up). Pick a theme, drag sliders, and the app's real components recolour live; Save commits the change to main under a new version, which publishes.

  • Per token — brightness / saturation / hue / opacity sliders (OKLCH, so a brightness step looks even across hues) plus a typed value
  • Per group — Surfaces, Text and each semantic family can be shifted at once
  • Contract — the same checks lint:css runs (scripts/lib/contract.mjs, exported as @wolffm/themes/contract), live; a failure blocks Save, and the save route re-checks before committing
  • Comfort — advisory meters for what AA cannot see: page glare, card-vs-page separation, border visibility, text harshness, and whether success / warning / danger still read as their meaning

The editor ships as @wolffm/task/editor (src/editor/ in the repo root); its save route is worker/src/routes/theme-editor.ts. Locally, pnpm run dev:api plus vite serve it at /editor.html against an in-memory GitHub — a local save never touches the real repo.

API Reference

React Utilities (New in v1.1.3+)

useTheme(): { theme: Theme, setTheme: (theme: Theme) => void }

React hook for stateful theme management. Automatically saves to sessionStorage and syncs across tabs.

const { theme, setTheme } = useTheme()

THEME_FAMILIES: ThemeFamily[]

Pre-configured array of all 8 theme families with icons and labels. Use with ThemePicker or ConnectedThemePicker components from @wolffm/task-ui-components.

import { THEME_FAMILIES } from '@wolffm/themes'
// Each family includes: lightTheme, darkTheme, lightLabel, darkLabel, lightIcon, darkIcon

THEME_ICON_MAP: Record<Theme, IconComponent>

Map of theme names to their corresponding icon components.

import { THEME_ICON_MAP } from '@wolffm/themes'
const Icon = THEME_ICON_MAP['cyberpunk-dark']

Core Functions

setTheme(theme: Theme): void

Apply a theme immediately. Sets data-theme attribute on <html> element.

getTheme(): Theme

Get the currently active theme.

saveTheme(theme: Theme): void

Save theme to sessionStorage and apply it.

loadTheme(): Theme

Load saved theme from sessionStorage, apply it, and return the theme name. Respects browser's prefers-color-scheme preference if no saved theme. Returns 'light' if no preference.

initTheme(): Theme

Convenience function. Same as loadTheme().

clearTheme(): void

Remove saved theme and reset to 'light'.

Types

type Theme =
  | 'light'
  | 'dark'
  | 'ocean-light'
  | 'ocean-dark'
  | 'cyberpunk-light'
  | 'cyberpunk-dark'
  | 'coffee-light'
  | 'coffee-dark'
  | 'lavender-light'
  | 'lavender-dark'
  | 'nature-light'
  | 'nature-dark'
  | 'pink-light'
  | 'pink-dark'
  | 'izakaya-light'
  | 'izakaya-dark'

const THEMES: readonly Theme[]

Browser Support

Works in all modern browsers that support:

  • CSS Custom Properties (CSS Variables)
  • ES2022 modules
  • sessionStorage

License

MIT

Author

WolffM - GitHub

  • @wolffm/task - Task management micro-frontend using these themes

版本与发布记录

@hadoku/themes 共发布 58 个版本,首次发布于 2026/10/28;过去 12 个月发布了 58 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.14.4latest2026/11/134 天前
5.14.32026/11/125 天前
5.14.22026/11/125 天前
5.14.12026/11/125 天前
5.14.02026/11/125 天前
5.13.462026/11/116 天前

关于 @hadoku/themes 的常见问题

@hadoku/themes 是什么?

16 themes with a symmetric, WCAG-verified token set and a complete Tailwind v4 color mapping - Light, Dark, Ocean, Cyberpunk, Coffee, Lavender, Nature, Pink, Izakaya

如何安装 @hadoku/themes?

在项目目录运行 npm install @hadoku/themes,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hadoku-check-icons、hadoku-codemod-icons,可以用 npx hadoku-check-icons 直接运行。

@hadoku/themes 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hadoku/themes 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hadoku/themes 可以商用吗?

@hadoku/themes 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hadoku/themes 的下载量有多少?

根据 npm 官方下载统计,@hadoku/themes 在 2026/10/17 – 2026/11/15 这 30 天内被下载 12,511 次,日均约 417 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hadoku/themes 还在维护吗?

最新版本 5.14.4 发布于 2026/11/13(4 天前);至今共发布 58 个版本,其中过去 12 个月发布了 58 个;首次发布于 2026/10/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。