@teamix-evo/tokens

Teamix Evo 设计 Token 资源包 — 每个变体一份完整、自包含的 token 集,给 CSS bundler(Tailwind v4)消费。

定位

tokens 是 Teamix Evo 的 视觉值层,纯资源包(无 JS 构建产物)。按 ADR 0020 的架构:

• 每个 variants/<name>/ 是一个完整自包含的 token 集 —— 不再有 default 基线 + variant 覆盖的合并模型
• 内含 theme.css(Tailwind v4 @theme {})与 base.tokens.json(W3C Design Tokens 引用数据)
• 设计知识(哲学 / 模式 / 品牌调性 / 生成流程)归属 @teamix-evo/skills 的 teamix-evo-design-<variant> skill,不在本包
• 可交互元素的 cursor: pointer(以及 disabled 态 cursor: not-allowed)由组件源码内显式声明,不再走全局 CSS 文件 — 见 ADR 0023

CLI 在运行时按变体加载本包的 variants/<name>/ 内容,写入消费方根 tokens/ 目录。

目录结构

packages/tokens/
├── manifest.json                       # 顶层 catalog(列出所有 variants 与 advertised files)
├── variants/
│   ├── opentrek/
│   │   ├── theme.css                   # Tailwind v4 @theme 变量
│   │   └── base.tokens.json            # W3C Design Tokens 引用数据
│   └── uni-manager/
│       ├── theme.css
│       └── base.tokens.json
├── scripts/
│   └── validate-variants.ts            # 变体校验脚本
└── package.json

历史的 default/ 基线、variants 下的 DESIGN.md / AGENTS.md / CLAUDE.md / philosophy/ / patterns/ / scenarios/ 已按 ADR 0020 移除 —— 设计知识全部进 skill,本包只剩 token 数据。

变体状态

| 变体 | 版本 | 主色 | 内容 | 配套 skill | | --------------- | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | opentrek | v4.1 | #0055EE (hsl(218.6 100% 46.7%)) | OpenTrek 品牌 token（AI 副驾驶场景，完整 5 档状态色 / accent-10 / chart-10 / sidebar+topbar / radius 4-16-9999 / PingFang SC） | teamix-evo-design-opentrek（自包含） | | uni-manager | v0.6.0 | #0064C8 (hsl(210 100% 39.2%)) | Uni-Manager 品牌 token（统一管理类业务，cd hybridcloud 锐利 radius 2-4-8 / 业务尺寸 token 同名同步声明） | teamix-evo-design-uni-manager（自包含） |

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

研发流程

1. 修改既有变体的 token

直接编辑 variants/<name>/theme.css 与 variants/<name>/base.tokens.json。每个变体独立维护,不影响其他变体。

2. 新增 Variant

mkdir -p variants/my-variant
# 1) 写 variants/my-variant/theme.css(Tailwind v4 @theme 块)
# 2) 写 variants/my-variant/base.tokens.json(W3C 引用数据)
# 3) 在 manifest.json variants 数组追加该 variant 条目,advertised files 列上述 2 个文件
# 4) 创建配套 skill(必须):
#    packages/skills/src/teamix-evo-design-my-variant/SKILL.md
#    并在 packages/skills/manifest.json 加 variant: "my-variant"
pnpm --filter @teamix-evo/tokens validate

3. 验证

pnpm --filter @teamix-evo/tokens validate

validate-variants.ts 执行:

1. 加载 manifest.json,确认 schema 合法、每个 variant 入口存在
2. 确认每个 advertised file 在 variants/<name>/ 下真实存在
3. 抽查 theme.css 含 @theme 块、base.tokens.json 是合法 JSON

4. 端到端预览

mkdir /tmp/test-tokens && cd /tmp/test-tokens
node /path/to/packages/cli/dist/index.js tokens init opentrek

观察生成的 tokens/(根目录,frozen+regenerable)、.teamix-evo/tokens-lock.json、.qoder/skills/、.claude/skills/ 内容。

灰阶语义体系（four-tier text / two-tier border）

按 cd hybridcloud 数字化色板 → shadcn 语义 token 映射规范落地，不引入 text-1..5 数字 token，按用途命名以保持 shadcn 纯度。各 token 各司其职，不是冗余分级：

| Token | uni-manager light | cd 对应 | 用途 | | --------------------------- | ----------------- | ---------- | ------------------------------------- | | --color-foreground | #1a1a1a | text-1 | 标题 / 强调 | | --color-foreground-body | #333333 | text-2 | 段落 / 表格 body / 大段正文 | | --color-muted-foreground | #696969 | text-3 | 次要 / placeholder / icon / Card desc | | --color-foreground-subtle | #808080 | text-4 | 辅助 / 表头 / 时间戳 / 计数器 | | --color-border | #d9d9d9 | border-1 | 输入控件 / 主要边框 | | --color-border-subtle | #e5e5e5 | border-4 | 容器分隔 / 表格行底 / 一级卡片 | | --color-muted | #f7f7f7 | — | secondary / hover 灰 / 表单填充 | | --color-panel | #f7f7f7 | bg-4 | 嵌套面板 / 表格表头 |

opentrek 同步声明同名 token（HSL 近似值），保证组件在两主题下都能拿到值。

「为什么 muted-foreground 和 foreground-subtle 都是灰文字？」 —— 因为语义不同：muted-foreground 是 Card description / Form helper / placeholder 等「次要文字」；foreground-subtle 是表头 / 时间戳 / 计数器等「辅助文字」（视觉更轻一档）。组件层按用途选 token，不是「色阶第几档」。

资源类型与策略

每个变体目录下的文件按以下规则落地(ADR 0020 §3):

| 文件 | 落地路径 | 策略 | 含义 | | --------------------------- | ----------------------------- | ----------- | ---------------------------------- | | theme.css | tokens/tokens.theme.css | regenerable | 根目录 — 每次 update 完全重写 | | base.tokens.json | (不安装,仅包内引用) | — | MCP/AI 工具链参考数据,不落地消费者 | | overrides.css(若变体声明) | tokens/tokens.overrides.css | frozen | 根目录 — 首次安装后不再覆盖 |

与 skills 的关系

| 维度 | tokens 包 | skills 包 | | -------- | ---------------------------------- | ------------------------------------------- | | 内容形式 | 视觉值(CSS 变量 / JSON token) | L4 协议(AI 触发规则 + 提示词) | | 入口 | 消费方根 tokens/ | IDE 的 .qoder/skills/ / .claude/skills/ | | 变体绑定 | 每变体一个自包含目录(ADR 0020) | manifest 的 variant 字段(ADR 0014 风格) | | 装机 | teamix-evo tokens init <variant> | teamix-evo skills add 或 tokens init 联动 |

详见 packages/skills/AGENTS.md。

依赖关系

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