tt-design-web-vue 0.1.0 → 0.1.4

package/CHANGELOG.md

@@ -2,7 +2,122 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## 0.1.4
+
+> 本版是 `0.1.1` 之后第一个发布到 registry 的版本。下方 `0.1.3` / `0.1.2` 两节的编号已归档，但从未发布，其内容一并包含在本版中：宿主从 `0.1.1` 升级到本版时，请连同那两节一起阅读。
+
+- 发布流程改为「版本号常驻」：`package.json` 的 `version` 与本文档顶部章节恒等于**下一个要发布的版本**，发布即 `npm publish`，不再有发布时的版本改动。此前「只在发版时才递增版本号」的规则已经导致 `0.1.2` / `0.1.3` 两节被归档却从未发布到 registry（`latest` 长期停在 `0.1.1`），宿主按 `^0.1.1` 装到的仍是 `0.1.1`；新约定下同类漂移会直接表现为 `package.json` 与 dist-tag 的差异，而不是藏在 CHANGELOG 的章节标题里。本次同时明确两条发版事实：`npm publish` 与 `yarn publish` 都会触发 `yarn prepack`（构建 + 包校验），这是删掉人工「发布时改版本」步骤后唯一的质量闸门；要「发布不改任何文件」必须用 `npm publish`，裸 `yarn publish` 会交互式询问新版本号并改写 `package.json`、自动建 commit 与 tag（需要时可用 `yarn publish --new-version <当前版本> --no-git-tag-version`）。
+- 按发布约定同步版本引用：`package.json`（`0.1.3` → `0.1.4`）、`README.md`、`plan.md` 与 Storybook 示例（`ActivityFeed.stories.ts`、`Descriptions.stories.ts`）中的当前版本引用全部对齐到 `0.1.4`；`AGENTS.md` / `CLAUDE.md` 的「版本与发布」章节与本仓库的 `tt-design-vue-manage-version` skill 改为记录新约定（版本号常驻、直接 `npm publish`、发布后立刻推进到下一个号），并删去不再存在的 `Unreleased` 流程描述。
+- 新增 `TtLayout` 的 `fill` 属性：开启后根节点 `height: 100%` + `overflow: hidden` 定高，`.tt-layout__body` 取 `flex: 1`，`.tt-layout__content` 成为唯一滚动区（`overflow: auto`），从而让 `#header` 与 `#footer` 固定在两端、只有正文滚动。此前组件只有内容驱动的 `min-height: 100%`，**没有表达「定高 + 正文自滚」的能力**：宿主若要在页面骨架上固定标题与页脚，只能自己写 `height`/`flex`/`overflow` 链或用绝对定位，而这正是 TongClaw 规范禁止的「用业务私有类重复发明页面骨架」。默认值 `false` 保持既有内容驱动行为，不改变任何现有消费方。同步新增 `layout.spec.ts`（5 例：区域按插槽渲染、默认不开启 fill、开启后加类、fill 规则含定高与滚动区、基类保持内容驱动）与 Storybook 的「撑满与正文自滚」示例。
+
+- 修复 `TtForm` 上下结构（`label-position="top"`）下标签到控件的间距翻倍成 16px 的问题。根因是同一段间距被两个来源各写一次：Element Plus 的 `.el-form-item--label-top .el-form-item__label` 自带 `margin-bottom: 8px`，而本库的 `.tt-form.el-form.el-form--label-top .el-form-item__label` 又用 `padding-bottom: 8px` 表达同一段间距（取值对齐参考项目 tt-design 的垂直表单），两条规则命中同一个标签元素、各自的特异性（`(0,2,0)` 与 `(0,4,0)`）又都压得住对方的复位，于是不是互相覆盖而是叠加成 16px。现于本库规则内清掉 Element Plus 的 margin（`margin-bottom: 0`），只保留 8px 的 padding：间距回到 8px，且不随 `size` 档漂移到 Element Plus 默认的 4 / 12px。标签元素自身仍是 34px 行高 + 8px 内边距 = 42px 的外框（DevTools 里量到的 60.66 × 42 就是这个盒子），这是本库把标签行高统一成 34px 后的预期值，本次不改动——改的只是它下沿到控件之间那段被重复计入的间距。
+- 新增 `tests/components/form.spec.ts`：断言上下结构的标签规则内只存在一段非零间距且显式写了 `margin-bottom: 0`，并断言真实渲染下 `.el-form--label-top.tt-form` 与 `.el-form-item--label-top.tt-form-item` 会同时出现在同一个表单上——这是两条规则叠加的前提条件，防止以后有人误判其中一条没生效。
+- 新增 `TtPageHeader` 页面标题区组件，把规范里的 `page-header__main` / `page-header__actions` 两个区域落成组件能力。宿主此前没有可用的标题区原语，每个页面各自用私有类写一遍「标题 + 描述 + 右侧操作」的布局，同一产品里出现多套几何；规范第 2 节又明确禁止「用业务私有类重复发明页面标题区和外层留白体系」。组件默认渲染 `page-title` 档标题（16/24、600、`<h1>`），主信息区与操作区间距取 `--tt-space-4`、操作区按钮间距取 `--tt-space-3`（与规范「按钮间距取 `--tt-space-3`」一致），窄屏操作区折行而不挤压标题；`default` 插槽可整体替换主信息区，便于挂徽标或 kicker。起始页 Hero（24/36、700）不由本组件承载。同步新增 Vitest 契约（标题档位与 `<h1>` 语义、描述按 prop / 插槽渲染、无描述时不渲染节点、操作区按插槽存在与否渲染、default 插槽整体替换、几何不写裸值）、VitePress 文档与导航、Storybook story，并更新 `docs/component-manifest.json`（Vue-only 默认扩展）与 `docs/component-compatibility.md`。
+- 修复 `TtFont` 标题档不符合规范字重与字号阶梯的问题。字重方面：`h1`–`h4` 此前统一写 `font-weight: 500`，而规范只允许 400 / 600 / 700 三档，500 既不在档位内、也让标题与同级标签的层级差异过弱；现改为新增的 `--tt-font-weight-regular` / `-semibold` / `-bold` 三档 token，标题取 `semibold`、正文与辅助文字取 `regular`（起始页 Hero 这类强调场景由宿主取 `bold`）。字号方面：`h1`–`h4` 此前把 `32px/48px`、`24px/36px`、`18px/28px`、`16px/24px` 写成裸值，宿主无法通过改 token 调整标题档，现在全部改绑既有的 `--tt-font-size-*` / `--tt-line-height-*` 阶梯。顺带修正一处阶梯外取值：`h3` 的行高由 `28px` 收敛到规范档位 `18/26`（对应 `--tt-line-height-xl`），这是本次唯一的字号类视觉变化。
+- 新增 `TtFont` 的 `page-title` 变体：与 `h4` 同为 16/24 档，但渲染 `<h1>`。规范第 3 节要求菜单页页面标题取 16/24、600，而此前的变体里只有 `h2`（24/36）够醒目，宿主只好把页面标题写成 `h2`，既越过档位、又让页面出现「标题比 Hero 还大」的层级倒挂。拆出语义变体而不是让宿主用 `h4` 顶替，是因为页面标题必须是一级标题语义，不能降级到四层标题。`FontVariant` 类型、Storybook 的 Controls 选项与字阶示例表同步更新，示例表补上字重列并修正 `h3` 的陈旧行高值（28px → 26px）。
+- 新增 `font.spec.ts` 的规范阶梯契约：断言字号与行高在 `Font/style.scss` 内不出现裸值、六个变体各自绑定对应 token、`h3` 落在 18/26 档且不再含 `28px`、字重不出现裸值与 `500`，以及三个字重 token 已在 `tokens.scss` 登记。
+- 修复深色主题下实心按钮变成「浅蓝底 + 深字」的问题（对照组：宿主 TongClaw 自己的暗色主按钮是饱和蓝底 + 白字，两者同屏会长成两种样子）。根因是实心态借用了 `--tt-text-inverse` 与 `--tt-color-grey-0` 当标签色：这两个 token 在深色主题下都翻成 `#041a31`，而 `--tt-color-primary` 在深色主题下是明度 68% 的浅色（`#5ca0ff`，它的本职是链接 / 文字按钮 / 焦点环这类**前景**色），于是实心按钮就成了浅底深字。新增一组专供填充的 token：`--tt-color-primary-solid` / `-solid-hover` / `-solid-active`、`--tt-color-error-solid` / `-solid-hover` / `-solid-active`，以及填充上的文字色 `--tt-text-on-brand`（两个主题恒为白）。浅色主题的实心底就是品牌色本身、`hover` 更亮 `active` 更沉，取值与改动前逐项一致；深色主题的实心底改取色阶 4 / 3 / 2 阶（`#2c6baf` → `#1d4972` → `#123149`），白字对比度由 2.65:1 提升到 5.48 / 9.34 / 13.45:1，hover 与 active 的方向也改成「按下变深」，与宿主的暗色节奏一致。
+- 新增 `--tt-text-on-tint`：给「浅色调填充」上的文字用（`Tag`、`Badge`、`Radio` 按钮组选中态、`Steps` 进行中、`DatePicker` 选中日、`QRCode`、`Card` 指标图标、`Avatar`、`Alert.is-dark`、`Upload` 状态图标、`CardSelect` 角标、`FloatButton`、`Image` 查看器 hover）。这些填充的底色在深色主题下被明度阶梯推导成浅色，文字必须跟着翻转（浅色主题白 / 深色主题 `#041a31`）——此前它们借的是 `--tt-bg-white` 或 `--tt-color-grey-0`，语义是「面」与「灰阶极值」，只是因为 `bg-white` 在深色主题下恰好等于深色才没出错。现在这些消费点全部改读该 token，视觉取值与改动前一致，但不再依赖「两个变量同时翻转恰好抵消」。拆成两个 token 而不是一个，是因为金盏花这类亮色系填充在深色主题下配白字只有 1.25:1，必须深字。
+- 修复禁用态借用品牌色浅阶当文字色导致「看不出是禁用、像坏掉」的问题：`TtButton` 实心主 / 危险态禁用时的浅蓝字压在 `--tt-color-primary-3` 浅蓝底上只有 1.88:1（浅色主题 1.50:1）；`TtCheckbox` 禁用选中的勾色同因，浅色主题是白勾压 `#add8ff`。现在统一走禁用语义的 `--tt-bg-disabled` + `--tt-text-disabled`（深色 3.20:1 / 浅色 1.95:1），`TtPopconfirm` 的确认按钮同步，`TtButton` 的默认 / `plain-danger` 变体也不再拿 `--tt-color-primary-3` / `--tt-color-red-3` 当禁用文字色。
+- 修复深色主题下压在深色遮罩上的文字不可见的问题：`TtImage` 查看器按钮（`--tt-overlay-color` 底 + `--tt-bg-white` 图标，深色主题下对比度约 1.15:1）与 `TtUpload` 列表操作图标（`--tt-overlay-black` 底）改用不随主题变化的 `--tt-color-absolute-white`。
+- 修复 `TtSwitch` 滑块圆点内的图标在浅色主题下不可见的问题：圆点底色由 Element Plus 固定为白色，原先覆盖的 `color: var(--tt-bg-white)` 让图标在浅色主题下也是白色（白图标 + 白圆点），深色主题下反而正常。现移除该覆盖，交回 Element Plus 的圆点图标色（`--el-switch-off-color` / `-on-color`，即轨道色）。
+- 修正 `TtColor` 气泡文字色的语义：原先写 `--tt-bg-white`，在深色主题下是因为气泡底色 `--tt-color-grey-8` 同时翻成白色才碰巧可读，现改读 `--tt-text-on-tint`，取值不变但不再依赖双向翻转。
+- 新增 `theme.spec.ts` 的填充对比度契约：断言实心标签色在两个主题下恒为白、深色实心底对白字 ≥ 4.5:1、深色 hover / active 不掉出 AA、浅色调填充文字在深浅两套主题下分别 ≥ 4.5:1 / 3:1；并逐个断言上述组件的填充文字 token 与禁用态 token 用法，防止再退回借用面色。
+- 新增全量色板 token：对齐 tt-design 的 `color-palette.js`，补齐 14 个色系 × 10 阶（`--tt-color-red-*` 至 `--tt-color-rose-pink-*`，共 140 个变量），此前组件库只有极客蓝 1–7 阶和薄暮红的 6 阶。色板数据以 Sass map 登记在 `src/styles/tokens.scss` 的 `$tt-palette`，浅色主题直接输出色板值，深色主题由 `tt-dark-step()` 推导，所以新增色系只需登记一次、light / dark / system 三个主题块同时生效。
+- 主色阶改为当前主题色系的别名：`--tt-color-primary-1` 至 `-7` 现在指向 `--tt-color-geek-blue-1` 至 `-7`（换主题色只改 `$tt-primary-family` 一行）。默认值不变，宿主既可以覆盖具体色系变量、也可以继续覆盖 `--tt-color-primary-*`，两条路径都会联动 TT 组件与 Element Plus 桥接变量；组件样式无需改动。
+- 新增换色系的公共 API：`applyColorFamily(family)` 从 `style.css` 已声明的 `--tt-color-<family>-N` 读出色阶，写成目标节点上的 `--tt-color-primary-1…7` 内联变量；`resetColorFamily()` 清除覆盖，`TT_COLOR_FAMILIES` / `TTColorFamily` 给出清单与类型，`DEFAULT_COLOR_FAMILY` 是回落值。宿主此前要逐条覆盖 7 个色阶，现在 `applyColorFamily('red')` 一行即可，且 hover / active 的明暗方向、shadow 透明度仍由库内规则决定，不会像手写覆盖那样把深浅两套色阶一起压平。色系名未知、或 `style.css` 未加载（读不到色板）时不写半套变量，而是清掉覆盖回落默认色系。实现上对齐参考项目 tt-design 的 `applyTheme(themeName)`，区别是那边 14 套色阶预生成在 JS 里，这里仍以 CSS 变量为唯一事实来源。
+- 深色主题的色板改为推导值，不再逐族手写：保留色相，在 HSL 空间按固定明度阶梯重算（1–4 阶 12% / 18% / 28% / 43%，5–10 阶 58% / 68% / 76% / 84% / 90% / 96%），其中 1–4 阶作为深色容器面另外把饱和度压到浅色板的 60%。默认极客蓝的 1 / 2 / 3 / 4 / 6 阶与推导前几乎一致（如 6 阶 `#5ca5ff` → `#5ca0ff`），5 阶与 7 阶按阶梯重新取值（`#5ca5ff` → `#2989ff`、`#85c0ff` → `#95b7ef`）；薄暮红等其它色系此前没有深色值，现在按同一规则推导。`--tt-color-grey-*` 深色下仍是「面」的层级，不参与推导。
+- 主色派生值改为引用当前生效的主色，不再在编译期写死默认色系：深色主题的 `--tt-focus-ring` 由 `color-mix(in srgb, var(--tt-color-primary) 32%, transparent)` 推导（此前硬编码 `rgb(92 165 255 / 32%)`），`--tt-color-primary-shadow` 同样改为 `color-mix()` 表达式（浅色 24% / 深色 28%）。两者默认观感与改动前逐项一致，但宿主换色系时会自动跟随，不必手工同步；作为副产物，Sass 里的 `tt-alpha()` 与 `$tt-primary-base` 已无引用，一并移除。
+- 修复 `TtChart` 图表主题色值与色板不一致的问题：`themeColors` 此前是 7 组手写近似色（明青 `#13c2c2`、霓虹蓝 `#1677ff`、酱紫 `#9254de`、日暮橙 `#ff7a45` 等都不在 TT 色板内），现在统一取色板 6 阶——主题色系打头、其余按固定顺序补足 6 色，色值只由色板决定。`geekBlue` 之外的图表配色会因此变化。
+- 主题契约测试从「读 `tokens.scss` 源码文本」改为「编译 `tokens.scss` 后断言 CSS 产物」，因为 token 现在由 mixin 生成、源码里不再逐条出现字面量；同时新增色板完整性（14 系 × 10 阶在 light / dark 均存在）、深色推导、主色别名、system 与 dark 一致四组断言。
+- `.storybook/theme.ts` 与色板对齐：主题切换器从 7 个色系补到 14 个（新增日暮橙、金盏花、日出、青柠、极光绿、天际蓝、脉冲粉、蔷薇粉），色系清单与默认值改为从库内 `TT_COLOR_FAMILIES` / `DEFAULT_COLOR_FAMILY` 派生，切换行为改调库内 `applyColorFamily`——Storybook 不再维护色板副本，也不再自读自写色阶。中文名用 `satisfies Record<TTColorFamily, string>` 约束，库新增色系而这里漏配会直接构成类型错误。主题名同步改用 CSS 变量族名：`dust-red` → `red`、`sunset-orange` → `orange`、`golden-purple` → `purple`。
+- Storybook 主题切换收敛为「只注入色阶」：不再自己维护 `--tt-color-primary` / hover / active / shadow 与 25 个 `--el-*` 桥接的内联覆盖，只把所选色系的 1–7 阶写到 `--tt-color-primary-1…7`，库内别名负责其余推导。这去掉了两类与库内脱节的取值——`--el-color-primary-light-1 / 2 / 4 / 6`（Element Plus 自身从未定义或消费，属死变量，已随本次收敛删除）与写死 24% 透明度的 `--tt-color-primary-shadow`；同时修正切换色系后 hover / active 仍按浅色方向取值的问题（现由库内明暗规则决定）。`mixWithWhite()` / `toRgba()` 及 `managedThemeVariables` 随之移除。
+- 新增 `tests/storybook/theme.spec.ts`：断言切换器清单与 `$tt-palette` 的 14 个色系逐项一致、每个色系都有唯一中文名、默认主题与 `$tt-primary-family` 一致（色阶注入行为改由库内契约测试覆盖）。
+- `tests/components/theme.spec.ts` 补充 `applyColorFamily` 的契约断言：色系名归一化、只写 7 个色阶且不写任何派生 token（`--tt-color-primary` / hover / active / shadow / `--el-*`）、色板读不到时回落到默认色系、`resetColorFamily` 清空内联覆盖，以及导出清单与编译产物里的 14 个色系一致；`public-api.spec.ts` 同步断言新 API 已从根入口导出。
+- 文档更新：`docs/theme.md` 修正「主色继承顺序」一节与实现相反的描述（实际是 `--el-color-primary: var(--tt-color-primary)`），补充「全量色板」色系清单与「深色主题的色板推导」规则；`README.md` 同步替换掉遗留的 `--micro-base-* → --micro-app-* → --el-*` 微前端继承链说明。
+- 修复 `TtDrawer` 关闭按钮内的图标不居中、贴在 32px 盒子左上角的问题。Element Plus 只给 `.el-drawer__close-btn` 声明了 `display: inline-flex`，主轴与交叉轴对齐仍是默认的 `flex-start`，而组件库只补了 `width` / `height`，于是 20px 的图标被顶到盒子左上；同库的 `TtDialog`（`.el-dialog__headerbtn`）从一开始就写全了 `display` / `align-items` / `justify-content`，两个浮层组件的关闭按钮因此长得不一样。现补齐这三条声明，与 Dialog 的关闭按钮对齐方式一致，尺寸、圆角、颜色、过渡取值都不变；`tests/components/drawer.spec.ts` 同步新增该规则的契约断言，防止再退回只写尺寸。
+
+## 0.1.3
+
+> **从未发布**：编号已归档，但当时 `latest` 停在 `0.1.1`，本节内容随 `0.1.4` 一起上线。编号不得复用。
+
+- 补齐 `TtTag` 内容区的截断能力：`.el-tag__content` 此前只有 `min-width: 0`（让 flex 子项**可**收缩），缺不可继承的 `overflow: hidden`，宿主给标签设 `max-width` 做省略时会看到超长内容撑破标签，只能在自己的样式里 `:deep(.el-tag__content)` 再补一次。现已补上 `overflow: hidden` + `text-overflow: ellipsis`；未设宽度约束时两者无副作用。
+- 修复 `TtCheckbox` 在无插槽内容时比方框宽 8px 的问题：Element Plus 无条件渲染 `.el-checkbox__label`，无插槽时它是一个空元素，而组件库里 `.el-checkbox__label` 的 `padding-left: 8px` 照旧生效，控件元素盒因此比方框宽 8px（实测 24px 方框 → 32px 盒子）。宿主把它放在固定宽度的列里居中时，多出来的 8px 会把方框挤偏最多 4px，只能反向补偿宽度。现改为内边距只在标签**有内容**时给（`:not(:empty)`），既保住「图标与文字间距」的语义，无插槽时也不再占位。
+- 新增 `TtTag` 的圆角与横向内边距变量 `--tt-tag-radius`（默认 `var(--tt-radius-base)`）与 `--tt-tag-padding-x`（默认 6px），默认值与改动前逐项一致。此前两者写死在基础规则里，同一标签做短标签时是方角小圆角、做列表里的状态 / 优先级标识时是药丸形且横向内边距更宽，宿主只能再叠一层选择器去覆盖库内规则；现与 `--tt-tag-height` / `--tt-tag-font-size` / `--tt-tag-line-height` 采用同一做法。`el-tag--small` / `el-tag--large` 两档预设仍各自持有自己的几何，不随这两个变量变化。
+- 新增 `TtMenu` 的图标间距变量 `--tt-menu-item-icon-gap`（默认 `0px`，与改动前一致）。Element Plus 只给带 `el-icon` 类的子元素留间距，调用方用裸 `<svg>` 或 CSS mask 的 `<span>` 承载图标时拿不到任何间距，图标会紧贴文字（设置页二级导航实测间距为 0，而设计系统登记的是 10px）。样式落在菜单行上：行本身是 flex，用 `gap` 表达，不关心图标是第几个子节点、也没有类名约定负担；变量本身声明在**菜单根元素**上，与 `--tt-menu-item-height` / `--tt-menu-item-radius` 同一位置，宿主在菜单根节点赋值即可生效。
+- 新增 `TtPopover` 的尺寸盒与内边距变量 `--tt-popover-min-width` / `--tt-popover-max-width`（默认 242px）/ `--tt-popover-padding`（默认 16px），默认值与改动前逐项一致。此前 `min-width` 与 `max-width` 写死在 242px，宿主要承载更宽的面板（如两列筛选面板 340px）时，这两个硬上限会连同 Element Plus 写下的 `width="auto"` 一起把浮层钉回 242px，只能再叠一层提升特异性的选择器去压；现与 `TtCard` 的内边距变量、`TtTag` / `TtTable` 的几何变量采用同一做法——可变量化的几何走变量，宿主持有尺寸盒。`tt-popover-long-text` 变体同步改为赋值变量，两条路径不再各写一份尺寸。
+- 新增 `TtPopover` 几何变量的回归测试：`popover.spec.ts` 覆盖三个变量的默认值、每处消费点确实读变量，并断言样式里不再残留属性位的裸值 242px。
+- 新增 `TtCheckbox` 的几何变量 `--tt-checkbox-size`（方框，默认 16px）与 `--tt-checkbox-height`（行高，默认 32px），默认值与改动前逐项一致。此前两者的尺寸写死在组件内部规则里，列表行内悬浮的选择框这类需要更大热区（24px）的场景，宿主只能覆盖 `.el-checkbox__inner` 这类内部结构；现与 `TtTag` 的 `--tt-tag-height`、`TtTree` 的 `--tt-tree-node-height`、`TtMenu` 的 `--tt-menu-item-height`、`TtTable` 的几何变量同一做法。勾（`::after`）的宽高与方框圆角改为按 `--tt-checkbox-size` 等比表达（16px 时精确等于原 4×8 与 3px），放大方框时勾的形状不变，宿主不需要单独赋值。
+- 新增 `TtCheckbox` 几何变量的回归测试：`checkbox.spec.ts` 覆盖两个变量的默认值、每处消费点确实读变量，以及勾与圆角按比例表达。
+- 新增 `TtTable` 的几何与排版变量 `--tt-table-header-height`（默认 32px）、`--tt-table-row-height`（默认 40px）、`--tt-table-cell-padding-x`（默认 14px）、`--tt-table-font-size`（默认 14px）、`--tt-table-line-height`（默认 22px），默认值与改动前逐项一致。此前表头高、数据行高、单元格横向内边距、字号与行高都写死在组件内部规则里，宿主做紧凑密度列表（表头 32px、行 40px、单元格横向 12px、字号 12/18）只能写 `(0,4,x)` 选择器去压 `.el-table__header th.el-table__cell` 这类内部结构，组件一改结构就会失配；现与 `TtTag` 的 `--tt-tag-height`、`TtTree` 的 `--tt-tree-node-height`、`TtMenu` 的 `--tt-menu-item-height`、`TtCard` 的内边距变量采用同一做法——可变量化的几何走变量，宿主赋值即可。
+- 新增 `TtTable` 的表头字重变量 `--tt-table-header-font-weight`（默认 400，与改动前一致）与末行分割线变量 `--tt-table-last-row-border-color`（默认 `var(--tt-border-color-light)`，与其它行同色）。表头字重此前写死，宿主做「表头 600」的列表页时无法通过变量表达；末行分割线此前无法去除，而表格外层通常还有一圈卡片描边，两道线在末行重叠。末行用**颜色**而不是开关表达：CSS 没有条件分支，而 Element Plus 会给每一行都画 `border-bottom`，宿主设成 `transparent` 即可去掉。两项默认值均保持改动前的观感。
+- 新增 `TtTable` 几何变量的回归测试：`table.spec.ts` 覆盖七个变量的默认值、每处消费点确实读变量，并断言样式里不再残留写死的 `font-size: 14px` / `padding: 0 14px` / `line-height: 22px` / 属性位的 `font-weight: 400`。
+- 新增 `TtCard` 的 `interactive` 属性，用于整卡可点的场景（导航入口、选择项）。此前调用方只能用原生 `<button>` 包一层卡片内容，卡片外观要自己重画、元素语义也从「卡片」变成「按钮」；现在开启 `interactive` 后组件补上 `role="button"` 与 `tabindex="0"`，把 `Enter` / `Space` 翻译成点击（`<div>` 根节点不会被浏览器自动转换这两个按键），并给出指针手势、hover 底色与 `--tt-focus-ring` 焦点环。默认关闭，行为与改动前一致。
+- 新增 `TtCard` 可点击形态的回归测试：`card.spec.ts` 覆盖 `interactive` 的类名与按钮语义、回车/空格触发点击、其它按键不触发，以及默认关闭时不含按钮语义。
+- 新增 `--tt-radius-xl`（12px），圆角阶梯扩展为 4 / 8 / 12 / 16：此前只有 4（base）、8（lg）、16（round）三档，宿主需要的弹窗 12px 圆角没有 token 落点，只能用页面私有值。`TtDialog`、`TtFloatButton`、`TtFilePreview` 中硬编码的 `12px` 已改为消费该 token。
+- 新增控件高度档 `--tt-control-height`（32px）、`--tt-control-height-compact`（28px）、`--tt-control-height-sm`（24px）、`--tt-control-height-lg`（40px），并让 Button、Input、Select、InputNumber、DatePicker、TimePicker、Cascader、TreeSelect 的高度改由 `--tt-control-height` 驱动。
+- 支持紧凑密度档：容器或页面根节点把 `--tt-control-height` 指向 `--tt-control-height-compact`，档内上述控件统一收敛到 28px。此前库内没有 28px 档，宿主只能写 `(0,4,0)` 级别的选择器对抗库内基础规则（如 `.tc-management-toolbar__filters .tc-management-select.tt-select`），现在只需切换一个变量。Switch、Checkbox、Radio 的尺寸属点选热区，不随密度档变化。
+- 新增 `theme.spec.ts` 契约用例：断言 4 / 8 / 12 / 16 圆角阶梯、四档控件高度，以及上述组件确实消费 `--tt-control-height`、三个浮层面板确实消费 `--tt-radius-xl`，防止几何值再次退化为硬编码。
+- 同步 `docs/theme.md`：圆角与排版表补入 `--tt-radius-xl` 与四档控件高度，并说明紧凑档的切换方式与参与组件范围。
+- 新增 `TtCard` 的 `--tt-card-body-padding`（默认 `0 20px 20px`）、`--tt-card-footer-padding`（默认 `12px 20px`）与 `--tt-card-border-color`（默认 `var(--tt-border-color-light)`）三个变量，并由它们驱动 `.el-card__body` / `.el-card__footer` 的内边距与卡片外边界色。此前卡片内边距与外边界色写死在组件内部规则里，宿主按上下文调整（如紧凑列表里的卡片）只能再叠一层选择器去覆盖库内规则；现与 `TtTag` 的 `--tt-tag-height`、`TtTree` 的 `--tt-tree-node-height`、`TtMenu` 的 `--tt-menu-item-height` 采用同一做法——可变量化的几何与边界色走变量，默认值与改动前逐项一致。
+- 新增 `TtDialog` 的头部内边距变量 `--tt-dialog-header-padding`（默认 `17px 56px 17px 20px`，与改动前的字面值一致），头部内边距改由它驱动。此前内边距写死在 `.el-dialog__header` 内部规则里，宿主用 `#header` 插槽放自定义头部（如「56px 头像 + 标题 + 操作按钮 + 右上关闭」这类比默认标题行更高的头部，设计要求 24px 24px 20px）时，只能再叠一层选择器去覆盖库内规则；现与 `TtCard` 的 `--tt-card-body-padding`、`TtTag` 的 `--tt-tag-height` 采用同一做法——可变量化的几何走变量，默认值逐项不变。
+- 按发布约定同步版本引用：`package.json`、`README.md`、`plan.md` 与 Storybook 示例（`ActivityFeed.stories.ts`、`Descriptions.stories.ts`）中的当前版本均由 `0.1.2` 更新为 `0.1.3`，`Unreleased` 内容归档到本版本。
+
+## 0.1.2
+
+> **从未发布**：编号已归档，但当时 `latest` 停在 `0.1.1`，本节内容随 `0.1.4` 一起上线。编号不得复用。
+
+- 新增 `TtTag` 的几何变量 `--tt-tag-height` / `--tt-tag-font-size` / `--tt-tag-line-height`（默认值与既有 `size` 预设一致），并让 `el-tag--small` / `el-tag--large` 两档也以变量表达。此前三档高度、字号与行高写死，而设计系统登记的默认档短标签是 26px / 14px，库内只提供 24 / 20 / 28 三档预设，宿主只能再叠一层选择器去覆盖库内规则；现与 `TtTree` 的 `--tt-tree-node-height`、`TtMenu` 的 `--tt-menu-item-height` 采用同一做法——可变量化的几何走变量，默认值不变。
+- 新增 `TtTag` 的几何变量回归测试：`tag.spec.ts` 覆盖基础规则以变量驱动高度/字号/行高，以及两档预设的变量取值与改动前一致。
+- 修复 `TtMenu` 垂直模式下条目既不可键盘到达、也没有可见焦点的问题：Element Plus 的键盘支持只在 `horizontal` 模式下装配（其 `menu.mjs` 里 `if (props.mode === "horizontal") new Menu(...)`），垂直菜单的项因此一直停在 `tabindex="-1"`，方向键与回车也完全无响应；同时它对 `.el-menu-item:focus` 写了 `outline: none`，而「焦点换底色」规则只写给 horizontal，键盘用户既走不进去也看不出位置。现由 `TtMenuItem` 默认 `tabindex="0"`（调用方仍可覆盖），`TtMenu` 在垂直模式下补上方向键循环、`Home` / `End` 跳首尾与回车/空格激活，并在 `style.scss` 按库内 `TtMenuPanelItem` 的约定给出底色 + `--tt-focus-ring` 焦点环。水平模式仍完全交给 Element Plus，不重复接管。此项同时修复了 `TtMenu` 作为常驻侧边导航使用时的可访问性缺陷。
+- 修复 `TtMenu` 的行内边距无法被宿主演制的问题：垂直模式下 Element Plus 用 `calc(base + level × level-padding)` 计算左内边距，本文件那条 `padding: 0 8px` 对它其实是**死声明**（Element Plus 的规则权重 (0,4,0) 高于此处的 (0,3,0)），实测始终取默认的 20px，与声明的 8px 差 12px；垂直分支里另有一条权重 (0,6,0) 的 `padding-left: 8px` 硬编码，会压过宿主写在行上的 `padding`，导致宿主做收起态（图标居中、左右内边距归零）时左侧仍留 8px、右侧被置零，图标偏移约 4px。现统一改为赋值 Element Plus 的源变量 `--el-menu-base-level-padding` / `--el-menu-level-padding`（默认 20/20 → 8/8），并把垂直分支的 `padding-left` 改为读该变量，声明的 8px 才真正生效、宿主的覆盖也才生效；层级缩进仍按每级 8px 递增。
+- 新增 `TtMenu` 的回归测试：`menu.spec.ts` 覆盖垂直菜单每项可 Tab 到达、调用方可覆盖 `tabindex`、方向键循环、`Home` / `End` 跳转、回车与空格激活（`<li>` 不会自动把按键转成点击）、跳过禁用项、水平模式不被本组件接管、分组内的项同样参与导航，以及焦点环与内边距变量的样式契约。
+- 修复 `TtDialog` 的 footer 与正文之间没有分界的问题：`footer` 原先 `border-top: 0`，正文最后一个字段与底部操作贴在一起，无法分组成两块。现改为 1px `--tt-border-color-light` 上分割线，并把内边距收敛为上下等值的 `16px 20px`（原 `9px 20px 20px` 上下不等，按钮偏向一侧）；最小高度同步由 62px 调至 64px。
+- 修复 `TtInput` 在弹窗、抽屉等浮层内比设计基线高 2px 的问题：Element Plus 从不给 `.el-input__wrapper` 声明 `box-sizing`，依赖宿主全局 `* { box-sizing: border-box }`；而浮层 Teleport 到 `body`，常落在宿主重置作用域之外，`box-sizing` 回落 `content-box` 后被自身 `padding: 1px` 顶成 34px（`.eg-app-shell` 作用域内的输入框是 32px，同一页面两种高度）。现在组件自己声明 `box-sizing: border-box`，不依赖宿主重置。
+- 修复 `TtInput` 把未传的属性以显式 `false` 透传给 Element Plus 的问题：本组件的 props 是「Element Plus 全部 Input 属性的可选副本」，仅为类型服务，而 Vue 解析不了从 element-plus 导入的类型，会把这一批属性一律推断成 `Boolean`，于是调用方没写的项在运行时也是 `false` 并覆盖 Element Plus 默认值（`inputStyle` 因此报 `Expected Object | Array | String, got Boolean`，`readonly`、`clearable` 等也被无意义地改写）。现在只透传调用方真正写过的属性，其余交给 Element Plus 用自己的默认值。
+- 新增 `TtTree` 的行高变量 `--tt-tree-node-height`（默认 40px），并由它驱动 `.el-tree-node__content` 与展开图标的高度、同步映射 Element Plus 的 `--el-tree-node-content-height`。此前行高写死 40px，宿主做侧栏这类紧凑树（32px）只能提升特异性去覆盖库内规则；现与 `TtMenuPanel.maxHeight` 采用同一做法——可变量化的几何走变量或属性，默认值不变。
+- 新增 `TtTree` 的回归测试：`tree.spec.ts` 覆盖数据与默认插槽透传、`tt-tree` 类名与调用方属性透传，以及行高变量的默认值与三处消费点。
+- 调整 `TtMenuPanel` / `TtMenuPanelItem` 的默认视觉，向库内既有弹层对齐。面板此前是全库唯一带 1px 描边的弹层，圆角用 `--tt-radius-lg`（8px）而非弹层统一的 `--tt-radius-base`（4px）、内边距 5px 而非 8px，与 `TtDropdown` / `TtSelect` / `TtCascader` 的 popper 并排看明显不同源；现已去掉描边，圆角与内边距改为与上述弹层一致。菜单行由 30px 提到 32px、内边距由 `4px 7px`（全库唯一的 7px）改为 `5px 8px` 并补 8px 行距，对齐 `TtSelect` 下拉的选项行——两者同为「紧贴触发器的选项列表」，此前密度档与库内任何组件都对不上；`size="rich"` 的 42px 同步提到 44px，保持两档差值不变。面板标题行外边距随之对齐到新的行内边距。
+- 新增 `TtMenuPanelItem` 的 `iconSurface` 属性：为图标列加浅灰底色方块，默认 `false`。此前图标格无条件带 `--tt-bg-subtle` 底色，是库内唯一给菜单图标画底块的组件，与 `TtMenu` / `TtDropdown` 的裸图标并列时像另一套设计；现在默认恢复裸图标，需要「图标即按钮」的观感时再打开。同时把图标格由 20px 放大到 24px、图标由 12px 放大到 14px，四边内间距从 4px 放宽到 5px；图标列几何在两种形态下保持不变，文字起始位置不漂移。
+- 同步更新 `TtMenuPanel` 的 Storybook 示例：新增「图标底色」一组对照展示 `iconSurface` 的两种形态，并修正 `head` / `foot` 示例里与新行内边距不一致的取值。
+- 新增上述改动的回归测试：`menu-panel.spec.ts` 覆盖 `iconSurface` 修饰类按开关生成、且两种形态下图标格都存在（底色不参与布局）。
+- 修复 `TtCheckbox` 把 `aria-label` 落在外层 `<label>`、导致无障碍名称丢失的问题：外层元素带插槽文案时，其可访问名来自内容，`aria-label` 会被浏览器直接忽略，真正可聚焦的 `<input>` 只剩文案作为名字——调用方显式传入的「为项目选择…」这类名字等于没写。现在把可访问名下沉到原生 `<input>`，外层不再重复；同时新增 `change` 事件（回传最新选中值），此前包装层未转发 Element Plus 的 `change`，调用方只能靠 `v-model` 自行比对旧值，拿不到「用户此刻改成了什么」。
+- 修复 `TtButton` 内联图标不可见、且与文字贴在一起的问题：`@element-plus/icons-vue` 渲染出的是只带 `viewBox`、不含宽高的裸 `<svg>`，既不满足 Element Plus「图标需带 `el-icon` 类」的间距规则（`.el-button [class*=el-icon]+span`），也不会自己撑开尺寸，因此图标会塌成 0 宽、文字紧贴其后。现在按钮内置 `.tt-button__icon` / `.tt-button__label` / `.tt-button__suffix` 三个槽盒子，svg 与图片统一按 14px 盒子渲染，按钮与文案槽各给 6px 间距；并新增 `icon`（与 `prefix` 同义）与 `suffix` 具名插槽，默认插槽可继续直接写「图标 + 文案」。
+- 新增 `TtButton` 的 `icon` / `prefix` / `suffix` 插槽：此前仅有默认插槽，调用方把图标写进默认插槽时既拿不到尺寸兜底也拿不到间距。`icon` 与 `prefix` 互为别名（前者优先），静态图标建议用 `icon` 以获得 `aria-hidden` 隔离；`suffix` 渲染在文案之后。
+- 新增 `TtInput` 的 `invalid` 属性：置为 `true` 时在常态、悬浮和聚焦三种状态下都给出错误描边。Element Plus 只在 `.el-form-item.is-error` 作用域内表达校验失败，调用方把输入框放在普通 `<label>` 里（没有 `el-form` 容器）时拿不到任何错误态。属性只参与类名生成，不落到原生元素；默认 `false`，原有形态不变。
+- 修复 `TtInput` 的前后缀插槽内图标塌成 0×0、把整个前缀盒挤没的问题：Element Plus 只给带 `el-icon` 类的图标定尺寸，`@element-plus/icons-vue` 直接写进 `#prefix` / `#suffix` 的裸 `<svg>` 不满足该条件，搜索框的放大镜等图标会完全不可见。现已对插槽内的直接子级 svg 兜底 14px，Element Plus 自身包装的 `el-icon` 图标不受影响。
+- 修复 `TtButton` 的危险语义与非实心形态互相冲突的问题：实心危险态的规则未排除 `ghost` / `neutral`，导致 `type="danger" ghost`（幽灵删除按钮）被渲染成实心红、`type="danger" neutral` 失去白面与描边，形态名存实亡。现在实心态显式排除这两个形态，并分别补上「透明底 + 危险色文字 + 浅红 hover」与「白面 + 控件描边 + 危险色文字 + 浅红 hover」两组声明。
+- 新增 `TtDialog` 的 `description` 属性：在标题下方渲染一行补充说明（16/24 标题 + 14px 二级正文色）。提供 `description` 或 `header` 插槽时改由本组件渲染标题行，并且不再把 `title` 交给 Element Plus，避免出现两个标题；只传 `title` 时仍走 Element Plus 原路径，原有形态不变。
+- 新增 `TtDialog` 的 `busy` 属性：置为 `true` 时默认屏蔽遮罩点击与 `Esc` 两条关闭路径，避免提交请求进行中弹窗被误关。调用方显式传入 `closeOnClickModal` / `closeOnPressEscape` 时仍以调用方为准；默认 `false`，原有形态不变。
+- 修复 `TtTreeSelect` 丢弃默认插槽、调用方无法自定义树节点内容的问题：Element Plus 的 `ElTreeSelect` 支持默认插槽（作用域 `{ node, data, store }`），而包装层未透传，业务侧给节点加自定义图标的写法会静默失效。现已按 `TtTree` 的同一方式透传。
+- 修复 `TtSelect` 丢弃调用方插槽的问题：`prefix`、`tag`、`label`、`loading`、`empty` 五个插槽此前未透传，多选标签自定义渲染（如为拥有者追加标记并单独控制单标签可关闭性）与空态/加载态文案替换都无法生效。现已补齐透传，其中 `tag`、`label` 保留 Element Plus 的作用域参数。
+- 新增 `TtMenuPanel` 与 `TtMenuPanelItem`：用于「紧贴触发器弹出的命令式菜单」。面板负责盒子（内边距、描边、圆角、底色、阴影、头/体/脚三段与正文滚动），**定位与宽度留给调用方**，因为各触发器朝向不同、弹窗上下文还需整体翻转；条目支持 `icon`/`trailing` 插槽、`selected` 已选态、`disabled`、`size="rich"` 双行密度档与 `layout="nav"` 导航行。组件库原有的 `TtList` 是展示型列表（无选中态与菜单语义），`TtMenu` 依赖 `ElMenu` 且行高写死，均不适合该场景。
+- 新增 `TtMenuPanel` 的回归测试：`menu-panel.spec.ts` 覆盖头/体/脚按需渲染、返回按钮与可访问名称、`maxHeight` 属性、调用方类名合并、条目的 `role="menuitem"` 与 `aria-current`、密度与布局变体、未提供插槽时不渲染空容器、以及禁用态不派发 `click`。
+- 新增 `TtMenuPanel` 的 Storybook 示例：该组件此前已公开导出并有回归测试，但缺少 `MenuPanel.stories.ts`，是唯一在 Storybook 导航里查不到的组件，预览覆盖留了一处缺口。示例按 `autodocs` 提供 `title`／`back`／`backLabel`／`maxHeight` 控件，并覆盖六组场景——基础图标行与已选态、一级导航行配二级返回标题行、`size="rich"` 双行条目、`layout="inline"` 提及与补全行、已选与禁用态、`head`／`foot` 插槽配 `maxHeight` 的内部滚动。
+- 修复 `scripts/test-package.mjs` 在 Windows + Node 20.12 及以上必然失败的问题：脚本用 `execFileSync` 直接 spawn `npm.cmd`/`npx.cmd`，而 Node 自 CVE-2024-27980 修复起要求经 shell 执行这类文件，否则抛 `EINVAL`。改为在 Windows 下统一以 shell 执行（POSIX 保持直接 spawn），使发布前的 `yarn test:package` 能实际跑通。
+- 新增 `TtButton` 的 `neutral` 属性：呈深色文字 + 控件描边 + 白面，品牌色只在 hover／focus／`selected` 时出现，用于「可切换的选项 / 下拉触发器」这类 chip 控件；默认变体的文字是主色，表达「链接式次要操作」，两者语义不同故并列存在，默认 `false`，原有形态不变。
+- 新增 `TtButton` 的 `ghost` 属性：常态无边框无底色，仅在 hover／focus／按下时出现浅色底，用于工具栏与列表行内的低强调操作；与设计系统 `ghost` 按钮契约一致（不通过 `border-color` 表达状态、不声明 `box-shadow`、`:focus-visible` 保留可见焦点环）。默认 `false`，原有形态不变。
+- 新增 `TtMenuPanelItem` 的 `layout="inline"` 行布局（前缀 | 标签 | 描述占满剩余 | 尾部），用于提及/补全这类「标题与描述同处一行」的条目；并修复无前缀图标时仍预留图标列、把尾部内容挤到中间的问题（新增 `--no-icon` 修饰类）。
+- 新增 `TtButton` 的 `selected` 属性：呈浅蓝底 + 品牌色文字，用于「当前已生效的选项」或「已展开的触发器」，与 `type` 正交；默认 `false`，原有形态不变。
+- 修复 `TtButton` 未剥离自身属性导致透出到原生元素的问题：`neutral`、`ghost`、`selected` 原先随 `$attrs` 落到底层 `ElButton`，再作为未知属性渲染到 `<button>`（产生 `neutral="true"` 等无效属性）。现只参与 TT 类名生成，不再外泄。
+- 新增上述改动的回归测试：`dialog.spec.ts` 覆盖 footer 分割线与等值内边距的样式契约；`input.spec.ts` 覆盖 wrapper 的 `border-box` 声明，以及「只透传调用方真传过的属性、未传项与直接使用 `ElInput` 时的布尔默认值完全一致」。`checkbox.spec.ts` 覆盖 `aria-label` 下沉到原生 `<input>` 且外层不再保留同名属性、未传 `aria-label` 时不写入、`change` 回传最新选中值，以及遮蔽 `aria-label` 后 `class`/`data-*` 等其余属性仍透传到根节点、调用方 `@change` 只触发一次。`button.spec.ts` 覆盖 `selected`／`neutral`／`ghost` 的类名生成、组合用于 chip 控件、三者均不落到原生 `<button>` 且保留 Element Plus 的 `nativeType`，以及 `icon`／`prefix`／`suffix` 槽盒子与 14px 尺寸、6px 间距的样式契约（含无默认插槽时不渲染文案槽）。`input.spec.ts` 覆盖 `invalid` 的类名生成、不透出到原生元素、三种状态都给出错误描边的样式契约，以及前后缀插槽内 svg 的 14px 尺寸兜底。
+- 新增上述改动的回归测试：`dialog.spec.ts` 覆盖 `description` 与标题并排渲染且不产生重复标题、仅传 `title` 时仍走 Element Plus 原路径、`busy` 下屏蔽遮罩与 `Esc` 关闭、以及调用方可显式覆盖 `busy` 的默认值；`tree-select.spec.ts` 覆盖默认插槽按 Element Plus 作用域透传、TT 下拉类名与调用方 `popperClass` 并存、以及未提供默认插槽时正常渲染。
+- 新增 `TtCardSelect` 的 `compact` 属性：收紧项内边距与圆角、网格最小列宽降到 180px，用于横向排列的窄卡片；默认 `false`，原有形态不变。
+- 新增 `TtCardSelect` 的 `selectable` 属性：置为 `false` 时卡片只作为「点击即触发」的动作项，不记忆选中态、不渲染选中标记与 `aria-pressed`，每次点击仅派发 `change`；默认 `true`，原有选择行为不变。
+- 新增上述改动的回归测试：`card-select.spec.ts` 覆盖 `compact` 与 `grid` 的组合类名及默认不启用，以及 `selectable: false` 下的动作组行为（不写选中值、重复点击不累积、无选中标记）。
+- 修复 `theme.spec.ts` 在 Windows 签出（`core.autocrlf=true`）下必然失败的问题：测试用 `\n` 匹配 `tokens.scss` 的多行区块标记，而签出文件是 CRLF，导致「未找到区块」误报。改为读取后归一化行尾，断言内容不变。
+- 按发布约定同步版本引用：`package.json`、`README.md`、`plan.md` 与 Storybook 示例（`ActivityFeed.stories.ts`、`Descriptions.stories.ts`）中的当前版本均由 `0.1.1` 更新为 `0.1.2`，`Unreleased` 内容归档到本版本。
+
+## 0.1.1
+
+- 修复 `TtPopconfirm` 的 `popperClass` 被 Element Plus 覆盖、TT 弹层样式整体失效的问题：`ElPopconfirm` 在 `mergeProps` 中把 `popper-class` 硬编码为 `el-popover`，且该键排在 `$attrs` 之后，TT 传入的 `tt-popconfirm` 无法落到弹层节点，`Popconfirm/style.scss` 全部选择器命中不到。改为经由未被覆盖的 `popper-options` 追加一个 `afterWrite` 阶段的 popper modifier，把 TT 类名直接写入真实 popper 元素；同时新增公开属性 `popperOptions`，使调用方自定义的 popper 配置与 TT 注入项可共存，`popperClass` 亦随之恢复生效。
+- 修复 `TtInput` 未转发 Element Plus `password-icon` 插槽的问题，自定义密码可见性图标不再静默退回默认图标，插槽作用域 `{ visible }` 正常透传。
+- 修复 `TtPagination` 丢弃 default 插槽、导致 `layout="slot"` 渲染空白的问题；新增 `defineExpose({ paginationRef })`，向调用方暴露内部 `ElPagination` 实例。
+- 修复 `TtPopover` 丢弃 default 插槽作用域、导致内容内主动关闭失效的问题，`{ hide }` 恢复透传；未提供 default 插槽时不再阻断 Element Plus `content` 属性的兜底渲染。
+- 修复 `TtSelect` 的 `header` 插槽被内置搜索框独占的问题，父组件传入的 `header` 内容改为与内置搜索框合并渲染，不再被丢弃。
+- 新增上述修复的回归测试：`popconfirm.spec.ts` 覆盖 TT 弹层类名落到真实 popper 元素（断言 `.tt-popconfirm.el-popper.is-light` 锚点可命中）与调用方 `popperOptions.modifiers` 共存；`pagination.spec.ts` 覆盖 `layout="slot"` 的 default 插槽渲染与 `paginationRef` 暴露；`popover.spec.ts` 覆盖 default 插槽 `{ hide }` 作用域与无插槽时的 `content` 属性兜底；`input.spec.ts` 覆盖 `password-icon` 插槽及其 `{ visible }` 作用域；`select.spec.ts` 补充父级 `header` 插槽渲染与内置搜索框共存的用例。
+- 扩充版本同步范围：`CLAUDE.md` 与 `AGENTS.md` 的「版本与发布」约定在 README 与计划文档之外，新增 Storybook 示例（`src/components/**/*.stories.ts`），准备发布时须一并更新其中出现的当前版本号，避免示例展示数据落后于实际版本。
+- 按上述约定同步 Storybook 示例中的当前版本引用：`ActivityFeed.stories.ts` 时间线文案与 `Descriptions.stories.ts` 的「当前版本」「版本」字段展示值均由 `0.1.0` 更新为 `0.1.1`。
 
 ## 0.1.0
 
@@ -59,3 +174,6 @@ All notable changes to this project will be documented in this file.
 
 - Migrated the existing Vue component source into an independently buildable package.
 - Added real JavaScript, declaration, and CSS build outputs.
+
+- 新增 `TtButton` 的「文字形态 + 已选态」组合样式（`.tt-button.tt-button-text.tt-button-selected:not(.is-disabled)`）：纯文字互斥切换（如排序控件「综合 / 最新 / 最热」，设计稿为无底色无描边、选中项深色 600、未选中项灰色 400）此前无法用现有变体表达——`type="text"` 会让三项都是品牌蓝，`selected` 单独的已选态又是浅蓝底 + 品牌色，与设计稿不符。现在该组合取 `--tt-text-title` 文字 + 600 字重 + 透明底/透明描边，hover、focus 与按下都保持同一文字色与透明底（`:focus-visible` 仍保留基础规则的 `--tt-focus-ring` 焦点环，与非选中文字形态一致）。规则只匹配「文字形态 + 已选态」同时成立，`.tt-button.tt-button-selected` 单独出现（含 neutral 等形态）的浅蓝底表现不变。
+- 新增 `TtButton` 的 `muted` 属性（次级文字色，默认 `false`）：纯文字互斥切换（如排序控件的未选中项「最新 / 最热」）此前没有任何落点——文字形态的常态文字色是品牌色（表达「链接式次要操作」），三项并排会有两项是蓝的，无法表达「未选中」。现在 `.tt-button.tt-button-text.tt-button-muted:not(.is-disabled)` 把未选中项落到 `--tt-text-secondary`（hover / focus 回到 `--tt-text-title`），与上一轮 `.tt-button.tt-button-text.tt-button-selected` 的深色 + 600 字重组成完整的一对，宿主不必写任何颜色。本规则只作用于「文字形态 + muted」这一组合：不写 type="text" 时 muted 不改变任何现有外观，`.tt-button.tt-button-selected` 与其它形态的表现不变。

package/README.md

@@ -2,7 +2,7 @@
 
 基于 Vue 3 与 Element Plus 的 TT Design 风格组件库。
 
-> 当前版本为 `0.1.0`。它从原 workspace 的 `tt-design-vue` 迁出，但作为独立项目构建并提供真实的 JavaScript、类型声明和 CSS 产物。
+> 当前版本为 `0.1.4`（下一次发布的版本号，发布即 `npm publish`，不再改版本）。registry 上的最新已发布版本可用 `npm view tt-design-web-vue dist-tags` 查询。本项目从原 workspace 的 `tt-design-vue` 迁出，作为独立项目构建并提供真实的 JavaScript、类型声明和 CSS 产物。
 
 ## 安装
 
@@ -32,9 +32,12 @@ createApp(App)
 主题模式通过 `data-tt-theme` 控制，也可使用公共 API：
 
 ```ts
-import { applyTheme } from 'tt-design-web-vue';
+import { applyColorFamily, applyTheme, resetColorFamily } from 'tt-design-web-vue';
 
 applyTheme('light'); // 'light' | 'dark' | 'system'
+
+applyColorFamily('red'); // 换主题色系，可选值见 TT_COLOR_FAMILIES（14 个）
+resetColorFamily(); // 回到库默认色系
 ```
 
 按需从根入口导入组件：
@@ -68,13 +71,13 @@ import 'tt-design-web-vue/dist/style.css';
 
 ## 主题
 
-组件库通过 `--tt-*` CSS 变量提供主题契约。主色会按以下顺序读取：
+组件库通过 `--tt-*` CSS 变量提供主题契约。主色阶是当前主题色系（默认极客蓝）的别名，色板是唯一事实来源：
 
 ```text
---micro-base-* → --micro-app-* → --el-* → TT 默认值
+--tt-color-geek-blue-1 … 7  →  --tt-color-primary-1 … 7  →  --el-color-primary
 ```
 
-这使独立项目可直接使用默认主题，同时也能在既有微前端宿主中继承主题变量。完整变量列表和覆盖示例见 [主题说明](./docs/theme.md)。
+换主题色只需覆盖对应色板变量，TT 组件与 Element Plus 桥接变量会一起跟随。全量色板（14 个色系 × 10 阶）、深色主题的推导规则和覆盖示例见 [主题说明](./docs/theme.md)。
 
 ## 兼容范围