@hadoku/themes

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

16个主题配有对称,WCAG验证的代号集和完整的Tailwind v4色彩映射——光,暗,大洋,Cyberpunk,咖啡,拉文德,自然,平克,伊扎卡亚

中文使用文档
文档目录35 节
  1. 主题
  2. 安装
  3. 使用量
  4. 导入 CSS
  5. 使用主题工具
  6. 应用到 HTML
  7. 第一帧前的访客主题画
  8. CSS 变量
  9. 颜色——5个语义家庭×6个令牌
  10. 颜色——结构
  11. 类型
  12. 间距
  13. 版式
  14. 过渡
  15. 用法示例
  16. 尾风 v4 兼容性
  17. 为甚么取名相?
  18. 变量映射
  19. 尾风集成
  20. V1.x的迁移
  21. 反应集成
  22. 使用 useTheme Hook (建议)
  23. 手动反应集成
  24. 框架实例
  25. 阴道
  26. 香草联署材料
  27. 主题编辑器
  28. API 参考
  29. 反应公用事业(在v1.1.3+中新建)
  30. 核心职能
  31. 类型
  32. 浏览器支持
  33. 许可证
  34. 作者
  35. 相关软件包

@wolffm/主题

使用 CSS 自定义属性的美丽色彩主题 。 框架不可知,随时可用于任何网络项目.

主题

8个主题家庭(16个主题),每个主题都有光和暗的变体:

  • 光线 (默认) / 阴暗 - 清正的蓝色和白色 深夜有紫色口音
  • 海洋 浅/暗 -- -- 深海蓝和热带珊瑚
  • 赛博朋克 浅/暗 -- -- 有电色的霓虹堤道
  • 咖啡 浅/暗 -- -- 浓咖啡和奶油
  • 薰衣草 浅/暗 -- -- 柔软的紫色优雅
  • 性质 浅/深 -- -- 由森林和地所激发的长叶绿地
  • 粉红色 光/暗 -- -- 泡泡粉红色和霓虹光
  • 伊扎克亚 Light/Dark-被日本伊扎克雅所启发的取暖音调(基苏纳竞技胜出)

安装

npm install @wolffm/themes

使用量

导入 CSS

import '@wolffm/themes/style.css'

使用主题工具

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', ...]

应用到 HTML

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

第一帧前的访客主题画

一个设置的页面 data-theme 从捆绑的油漆 曾经没有线,然后 交换. @wolffm/themes 发布每个 hadoku 页的预绘脚本 位于顶端的内线 <head>: 它读取存储的选择( 或处理粘度) 随机黑暗主题给一个从未选择过的人), sets data-theme 在此之前 将决定公布为 window.__hadokuTheme编辑 标题 src/theme-bootstrap.js 记录它能解决和暴露的东西.

这一定是 内入 语句。 A 类 <script src>,模块或捆绑的脚本 在第一次涂料后运行,它打败了这一点。 采取两种方式之一:

// 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')

文本没有关闭脚本标记, 也没有 <!--这样它就可以进入一个 <script> 元素未脱逃( e)test/theme-bootstrap.test.mjs 执行). 这个 电话 /session/whoami 财务报告和审定财务报表 /prefs/api/v1/portfolio 通过相对的 URL,所以它的 截接设备 :remember(), (中文(简体) ), adopt())只研究取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自取自. 永远不要把它复制到回扣中: 导入它, 这样每个页面都会收到一个新的主题 有个版本的凸起.

CSS 变量

每个主题定义47个变量(41个颜色+6个阴影). 颜色变量使用 --color-* 命名空间——它也是Tailwind v4的——所以它们直接映射到 公用事业。 其他东西都是空的 --hdk-* 避免与 尾风入内.

我用哪个代号来表示X? → THEME_USAGE_GUIDE.md。 。 。 . 这是在写任何风格之前读取(和指点代理)的医生.

颜色——5个语义家庭×6个令牌

每个家庭都有一套相同的 矩是点: 对称猜想总是对的.

填满梯度/压入锡特悬浮上方填充时的文本关于锡的文本
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

颜色——结构

  • --color-text (+ 数) -secondary, (中文(简体) ), -tertiary, (中文(简体) ), -muted(中文(简体) )
  • --color-border (+ 数) -light(中文(简体) )
  • --color-bg (+ 数) -card, (中文(简体) ), -alt, (中文(简体) ), -hover, (中文(简体) ), -overlay(中文(简体) )

每个 on-* 双子被校验为 : 4.5: 1 相对于每个主题的表面 scripts/check-contrast.mjs。 。 。 .

类型

  • --font-family
  • --hdk-text-* (xs, sm, md, base, lg) - 字体大小
  • --font-weight-* (正常,半粗体,粗体)
  • --line-height-* (正常,放松)

间距

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

版式

  • --hdk-radius (+ sm, lg 变体) - 边框半径
  • --hdk-shadow-* (sm, md, lg, 聚焦, 聚焦- sm, 聚焦- alt)

过渡

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

用法示例

.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);
}

尾风 v4 兼容性

此软件包使用命名空格 CSS 变量(--hdk-*)来避免与Tailwind v4的内部变量相撞.

为甚么取名相?

Tailwind v4 内部使用 CSS 自定义属性 :

  • --spacing-* 权限 max-w-md, (中文(简体) ), p-4, (中文(简体) ), gap-*等 (中文(简体) ).
  • --radius-* 权限 rounded-md, (中文(简体) ), rounded-lg等 (中文(简体) ).
  • --font-size-* 权限 text-sm, (中文(简体) ), text-base等 (中文(简体) ).
  • --shadow-* 权限 shadow-sm, (中文(简体) ), shadow-md等 (中文(简体) ).

没有命名间隔, 主题变量像 --spacing-md: 8px 将打破 max-w-md (从28rem改为8px).

变量映射

旧名( v1. x)新名称( 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

尾风集成

3个进口,没有手写 @theme 块 :

@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) */

你现在得到 bg-primary, (中文(简体) ), text-on-primary, (中文(简体) ), bg-success-bg, (中文(简体) ), text-on-danger-bg, (中文(简体) ), border-border, (中文(简体) ), bg-bg-card 每一个标志,作为一个效用.

永远不要手卷 @theme 颜色块. 本地拷贝就是漂移 此软件包的存在是为了防止; tailwind-colors.css 从 style.css 如果两者意见不一,CI就会失败.

步骤1必须保持不下层. 尾风各喷出 @theme 进入 @layer theme 作为 :root { --x: var(--x) },这是自我优惠和 自行无效。 它解决仅仅因为 style.css 声明如下: 任何级联层外的属性, 和无层取胜。 导入它 layer(...) 和所有41个颜色 沉默地变成 transparent。 。 。 .

tailwind-integration.css (步骤4)是单独和可选的——它地图 --hdk-* 半径/ 阴影/ 类型进入 rounded-*, (中文(简体) ), shadow-*, (中文(简体) ), text-*。 。 。 .

V1.x的迁移

在您的 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)

反应集成

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
      }}
    />
  )
}

手动反应集成

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>
  )
}

框架实例

阴道

<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>

香草联署材料

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)
  })
})

主题编辑器

主办地点 https://hadoku.me/ 任务/编辑** (服务级别及以上)。 选一个主题, 拖动滑动器,而该应用程序的真正组件会重新显示颜色; 保存 承诺 改为 main 以新的版本出版.

  • 每一个标志 ——亮度/饱和度/hue/不透明滑块(OKLCH,故作 亮度阶梯看起来甚至横穿花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花花
  • 每组 ——地表,文字和每个语义家族可一并转移
  • 合同 - 同样的支票 lint:css 运行( r)scripts/lib/contract.mjs, (中文(简体) ), 导出为 @wolffm/themes/contract),活;一个失败块保存和 执行前保存路径再检查
  • 舒适 ——AA看不到的咨询仪表:页面闪光,卡-vs-页面 分隔、边界可见度、文本严酷度以及是否 success 编号 : warning 编号 : danger 仍然读作意义

编辑是 @wolffm/task/editor (弧/编辑/在还原根中);其 保存路径 worker/src/routes/theme-editor.ts在本地, pnpm run dev:api 加号 vite 服务于 /editor.html 以纪念吉特胡卜为对象 永远不要碰真正的回放.

API 参考

反应公用事业(在v1.1.3+中新建)

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

状态主题管理反应钩. 自动保存到会话Storage并同步跨标签.

const { theme, setTheme } = useTheme()

THEME_FAMILIES: ThemeFamily[]

预配置了所有8个有图标和标签的主题家族的阵列. 使用方式 ThemePicker 或者说 ConnectedThemePicker 组件从 @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>

主题名称地图到它们相应的图标组件.

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

核心职能

setTheme(theme: Theme): void

立即应用主题 。 设定 data-theme 属性 <html> 键.

getTheme(): Theme

获取当前活动主题 .

saveTheme(theme: Theme): void

将主题保存到会话Storage并应用它 .

loadTheme(): Theme

从会话Storage上装入所保存的主题, 应用它, 并返回主题名称 。 尊重浏览器 prefers-color-scheme 如果未保存主题, 则优先选择 。 如果没有选择, 返回“ 光 ” .

initTheme(): Theme

方便功能. 与 loadTheme()。 。 。 .

clearTheme(): void

删除已保存的主题并重置为"光" .

类型

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[]

浏览器支持

在所有支持的现代浏览器中工作:

  • CSS 自定义属性( CSS 变量)
  • ES2022 模块
  • 会话集

许可证

麻省理工学院

作者

沃尔夫M - GitHub 图像

版本与发布记录

@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个主题配有对称,WCAG验证的代号集和完整的Tailwind v4色彩映射——光,暗,大洋,Cyberpunk,咖啡,拉文德,自然,平克,伊扎卡亚

如何安装 @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 和提交记录判断。