@teamix-evo/design

Teamix Evo 设计体系资源包 — 中性 B 端基线 + 多变体（variants）覆盖。

定位

design 是 Teamix Evo 的资源层，是一个纯资源包（无 JS 构建产物），按 ADR 0010 的 default + variants 模型组织：

• default/ — 变体中立的 B 端基线（philosophy / foundations / patterns / scenarios / tokens）
• variants/<name>/ — 业务变体覆盖（按文件路径"覆盖"或"新增"）

CLI 包在运行时通过 loadDesignPack / mergeDefaultAndVariant 把两者按文件路径合并，逐文件分类（frozen / regenerable / managed）后写入消费方的 .teamix-evo/design/。

目录结构

packages/design/
├── default/                          # 中性 B 端基线（任何 variant 都消费）
│   ├── DESIGN.md                     # 设计纲领（变体覆盖时整文件替换）
│   ├── AGENTS.md / CLAUDE.md         # AI 入口
│   ├── pack.json                     # default 元数据
│   ├── philosophy/                   # 设计理念
│   ├── foundations/                  # 设计基础（color / typography / spacing / radius / shadow / motion / effects / tokens）
│   ├── patterns/                     # 页面模式（page-types / journeys / flows）
│   ├── scenarios/                    # 业务场景模板与示例
│   └── adr/                          # 设计决策记录
├── variants/
│   ├── opentrek/                     # OpenTrek 变体（品牌 / voice / 调性）
│   │   ├── pack.json
│   │   ├── DESIGN.md / AGENTS.md / CLAUDE.md
│   │   ├── brand/
│   │   └── foundations/              # 仅装载需要覆盖的子目录
│   └── uni-manager/                  # 云资源管理变体（AI 副驾驶 / 大屏 / 拓扑）
│       ├── pack.json
│       ├── patterns/cloud-*.md
│       ├── scenarios/                # AI 场景 A-G
│       └── foundations/              # 大屏 / 场景化动效
├── manifest.json                     # 顶层目录（列出 default + 全部 variant）
├── scripts/
│   └── validate-variants.ts          # 变体校验脚本
└── package.json

合并语义（ADR 0010 §4）

mergeDefaultAndVariant(defaultDir, variantDir) 按 pack-relative 路径 合并两棵树：

| 情形 | 行为 | 落地分类 | |------|------|----------| | 仅 default 有 | 保留 default 文件 | defaultPassThrough | | default + variant 同路径 | variant 文件覆盖 default | overrides | | 仅 variant 有（新增姿势） | 直接附加 variant 文件 | variantAdds |

设计原则：

• 优先「新增」——变体作者直接 variants/<name>/<新路径> 即可，不必重复 default 内容
• 「覆盖」用于真正需要替换的核心文档（如 OpenTrek 的 DESIGN.md、AGENTS.md）
• 单一文件粒度，不做行级 / 段落级 merge — 复杂度推到正确的层

变体状态

| 变体 | 内容 | 配套 skill | |------|------|-----------| | default | 中性 B 端基线（CRUD / 审批 / 导入导出 / 设置中心 / 报表） | teamix-evo-design-rules（基线） | | opentrek | OpenTrek 品牌（沉稳克制） + brand voice / examples | + teamix-evo-design-rules-opentrek（自动叠加） | | uni-manager | 云资源 patterns + AI 副驾驶 7 类场景 + 大屏 / 拓扑 | + teamix-evo-design-rules-uni-manager（自动叠加） |

teamix-evo design init <variant> 在写完 pack.lock.json 之后会自动调用 runSkillsAdd，把对应的 teamix-evo-design-rules-<variant> skill 一并装入。

研发流程

1. 修改基线（影响所有 variant）

直接编辑 default/ 下文件。改动会同时影响所有未在该路径上做 override 的变体。

2. 新增 / 修改变体专属内容

优先用「新增」姿势——只在 variants/<name>/<路径> 下放新文件：

• 通用资产 → variants/<name>/foundations/、patterns/、scenarios/
• 品牌资产 → variants/<name>/brand/
• AI 场景 → variants/<name>/scenarios/examples/

只有当 default 文件真的需要替换（例如 DESIGN.md / AGENTS.md / CLAUDE.md 的整体内容）时才在 variant 下放同路径文件做覆盖。

3. 新增 Variant

mkdir -p variants/my-variant
# 1) 写 pack.json:
#    {
#      "schemaVersion": 1,
#      "name": "my-variant",
#      "displayName": "My Variant",
#      "version": "0.1.0",
#      "extends": "default",
#      "description": "..."
#    }
# 2) 在 manifest.json 顶层 variants 数组添加该 variant
# 3) 按需添加 DESIGN.md / brand/ / foundations/ ... 等
# 4) 创建对应的变体 skill（建议）：
#    packages/skills/skills/teamix-evo-design-rules-my-variant/SKILL.md
#    并在 packages/skills/manifest.json 加 variant: "my-variant" 字段
pnpm --filter @teamix-evo/design validate

4. 验证

pnpm --filter @teamix-evo/design validate

validate-variants.ts 执行：

1. 加载 manifest.json 顶层目录，确认每个 variant 入口存在
2. 加载 default + 每个 variant 的 pack.json，确认 schema 合法
3. 走 mergeDefaultAndVariant 一遍，确保不报错
4. 通过 classifyPackFile 给每个合并后的文件打分类，确保策略可解析

5. 端到端预览

在临时目录跑：

mkdir /tmp/test-design && cd /tmp/test-design
node /path/to/packages/cli/dist/index.js design init opentrek
node /path/to/packages/cli/dist/index.js design init uni-manager   # 另一目录

观察生成的 .teamix-evo/tokens/(W1.4 提层后的 tokens)、.teamix-evo/design/(其余文档)、.qoder/skills/、.claude/skills/ 内容。

资源类型与策略

每个文件由 packages/cli/src/core/design-pack-classify.ts 按 pack-relative 路径自动分类:

| 路径前缀（pack 内） | 落地路径 | 策略 | 含义 | | --- | --- | --- | --- | | DESIGN.md / AGENTS.md / CLAUDE.md | .teamix-evo/design/<file> | managed | 标记区内 CLI 维护,标记外用户自由编辑 | | foundations/tokens/*.json / *.css(除 overrides) | .teamix-evo/tokens/<file> | regenerable | W1.4 提层 — 每次 update 完全重写 | | foundations/tokens/tokens.overrides.css | .teamix-evo/tokens/tokens.overrides.css | frozen | W1.4 提层 — 首次安装后不再覆盖 | | philosophy/*.md / foundations/*.md 等普通文档 | .teamix-evo/design/<file> | regenerable | 整文件重写 | | pack-internal README.md / pack.json | (不安装) | (不安装) | 仅供 design 包自身维护 |

与 skills 的关系

| 维度 | design 包 | skills 包 | |------|----------|-----------| | 内容形式 | L3 知识（Markdown / JSON / CSS） | L4 协议（AI 触发规则 + 提示词） | | 入口 | .teamix-evo/design/ | IDE 的 .qoder/skills/ / .claude/skills/ | | 变体绑定 | 多变体目录 + 文件覆盖（ADR 0010） | manifest 的 variant 字段（ADR 0014 风格） | | 装机 | teamix-evo design init <variant> | teamix-evo skills add 或 design init 联动 |

详见 packages/skills/AGENTS.md。

依赖关系

本包无运行时依赖
@teamix-evo/registry — devDependency（validate 脚本与 schema 使用）
CLI 包 → 运行时 require.resolve 本包获取资源路径