@iquji-web/web-theme 0.1.1 → 0.1.3

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 (2) hide show
  1. package/README.md +78 -5
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,9 +1,82 @@
1
- # Web theme
1
+ # @iquji-web/web-theme
2
2
 
3
- `@iquji-web/web-theme` 只提供通用 theme 能力,JavaScript、类型声明、必要样式及功能测试随源码交付。
3
+ 简体中文 | [English](README.en.md)
4
4
 
5
- 安装使用本目录锁文件,运行 `bun install --frozen-lockfile` 和 `bun run check`。正式入口只导出 `dist` 中的 JavaScript、类型声明和独立 CSS,不要求消费者编译本包源码。
5
+ Iquji Web 设计系统与主题机制,提供语义化 CSS Tokens、明暗主题与密度切换、持久化上下文 Provider 以及首帧无闪烁防闪脚本。
6
6
 
7
- `--iquji-color-action-primary`、`--iquji-color-action-danger` 及各自的 `-hover` 变量提供填充操作背景,`--iquji-color-action-contrast` 提供白色前景;它们独立于阅读用强调色和状态提醒色。应用覆盖操作变量时仍须保持明暗主题的可读对比度,不用状态提醒的浅色文字充当红底按钮背景。禁用操作使用 `--iquji-color-disabled-fill` 和 `--iquji-color-disabled-text`。
7
+ ---
8
8
 
9
- 输入类控件使用独立的 `--iquji-color-control-border`、`--iquji-color-control-hover-border`、`--iquji-color-control-focus-border` 和 `--iquji-control-focus-shadow`。默认以明暗主题的中性描边与 1px 柔和外晕标识聚焦;品牌色覆盖不会生成粗色环。按钮、导航等键盘入口仍使用 `--iquji-focus-ring`,高对比度模式保留系统可见焦点。
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
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iquji-web/web-theme",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "files": [