@teamix-evo/design

Teamix Evo 设计体系资源包 — 包含模板库和 variant 实现。

定位

design 是 Teamix Evo 的资源层，是一个纯资源包（无 JS 构建产物），提供：

• _template/ — Handlebars 模板研发区（所有 variant 共享的模板源）
• library/ — variant 实现目录（每个 variant 一个子目录）

CLI 包在运行时从本包中读取 manifest 和模板文件进行渲染。

目录结构

packages/design/
├── _template/                     # 模板研发区（下划线前缀，不被 variant 扫描器收录）
│   ├── README.md                  # 模板研发指南
│   ├── manifest.json.hbs
│   ├── DESIGN.md.hbs
│   ├── AGENTS.md.hbs
│   ├── brand/                     # 品牌调性模板
│   ├── philosophy/                # 设计理念模板
│   ├── foundations/               # 设计基础模板
│   ├── tokens/                    # 设计 Token 模板
│   ├── business/                  # 业务语义模板
│   ├── scenarios/                 # AI 场景模板
│   ├── patterns/                  # 页面模式模板
│   ├── ai-rules/                  # AI 设计规则模板
│   └── adr/                       # 设计决策记录模板
├── library/
│   └── opentrek/                  # 首个 variant
│       ├── manifest.json          # Variant 清单（符合 registry Schema）
│       └── _data.json             # 模板渲染上下文数据
├── scripts/
│   └── validate-variants.ts       # Variant 校验脚本
└── package.json

研发流程

1. 环境准备

# 在仓库根目录
pnpm install

# registry 包需先构建（validate 脚本依赖）
pnpm --filter @teamix-evo/registry build

2. 修改模板

模板文件位于 _template/ 目录，使用 Handlebars 语法：

1. 编辑 .hbs 文件
2. 文件顶部保留标识注释：{{!-- teamix-evo:template id="<id>" --}}
3. 变量使用 {{variableName}}，引用 variant 的 _data.json 数据
4. Managed regions 使用 HTML 注释标记

3. 新增 Variant

# 1. 创建 variant 目录
mkdir library/my-variant

# 2. 创建 manifest.json（遵循 VariantManifest Schema）
# 3. 创建 _data.json（模板渲染上下文）
# 4. 验证
pnpm --filter @teamix-evo/design validate

manifest.json 必须包含：

• schemaVersion: 1
• package: "design"
• variant: "<variant-name>"
• displayName, description, version
• engines: { "teamix-evo": ">=0.1.0" }
• ide: ["qoder"]
• resources: [...] — 声明所有资源及其 source/target/策略

_data.json 提供 Handlebars 渲染所需的上下文变量（颜色、字体、间距等）。

4. 修改 Variant 数据

编辑 library/<variant>/_data.json，修改设计 token 值：

• colors.light.* / colors.dark.* — HSL 格式色值
• fontFamily.* — 字体族配置
• radius — 圆角基准值
• typography.* — 字号、行高等

5. 验证

# 校验所有 variant 的 manifest 和资源路径
pnpm --filter @teamix-evo/design validate

该脚本执行：

1. 扫描 library/ 下所有非 _ / . 开头的目录
2. 读取并验证 manifest.json（使用 registry 包的 Schema）
3. 检查所有 resource 的 source 路径是否存在

6. 预览渲染结果

# 构建 CLI 后在临时目录测试
cd /tmp && mkdir test-project && cd test-project
node /path/to/packages/cli/dist/index.js design init opentrek

查看生成的 DESIGN.md、AGENTS.md、.teamix-evo/ 目录内容。

资源类型与策略

| 资源 | 类型 | 策略 | 说明 | | -------------------- | -------- | ----------- | --------------------------------------- | | DESIGN.md | doc | managed | 标记区内由 CLI 维护，标记外用户自由编辑 | | AGENTS.md | doc | managed | 同上 | | base.tokens.json | tokens | regenerable | 每次 update 完全重写 | | semantic.tokens.json | tokens | regenerable | 同上 | | tailwind.preset.ts | tokens | regenerable | 同上 | | tokens.generated.css | tokens | regenerable | 同上 | | tokens.theme.css | tokens | regenerable | 同上 | | tokens.overrides.css | tokens | frozen | 首次安装后不再覆盖 | | ai-rules/ | ai-rules | regenerable | 递归目录，整体重写 |

模板变量参考

| 变量 | 类型 | 说明 | | -------------- | ------ | ---------------------------------------- | | variant | string | 变体标识（如 "opentrek"） | | displayName | string | 设计语言显示名（如 "OpenTrek"） | | description | string | 设计语言描述 | | version | string | 版本号 | | projectName | string | 目标项目名 | | primaryColor | string | 主色 | | colors | object | 色彩定义 { light: {...}, dark: {...} } | | fontFamily | object | 字体族 { sans, mono } | | typography | object | 排版配置 | | spacing | object | 间距配置 | | radius | object | 圆角配置 | | shadow | object | 阴影配置 |

关键约定

• _template/ 下划线前缀：variant 扫描器自动跳过
• .hbs 后缀：CLI 渲染时去除，生成对应格式文件
• tokens.overrides.css 是 frozen 资源：用户可自定义覆盖，永不被 CLI 覆盖
• 资源路径在 manifest 中以 _template/ 开头时，从包根目录解析

依赖关系

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