@teamix-evo/tokens 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teamix Evo Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @teamix-evo/tokens
+
+> Teamix Evo 设计 Token 资源包 — 每个变体一份完整、自包含的 token 集,给 CSS bundler(Tailwind v4)消费。
+
+## 定位
+
+tokens 是 Teamix Evo 的 **视觉值层**,纯资源包(无 JS 构建产物)。按 [ADR 0020](../../docs/adr/0020-design-to-tokens-skill-fusion.md) 的架构:
+
+- 每个 `variants/<name>/` 是一个**完整自包含**的 token 集 —— 不再有 default 基线 + variant 覆盖的合并模型
+- 内含 `theme.css`(Tailwind v4 `@theme {}`)与 `base.tokens.json`(W3C Design Tokens 引用数据)
+- 设计知识(哲学 / 模式 / 品牌调性 / 生成流程)归属 `@teamix-evo/skills` 的 `teamix-evo-design-<variant>` skill,**不在本包**
+- shadcn 全局偏好(pointer cursor 等)归属 `@teamix-evo/ui/src/preferences.css`,由 `teamix-evo ui init` 部署
+
+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**    | OpenTrek 品牌 token(沉稳克制 AI 副驾驶)  | `teamix-evo-design-opentrek`(自包含)      |
+| **uni-manager** | Uni-Manager 品牌 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
+
+```bash
+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. 验证
+
+```bash
+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. 端到端预览
+
+```bash
+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/` 内容。
+
+## 资源类型与策略
+
+每个变体目录下的文件按以下规则落地(ADR 0020 §3):
+
+| 文件                          | 落地路径                      | 策略        | 含义                          |
+| ----------------------------- | ----------------------------- | ----------- | ----------------------------- |
+| `theme.css`                   | `tokens/tokens.theme.css`     | regenerable | 根目录 — 每次 update 完全重写 |
+| `base.tokens.json`            | `tokens/base.tokens.json`     | regenerable | 根目录 — 每次 update 完全重写 |
+| `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`](../skills/AGENTS.md)。
+
+## 依赖关系
+
+```
+本包无运行时依赖
+@teamix-evo/registry — devDependency(validate 脚本与 schema 使用)
+CLI 包 → 运行时 require.resolve 本包获取资源路径
+```

package/manifest.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://teamix-evo.dev/schema/tokens-package/v1.json",
+  "schemaVersion": 1,
+  "package": "tokens",
+  "version": "0.5.0",
+  "engines": {
+    "teamix-evo": ">=0.1.0"
+  },
+  "description": "Design tokens for Tailwind v4 @theme. Each variant is a complete, self-contained token set.",
+  "variants": [
+    {
+      "name": "opentrek",
+      "displayName": "OpenTrek",
+      "version": "0.5.0",
+      "description": "OpenTrek brand tokens — AI 副驾驶场景的视觉语言",
+      "files": [
+        "variants/opentrek/theme.css",
+        "variants/opentrek/base.tokens.json"
+      ]
+    },
+    {
+      "name": "uni-manager",
+      "displayName": "Uni-Manager",
+      "version": "0.5.0",
+      "description": "Uni-Manager brand tokens — 统一管理类业务的视觉语言",
+      "files": [
+        "variants/uni-manager/theme.css",
+        "variants/uni-manager/base.tokens.json"
+      ]
+    }
+  ],
+  "shared": []
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@teamix-evo/tokens",
+  "version": "0.4.0",
+  "description": "Design tokens (CSS custom properties) for Teamix Evo — consumed by CSS bundlers (Tailwind v4 @theme)",
+  "type": "module",
+  "files": [
+    "default",
+    "variants",
+    "manifest.json"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "@teamix-evo/registry": "0.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "validate": "tsx scripts/validate-variants.ts",
+    "test": "echo 'validate only' && pnpm validate",
+    "typecheck": "echo 'no ts source'",
+    "lint": "echo 'no ts source'",
+    "build": "echo 'pure resource package, no build needed'"
+  }
+}