@yh-ui/theme 1.0.5 → 1.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +55 -207
  3. package/package.json +3 -2
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2024-present YH-UI Team
3
+ Copyright (c) 2026 YH-UI Team
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,248 +1,96 @@
1
1
  # @yh-ui/theme
2
2
 
3
- <p align="center">
4
- <img src="https://raw.githubusercontent.com/1079161148/yh-ui/main/docs/public/logo.svg" width="100" height="100" alt="YH-UI Logo">
5
- </p>
6
-
7
- <h3 align="center">YH-UI 行业领先主题系统</h3>
8
-
9
- <p align="center">
10
- 12 种预设主题 · 4 种颜色算法 · 色盲友好模式 · 3 档密度配置 · 丝滑切换动画 · 跟随系统暗色
11
- </p>
12
-
13
- <p align="center">
14
- <a href="https://www.npmjs.com/package/@yh-ui/theme">
15
- <img src="https://img.shields.io/npm/v/@yh-ui/theme.svg?style=flat-square&colorB=409eff" alt="npm version">
16
- </a>
17
- <a href="https://www.npmjs.com/package/@yh-ui/theme">
18
- <img src="https://img.shields.io/npm/dm/@yh-ui/theme.svg?style=flat-square&colorB=409eff" alt="npm downloads">
19
- </a>
20
- <a href="https://github.com/1079161148/yh-ui/blob/main/LICENSE">
21
- <img src="https://img.shields.io/npm/l/@yh-ui/theme.svg?style=flat-square" alt="license">
22
- </a>
23
- </p>
24
-
25
- ---
26
-
27
- ## ✨ 为什么选择 YH-UI 主题系统？
28
-
29
- | 能力 | YH-UI | Element Plus | Naive UI |
30
- | ---------------- | ----------- | ------------ | -------- |
31
- | 预设主题数 | **12 种** | 1 种 | 有限 |
32
- | 颜色算法 | **4 种** | ❌ | ❌ |
33
- | 色盲友好模式 | **4 种** ✅ | ❌ | ❌ |
34
- | 密度配置 | **3 档** ✅ | ❌ | ❌ |
35
- | 主题切换动画 | ✅ 丝滑 | ❌ | ❌ |
36
- | 跟随系统暗色 | ✅ | 手动 | 手动 |
37
- | 偏好持久化 | ✅ | ❌ | ❌ |
38
- | CSS 变量设计令牌 | ✅ 完整 | 部分 | 部分 |
39
-
40
- ---
41
-
42
- ## 📦 安装
3
+ YH-UI 的主题和设计令牌包。它负责生成 CSS 变量、切换预设主题、管理暗色模式、密度、圆角、响应式主题和组件级覆盖，让组件库和业务页面共享同一套视觉状态。
43
4
 
44
- ```bash
45
- # pnpm（推荐）
46
- pnpm add @yh-ui/theme
5
+ [Theme Guide](https://1079161148.github.io/yh-ui/guide/theming) | [GitHub](https://github.com/1079161148/yh-ui)
47
6
 
48
- # npm
49
- npm install @yh-ui/theme
50
- ```
7
+ ## Highlights
51
8
 
52
- > **注意**：`@yh-ui/theme` 是 `@yh-ui/yh-ui` 的子包，通常无需单独安装。
9
+ - 预设主题：`default`、`dark`、`blue`、`green`、`purple`、`orange`、`rose`、`amber`、`teal`、`indigo`、`slate`、`zinc`。
10
+ - 运行时主题管理：`initTheme`、`useTheme`、`ThemeManager` 可读取、切换和持久化主题。
11
+ - 颜色算法：支持 `default`、`vibrant`、`muted`、`pastel`，可基于主色生成更完整的色板。
12
+ - 暗色和系统跟随：可手动切换，也可响应 `prefers-color-scheme`。
13
+ - 密度和可访问性：支持密度配置、色盲友好模式、对比度检查和根据背景色获取文本色。
14
+ - 组件级覆盖：可以为某个组件设置局部 token，不必改全局主题。
53
15
 
54
- ---
16
+ ## Install
55
17
 
56
- ## 🔨 快速开始
18
+ ```bash
19
+ pnpm add @yh-ui/theme
20
+ ```
57
21
 
58
- ### 在 Vue 应用中使用
22
+ ## Use as Vue Plugin
59
23
 
60
24
  ```ts
61
25
  import { createApp } from 'vue'
62
- import { createYhTheme } from '@yh-ui/theme'
26
+ import { ThemePlugin } from '@yh-ui/theme'
63
27
  import App from './App.vue'
64
28
 
65
29
  const app = createApp(App)
66
30
 
67
- const theme = createYhTheme({
68
- preset: 'purple', // 12 种预设主题
69
- algorithm: 'vibrant', // 颜色算法
70
- density: 'default', // 密度档位
71
- followSystem: true, // 跟随系统暗色模式
72
- transition: true, // 开启切换动画
73
- persist: true // 持久化到 localStorage
31
+ app.use(ThemePlugin, {
32
+ preset: 'blue',
33
+ dark: false,
34
+ followSystem: true,
35
+ persist: true,
36
+ algorithm: 'vibrant'
74
37
  })
75
38
 
76
- app.use(theme)
77
39
  app.mount('#app')
78
40
  ```
79
41
 
80
- ### 在组件中动态切换
42
+ ## Use in Components
81
43
 
82
44
  ```vue
83
45
  <script setup lang="ts">
84
46
  import { useTheme } from '@yh-ui/theme'
85
47
 
86
- const { preset, isDark, density, setPreset, toggleDark, setDensity } = useTheme()
48
+ const theme = useTheme()
49
+
50
+ function switchTheme() {
51
+ theme.setPreset('purple')
52
+ theme.setDensity('compact')
53
+ }
87
54
  </script>
88
55
 
89
56
  <template>
90
- <div>
91
- <!-- 切换主题预设 -->
92
- <button @click="setPreset('ocean')">Ocean 主题</button>
93
- <button @click="setPreset('violet')">Violet 主题</button>
94
-
95
- <!-- 切换暗色 -->
96
- <button @click="toggleDark()">{{ isDark ? '切换亮色' : '切换暗色' }}</button>
97
-
98
- <!-- 切换密度 -->
99
- <button @click="setDensity('compact')">紧凑</button>
100
- <button @click="setDensity('default')">默认</button>
101
- <button @click="setDensity('comfortable')">宽松</button>
102
- </div>
57
+ <button @click="switchTheme">Switch theme</button>
103
58
  </template>
104
59
  ```
105
60
 
106
- ---
107
-
108
- ## 🎨 预设主题列表
109
-
110
- | 主题名 | 说明 |
111
- | ----------- | ------------------ |
112
- | `default` | 科技蓝（默认） |
113
- | `purple` | 优雅紫 |
114
- | `ocean` | 深海蓝 |
115
- | `violet` | 紫罗兰 |
116
- | `rose` | 玫瑰红 |
117
- | `amber` | 琥珀金 |
118
- | `emerald` | 翡翠绿 |
119
- | `slate` | 石板灰（极简中性） |
120
- | `cyberpunk` | 赛博朋克（霓虹风） |
121
- | `sakura` | 樱花粉 |
122
- | `forest` | 深林绿 |
123
- | `nordic` | 北欧冷色 |
124
-
125
- ---
126
-
127
- ## ⚙️ 配置项
128
-
129
- ### `createYhTheme(options)`
130
-
131
- | 选项 | 类型 | 默认值 | 说明 |
132
- | ---------------- | ------------------------------------------------------------------- | ----------- | ----------------------------------- |
133
- | `preset` | `ThemePreset` | `'default'` | 预设主题名 |
134
- | `algorithm` | `'default' \| 'vibrant' \| 'soft' \| 'dark'` | `'default'` | 颜色生成算法 |
135
- | `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | 密度档位 |
136
- | `colorBlindMode` | `'protanopia' \| 'deuteranopia' \| 'tritanopia' \| 'achromatopsia'` | `undefined` | 色盲友好模式 |
137
- | `followSystem` | `boolean` | `false` | 是否跟随系统暗色偏好 |
138
- | `transition` | `boolean` | `true` | 是否开启主题切换 transition 动画 |
139
- | `persist` | `boolean` | `false` | 是否将用户偏好持久化到 localStorage |
140
- | `namespace` | `string` | `'yh'` | CSS 变量命名空间前缀 |
141
-
142
- ### `useTheme()` 返回值
143
-
144
- | 属性/方法 | 类型 | 说明 |
145
- | ------------------------- | --------------------- | ---------------- |
146
- | `preset` | `Ref<ThemePreset>` | 当前主题预设 |
147
- | `isDark` | `Ref<boolean>` | 是否为暗色模式 |
148
- | `density` | `Ref<Density>` | 当前密度 |
149
- | `algorithm` | `Ref<Algorithm>` | 当前颜色算法 |
150
- | `colorBlindMode` | `Ref<ColorBlindMode>` | 当前色盲模式 |
151
- | `setPreset(preset)` | `Function` | 切换主题预设 |
152
- | `toggleDark()` | `Function` | 切换暗色/亮色 |
153
- | `setDensity(density)` | `Function` | 设置密度档位 |
154
- | `setAlgorithm(algorithm)` | `Function` | 设置颜色算法 |
155
- | `setColorBlindMode(mode)` | `Function` | 设置色盲友好模式 |
156
- | `resetTheme()` | `Function` | 重置为默认主题 |
157
-
158
- ---
159
-
160
- ## 🎨 CSS 设计令牌（Design Tokens）
161
-
162
- 主题系统通过 CSS 自定义属性（CSS Variables）实现，可在任意样式中使用：
163
-
164
- ```scss
165
- // 主色系
166
- --yh-color-primary
167
- --yh-color-primary-light-3
168
- --yh-color-primary-dark-2
61
+ ## Direct Utilities
169
62
 
170
- // 文字颜色
171
- --yh-text-color-primary
172
- --yh-text-color-regular
173
- --yh-text-color-secondary
174
- --yh-text-color-placeholder
63
+ ```ts
64
+ import {
65
+ checkContrast,
66
+ getTextColorForBackground,
67
+ setThemePreset,
68
+ toggleDarkMode
69
+ } from '@yh-ui/theme'
70
+
71
+ setThemePreset('teal')
72
+ toggleDarkMode()
73
+ checkContrast('#111827', '#ffffff')
74
+ getTextColorForBackground('#409eff')
75
+ ```
175
76
 
176
- // 背景颜色
177
- --yh-bg-color
178
- --yh-bg-color-page
179
- --yh-bg-color-overlay
77
+ ## Design Tokens
180
78
 
181
- // 边框
79
+ The package writes YH-UI CSS variables such as:
80
+
81
+ ```css
82
+ --yh-color-primary
83
+ --yh-color-success
84
+ --yh-text-color-primary
85
+ --yh-bg-color
182
86
  --yh-border-color
183
- --yh-border-color-light
184
87
  --yh-border-radius-base
185
-
186
- // 间距（密度相关）
187
- --yh-spacing-xs
188
- --yh-spacing-sm
189
- --yh-spacing-md
190
- --yh-spacing-lg
191
-
192
- // 组件尺寸
193
- --yh-component-size-small
194
88
  --yh-component-size-default
195
- --yh-component-size-large
89
+ --yh-density-factor
196
90
  ```
197
91
 
198
- 在自定义组件中使用：
199
-
200
- ```scss
201
- .my-card {
202
- background: var(--yh-bg-color);
203
- border: 1px solid var(--yh-border-color);
204
- border-radius: var(--yh-border-radius-base);
205
- color: var(--yh-text-color-primary);
206
- padding: var(--yh-spacing-md);
207
- }
208
- ```
209
-
210
- ---
211
-
212
- ## 🌙 暗色模式
213
-
214
- YH-UI 主题系统提供两种暗色模式激活方式：
215
-
216
- ### 方式一：受控切换
217
-
218
- ```ts
219
- const { toggleDark, isDark } = useTheme()
220
- toggleDark() // 手动切换
221
- ```
222
-
223
- ### 方式二：跟随系统（推荐）
224
-
225
- ```ts
226
- createYhTheme({ followSystem: true })
227
- // 自动响应 prefers-color-scheme: dark
228
- ```
229
-
230
- ---
231
-
232
- ## ⚠️ 注意事项
233
-
234
- 1. **主题包含 CSS 文件**：需要在入口统一引入样式，`@yh-ui/yh-ui/css` 会自动包含主题样式
235
- 2. **SSR**：服务端不存在 `localStorage`，`persist: true` 时需配合 Nuxt Cookie 持久化
236
- 3. **色盲模式**：启用色盲模式后，颜色算法将强制切换以保证 WCAG 对比度合规
237
- 4. **命名空间**：自定义 `namespace` 时，CSS 变量前缀会相应变更，需同步修改样式引用
238
-
239
- ---
240
-
241
- ## 🔗 相关资源
242
-
243
- - [📖 官方文档 — 主题系统](https://1079161148.github.io/yh-ui/guide/theming)
244
- - [📦 GitHub 仓库](https://github.com/1079161148/yh-ui)
92
+ These variables are consumed by YH-UI components and can also be used in your own CSS.
245
93
 
246
- ## 📄 开源协议
94
+ ## License
247
95
 
248
- MIT License © 2024-present YH-UI Team
96
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yh-ui/theme",
3
- "version": "1.0.5",
3
+ "version": "1.0.8",
4
4
  "description": "YH-UI theme and design tokens",
5
5
  "type": "module",
6
6
  "sideEffects": [
@@ -22,7 +22,8 @@
22
22
  "types": "./dist/*.d.ts",
23
23
  "import": "./dist/*.mjs",
24
24
  "require": "./dist/*.cjs"
25
- }
25
+ },
26
+ "./package.json": "./package.json"
26
27
  },
27
28
  "files": [
28
29
  "dist",