@iquji-web/web-theme 0.1.2 → 0.1.4
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.
- package/README.md +78 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,9 +1,82 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @iquji-web/web-theme
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
简体中文 | [English](README.en.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Iquji Web 设计系统与主题机制,提供语义化 CSS Tokens、明暗主题与密度切换、持久化上下文 Provider 以及首帧无闪烁防闪脚本。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
---
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## 安装
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @iquji-web/web-theme
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 引入 Tokens 样式
|
|
18
|
+
|
|
19
|
+
在你的应用入口(如 `main.tsx` 或 `index.html`)优先引入:
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import "@iquji-web/web-theme/tokens.css";
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
CSS Tokens 支持通过 `[data-theme="light"]` 与 `[data-theme="dark"]` 动态适配:
|
|
26
|
+
- 基础颜色:`--iquji-color-canvas`, `--iquji-color-surface`, `--iquji-color-border`, `--iquji-color-text`, `--iquji-color-muted`
|
|
27
|
+
- 交互强调:`--iquji-color-accent`, `--iquji-color-action-primary`, `--iquji-color-action-danger`
|
|
28
|
+
- 间距与字号:`--iquji-space-1` 至 `--iquji-space-16`, `--iquji-font-size-*`
|
|
29
|
+
- 圆角与投影:`--iquji-radius-*`, `--iquji-shadow-*`
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 主题 Provider 与 Hook
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import { IqujiThemeProvider, useIqujiTheme } from "@iquji-web/web-theme";
|
|
37
|
+
|
|
38
|
+
export function App() {
|
|
39
|
+
return (
|
|
40
|
+
<IqujiThemeProvider defaultMode="system" storageKey="app.theme">
|
|
41
|
+
<ThemeToggle />
|
|
42
|
+
</IqujiThemeProvider>
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function ThemeToggle() {
|
|
47
|
+
const { mode, resolvedTheme, setMode } = useIqujiTheme();
|
|
48
|
+
|
|
49
|
+
return (
|
|
50
|
+
<button onClick={() => setMode(resolvedTheme === "dark" ? "light" : "dark")}>
|
|
51
|
+
当前主题: {resolvedTheme} (模式: {mode})
|
|
52
|
+
</button>
|
|
53
|
+
);
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 首帧防闪脚本 (Prepaint Script)
|
|
60
|
+
|
|
61
|
+
在服务端渲染 (SSR) 或 HTML `<head>` 注入 `IqujiThemePrepaintScript`,在 React 水合和页面首帧渲染前同步读取主题,彻底避免深色模式下的白色闪屏:
|
|
62
|
+
|
|
63
|
+
```tsx
|
|
64
|
+
import { IqujiThemePrepaintScript } from "@iquji-web/web-theme";
|
|
65
|
+
|
|
66
|
+
// 在 HTML <head> 中尽早执行
|
|
67
|
+
<head>
|
|
68
|
+
<IqujiThemePrepaintScript storageKey="app.theme" defaultMode="system" />
|
|
69
|
+
</head>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 开发与构建
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
bun install --frozen-lockfile
|
|
78
|
+
bun run build # 编译打包到 dist/
|
|
79
|
+
bun run typecheck # 类型检查
|
|
80
|
+
bun run test # 单元测试
|
|
81
|
+
bun run check # 完整检查
|
|
82
|
+
```
|