@teamix-evo/mcp 0.4.2 → 0.4.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/dist/data/adr/0001-three-layer-alignment.md +11 -11
- package/dist/data/adr/0005-ui-no-variant.md +4 -4
- package/dist/data/adr/0006-ui-upgrade-no-baseline.md +6 -6
- package/dist/data/adr/0010-design-default-and-variants.md +1 -1
- package/dist/data/adr/0019-project-upgrade-flow.md +13 -13
- package/dist/data/adr/0021-semantic-color-api-unification.md +28 -0
- package/dist/data/adr/0025-component-props-explicit-declaration.md +14 -13
- package/dist/data/adr/0026-component-level-token-alias.md +22 -22
- package/dist/data/adr/0027-component-visual-token-alignment.md +1 -1
- package/dist/data/adr/0028-ui-component-categorization.md +10 -9
- package/dist/data/adr/0029-input-split-and-prefix-suffix-removal.md +6 -0
- package/dist/data/adr/0033-entry-skill-global-only-scope.md +12 -11
- package/dist/data/adr/0036-ui-v2-shadcn-baseline-rebuild.md +146 -0
- package/dist/data/adr/0037-filter-bar-composable-architecture.md +426 -0
- package/dist/data/adr/0038-create-agents-md-skill-trigger-fallback.md +99 -0
- package/dist/data/adr/0040-component-source-layer-upgrade-flow.md +104 -0
- package/dist/data/adr/README.md +13 -5
- package/package.json +2 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0001. UI 组件研发三层对齐:能力 = shadcn ∪ antd / 理念 = design / 工程 = shadcn
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-05-15
|
|
5
5
|
- **Region**: 0001–0099 工程哲学
|
|
6
6
|
- **Related ADR**: [0005 UI 包不分 variant](0005-ui-no-variant.md) / [0014 ui/biz-ui/templates 三层](0014-ui-biz-ui-templates-tier.md)(本 ADR 在三个粒度上落实)
|
|
@@ -15,21 +15,21 @@ teamix-evo 的 ui 包面对一个上游生态的取舍问题:**shadcn/ui** 与 *
|
|
|
15
15
|
|
|
16
16
|
## Options Considered
|
|
17
17
|
|
|
18
|
-
| 选项
|
|
19
|
-
|
|
|
20
|
-
| 全盘对齐 shadcn
|
|
21
|
-
| 全盘对齐 antd
|
|
22
|
-
| **三层切分对齐(本决策)** | 各取所长,覆盖最广
|
|
18
|
+
| 选项 | 优点 | 缺点 |
|
|
19
|
+
| ------------------------ | ------------------------ | --------------------------------------------------------------- |
|
|
20
|
+
| 全盘对齐 shadcn | 工程一致、生态成熟 | antd 用户惯用的能力(loading / icon prop / shape / block 等)缺失 |
|
|
21
|
+
| 全盘对齐 antd | 能力完整、中后台用户熟悉 | 工程笨重(less + ConfigProvider 运行时主题),与源码注入模式不兼容 |
|
|
22
|
+
| **三层切分对齐(本决策)** | 各取所长,覆盖最广 | 每新增组件需做并集对照表(维护成本) |
|
|
23
23
|
|
|
24
24
|
## Decision
|
|
25
25
|
|
|
26
26
|
UI 组件研发的对齐规则按三层切分,**任何冲突时三层切分优先于其它细则**:
|
|
27
27
|
|
|
28
|
-
| 维度
|
|
29
|
-
|
|
|
30
|
-
| **能力 / 功能**
|
|
31
|
-
| **设计理念**
|
|
32
|
-
| **代码实现 / 部署 / 规范** | **shadcn**
|
|
28
|
+
| 维度 | 对齐对象 | 含义 |
|
|
29
|
+
| -------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| **能力 / 功能** | **shadcn ∪ antd 的合集** | shadcn 缺什么、antd 有什么,补;反之亦然。**做并集,不做交集** |
|
|
31
|
+
| **设计理念** | **`@teamix-evo/design` 的 OpenTrek 体系** | 视觉 / 间距 / 圆角 / 字号 / 阴影 / 动效 / 交互预期 / AI 生成纪律全部走 design,**不参照 antd 视觉,也不参照 shadcn 视觉** |
|
|
32
|
+
| **代码实现 / 部署 / 规范** | **shadcn** | 文件结构、源码注入分发、cva 范式、forwardRef + Slot、TypeScript 写法、命名风格、registryDependencies 思想全部对齐 shadcn,**不照搬 antd 的运行时主题 / less / 样式封装方式** |
|
|
33
33
|
|
|
34
34
|
简记:**能力做并集,理念跟 design,工程跟 shadcn**。
|
|
35
35
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0005. UI 包不分 variant,所有视觉差异通过 design tokens 实现
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-05-14
|
|
5
5
|
- **Region**: 0100–0999 协议与工具
|
|
6
6
|
- **Related ADR**: [0001 三层对齐](0001-three-layer-alignment.md) / [0006 UI 升级机制无 baseline](0006-ui-upgrade-no-baseline.md) / [0010 design 默认+变体](0010-design-default-and-variants.md) / [0014 ui/biz-ui/templates 三层](0014-ui-biz-ui-templates-tier.md)
|
|
@@ -24,9 +24,9 @@
|
|
|
24
24
|
|
|
25
25
|
## Options Considered
|
|
26
26
|
|
|
27
|
-
| 选项
|
|
28
|
-
|
|
|
29
|
-
| UI 按 variant 切分
|
|
27
|
+
| 选项 | 优点 | 缺点 |
|
|
28
|
+
| ------------------------------------ | -------------------------------------------------- | ------------------------------------------------------- |
|
|
29
|
+
| UI 按 variant 切分 | 单 variant 内组件可深度定制视觉 | 维护成本随 variant 数量线性增长;同步问题 |
|
|
30
30
|
| **UI 不分 variant,靠 token(本决策)** | 一套组件吃所有 variant;切换 variant 仅改 design 包 | 强依赖 semantic 命名稳定;variant 间语义集合必须严格对齐 |
|
|
31
31
|
|
|
32
32
|
## Decision
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0006. UI 升级机制不预埋 baseline,依靠 AI + skill 做语义合并
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-05-14
|
|
5
5
|
- **Region**: 0100–0999 协议与工具
|
|
6
6
|
- **Related ADR**: [0003 资源升级三态语义](0003-update-strategy-tri-state.md) / [0005 UI 包不分 variant](0005-ui-no-variant.md) / [0013 Skills source-mirror 模型](0013-skills-source-mirror.md)(skills upgrade 同型动作:同样无 baseline,靠语义合并 + skill 引导)
|
|
@@ -20,11 +20,11 @@ UI 包采用源码注入分发(`teamix-evo ui add <id>` 把组件源码写到业
|
|
|
20
20
|
|
|
21
21
|
## Options Considered
|
|
22
22
|
|
|
23
|
-
| 选项
|
|
24
|
-
|
|
|
25
|
-
| 三方合并 + baseline
|
|
26
|
-
| 完全覆盖
|
|
27
|
-
| **AI 语义合并 + skill 引导(本决策)** | 不污染、简化、AI 兜底语义判断 | 比三方合并精确度差,大改时仍需人介入
|
|
23
|
+
| 选项 | 优点 | 缺点 |
|
|
24
|
+
| ------------------------------------ | ----------------------------- | ---------------------------------------------------------------- |
|
|
25
|
+
| 三方合并 + baseline | 精确 | baseline 必须随 ui add 一起落地到业务项目(污染),且需历史快照管理 |
|
|
26
|
+
| 完全覆盖 | 简单 | 丢用户定制 |
|
|
27
|
+
| **AI 语义合并 + skill 引导(本决策)** | 不污染、简化、AI 兜底语义判断 | 比三方合并精确度差,大改时仍需人介入 |
|
|
28
28
|
|
|
29
29
|
## Decision
|
|
30
30
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0010. `@teamix-evo/design` 采用 `default + variants/<name>/` 模型,工程默认与业务变体彻底解耦
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-05-18
|
|
5
5
|
- **Region**: 0100–0999 协议与工具
|
|
6
6
|
- **Related ADR**: [0001 三层对齐](0001-three-layer-alignment.md) / [0005 UI 不分 variant](0005-ui-no-variant.md) / [0007 治理文档放根](0007-governance-docs-at-root.md) / [0008 ESLint 视觉规则 warn 基线](0008-eslint-visual-rules-warn-baseline.md) / [0014 ui/biz-ui/templates 三层](0014-ui-biz-ui-templates-tier.md)
|
|
@@ -134,19 +134,19 @@ design 包改 token 名(如 `--color-fg-muted` → `--color-text-muted`),`design
|
|
|
134
134
|
|
|
135
135
|
## Implementation status
|
|
136
136
|
|
|
137
|
-
- **本 ADR
|
|
138
|
-
-
|
|
139
|
-
-
|
|
140
|
-
1. lock schema v2 + migration
|
|
141
|
-
2. snapshot 模块 + `restore`
|
|
142
|
-
3. managed-region
|
|
143
|
-
4. `
|
|
144
|
-
5. `teamix-evo init
|
|
145
|
-
6. `teamix-evo update` orchestrator
|
|
146
|
-
7. `
|
|
147
|
-
8. token rename hint 写入 + skill `teamix-evo-upgrade`
|
|
148
|
-
9. W1.4 tokens
|
|
149
|
-
10. 文档站 5 命令导引 +
|
|
137
|
+
- **本 ADR**：方向锁定 + **D1 全量落地完成（v0.8 发版批次）**
|
|
138
|
+
- **当前版本**：v0.8 发版周期
|
|
139
|
+
- **拆解任务**：
|
|
140
|
+
1. ✅ lock schema v2 + migration（`project-config-schema-v2`）
|
|
141
|
+
2. ✅ snapshot 模块 + `restore` 命令（`snapshot-module` + `restore-command`）
|
|
142
|
+
3. ✅ managed-region 解析器（`registry-split-managed-regions`）
|
|
143
|
+
4. ✅ `tokens update` 真实现 + 三态分流（`tokens-update-tristate-dispatch`）
|
|
144
|
+
5. ✅ `teamix-evo init`（已有工程接入；6 类冲突 + wizard + partial 恢复）
|
|
145
|
+
6. ✅ `teamix-evo update` orchestrator（`add-update-command`）
|
|
146
|
+
7. ✅ `teamix-evo switch` + variant migration（`cli-switch-command`）
|
|
147
|
+
8. ✅ token rename hint 写入 + skill `teamix-evo-upgrade`（`tokens-rename-hint` + `skills-add-upgrade-skill`）
|
|
148
|
+
9. ✅ W1.4 tokens 提层兼容迁移（`cli-init-tokens-migrate`）
|
|
149
|
+
10. ✅ 文档站 5 命令导引 + TrekClaw e2e example（`packages/docs/docs/cli/index.md` + `example-trekclaw.md`）
|
|
150
150
|
|
|
151
151
|
## Source
|
|
152
152
|
|
|
@@ -97,3 +97,31 @@ default | muted | primary | success | warning | destructive
|
|
|
97
97
|
- 二次回退触发:用户对 `tone` 命名的业界流行度质疑(2026-05-29 下午)—— 实测 `tone` 仅 Polaris 一家,业界主流是 `color` / `variant`,本 ADR 据此从 `tone` 回退到 `color`
|
|
98
98
|
- 关联记忆:`shadcn基线项目语义色双prop命名决策` / `语义色标准档位不包含info色的决策` / `shadcn 新组件代码规范`
|
|
99
99
|
- 关联组件:Icon / Spinner / Button / Badge / Tag(本 ADR 立项前已落地的混合命名,本次统一)
|
|
100
|
+
|
|
101
|
+
## Addendum: Tag `status` 8 档枚举(2026-06)
|
|
102
|
+
|
|
103
|
+
Tag 在原 `variant`(形态) + `color`(语义色 5 档)正交体系基础上,新增 `variant='status'` 形态 + `status` prop 表达**业务状态机**轴(参考 teamix-pro `@ali/teamix-status-tag` 与 antd Upload/Result 的 `status` prop 习惯)。
|
|
104
|
+
|
|
105
|
+
**8 档命名与 token 映射**
|
|
106
|
+
|
|
107
|
+
| `status` | 中文 | 底层 token | 默认图标(`showIcon`) |
|
|
108
|
+
| --------- | ------ | ---------------------------- | ------------------------------ |
|
|
109
|
+
| `default` | 默认 | `--color-muted-foreground` | `Circle` |
|
|
110
|
+
| `success` | 成功 | `--color-success` | `CheckCircle2` |
|
|
111
|
+
| `running` | 运行中 | `--color-primary` | `PlayCircle` |
|
|
112
|
+
| `error` | 失败 | `--color-destructive` | `XCircle` |
|
|
113
|
+
| `warning` | 提醒 | `--color-warning` | `AlertCircle` |
|
|
114
|
+
| `pause` | 暂停 | `--color-muted-foreground` | `PauseCircle` |
|
|
115
|
+
| `loading` | 加载中 | `--color-muted-foreground` | `Loader2`(自带 `animate-spin`) |
|
|
116
|
+
| `help` | 帮助 | **新增 `--color-help`** 4 档 | `HelpCircle` |
|
|
117
|
+
|
|
118
|
+
**与本 ADR 主体的关系**
|
|
119
|
+
|
|
120
|
+
- `status` 是**业务状态机轴**(本 ADR §一明确不治理),非颜色枚举 —— 8 档名称直接采纳运行态业务话术(`running` / `pause` / `loading`),**不与 `color` 5 档同名约束**
|
|
121
|
+
- 例外:`status='error'` 与 `color='destructive'` 在底层共用 `--color-destructive` token —— 业务状态机轴允许用 `error` 字面值(antd 习惯,运行态自然语义),颜色轴仍只接受 `destructive`(本 ADR 主体规则不变)
|
|
122
|
+
- `status='running'` 与 `color='primary'` 共用 `--color-primary` —— 同理,语义独立但底层映射对齐
|
|
123
|
+
- `variant='status'` 与 `color` / `palette` / 自定义 `icon` **互斥**:状态形态由 `status` 闭环驱动颜色与图标,无外部颜色注入
|
|
124
|
+
|
|
125
|
+
**Token 增量**
|
|
126
|
+
|
|
127
|
+
仅 `--color-help` 一档新增(双变体 OpenTrek + uni-manager 同步),其余 token 均已存在。详见同期 changeset `tag-status-variant`。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0025. 组件 props 必须显式声明 + 数据录入类必须暴露 value/onChange 受控套
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-06-01
|
|
5
5
|
- **Region**: 0100–0999 协议与工具
|
|
6
6
|
- **Related ADR**: [ADR 0023](0023-cursor-pointer-explicit-in-component-source.md) · [ADR 0024](0024-scoped-css-radix-state-conflict.md)
|
|
@@ -32,10 +32,10 @@ Radix 的命名(`onCheckedChange` / `onValueChange`)与 antd / cd / 业务习惯
|
|
|
32
32
|
|
|
33
33
|
## Options Considered
|
|
34
34
|
|
|
35
|
-
| 选项
|
|
36
|
-
|
|
|
37
|
-
| A. 维持现状(空 extends 透传)
|
|
38
|
-
| B. **显式列出每个支持的 prop + JSDoc 中文注释** | meta 自动表完整;Storybook controls 完整;AI 可读 | 每个组件多 ~20 行类型声明,需对齐 Radix 行为
|
|
35
|
+
| 选项 | 优点 | 缺点 |
|
|
36
|
+
| ----------------------------------------------- | ----------------------------------------------- | -------------------------------------------------- |
|
|
37
|
+
| A. 维持现状(空 extends 透传) | 写法少,类型自动完整 | meta props 空 / AI 不可用 / Storybook 控件缺数据源 |
|
|
38
|
+
| B. **显式列出每个支持的 prop + JSDoc 中文注释** | meta 自动表完整;Storybook controls 完整;AI 可读 | 每个组件多 ~20 行类型声明,需对齐 Radix 行为 |
|
|
39
39
|
|
|
40
40
|
## Decision
|
|
41
41
|
|
|
@@ -77,6 +77,7 @@ export interface CheckboxProps
|
|
|
77
77
|
```
|
|
78
78
|
|
|
79
79
|
**关键点**:
|
|
80
|
+
|
|
80
81
|
- 用 `Omit<RadixProps, 'overridden-keys'>` 排除被本地重写的字段,避免类型冲突
|
|
81
82
|
- 所有暴露给业务的 prop **必须**带中文 JSDoc(`generate-meta.ts` 提取的就是这部分)
|
|
82
83
|
- **不在 interface 暴露的 prop = 不支持** — 不允许"暗中支持但不声明"
|
|
@@ -85,14 +86,14 @@ export interface CheckboxProps
|
|
|
85
86
|
|
|
86
87
|
数据录入类(用户输入 / 选择 / 调整某个 value 的组件)**必须**至少有这一对受控 prop:
|
|
87
88
|
|
|
88
|
-
| 组件类型
|
|
89
|
-
|
|
|
90
|
-
| 单值输入(Input / Textarea / NumberInput / DatePicker / TimePicker / ColorPicker / Select 单选 / Combobox 单选) | `value`
|
|
91
|
-
| 布尔值(Checkbox / Switch)
|
|
92
|
-
| 多值(Select 多选 / Combobox 多选 / CheckboxGroup)
|
|
93
|
-
| 数值滑动(Slider / Rate)
|
|
94
|
-
| 树形(Tree / TreeSelect)
|
|
95
|
-
| 级联(Cascader)
|
|
89
|
+
| 组件类型 | 受控 value | 受控 onChange | 非受控初值 |
|
|
90
|
+
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------- | ------------------------ |
|
|
91
|
+
| 单值输入(Input / Textarea / NumberInput / DatePicker / TimePicker / ColorPicker / Select 单选 / Combobox 单选) | `value` | `onChange` 或 Radix 命名(透传时显式声明) | `defaultValue` |
|
|
92
|
+
| 布尔值(Checkbox / Switch) | `checked` | `onCheckedChange` | `defaultChecked` |
|
|
93
|
+
| 多值(Select 多选 / Combobox 多选 / CheckboxGroup) | `value: string[]` | `onChange: (next: string[]) => void` | `defaultValue: string[]` |
|
|
94
|
+
| 数值滑动(Slider / Rate) | `value: number[]` 或 `value: number` | `onValueChange` 或 `onChange` | `defaultValue` |
|
|
95
|
+
| 树形(Tree / TreeSelect) | `value` / `selectedKeys` / `checkedKeys` | 对应 onChange / onSelect / onCheck | `default*` |
|
|
96
|
+
| 级联(Cascader) | `value: string[]` | `onChange: (path, options) => void` | `defaultValue` |
|
|
96
97
|
|
|
97
98
|
业务工程**必须能用受控模式跑通**;非受控只是便利封装。
|
|
98
99
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0026. 组件级 token 别名(`--radius-{component}` 等)的创建准则
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-06-02
|
|
5
5
|
- **Region**: 0100–0999 协议与工具
|
|
6
6
|
- **Related ADR**: [ADR 0020](0020-design-to-tokens-skill-fusion.md)(tokens 包 / skill 边界) · [ADR 0022](0022-preferences-css-boundary.md)(已 superseded,曾约束 preferences.css 不放 token alias)
|
|
@@ -15,20 +15,20 @@ W4–W5 优化时多次遇到"组件圆角该怎么定义"的问题。早期默
|
|
|
15
15
|
|
|
16
16
|
这暴露了两类完全不同的 token 角色:
|
|
17
17
|
|
|
18
|
-
| 层
|
|
19
|
-
|
|
|
18
|
+
| 层 | 类型 | 例子 | 谁定义 | 谁消费 |
|
|
19
|
+
| ------- | ---------------- | ------------------------------------------------------------------------------ | --------------------- | ------------------------------------------------------------------- |
|
|
20
20
|
| Layer 1 | scale primitives | `--radius-sm` / `--radius-md` / `--radius-lg` / `--radius-xl` / `--radius-2xl` | 各 variant 可独立覆盖 | 所有组件,通过 Tailwind 标准 utility `rounded-{sm\|md\|lg\|xl\|2xl}` |
|
|
21
|
-
| Layer 2 | 组件语义别名
|
|
21
|
+
| Layer 2 | 组件语义别名 | `--radius-dialog` / `--radius-tag` | 各 variant 可独立覆盖 | 仅该组件,通过 `rounded-[var(...)]` arbitrary value |
|
|
22
22
|
|
|
23
23
|
ADR 0022(已 superseded)曾约束"preferences.css 边界",但没有规范"什么时候可以加 Layer 2 别名"。本 ADR 补这一条。
|
|
24
24
|
|
|
25
25
|
## Options Considered
|
|
26
26
|
|
|
27
|
-
| 选项
|
|
28
|
-
|
|
|
29
|
-
| A. 严格一层 — 所有组件走 scale,不允许 Layer 2
|
|
30
|
-
| B. **二层模式 — 优先 scale,严控 Layer 2 创建条件(推荐)** | scale 是默认路径(简单);Layer 2 作为 escape hatch,有明确触发条件 | 需要 ADR 守门;否则 Layer 2 会无序蔓延变成"杂物间"
|
|
31
|
-
| C. 全自由 — 任何组件都可加 `--radius-{name}`
|
|
27
|
+
| 选项 | 优点 | 缺点 |
|
|
28
|
+
| -------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| A. 严格一层 — 所有组件走 scale,不允许 Layer 2 | token 架构最简 / 一致性最强 | 跨变体视觉差异大的组件被强制对齐,失去变体差异化能力(opentrek Dialog 必须从 16 收到 6,失去"圆润"视觉特征) |
|
|
30
|
+
| B. **二层模式 — 优先 scale,严控 Layer 2 创建条件(推荐)** | scale 是默认路径(简单);Layer 2 作为 escape hatch,有明确触发条件 | 需要 ADR 守门;否则 Layer 2 会无序蔓延变成"杂物间" |
|
|
31
|
+
| C. 全自由 — 任何组件都可加 `--radius-{name}` | 最大灵活性 | 跟 ADR 之前踩坑的"AI / 业务工程不知道该用哪个 token"反模式重合;token 数量爆炸 |
|
|
32
32
|
|
|
33
33
|
## Decision
|
|
34
34
|
|
|
@@ -39,8 +39,8 @@ ADR 0022(已 superseded)曾约束"preferences.css 边界",但没有规范"什么
|
|
|
39
39
|
新增组件 / 优化组件时,**圆角默认**写:
|
|
40
40
|
|
|
41
41
|
```tsx
|
|
42
|
-
className=
|
|
43
|
-
className=
|
|
42
|
+
className = 'rounded-md'; // 走 --radius-md (uni-manager 2 / opentrek 6 / Tailwind 默认 6)
|
|
43
|
+
className = 'rounded-lg'; // 走 --radius-lg (uni-manager 4 / opentrek 8 / Tailwind 默认 8)
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
各 variant 在 `@theme {}` 块里覆盖 `--radius-sm/md/lg/xl/2xl` 满足该 variant 的视觉调性。
|
|
@@ -49,22 +49,22 @@ className="rounded-lg" // 走 --radius-lg (uni-manager 4 / opentrek 8 / Tailwin
|
|
|
49
49
|
|
|
50
50
|
### 规则 B — 满足以下**全部**条件才可创建 Layer 2 别名
|
|
51
51
|
|
|
52
|
-
| #
|
|
53
|
-
| --- |
|
|
54
|
-
| 1
|
|
55
|
-
| 2
|
|
56
|
-
| 3
|
|
57
|
-
| 4
|
|
52
|
+
| # | 条件 | 备注 |
|
|
53
|
+
| --- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| 1 | 跨变体的目标值**无法被同一个 scale 档同时满足** | 例:Dialog 在 opentrek 想要 16px,uni-manager 想要 2px。无任何 `rounded-{sm\|md\|lg\|xl\|2xl}` 在两个 variant 同时落到这两个值 |
|
|
55
|
+
| 2 | 该组件视觉**确实有跨变体差异化的设计意图**,不是 token 命名洁癖 | 例:Dialog 跨变体差异是"圆润感 vs 锐利感"的设计语言,非可省略 |
|
|
56
|
+
| 3 | 不能通过组合 `cn()` / 变体 className 实现 | 同一 `<Dialog>` 源码不能写"变体感知 className",所以 Dialog 必须有 token alias |
|
|
57
|
+
| 4 | 命名清晰指向具体组件 | `--radius-{component-id}`,如 `--radius-dialog` / `--radius-tag` |
|
|
58
58
|
|
|
59
59
|
不满足全部 4 条 → **走 Layer 1 scale**。
|
|
60
60
|
|
|
61
61
|
### 规则 C — 现存 Layer 2 别名 audit(本 ADR 落地时)
|
|
62
62
|
|
|
63
|
-
| Token
|
|
64
|
-
|
|
|
65
|
-
| `--radius-button` | **已移除**(W1-Button 优化时) | 走 `rounded-md` 即可(uni 2 / opentrek 6 / 标准 6),无变体差异化需求
|
|
66
|
-
| `--radius-dialog` | **保留**
|
|
67
|
-
| `--radius-tag`
|
|
63
|
+
| Token | 状态 | 理由 |
|
|
64
|
+
| ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
65
|
+
| `--radius-button` | **已移除**(W1-Button 优化时) | 走 `rounded-md` 即可(uni 2 / opentrek 6 / 标准 6),无变体差异化需求 |
|
|
66
|
+
| `--radius-dialog` | **保留** | uni 2 / opentrek 16 跨档不可对齐;有"圆润 vs 锐利"设计语言差异;Dialog/AlertDialog/Sheet 共享 |
|
|
67
|
+
| `--radius-tag` | **保留** | uni 4 / opentrek 4(同值但不在任一 variant 的同一 scale 档:opentrek `rounded-sm`=4 ✓ / uni `rounded-sm`=0 ✗);需 alias 才能跨变体对齐 |
|
|
68
68
|
|
|
69
69
|
### 规则 D — 同样模式适用于其他 token namespace
|
|
70
70
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0027. 组件视觉属性全轴对齐设计系统基线
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-06-02
|
|
5
5
|
- **Region**: 0001–0099 工程哲学
|
|
6
6
|
- **Related ADR**: 0010 (design-default-and-variants), 0026 (component-level-token-alias), 0032 (opentrek-v4.1-brand-token-alignment)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 0028. UI 组件分类对齐 Ant Design 5.x + 引入 `deprecated` 类
|
|
2
2
|
|
|
3
|
-
- **Status**:
|
|
3
|
+
- **Status**: Superseded by [0036](./0036-ui-v2-shadcn-baseline-rebuild.md)
|
|
4
4
|
- **Date**: 2026-06-02
|
|
5
5
|
- **Region**: 0100–0999 协议与工具
|
|
6
6
|
- **Related ADR**: 0014 (ui-biz-ui-templates-tier), 0025 (component-props-explicit)
|
|
@@ -51,15 +51,16 @@ teamix-evo 定位**中后台研发**(opentrek + uni-manager 都是管控台),**A
|
|
|
51
51
|
|
|
52
52
|
### 完整组件归类(87 个)
|
|
53
53
|
|
|
54
|
-
- **general(3)
|
|
55
|
-
- **layout(
|
|
56
|
-
- **navigation(5)
|
|
57
|
-
- **data-entry(20)
|
|
58
|
-
- **data-display(19)
|
|
59
|
-
- **feedback(
|
|
60
|
-
- **deprecated(
|
|
54
|
+
- **general(3)**：button、icon、typography
|
|
55
|
+
- **layout(6)**：flex、grid、page-header、resizable、separator、sidebar
|
|
56
|
+
- **navigation(5)**：affix、breadcrumb、dropdown-menu、pagination、steps
|
|
57
|
+
- **data-entry(20)**：auto-complete、cascader、checkbox、color-picker、date-picker、field、filter-bar、form、input、input-number、label、radio-group、rate、select、slider、switch、time-picker、transfer、tree-select、upload
|
|
58
|
+
- **data-display(19)**：accordion、avatar、badge、calendar、card、carousel、collapsible、data-table、descriptions、empty、hover-card、item、statistic、table、tabs、tag、timeline、tooltip、tree
|
|
59
|
+
- **feedback(14)**[^1]：alert、alert-dialog、command、dialog、notification、popconfirm、popover、progress、result、sheet、skeleton、sonner、spinner、watermark
|
|
60
|
+
- **deprecated(19)**[^1][^2]：已有 — aspect-ratio、image、kbd；新增 — app、anchor、context-menu、float-button、menubar、navigation-menu、tour、toggle-group、toggle、segmented、native-select、mentions、input-otp、scroll-area、masonry、drawer
|
|
61
61
|
|
|
62
|
-
[^1]: 2026-06-02 补丁 — `command` 原拟归 deprecated(
|
|
62
|
+
[^1]: 2026-06-02 补丁 — `command` 原拟归 deprecated("仅 Storybook 留档"),但事实上被 active 的 `select` / `auto-complete` 运行时强 import,不能不外发;同时作为 Combobox / Select / AutoComplete 同源下拉内核(ADR 0029)在架构上起底座作用。故从 deprecated 撤回,与 popover 同档归 `feedback`(反馈式弹层底座)。
|
|
63
|
+
[^2]: 2026-06-04 补丁 — `drawer` 从 feedback 移入 deprecated，因其是 Sheet 的纯别名 re-export，无独立实现；`space` 从 layout 移除，因其从未实现为独立 entry，Flex 已完整覆盖 antd Space 能力。feedback 15→14，layout 7→6，deprecated 18→19。
|
|
63
64
|
|
|
64
65
|
### 与 AntD 的偏离
|
|
65
66
|
|
|
@@ -9,10 +9,10 @@
|
|
|
9
9
|
|
|
10
10
|
`@teamix-evo/skills` 当前混了两类性质完全不同的 skill,放在同一个 `manifest.skills` 数组里:
|
|
11
11
|
|
|
12
|
-
| 类型
|
|
13
|
-
|
|
|
14
|
-
| **lifecycle skill / orchestrator** | `teamix-evo-manage`
|
|
15
|
-
| **content skill / variant 内容**
|
|
12
|
+
| 类型 | 例子 | 安装语义 |
|
|
13
|
+
| ---------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
14
|
+
| **lifecycle skill / orchestrator** | `teamix-evo-manage` | 工具型。作为生命周期入口被调用(初始化、升级、卸载、placeholder→real 迁移)。**装一次即可**,不需要跟项目走。 |
|
|
15
|
+
| **content skill / variant 内容** | `teamix-evo-design-<variant>`、`teamix-evo-code-<variant>` | 跟 variant 绑定。装在哪个项目就影响哪个项目的页面 / 文件生成规则。**必须随项目走**。 |
|
|
16
16
|
|
|
17
17
|
实际用户路径:
|
|
18
18
|
|
|
@@ -28,17 +28,17 @@
|
|
|
28
28
|
|
|
29
29
|
## Options Considered
|
|
30
30
|
|
|
31
|
-
| 选项
|
|
32
|
-
|
|
|
33
|
-
| A. SkillEntry 加 `scope` 字段,bulk init 按 scope 过滤(本决策)
|
|
34
|
-
| B. 运行时去重(`skills init` 检测 `~/.claude/skills/<id>` 已存在则跳过)
|
|
35
|
-
| C. 在 `teamix-evo-manage` 自身的 SKILL.md 决策树里手动让 AI 排除 manage | 不动 CLI / manifest
|
|
36
|
-
| D. 把 `teamix-evo-manage` 拆成独立 npm 包
|
|
31
|
+
| 选项 | 优点 | 缺点 |
|
|
32
|
+
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
33
|
+
| A. SkillEntry 加 `scope` 字段,bulk init 按 scope 过滤(本决策) | 声明式;符合 manifest 契约;新增 lifecycle skill 只需打一个标签;现存 manifest 不写该字段也兼容 | 引入一个语义字段,需要 schema bump;CLI 增加分支 |
|
|
34
|
+
| B. 运行时去重(`skills init` 检测 `~/.claude/skills/<id>` 已存在则跳过) | 不动 manifest | 依赖外部状态;同名不同版本时反而锁死;语义不显式 |
|
|
35
|
+
| C. 在 `teamix-evo-manage` 自身的 SKILL.md 决策树里手动让 AI 排除 manage | 不动 CLI / manifest | 每次新增 lifecycle skill 都要改 markdown;契约不机器可读;AI 偏离指令时无法兜底 |
|
|
36
|
+
| D. 把 `teamix-evo-manage` 拆成独立 npm 包 | 物理隔离 | 破坏单包多 group 原则;用户安装路径变复杂;需要 CI 改造 |
|
|
37
37
|
|
|
38
38
|
## Decision
|
|
39
39
|
|
|
40
40
|
1. `SkillEntrySchema`(`packages/registry/src/schema/manifest.ts`)新增可选字段 `scope: SkillScopeSchema.optional()`,复用已有的 `SkillScopeSchema = z.enum(['project', 'global'])`。`undefined` 视为隐式 `"project"`。
|
|
41
|
-
2. `packages/skills/manifest.json`
|
|
41
|
+
2. `packages/skills/manifest.json` 中所有 lifecycle 工具型 skill 标 `"scope": "global"`：当前包含 `teamix-evo-manage`（orchestration 入口）与 `teamix-evo-upgrade`（staging / hints apply 工具，跨 variant 共用，不携带业务内容）；其余 content skill（`teamix-evo-design-<variant>` / `teamix-evo-code-<variant>`）不动。
|
|
42
42
|
3. `runSkillsInit`(`packages/cli/src/core/skills-add.ts`,自举路径)candidate 过滤:若 `(s.scope ?? 'project') !== <current install scope>`,跳过(debug 日志说明)。**verb 命名见 [ADR 0034](0034-skills-cli-verb-alignment.md)**。
|
|
43
43
|
4. `runSkillsAdd`(增量,显式指名)**不**过滤,但若指名的 skill 声明的 scope 与当前 scope 不一致,emit 一条 `logger.warn`,提示推荐 scope。**用户显式指令优先,自负责。**
|
|
44
44
|
5. `create-teamix-evo` 的两个 preset(`opentrek` / `uni-manager`)从 `skills.entries` 移除 `teamix-evo-manage`。`skills.entries` 只剩 `design-${variant}` + `code-${variant}` 两条 variant 内容。orchestrator 末尾 next-steps 输出多一行,提示用户独立全局装 manage。
|
|
@@ -62,3 +62,4 @@
|
|
|
62
62
|
|
|
63
63
|
- 用户反馈:「用户使用时会先全局安装 teamix-evo-manage 这个技能,然后使用该技能初始化工程,但是初始化过程中又会在项目级安装本技能,导致用户侧会有两个该技能」
|
|
64
64
|
- 实施 plan:`/Users/lyca/.claude/plans/refactored-roaming-grove.md`
|
|
65
|
+
- 2026-06-15 复盘补遗：`teamix-evo-upgrade` 上线时 manifest 漏标 scope 字段（隐式 project）。复盘后判定其内容形态属于 lifecycle 工具型（通用工作流、跨 variant 共用、强项目状态绑定占比 <10%），与 manage 同站 global。同步标 `"scope": "global"`，落地动作与 manage 完全一致。
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# 0036. UI 组件库 v2：以 shadcn v4 为基线全量重建
|
|
2
|
+
|
|
3
|
+
- **Status**: Accepted
|
|
4
|
+
- **Date**: 2026-06-05
|
|
5
|
+
- **Region**: 0001–0099 工程哲学
|
|
6
|
+
- **Related ADR**: Supersedes 0001, 0005, 0006, 0010, 0025, 0026, 0027, 0028, 0029
|
|
7
|
+
|
|
8
|
+
## Context
|
|
9
|
+
|
|
10
|
+
`@teamix-evo/ui` v1 从 shadcn v3 出发，叠加 antd 能力并集，积累了 87+ 组件。过程中出现以下问题：
|
|
11
|
+
|
|
12
|
+
1. **双对标负担**：每个组件都要做"shadcn ∪ antd 并集"，决策成本高、更新难跟进
|
|
13
|
+
2. **旧 shadcn 架构绑定**：forwardRef、`@layer base` border 兜底、hsl 色值等 v3 模式已过时
|
|
14
|
+
3. **Token 分层不清**：全局 token 与组件级行为覆盖混在一个 theme.css 里（uni-manager 544 行）
|
|
15
|
+
4. **文档多源漂移**：meta.md 手写、Storybook 描述手写、TSDoc 各写各的，三处信息不同步
|
|
16
|
+
5. **能力增强方向模糊**：antd 为锚点导致"追赶 antd"而非"面向业务场景"
|
|
17
|
+
|
|
18
|
+
同时，shadcn 已演进到 v4（radix-nova style、React 19 patterns、data-slot、oklch、Tailwind v4 @theme），架构显著优于 v3。
|
|
19
|
+
|
|
20
|
+
## Decision
|
|
21
|
+
|
|
22
|
+
### D1. 全量废弃 v1 组件源码，以 shadcn v4 (radix-nova) 为基线重建
|
|
23
|
+
|
|
24
|
+
- 现有 `packages/ui/src/` 内容备份到 `packages/ui/src-v1-archive/`
|
|
25
|
+
- 从 shadcn v4 最新版初始化全部基线组件
|
|
26
|
+
- 超出 shadcn 的组件按 shadcn 工程风格自研
|
|
27
|
+
|
|
28
|
+
### D2. Token 架构：`theme.css` + `overrides.css` 两文件制
|
|
29
|
+
|
|
30
|
+
每个变体目录结构：
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
packages/tokens/variants/{variant}/
|
|
34
|
+
├── theme.css ← @theme token 声明（Tailwind v4 消费）
|
|
35
|
+
└── overrides.css ← 变体组件行为覆盖（[data-theme] scoped CSS）
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- `base.tokens.json` 删除（原为 AI 生成辅助文件，非运行时依赖）
|
|
39
|
+
- `theme.css` 为全局 token 声明唯一源
|
|
40
|
+
- `overrides.css` 处理跨变体的组件级行为差异（focus 机制、button shadow、dialog padding 等）
|
|
41
|
+
|
|
42
|
+
### D3. `data-theme` 属性双变体统一声明
|
|
43
|
+
|
|
44
|
+
所有消费方项目必须在 `<html>` 上声明 `data-theme`：
|
|
45
|
+
|
|
46
|
+
```html
|
|
47
|
+
<html data-theme="opentrek">
|
|
48
|
+
<!-- 或 "uni-manager" -->
|
|
49
|
+
</html>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- 脚手架自动写入
|
|
53
|
+
- `ui init` CLI 输出提示（AI coding 场景由 AI 添加）
|
|
54
|
+
- 即使 opentrek 的 `overrides.css` 为空也要声明，防御未来升级
|
|
55
|
+
|
|
56
|
+
### D4. 能力增强不再对齐 antd，由用户定义目标
|
|
57
|
+
|
|
58
|
+
- 废弃"shadcn ∪ antd 并集"策略（旧 ADR 0001）
|
|
59
|
+
- 组件能力需求由用户逐组件提供，以业务场景为导向
|
|
60
|
+
- shadcn 组件作为基线，增强能力按 shadcn 工程风格实现
|
|
61
|
+
|
|
62
|
+
### D5. TSDoc 为唯一文档手写源
|
|
63
|
+
|
|
64
|
+
信息流：
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
TSDoc (唯一手写源)
|
|
68
|
+
├──→ Storybook autodocs plugin → 组件名、描述、何时使用、API 表
|
|
69
|
+
├──→ gen:meta 脚本 → meta.md（自动生成，CI 守门）
|
|
70
|
+
└──→ MCP server → 读 meta.md 或直接 parse TSDoc
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
TSDoc 自定义标签：
|
|
74
|
+
|
|
75
|
+
- `@when` — 何时使用（列表形式）
|
|
76
|
+
- 首段 — 组件中文名 + 描述
|
|
77
|
+
|
|
78
|
+
开发者只手写两个文件：
|
|
79
|
+
|
|
80
|
+
1. `<id>.tsx`（含 TSDoc + Props interface JSDoc）
|
|
81
|
+
2. `<id>.stories.tsx`（仅代码演示 Stories）
|
|
82
|
+
|
|
83
|
+
### D6. Storybook 页面结构
|
|
84
|
+
|
|
85
|
+
每个组件的 autodocs 页包含：
|
|
86
|
+
|
|
87
|
+
1. **组件名 + 中文名**（`meta.title`）
|
|
88
|
+
2. **描述**（从 TSDoc 首段提取）
|
|
89
|
+
3. **何时使用**（从 TSDoc `@when` 提取）
|
|
90
|
+
4. **代码演示**（手写 Stories）
|
|
91
|
+
5. **API Props 表**（autodocs 从 TypeScript interface + JSDoc 自动生成）
|
|
92
|
+
|
|
93
|
+
### D7. shadcn v4 工程模式对齐
|
|
94
|
+
|
|
95
|
+
| 特性 | 采用 |
|
|
96
|
+
| ---------------------------------- | ----------------------- |
|
|
97
|
+
| `data-slot` 属性系统 | ✅ 所有组件标记 |
|
|
98
|
+
| React 19 函数组件（无 forwardRef） | ✅ 默认不加，按需后补 |
|
|
99
|
+
| cva（class-variance-authority） | ✅ 有枚举 prop 的组件用 |
|
|
100
|
+
| Tailwind v4 `@theme inline` | ✅ |
|
|
101
|
+
| oklch 或 hex 色值 | 按用户新 token design |
|
|
102
|
+
| `radix-ui` 单包导入 | ✅ |
|
|
103
|
+
| lucide-react 图标 | ✅ |
|
|
104
|
+
| `cn()` = clsx + tailwind-merge | ✅ |
|
|
105
|
+
|
|
106
|
+
### D8. React 18 兼容
|
|
107
|
+
|
|
108
|
+
- 默认使用 shadcn v4 写法（无 forwardRef）
|
|
109
|
+
- React 18 下 ref 不会转发，绝大多数场景无影响
|
|
110
|
+
- 极少数需要 ref 的组件后续按需单独加 forwardRef
|
|
111
|
+
|
|
112
|
+
### D9. 旧 ADR 归档
|
|
113
|
+
|
|
114
|
+
以下 ADR 标记为 `Superseded by 0036`：
|
|
115
|
+
|
|
116
|
+
| ADR | 原决策 | 被取代原因 |
|
|
117
|
+
| ---- | -------------------------- | --------------------------------- |
|
|
118
|
+
| 0001 | 三层对齐（能力/理念/工程） | 不再做 antd 并集 |
|
|
119
|
+
| 0005 | UI 包不分 variant | 现在用 data-theme + overrides.css |
|
|
120
|
+
| 0006 | UI 升级机制无 baseline | 全量重建，旧升级策略不适用 |
|
|
121
|
+
| 0010 | design 默认+变体模型 | 纯变体，无 default 基线 |
|
|
122
|
+
| 0025 | Props 显式声明规范 | TSDoc 新范式取代 |
|
|
123
|
+
| 0026 | 组件级 token alias | overrides.css 取代组件内 token |
|
|
124
|
+
| 0027 | 组件视觉 token 对齐 | 全量重建，旧对齐规则不适用 |
|
|
125
|
+
| 0028 | UI 组件分类 | 新组件清单由用户定义 |
|
|
126
|
+
| 0029 | Input 拆分 | 全量重建，旧拆分决策不适用 |
|
|
127
|
+
|
|
128
|
+
## Consequences
|
|
129
|
+
|
|
130
|
+
- **Positive**:
|
|
131
|
+
- 与 shadcn 社区完全同步，享受生态红利
|
|
132
|
+
- Token 分层清晰，新增变体仅需两个 CSS 文件
|
|
133
|
+
- 文档单源（TSDoc），消除多源漂移
|
|
134
|
+
- 组件源码精简（shadcn v4 比 v1 并集代码少 60%+）
|
|
135
|
+
- AI 生成/理解成本大幅降低（标准 shadcn 模式）
|
|
136
|
+
- **Negative**:
|
|
137
|
+
- 需要全量重写所有组件（一次性大投入）
|
|
138
|
+
- 旧版本消费方无法平滑升级（breaking change）
|
|
139
|
+
- 放弃 antd 并集意味着部分能力需用户显式提需求
|
|
140
|
+
- **Trade-off**:
|
|
141
|
+
- 用"一次性重建成本"换"长期维护效率 + AI 友好度"
|
|
142
|
+
- 用"用户主动提需求"换"不再盲目追赶 antd"
|
|
143
|
+
|
|
144
|
+
## Source
|
|
145
|
+
|
|
146
|
+
2026-06-05 架构分析讨论。基于对 shadcn v4 (radix-nova, shadcn@4.10.0) 源码的深度分析，对比现有 v1 架构的 7 个痛点，做出全量重建决策。
|