tt-design-web-vue 0.1.1 → 0.1.5

package/CHANGELOG.md

@@ -2,7 +2,166 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## 0.1.5
+- **`TtAi*` 一族迁到 `src/ai/`**：8 个 AI 会话组件（`AiExecutionFeed` / `AiToolCall` / `AiStatusCode` / `AiFoldText` / `AiResultPanel` / `AiArtifactRow` / `AiTodoProgress` / `AiSubagentLineage`）从 `src/components/` 移到 `src/ai/`，与通用组件分开管理，避免通用组件目录被「只服务 AI 会话信息流、其他页面不消费」的组件淹没。**对消费方无影响**：公开入口仍是 `src/index.ts`，`TtAi*` 的导出名、props、事件、插槽、`tt-*` 类名与全部视觉行为逐项不变；`package.json` 的 `exports` 只暴露包根与 `style.css` / `rich-text.css`，不含内部目录路径，单文件深路径引用本就不在公共契约内。族内样式注册（`src/styles/index.scss`）、定向 Vitest、Storybook story 与文档登记方式一并保持不变；`TtAi*` 之间的相对引用与族契约的路径锚点已同步更新。
+- **破坏性变更与行为变更（`TtAiToolCall` / `TtAiExecutionFeed`，消费方升级前必读）**
+  - **过程行几何 28px → 24px**：`--tt-ai-tool-call-row-height` 默认改为 `var(--tt-control-height-sm)`（24px，复用既有控件高度档，不新增数值）。行结构按 DSH `ToolRow` 重建为 24px 单行：`[16px 行首盒（状态/图标，悬停切箭头）] 6px [title] 8px [2px 分隔点] 8px [summary 占满并单行省略]`。
+  - **移除 `lines?: number`**：明细改「段内滚动」后不再有行数上限概念，保留会造成「接受了但不生效」的静默空转。`TtAiFoldText` 组件本身保留（其折叠能力仍被宿主的思考文本与过程文本使用），移除的只是 `TtAiToolCall` 对它的用法与该入参；折叠与段内滚动**二选一**，不叠加（叠加会形成「折叠里再折叠」——用户先要展开行、再要展开文本，且折叠后的可视线索与段内滚动条重复）。
+  - **移除明细「两个并排卡片」结构**：类 `.tt-ai-tool-call__panes` / `__pane` / `__pane-label` / `__pane-body` 与变量 `--tt-ai-tool-call-pane-gap` / `--tt-ai-tool-call-pane-min-width` / `--tt-ai-tool-call-pane-max-height` 全部删除（此前靠 `repeat(auto-fit)` 栅格排版，`240px` 硬下限在窄容器下会把整行撑出容器）。
+  - **移除 `.tt-ai-tool-call__status` 与 `.tt-ai-tool-call__spacer`**：行尾不再渲染任何状态标记或箭头，状态下沉到行首（原先行尾的可见 `AiStatusCode` 用法与 `size="sm"` 一并移除，行首状态点改用 `marker="dot"`）；摘要占满剩余宽度后不再需要撑开用的 spacer。
+  - **`statusLabel` 语义变更**：此前是**可见**的行尾标签，现改为**视觉隐藏**文本（仍传同一 prop，但不再可见）；依赖可见状态文案的调用方需改走别的行内容。
+  - **状态语义改由「视觉隐藏文本」承载**（不变量 3「状态不靠颜色」）：行首状态点是装饰性的（`aria-hidden`），状态的文字名以 1px 裁剪盒交给辅助技术（**用 `clip` 而非 `display: none`**，后者会把文本移出可访问性树）；文案仍一律由调用方经 `statusLabel` 提供，组件不内置任何状态文案；`TtAiStatusCode` 的标记（状态点或图标）同样一律 `aria-hidden`，文字名由调用方经 `label` 提供，`label` 与 `name` 都为空时组件整体 `aria-hidden`，不会自己编出一句状态文案。
+  - **`TtAiExecutionFeed` 折叠行：成功态不再渲染可见状态标记**（需求人裁决「跟 DSH 一样成功态无状态标记」；DSH 的 `TurnProcessNodeView` 折叠行只有 `label + chevron`，任何状态都不给状态点）：成功态只保留「标题 + 计数摘要 + chevron」；非成功态（进行中 / 失败 / 中断等待 / 未知）仍在行首给状态点、行尾给可见状态名。状态语义仍对辅助技术可读 —— 新增 `__status-text` 视觉隐藏载体，放在按钮**内**使状态名进入该行的可访问名（读屏播报「执行过程 · N 次工具调用 · 已完成」）。
+  - **新增 `summary?: string`**：渲染为 title 之后的「2px 分隔点 + 单行省略文本」，占据行的剩余宽度；**空 summary 连分隔点一起不渲染**（行末不留孤立圆点）。摘要取 `--tt-text-placeholder` 档（H2 裁决：TT 无 tertiary 档，与 DSH caption 同档）。
+  - **行首承担状态**（对齐 DSH `ToolRow.leadingFor()`）：**失败**与**中断等待**显示状态点，其余（含**成功**、进行中、未定）显示节点图标 —— 由此「成功态无可见状态标记」成立：成功行显示的是工具自己的图标，不是状态标记。
+  - **箭头改悬停出现**：收起态在行首盒内同时渲染节点图标与预览箭头，行悬停或行获得键盘焦点时图标淡出、箭头淡入；展开态只显示箭头。两处均带 `prefers-reduced-motion` 兜底。
+  - **与 DSH 的一处有意分歧**：DSH 的行是 `div[role="button"]` + 内嵌 `button.leading`；Vue 侧照抄会形成 **button 套 button 的非法 HTML**。故改为「整行单一原生 `<button>` + 行首为装饰 `<span>`」：点行首即点整行，一次事件、天然不重复触发，并已加用例锁定行内不得出现嵌套 `button` / `[role="button"]`。
+  - **`TtAiToolCall` 明细重构为「一个卡片 + IN/OUT 两段」**（按 DSH `.ioCard` / `.ioSection` / `.ioLabel`）：一个数据面容器（1px 描边 + `--tt-radius-xl` 12px 圆角 + `--tt-bg-subtle` 底，`overflow: hidden`），内部两段各自按 `--tt-ai-tool-call-io-max-height`（默认 150px）**限高并独立纵向滚动**，段间为**全宽分隔线**；段内为「标签列 + 载荷列」网格（`grid-template-columns: max-content 1fr`、`column-gap` 12px、`align-items: baseline`），标签取 `--tt-text-placeholder`（比载荷淡一档，读作标签而非内容）并 `position: sticky; top: 0`，失败调用的输出用 `--tt-color-error`。滚动条做了内缩（`::-webkit-scrollbar-thumb` 透明边框 + `padding-box` 裁剪），滑块不贴圆角卡片边缘。
+  - **窄容器防回归按新结构重验**：防溢出机制由「栅格下限夹取」改为「换行 + 收缩链」（卡片与段均 `min-width: 0`、段 `overflow-x: hidden`、载荷 `white-space: pre-wrap` + `overflow-wrap: anywhere`）。**真实浏览器实测**（Vite SSR 渲染真实组件 DOM + 无头 Chrome 取几何）：120 / 160 / 200 / 240 / 320 / 480 / 640px 七个宽度下，卡片、段与文档横向溢出均为 **0**；段高恒 ≤ 150px；段间分隔线铺满卡片内容宽；长内容确实在段内滚动而非撑开卡片。旧机制相关源码已彻底移除，不留「变量还在但不再生效」的假防线。
+  - 新增明细结构类 `__io-card` / `__io-section` / `__io-label` / `__io-text`（+ 失败态 `__io-text--error`）/ `__io-divider`；新增行首结构类 `__leading` / `__leading-state` / `__sep` / `__summary` / `__status-text`。**未变**：`title` / `icon` / `meta` / `status` / `input` / `output` / `inputLabel` / `outputLabel` / `nested` / `v-model:expanded` 及事件、插槽。
+  - 同步更新：`AiToolCall.stories.ts` 重写为「状态 × 摘要 × 明细有无」矩阵并新增「明细两段」story（长短不一 / 两段都长 / 无空格长串 / 只有 IN 段 / 失败输出）；`AiExecutionFeed.stories.ts` 消费处改用 `summary`；`ai-tool-call.spec.ts` 18 → 32 → **35 条**（H3 结构与无障碍用例、H4 明细结构性用例 12 条，状态与明细用例改写为新机制）；`ai-execution-feed.spec.ts` 调整 2 处原断言（原要求成功态渲染状态点与可见状态名）并新增「成功无标记 / 非成功有标记」对照断言；族契约 `ai-message-flow.spec.ts` 随两轮各更新三处并**保持约束强度**（过程行 28px → 24px；高度 4px 阶梯校验允许**字面 0**（「0 即 0×4」，分隔线改用 `border-top` 表达、盒高归零），并对视觉隐藏块加**精确豁免**并写明理由；状态载体断言改为新机制；`repeat()` 栅格夹取不变量**本体仍全量生效**，仅把锚点从「AiToolCall 含 auto-fit 栅格」改为「AiToolCall 用 `max-content 1fr` 且不含 auto-fit」，避免锚定一个已消失的写法）。
+
+- **新增 AI 会话组件族（`TtAi*`，首期 8 个）**，把会话详情页执行信息流的视觉与交互一次性收进组件库，页面只做组合、不写覆盖样式。此前库内没有 AI 对话专用组件（`ActivityFeed` 只是 `Timeline` 的薄包装、`Message` 是 toast），执行过程的「每类节点一张彩色卡 + 彩色状态圆点」由此无处收敛，只能落在页面样式里。族内分工：`TtAiExecutionFeed` 是过程区的**唯一入口**（32px 整行按钮折叠行 + 24px 单列过程行容器 + 左侧 1px 中性引导线，两层折叠、收起不影响承载位）；`TtAiToolCall` 是过程行（16px 图标盒 + 主文案 + 摘要 + 悬停箭头，行内明细为「一个卡片 + IN/OUT 两段」，`nested` 用左缩进 + 中性左边框表达递归子调用层级）；`TtAiStatusCode` 承担状态多通道；`TtAiFoldText` 统一截断与折叠语；`TtAiResultPanel` 是结果区唯一的数据面容器（r8、无阴影、内部 12px 栅格）；`TtAiArtifactRow` 把产物从大卡片改为行、超过 4 项折叠为「全部 N 个」；`TtAiTodoProgress` 是输入区 dock 的待办/目标变体；`TtAiSubagentLineage` 是会话头部血缘（只身份 + 状态）。
+  - **状态色**按「成功态一律中性色、彩色只用于进行中/失败/中断等待」落定：`--tt-ai-status-code-color` 在 `success` 上是 `--tt-text-secondary`，`pending` / `unknown` 是 `--tt-text-placeholder`，只有 `running` / `failed` / `warning` 分别取 `--tt-color-primary` / `--tt-color-error` / `--tt-text-warning`，且**不使用** `--tt-color-success` 与任何底色 —— 原来的绿色完成点正是被反馈的对象。`status` 是必填项，`TtAiToolCall` 不传 `status` 时**不渲染任何状态标记**：缺失终态不会被默认判成成功（不变量「不编造执行事实」）。
+  - **`TtAiFoldText` 的截断契约**：截断语统一为「… 其余 N 行」，且**展开后能拿到完整内容**（折叠只按换行截取前 N 行，展开后原样给出传入的整段文本，不做二次截断；`text` 与展示上限无关）。与折叠正交的 `truncated` 用于调用方声明「上游数据本身已被截断」——那种情况下库里没有完整内容，组件始终给出标注，不静默丢内容。
+  - **几何落在 4px 阶梯上并全部走变量**：折叠行 `--tt-ai-execution-feed-row-height` 默认 `var(--tt-control-height)`（32px）、过程行 `--tt-ai-tool-call-row-height` 默认 `var(--tt-control-height-sm)`（24px）、产物行 `--tt-ai-artifact-row-height` 默认 `var(--tt-control-height)`（32px）、图标盒 16px（`TtIcon` 的 `size`）、行间距 4px（`--tt-space-1`）、明细区圆角 8px（`--tt-radius-lg`）、状态点圆角 `--tt-radius-round`。样式里没有裸色值、没有 `--dsw-*`、没有 12px 圆角与 0.5px 发丝边（不引入 DSH 视觉语言），字阶与间距全部读 `--tt-*`。
+  - **无障碍**：折叠行与过程行整行是原生 `<button>`（`aria-expanded` + `aria-controls` 指向受控节点，无可展开内容时渲染 `<div>` 而不是 disabled 按钮）；焦点可见（`--tt-focus-ring`）；`TtAiFoldText` / `TtAiArtifactRow` / `TtAiTodoProgress` 的展开控件都带 `aria-expanded` 与辅助技术名称；`reduced-motion` 下关掉 chevron 旋转、状态图标 spin 与进度条过渡。
+  - **承载位与过程行的诚实边界**：`TtAiTodoProgress` 在清单为空时**整块不渲染**（清单为空是「没有投影」，不是「一件都没做」，给出 `0/0` 会被读成后者）；`TtAiToolCall` 在没有明细可展开时渲染 `<div>` 而不是按钮，指针手势与 hover 反馈只挂在 `--expandable` 修饰类下；`TtAiSubagentLineage` 同理只在 `selectable` 打开时才是按钮，默认不给点了没反应的假交互。
+  - **定向测试**：8 个组件用例（`ai-status-code` / `ai-fold-text` / `ai-execution-feed` / `ai-tool-call` / `ai-result-panel` / `ai-artifact-row` / `ai-todo-progress` / `ai-subagent-lineage`）+ 族契约 `ai-message-flow`。族契约直接读组件源码与样式，锁住「只吃 `--tt-*`、无裸色值、无 `--dsw-*`、无 `--tt-color-success`、几何落在折叠行 32px / 过程行 24px / 图标盒 16px、凡有过渡或动画的样式文件都带 `prefers-reduced-motion`」。
+  - 同步 `docs/component-manifest.json` 与 `docs/component-compatibility.md`：8 个 `TtAi*` 组件登记为 Vue-only 默认扩展。**注**：本条原先记的导出计数快照「默认再导出 83 → 91、运行时组件/子组件导出 109 → 117」与当前 manifest 实测值（`vueDefaultReexports: 107`、`vueRuntimeComponentExportCount: 133`）不一致，计数口径待确认后补正，不留下对不上的数字。
+
+- **新增 TtIcon 图标族 `ttIcons/`（取自 DeepSeek Harness，MIT）**：按需求人裁决「图标不自行设计，直接用 DSH 的图标」，用一次性脚本 `scripts/extract-dsh-icons.mjs` 从 DSH 的 `packages/client/ui-primitives/src/icons/index.tsx`（单文件 78 个内联 SVG）静态抽取 **16 个**过程区所需图标，生成到 `src/components/Icon/ttIcons/`，并由 `src/index.ts` 的 `export * from './components/Icon/ttIcons'` 统一导出。每个 SFC 的 props 为 `size`（默认 = 该图标自身绘制尺寸，由源签名解析，不按名字猜）与 `color`（默认 `currentColor`），文件头逐条写明来源、原始导出名、源路径与 MIT 许可（Copyright (c) 2026 DeepSeek）。脚本幂等（重复运行不产生 diff，`--check` 只校验）、失败即停（源里找不到图标、默认尺寸解析不出、子节点含动态 JSX、出现未映射的驼峰属性都显式报错，不静默生成错图标），生成物可逐行 `git diff` 审查。
+  - **`TtIcon` 无需适配即可承载新图标**（已验证，未改 `Icon.vue`）：`TtIcon` 以 `font-size` 承载尺寸，Element Plus 的 `.el-icon svg{width:1em;height:1em}` 覆盖 SVG 自身的 `width`/`height` 呈现属性，因此 `<TtIcon :icon="TtIconSearchOutline16" :size="12" />` 按 12px 渲染，与库内既有 `@element-plus/icons-vue` 图标同一机制；单独使用时回落该图标固有尺寸。宿主前置条件（先加载 `element-plus/dist/index.css`）已写入 `ttIcons/README.md`。
+  - **未自造任何图标**：本轮请求的 16 个图标在 DSH 源中全部命中，无缺口；DSH 其余 62 个候选池与「先查池、查不到再报需求人设计」的规则登记在 `ttIcons/README.md`。
+  - **定向用例 `tests/components/tt-icons.spec.ts`（现 10 条）**：清单与生成物一一对应、每个图标的画布与默认尺寸与 DSH 源**独立解析**结果一致、`size`/`color` 可覆盖、文件头许可齐备、`TtIcon` 组合契约，以及**逐条核对每段路径数据原文存在于 DSH 源**（证明是移植而非自造）。该「移植性」断言做过定点变异验证：改动一条路径数据的单个字符即被捕获并报出具体图标名。
+
+- **新增 `TtSelect` / `TtTreeSelect` 选中标签的限宽与单行截断**：此前只有 `TtTag` 有截断能力，选择器内部自己渲染的 `.el-tag` 没有覆盖 —— 标签高度固定 24px，超长文案（如项目资料名）换行会把标签撑变形，宿主只能写 `:deep(.el-tag){max-width}` 与 `:deep(.el-tag__content){overflow/text-overflow/white-space}` 两处绕过组件库（应用端项目资料选择器即为其一）。现新增 `--tt-select-tag-max-width` 出口（默认 `100%`，即 Element Plus 原值，不赋值时行为与改动前逐项一致），并让 `.el-tag__content` 单行省略。变量用**回退值**写法（`var(--x, 100%)`）而不是在根元素声明默认值，宿主在组件元素或祖先容器任一处赋值都生效；截断无条件生效（固定高度下换行本就是错显示）。同步删除应用端项目资料选择器的两处 `:deep()` 绕过与其重复声明的 `min-height`。
+
+- **新增 `TtTag` 的 `neutral` 属性**，用于**不带状态语义**的类型 / 分类标识（白底 + 控件描边 + 中性文字色），默认关闭、行为与改动前一致。此前这类标签只能写 `effect="plain"`，但 Element Plus 默认给标签加 `.el-tag--primary`，组件库里 `.el-tag--primary.el-tag--plain` 会把描边与文字染成品牌色（实测描边 `--tt-color-primary-3`、文字 `--tt-color-primary`），宿主想拿到「灰框 + 深色字」只能自己写选择器覆盖库内颜色。`neutral` 把任意 `type` 拉回中性格；语义状态标签仍用 `type` + `effect`，两者正交。
+  - 新增 `--tt-tag-plain-color`（默认 `var(--tt-text-secondary)`，与改动前一致）驱动中性描边形态的文字色，`.el-tag--plain` 不再写死次级色；宿主按上下文需要更深字色时下发变量即可，不必覆盖库内规则。
+  - 新增回归测试 `tag.spec.ts`：覆盖 `neutral` 规则必须排在全部 typed plain 规则之后（同特异性后写者胜）、三项中性取值、默认关闭时不加类名，以及 `neutral` 不作为未知属性透出到 DOM。
+
+- 新增 `TtCard` 可点击形态的悬浮底色变量 `--tt-card-interactive-hover-bg`（默认 `var(--tt-color-primary-1)`，取值与改动前逐项一致）：`interactive` 卡片的悬浮底色原先写死为浅蓝填充，这对「多选一」的选择型卡片是对的，但「整卡即入口」的导航卡片（例如应用端自动化列表卡）需要只高亮描边、不要整卡填充。宿主把该变量设成卡片自身底色即可，不必写选择器覆盖 `.tt-card--interactive:hover`。与 `--tt-card-body-padding` 同一做法：默认值声明在组件元素自身，宿主必须在卡片元素上赋值。
+- 新增 `TtCard` 的悬浮阴影变量 `--tt-card-hover-shadow`（默认 `0 4px 12px var(--tt-shadow-color)`，取值与改动前逐项一致）：`shadow="hover"` 原先固定「高亮描边 + y4/blur12 阴影」，对卡片列表偏重；宿主把该变量设成 `none` 即可只保留按钮式的描边高亮。
+- 统一 5 种浮层组件（`TtSelect` / `TtDropdown` / `TtCascader` / `TtMenu` / `TtTreeSelect`）的下拉面板阴影：原来写死的 `0 2px 20px var(--tt-color-grey-2)` 改为登记值 `var(--tt-shadow-md)`。原写法把「颜色」当「阴影色」用——浅色主题下 `--tt-color-grey-2` 是 `#e9ecf2`（近白），20px 模糊会摊成一圈发光；暗色主题下同一变量翻成 `#082337`（近黑），又变成一团黑雾。改用语义阴影 token 后，浅色为 `0 8px 24px rgb(8 17 38 / 12%)`、暗色为 `0 8px 24px rgb(0 0 0 / 36%)`，与 `TtDialog` / `TtDrawer` / `TtDatePicker` 等既有浮层一致；同时也修掉了 `TtDropdown` 与 `TtMenuPanel` 违反各自规范（`surfaceShadow -> --tt-shadow-md`）的问题。面板尺寸、圆角、内边距、选项几何与交互全部不变。
+  - 新增浮层阴影契约用例：锁定这 5 个组件的 popover surface 必须使用 `--tt-shadow-md`；全库任何 `box-shadow` **声明**中不得再出现 `0 2px 20px`（历史取值仅作为说明性注释保留）；并逐条审查所有组件的 `box-shadow` 声明，禁止把 `--tt-color-grey-*` 当阴影色（`inset` 描边不在此列）。
+
+- 修复 `TtForm` / `TtFormItem` 把 Element Plus 布尔属性默认值 `true` 覆盖为 `false` 的问题：两者用 `defineProps<Partial<FormProps | FormItemProps>>()` 声明属性后把整个 `props` 合并回 `$attrs` 再透传，而 Vue 对**声明过但缺席的 Boolean 属性**会解析成 `false`，于是 `showMessage`、`validateOnRuleChange`、`scrollIntoViewOptions` 被显式写成 `false` 传给 Element Plus，压过对方 `default: true` 的默认值。实际后果是**表单校验失败只有红框、没有任何错误文案**（`showMessage` 在 Element Plus 里同时控制字段与表单两级，任一为 `false` 即不渲染 `.el-form-item__error`），宿主只能每个页面显式再传一次 `show-message` 绕过。现按 Element Plus 的默认值补齐三项，未传时与对方一致，显式传 `false` 时仍可关闭。其余 Boolean 属性（`inline`、`hideRequiredAsterisk`、`scrollToError`、`disabled`、`inlineMessage` 等）的 Element Plus 默认值本就是 `false`/`undefined`，未做改动。
+  - 新增回归测试 `form.spec.ts`：覆盖「错误态同时渲染错误文案」「显式 `showMessage=false` 只保留错误态」「未传 `showMessage` 时组件自身与内部 `ElFormItem` / `ElForm` 的取值都是 `true`」，后两条同时锁住「不得再把对方默认值透传成 `false`」这条契约。
+- 修复 `TtButton` **链接形态（`link`）在页面上渲染成浅灰描边白底块**：规范登记 `link`「不承载普通按钮的高度、背景、边框或阴影」，且明确「`text` 与 `link` 形态在组件库内解析为 `min-width: auto`、透明边框与透明底色」，但组件库此前只给 `text` 形态做了透明解析，`link` 只有一条 `text-decoration: underline`。于是基础规则 `.tt-button.el-button` 里**无条件**的 `border-color` / `background-color`（0,3,0）生效，而 Element Plus 自身的 `.el-button.is-link{border-color:transparent;background:transparent}`（0,2,0）权重更低且更早加载，透明解析被静默压掉。现给链接形态补齐透明边框与透明底色，并把 `hover` / `focus` / `active` 三个状态一并清零（基础规则对应分支为 0,4,0，不清零则悬浮 / 聚焦 / 按下时边框与底色会重新出现）；写法与基础规则同为 0,3,0 / 0,4,0 且置于文件后部，靠顺序取胜，不引入提权。文字色不在本层写死，仍由基础规则读 `--el-button-*-text-color`，`.tt-button-danger.tt-button-link` 因此继续得到错误色；`:focus-visible` 的焦点环未被覆盖，键盘焦点环不变。**本缺陷影响所有 `<TtButton link>` 使用点，应用端资料库「会话来源」链接即为其一。**
+- 补齐 `TtButton` **`link` 与 `text` 形态的高度清零**：规范「Link Button 正常态」登记这两个形态「不承载普通按钮的高度」，但基础规则 `.tt-button.el-button` 给所有按钮 `height: var(--tt-control-height)`（32px）且二者都没覆盖。后果是行内文字操作会把所在行撑高：应用端资料库的文档详情元信息、目录树「来源」列的行高被撑到 **32px**，修复后在真实浏览器（构建产物 + headless Chrome）实测 `height` 为 **23.33px**（内容自适应）。现给 `link` 与 `text` 各补 `height: auto; min-height: 0`（`min-height` 用于防止 flex 容器把行内文字操作拉伸回控件高）。修复方式为同权重后写，不引入提权、不涉及公开 API。
+  - `button.spec.ts` 15 → 17 → **18 条**：新增链接形态透明解析的契约断言（含三个状态分支必须存在、且本层不得写死品牌色）与链接形态 DOM 类名断言；并断言 `link` 的**顶层**声明区与 `text` 块内都必须含 `height: auto` 与 `min-height: 0`。两轮新增断言都做过**定点变异**（分别删掉 `link` / `text` 的清零、删掉顶层透明声明）均被捕获，恢复后全绿。透明解析断言还有**两处自身缺陷在验证中被逐次暴露并修正**：①按非贪婪匹配取到的是库内**另一处**同名选择器（盒几何 `padding` 清零），误报「不含透明声明」，改为按内容取到承载透明解析的那一块；②修正后做反向验证**未被捕获** —— 取到的整块包含嵌套的 `hover` / `focus` / `active` 分支，其内的透明声明把顶层缺失掩盖了；改为只截取块内第一个 `&:` 之前的**顶层**声明区再断言，反向验证通过（删掉顶层清零即失败）。这条缺陷本身说明：断言「存在某字符串」不等于断言「该声明在正确层级」。
+- 修复 `TtInput` 字数计数器（`show-word-limit`）在应用端呈蓝色：Element Plus 用 `--el-color-info` 给计数器着色，而宿主主题桥会把该变量映射成品牌色，计数器因此跟着变蓝。计数器属于辅助文字，现由组件库显式声明为占位文字色 `--tt-text-placeholder`，超出上限时切 `--tt-color-error`（不依赖宿主变量，也不会把 Element Plus 的超限红色压掉）。
+- 修复 `TtDatePicker` 日期区间（`daterange` / `datetimerange`）的文字与占位符居中：Element Plus 的 `.el-date-editor .el-range-input { text-align: center }` 会把「开始时间 / 结束时间」顶到控件中间，在筛选工具栏里与相邻的搜索框、下拉选择不是一套观感。现改回左对齐，与 `.el-input__inner` 同一口径。单日期选择、时间选择、面板与浮层几何不变。
+- **`TtAiToolCall` 明细双栏栅格在窄容器下的横向溢出（当时记录；该机制已被上文「一个卡片 + 两段」整体取代）**：栅格原为 `repeat(auto-fit, minmax(var(--tt-ai-tool-call-pane-min-width), 1fr))`，`240px` 是**硬下限**，栅格宽度不足 240px 时轨道压不到下限以下、整行被撑出容器；当时改为 `minmax(min(240px, 100%), 1fr)`（列宽行为在宽容器下与改动前逐项相同）并实测「栅格宽度 120 / 180 / 200 / 239px 时改动前分别溢出 136 / 76 / 56 / 17px，改动后溢出均为 0 且折叠为单列铺满」；注意真实组件里栅格比外层窄 16px（`__detail` 的左内边距），因此**外层** 240px 时改动前仍会溢出 16px，等价点换算到外层是 256px。该 `auto-fit` 栅格随后在明细重构中被整体移除，防溢出改由「换行 + 收缩链」承担（见上文），相关源码、变量与定向用例一并随之改写。
+
+- 规范与元数据：上述各条改动**均未修改设计系统规范数值** —— 图标来源属实现层事实（不新增规范数值）；`TtButton` 的 link/text 合同与 `TtForm` 的默认值行为早已登记在 `docs/design-system` 侧（`button/spec.md:190`、`:228`），本次是组件库实现向规范收敛，不涉及规范改值。`docs/component-manifest.json` 与 `docs/component-compatibility.md` 按新增组件同步登记。
+
+## 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
 
@@ -70,3 +229,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.1`。它从原 workspace 的 `tt-design-vue` 迁出，但作为独立项目构建并提供真实的 JavaScript、类型声明和 CSS 产物。
+> 当前版本为 `0.1.5`（下一次发布的版本号，发布即 `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)。
 
 ## 兼容范围