paseo-antd-themes 0.1.0 → 0.2.0

package/DESIGN.md

@@ -33,7 +33,7 @@
 | 容器 | `colorBgContainer` / `paseoSurface1` | `bg-container` / `bg-surface-1` | 卡片、输入框、默认按钮、面板 | `#F5F4EC` | `#1E2120` |
 | 浮层 | `colorBgElevated` / `paseoSurface2` | `bg-elevated` / `bg-surface-2` | 弹层、下拉、Modal、Message、Segmented 选中滑块 | `#FFFFFF` | `#272A29` |
 | 侧栏 | `paseoSurfaceSidebar` | `bg-surface-sidebar` | Sider、Menu 底色 | `#E2E0D6` | `#141716` |
-| 面板头 | `paseoSurfaceHead` | `bg-surface-head` | Card 头、Table 表头 | `#E0DDD0` | `#1E2120` |
+| 面板头 | `paseoSurfaceHead` | `bg-surface-head` | Card 头（表格表头与表格同底，不用它） | `#E0DDD0` | `#1E2120` |
 | 卡片 hover | `paseoSurfaceHover` | `bg-surface-hover` | 卡片 / 表格行 hover | `#DDD9CE` | `#1E2120` |
 | 强填充 | `paseoSurface3` / `paseoSurface4` | `bg-surface-3` / `bg-surface-4` | 控件内的强对比填充：菜单 hover / 选中、进度轨道 | `#D7D2C7` / `#D1CCBF` | `#434645` / `#595B5B` |
 
@@ -59,7 +59,7 @@
 规则：
 
 - **降级强调用 `text-text-secondary`，不要用 `opacity`**。主题已经给了四档，`opacity: 0.6` 在不同表面上会落进对比度盲区。
-- `text-text-quaternary` 在浅色下只有约 3:1，任何需要阅读的内容都不许用它；它只用于 placeholder、disabled。
+- `text-text-quaternary` 在浅色下约 2.5:1，任何需要阅读的内容都不许用它；它只用于 placeholder、disabled。
 - 三级（元信息）的 4.5:1 承诺覆盖页面底与卡片两种表面；浮层（`#FFFFFF` / `#272A29`）上不保证，浮层里的说明文字升一档改用二级。
 - 表格数字、ID、代码、diff 内容用 `font-mono`；金额和统计加 `tabular-nums` 保持列对齐。
 - 标题不需要单独颜色：用 `text-text` + 字重 600 表达层级。
@@ -82,6 +82,7 @@
 - **链接与主色同族**：`colorLink` 在 Claude 浅色取主色的 text 档（`#A34E2D`，不是 3.86:1 的填充档），Paseo 深色取更亮的绿。整套界面只有一个品牌色相，不再单独引入链接蓝；hover / active 都在同族内加深并过 4.5:1。
 - **语义色只表达状态**，不做装饰背景、不做分类标签的默认色。分类、图表请用身份色（见下）。
 - 主按钮上的白字是刻意校准过的：Claude 浅色 `#BA5B37` 上白字 4.53:1，刚好过线。**不要用更浅的品牌装饰色 `#D97757` 做按钮底色**，白字只有 3.12:1。
+- **深色的语义色是文字档，不是填充档**：`colorError` 在深色是浅红（作文字 5.8:1），antd 的实心 danger 按钮会直接拿它当底色；主题为此把标签改成墨字（`Button.dangerColor`），但视觉上仍是一块浅色。确认类操作优先用描边 danger。
 - 需要换品牌色时用 `extendTheme` 覆盖 `colorPrimary`，它会重建整个十槽色族；直接嵌套 `ConfigProvider theme={{ token: { colorPrimary } }}` 会被算法覆盖，详见 README 的「从一个内置主题扩展」。
 
 ### 扩展色：状态点、diff、身份色、选区
@@ -92,14 +93,15 @@
 | 已合并 | `paseoStatusMerged` | `bg-status-merged` | 合并类状态，唯一允许的紫色语义 |
 | diff 行底 | `paseoDiffAddition` / `paseoDiffDeletion` | `bg-diff-addition` / `bg-diff-deletion` | 整行背景 |
 | diff 文字 | `paseoDiffAdditionText` / `paseoDiffDeletionText` | `text-diff-addition-text` 等 | 词级高亮与 `+12 −3` 统计 |
-| 身份色 | `paseoIdentity*`（10 色） | `bg-identity-violet` 等 | 主机 / agent / 项目标识；一律配白字 |
+| 身份色 | `paseoIdentity*`（10 色） | `bg-identity-violet` 等 | 主机 / agent / 项目标识 |
+| 身份色文字 | `paseoIdentityInk` | `text-identity-ink` | 身份色块上的文字：亮色白字、暗色墨字 |
 | 选区 | `paseoSelection` | `selection:bg-selection` | `::selection` 背景，不要手写半透明色 |
 
 规则：
 
 - 状态点与语义色是两套：**文字用 `text-success`，点用 `bg-status-dot-success`**。状态点是按「非文字图形」调过的亮度（深色下明显更亮），语义色是按 4.5:1 文字阈值调的，两者不要互相顶替。
 - diff 行底只负责「哪一行是增/删」，**统计数字用 `diff-*-text`**；把状态色直接铺在行底上会低于 4.5:1（浅色行底只有约 4.3）。
-- 身份色按等响度归一化，白字永远落在 4.2–5.2:1 区间；不要从中挑一个再调亮，色相只负责「是谁」，不负责「多重要」。
+- 身份色按等响度归一化，色块上的文字一律用 `paseoIdentityInk`：亮色是白字（4.7–5.2:1），暗色是墨字（6.1–6.4:1）。不要假设白字在深色下可用——那十条浅彩色配白字只有 2.6:1。不要从中挑一个再调亮，色相只负责「是谁」，不负责「多重要」。
 
 ### 边框与分隔
 
@@ -192,10 +194,10 @@
 
 | 组件 | 主题已配 | 使用规则 |
 | --- | --- | --- |
-| Button | 主按钮白字、hover/active 加深、三级投影 | 每个区块最多一个 `type="primary"`；次级操作用默认按钮；第三级用 `type="text"`；删除才用 `danger`。loading 图标由 Provider 统一，不要自己传 |
+| Button | 主按钮白字、hover/active 加深、三级投影；深色实心 danger 用墨字 | 每个区块最多一个 `type="primary"`；次级操作用默认按钮；第三级用 `type="text"`；删除才用 `danger`，确认类操作优先描边（`danger` + 默认类型）。loading 图标由 Provider 统一，不要自己传 |
 | Input / Select | 边框色、hover/active 主色、12px 圆角、40px 高 | 错误态交给 `status="error"`，不要手写红边框；Select 的长列表见上文 `listItemHeight` |
 | Card | `surface-1` 底、12px 圆角、头用 `surface-head`、默认无阴影 | 卡片是页面上的「纸」，不要嵌套三层卡片；卡片头与正文之间用 `border-split`；`hoverable` 才出现悬浮投影 |
-| Table | 表头 `surface-head`、行 hover `surface-hover`、行线 `border-split`、斑马纹 `colorFillAlter`（派生自 `fill-quaternary`） | 斑马纹与行 hover 不要同时开；数字列右对齐并用 mono；空态用 Empty，不要自己画 |
+| Table | 表头与表格同底（`surface-1`，靠字重 + `border-split` 行线区分）、行 hover `surface-hover`、行线 `border-split`、斑马纹 `colorFillAlter`（派生自 `fill-quaternary`） | 斑马纹与行 hover 不要同时开；数字列右对齐并用 mono；空态用 Empty，不要自己画 |
 | Segmented / Tabs | Segmented：`Segmented.trackBg`（亮暗都用页面底 `surface0`）+ 4px 内边距 + 4px 项间距；Tabs：ink bar 主色 | 两者都表达「切视图」，同一区域只选一个；Segmented 选项不超过 5 个 |
 | Menu / Layout | 侧栏底 `surface-sidebar`，hover/选中按表面分层 | 侧栏菜单只用一级图标 + 文字，不塞按钮组；选中项由路由决定，不要手写背景 |
 | Tag / Badge | Tag 8px 圆角；Badge 用胶囊/圆点 | 状态用语义色的 text/bg 槽；分类用身份色；Tag 里不放可点击的主操作 |
@@ -218,7 +220,7 @@
 | `extendTheme(base, { token })` 换色 | 嵌套 `ConfigProvider` 传 seed token |
 | 用 `text-link` 做链接（主色系 text 档） | 用主色填充色当链接（浅色仅 3.86:1） |
 | 彩色文字用 `text-primary-text` | 用 `text-primary` 写正文 |
-| 换槽位配对后重新生成 `tailwind.css` | 混搭主题 + 默认 `tailwind.css`（工具类会与组件色漂移） |
+| 换槽位配对后重新生成 `tailwind.css` / `tailwind-vars.css` | 混搭主题 + 默认 Tailwind 产物（工具类会与组件色漂移） |
 
 ## 定制与覆盖
 

package/MAPPING.md

@@ -90,9 +90,9 @@ Claude 品牌表面 + Claude Code 信号色 + paseo 归一化状态色（OKLCH L
 | `colorBgSpotlight` | map | `#1F1E1D` | `—` | Tooltip stays dark ink with white text. |
 | `colorBgMask` | map | `rgba(20, 20, 19, 0.45)` | `—` |  |
 | `colorText` | map | `#3C3C2C` | `foreground` |  |
-| `colorTextSecondary` | map | `#5C5C54` | `foregroundMuted` |  |
+| `colorTextSecondary` | map | `#55554B` | `foregroundMuted` |  |
 | `colorTextTertiary` | map | `#65635E` | `foregroundExtraMuted` |  |
-| `colorTextQuaternary` | map | `#878681` | `foregroundFaint` | Placeholder/disabled only — not a body-text level. |
+| `colorTextQuaternary` | map | `#98978F` | `foregroundFaint` | Placeholder/disabled only — not a body-text level. |
 | `colorTextLightSolid` | map | `#FFFFFF` | `—` | Danger/solid labels stay white; primary buttons override with Button.primaryColor. |
 | `colorBorder` | map | `#DBD9D0` | `border` |  |
 | `colorBorderSecondary` | map | `#E8E6DF` | `borderAccent` |  |
@@ -122,8 +122,10 @@ Claude 品牌表面 + Claude Code 信号色 + paseo 归一化状态色（OKLCH L
 | `boxShadowTertiary` | map | `0 1px 2px rgba(31, 30, 29, 0.04), 0 4px 12px rgba(31, 30, 29, 0.06)` | `—` |  |
 ## Tailwind 变量映射
 
-`src/tailwind/theme.css` 由 `scripts/gen-tailwind.ts` 生成：值经 antd 管线解析（含算法派生的
-hover/active/色阶槽位），浅色写在 `:root`，深色同时写在 `@media (prefers-color-scheme: dark)` 与 `.dark`。
+`src/tailwind/{theme.css,vars.css,preset.cjs}` 由 `scripts/gen-tailwind.ts` 生成：值经 antd 管线解析（含算法派生的
+hover/active/色阶槽位）。`theme.css` 是 Tailwind v4 导出（`@theme inline`）；`vars.css` 是同一批变量的 v3 版本；
+`preset.cjs` 是 v3 preset，每个 utility 的值都指向 `var(--paseo-*)`。浅色写在 `:root`，深色同时写在
+`@media (prefers-color-scheme: dark)` 与 `.dark`。
 
 | Tailwind 变量 | 浅色值（Claude Light） | 深色值（Paseo Dark） | antd token 来源 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -191,9 +193,9 @@ hover/active/色阶槽位），浅色写在 `:root`，深色同时写在 `@media
 | `--paseo-surface-head` | `#E0DDD0` | `#1E2120` | `paseoSurfaceHead` / `paseoSurface1` | 深色主题没有 paper-on-paper 表头概念，用面板色 surface1 补位（与 Table.headerBg 一致）。 |
 | `--paseo-surface-hover` | `#DDD9CE` | `#1E2120` | `paseoSurfaceHover` / `paseoSurface1` | 深色主题的卡片 hover 就是面板色 surface1（与 Table.rowHoverBg 一致）。 |
 | `--paseo-text` | `#3C3C2C` | `#fafafa` | `colorText` |  |
-| `--paseo-text-secondary` | `#5C5C54` | `#A1A5A4` | `colorTextSecondary` |  |
+| `--paseo-text-secondary` | `#55554B` | `#A1A5A4` | `colorTextSecondary` |  |
 | `--paseo-text-tertiary` | `#65635E` | `#8A8E8D` | `colorTextTertiary` |  |
-| `--paseo-text-quaternary` | `#878681` | `#595B5B` | `colorTextQuaternary` |  |
+| `--paseo-text-quaternary` | `#98978F` | `#595B5B` | `colorTextQuaternary` |  |
 | `--paseo-text-light-solid` | `#FFFFFF` | `#fff` | `colorTextLightSolid` |  |
 | `--paseo-border` | `#DBD9D0` | `#252B2A` | `colorBorder` |  |
 | `--paseo-border-secondary` | `#E8E6DF` | `#2F3534` | `colorBorderSecondary` |  |
@@ -227,6 +229,7 @@ hover/active/色阶槽位），浅色写在 `:root`，深色同时写在 `@media
 | `--paseo-identity-red` | `#ad5151` | `#d88381` | `paseoIdentityRed` |  |
 | `--paseo-identity-amber` | `#807046` | `#b29d64` | `paseoIdentityAmber` |  |
 | `--paseo-identity-blue` | `#4773ae` | `#7ba1d5` | `paseoIdentityBlue` |  |
+| `--paseo-identity-ink` | `#FFFFFF` | `#1F1E1D` | `paseoIdentityInk` |  |
 | `--paseo-font` | `system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif` | `system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif` | `fontFamily` |  |
 | `--paseo-font-mono` | `SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace` | `SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace` | `fontFamilyCode` |  |
 | `--paseo-radius-xs` | `4px` | `4px` | `borderRadiusXS` |  |

package/README.md

@@ -165,6 +165,35 @@ import { antdDarkTheme, antdLightTheme, paseoDarkTheme } from "paseo-antd-themes
 </div>
 ```
 
+### Tailwind v3（preset + 变量表）
+
+v3 没有 `@theme`，同一批变量以「preset + CSS 变量」两份产物发布：
+
+```js
+// tailwind.config.js
+const preset = require("paseo-antd-themes/tailwind-preset");
+
+module.exports = {
+  content: ["./src/**/*.{ts,tsx}"],
+  presets: [preset],
+  // antd 自带 reset；preflight 二选一
+  corePlugins: { preflight: false },
+};
+```
+
+```css
+/* 入口 CSS */
+@import "paseo-antd-themes/tailwind-vars.css";
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+preset 里每个 utility 的值都是 `var(--paseo-*)`，所以：
+
+- 单主题：`tailwind-vars.css` 提供 `:root` / `.dark` 两套值，切明暗不需要重新构建。
+- 多主题（同一页面在不同配对之间切换）：不要用 `tailwind-vars.css`，改用包根导出的 `generateTailwindVariables(theme)`，为每套主题各生成一份变量块并挂到不同选择器上（`[data-pair="…"][data-scheme="…"]`）。demo 就是这么做的，切换配对时工具类会跟着变。
+
 常用类一行速查：`bg-surface-1`（纸感卡片底）、`border-split`（分隔线）、`font-mono`（等宽）、`rounded-md`（12px 圆角）。
 
 暗色下不写 `dark:` 的类会随 `--paseo-*` 变量自动换色；需要浅深用不同 token 时用 `dark:` 变体：
@@ -240,9 +269,9 @@ import { PaseoThemeProvider } from "paseo-antd-themes";
 - **不要引 `antd/dist/reset.css`**：Tailwind preflight 已覆盖它的全部页面级职责；遗留页面必须引时要带 `layer(reset)`。
 - **`PaseoThemeProvider` 注入的行为 CSS 是无层级的**（loading 图标、Segmented/Select 间隙），会赢过 utilities——想用工具类改这几处时压不过它。不需要这些行为时用 `behaviors` 逐项关掉，关掉的项不会注入任何 CSS。
 
-另见上一小节的两点有意覆盖（`text-text-secondary` 命名、font/radius 刻度）。以上结论的完整论证见 [antd v6 + Tailwind v4 组合最佳实践](./docs/antd-v6-tailwind-v4.md)。
+另见上一小节的两点有意覆盖（`text-text-secondary` 命名、font/radius 刻度）。以上结论的完整论证见 [antd v6 + Tailwind v4 组合最佳实践](https://github.com/BanShan-Alec/paseo-antd-theme/blob/master/docs/antd-v6-tailwind-v4.md)。
 
-想系统理解新版概念与覆盖方式，见博客《[从 antd v4 + Tailwind v3 到 antd v6 + Tailwind v4（上）：先搞懂概念，再学会覆盖](./docs/antd-v6-tailwind-v4-part1-concepts-and-overrides.md)》。如果你必须留在 Tailwind v3，见《[antd v6 + Tailwind v3 最佳实践：不开 layer，用构建期 token 同步](./docs/antd-v6-tailwind-v3-best-practices.md)》。
+想系统理解新版概念与覆盖方式，见博客《[从 antd v4 + Tailwind v3 到 antd v6 + Tailwind v4（上）：先搞懂概念，再学会覆盖](https://github.com/BanShan-Alec/paseo-antd-theme/blob/master/docs/antd-v6-tailwind-v4-part1-concepts-and-overrides.md)》。如果你必须留在 Tailwind v3，见《[antd v6 + Tailwind v3 最佳实践：不开 layer，用构建期 token 同步](https://github.com/BanShan-Alec/paseo-antd-theme/blob/master/docs/antd-v6-tailwind-v3-best-practices.md)》。
 
 ## Exports
 

package/dist/index.d.ts

@@ -6,5 +6,9 @@ export { claudeLightTheme } from './themes/claude/theme.js';
 export { paseoDarkTheme } from './themes/paseo-dark/theme.js';
 export { extendTheme } from './extendTheme.js';
 export type { ThemeExtension } from './extendTheme.js';
-export { generateTailwindCss } from './tailwind/build.js';
-export type { TailwindThemePair } from './tailwind/build.js';
+export { hexLuminance } from './shared/colors.js';
+export type { DerivedToken, TokenMapping } from './shared/theme.js';
+export { CLAUDE_LIGHT_DERIVED_TOKENS, CLAUDE_LIGHT_TOKEN_MAPPING, } from './themes/claude/theme.js';
+export { PASEO_DARK_TOKEN_MAPPING, PASEO_DERIVED_TOKENS, } from './themes/paseo-dark/theme.js';
+export { generateTailwindCss, generateTailwindPreset, generateTailwindVariables, generateTailwindVarsCss, } from './tailwind/build.js';
+export type { TailwindThemePair, TailwindVariable } from './tailwind/build.js';