@teamix-evo/skills 0.5.0 → 0.6.0

package/src/teamix-evo-design-opentrek/rules/sidebar-spec.md

@@ -0,0 +1,217 @@
+# Sidebar 完整规格
+
+> 适用于所有 L1/L2 页面的侧边栏框架组件。Sidebar 是全局框架组件（`page-frame.json` → `frameComponents.sidebar`），所有含 Sidebar 的页面自动继承此规范。
+>
+> **真相源**：
+> - 宽度/Token → [`design-tokens.json`](./design-tokens.json) → `sidebarRules`
+> - 框架继承 → [`page-frame.json`](./page-frame.json) → `frameComponents.sidebar`
+> - 品牌 Logo SVG → [`_assets/`](./_assets/)
+
+---
+
+## 1. 整体容器
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| position | `fixed` | 固定定位，不随内容滚动 |
+| width | `var(--layout-sidebar-width)` (240px) | 展开态宽度 |
+| background | `hsl(var(--sidebar))` | 即 `--gray-muted` |
+| z-index | `100` | 高于内容层 |
+| display | `flex` / `flex-direction: column` | 垂直排列 header + content + footer |
+| transition | `width 0.2s ease` | 展开/收起动画 |
+
+---
+
+## 2. sidebar-header 容器
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| height | 不固定（由内容撑开） | 禁止硬编码 56px 等固定高度 |
+| padding | `16px 16px 0` | 顶部 16px 保证 Logo 距页面顶边距 |
+| display | `flex` | 水平排列 Logo + 折叠按钮 |
+| align-items | `center` | 垂直居中 |
+| gap | `var(--gap-xs)` (4px) | Logo 与折叠按钮间距 |
+
+---
+
+## 3. sidebar-logo 容器
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| height | `32px` | Logo 可视区域高度 |
+| display | `flex` | 内部元素水平排列 |
+| align-items | `center` | 垂直居中 |
+| overflow | `hidden` | 防止内容溢出 |
+| flex-shrink | `0` | 禁止压缩 |
+
+---
+
+## 4. 品牌 SVG Logo
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| width | `154px` | 保持宽高比 404:84 |
+| height | `32px` | 与容器高度一致 |
+| viewBox | `0 0 404 84` | 原始设计稿尺寸 |
+| 来源文件 | `OP_DEV-2.svg` | 完整品牌矢量图（默认产品） |
+
+---
+
+## 5. sidebar-content 区域
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| flex | `1` | 占满剩余空间 |
+| padding-top | `24px` | 导航菜单与 header 的间距 |
+| padding-bottom | `12px` | 底部留白 |
+| overflow-y | `auto` | 内容超出时可滚动 |
+
+---
+
+## 6. 收起态（Collapsed）
+
+> 点击收起按钮后，侧栏从 240px 收窄至 68px，Logo 切换为纯图标，展开按钮置于 Logo 下方。
+
+### 6.1 整体布局
+
+| 属性 | 展开态 | 收起态 | 说明 |
+|------|--------|--------|------|
+| sidebar width | `240px` | `68px` | CSS 变量 `--layout-sidebar-width` 仅控制展开态 |
+| transition | — | `width 0.2s ease` | 展开/收起动画 |
+| overflow | `hidden` | `visible` | 收起态允许 flyout 溢出 |
+
+### 6.2 sidebar-header 收起态
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| padding | `16px 0 0` | 仅保留顶部间距，水平归零 |
+| flex-direction | `column` | 垂直排列 Logo + 展开按钮 |
+| align-items | `center` | 水平居中 |
+
+### 6.3 收起态 Logo
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| 来源文件 | `OP_LOGO.svg` | 仅图标（黑色圆角矩形 + 白色钻石图案），无产品文字 |
+| width × height | `30px × 30px` | 适配 68px 侧栏宽度 |
+| viewBox | `0 0 84 84` | 原始正方形画布 |
+| 切换逻辑 | 完整 Logo 隐藏 → 收起 Logo 显示 | CSS class `.collapsed-logo` 控制 |
+
+### 6.4 展开按钮
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| 位置 | Logo 正下方 | `margin-top: 8px` |
+| 尺寸 | `18px × 18px` | 与收起按钮一致 |
+| 图标 | Lucide `PanelLeftOpen` | `<path d="m14 9 3 3-3 3"/>` 方向朝右 |
+| 颜色 | `hsl(var(--muted-foreground))` | hover → `hsl(var(--gray-primary))` |
+| 展开态可见性 | `display: none` | 仅收起态显示 |
+
+### 6.5 收起/展开按钮对照
+
+| 按钮 | 图标 | 可见条件 | 位置 |
+|------|------|----------|------|
+| 收起按钮 `.sidebar-collapse-btn` | Lucide `PanelLeftClose`（箭头朝左） | 展开态 | sidebar-header 右侧（`margin-left: auto`） |
+| 展开按钮 `.sidebar-expand-btn` | Lucide `PanelLeftOpen`（箭头朝右） | 收起态 | Logo 下方居中 |
+
+---
+
+## 7. 品牌 Logo 资源清单
+
+| 文件名 | 用途 | 存放路径 |
+|--------|------|----------|
+| `OP_DEV-2.svg` | 展开态完整 Logo（含 OPENTREK DEV 文字） | `rules/_assets/` |
+| `OP_LOGO.svg` | 收起态纯图标 Logo | `rules/_assets/` |
+| `OP_AI STUDIO.svg` | AI Studio 产品变体 | `rules/_assets/` |
+| `OP_AGENT RUNTIME.svg` | Agent Runtime 产品变体 | `rules/_assets/` |
+| `OP_OPS.svg` | OPS 产品变体 | `rules/_assets/` |
+| `OP_AI GATEWAY.svg` | AI Gateway 产品变体 | `rules/_assets/` |
+
+### 7.1 Logo 资源引用规则
+
+品牌 Logo **必须使用** `_assets/` 目录中的 SVG 文件，禁止使用文字占位或外部图片链接。
+
+**资源映射表**：
+
+| 产品线 | SVG 文件 | 使用场景 |
+|---|---|---|
+| AI Gateway | `_assets/OP_AI GATEWAY.svg` | AI 网关相关页面 |
+| AI Studio | `_assets/OP_AI STUDIO.svg` | AI 开发平台相关页面 |
+| Agent Runtime | `_assets/OP_AGENT RUNTIME.svg` | Agent 运行时相关页面 |
+| DEV | `_assets/OP_DEV-2.svg` | 开发者工具相关页面 |
+| OPS | `_assets/OP_OPS.svg` | 运维相关页面 |
+| 通用 Logo | `_assets/OP_LOGO.svg` | 产品线未明确时使用 |
+
+**引用方式**：
+- 生成页面时，根据当前产品线从上表选择对应 SVG
+- Logo 放置在 Sidebar 品牌区域（顶部），与产品名文字并排
+- **必须以 inline SVG 方式嵌入**（直接将 SVG path 写入 JSX/HTML），禁止用 `<img src>` 或外部引用
+- 仅截取 SVG 的**图标部分**（viewBox `0 0 84 84`），文字（OPENTREK / AI GATEWAY）由 Sidebar 右侧 `<span>` 双行渲染
+
+**inline SVG 实现要求**：
+- 外层 `<rect>` 使用 `fill="currentColor"`，内层图案使用 `fill="white"` — 容器通过 `text-foreground` 类控色，自动适配主题
+- `<clipPath>` 的 `id` 必须全局唯一（按页面命名，如 `opai-logo-clip-{page-name}`），避免同 DOM 多个 SVG id 冲突
+- Logo 组件尺寸：`size-8`（32×32px），与 §3 sidebar-logo 容器 `height: 32px` 对齐
+- path 数据必须来自 `_assets/` 中对应 SVG 文件的真实内容，禁止简化或自绘近似图形
+
+**禁止项**：
+- ❌ 使用纯文字模拟 Logo（如用 div + font-weight:bold 模拟品牌标识）
+- ❌ 使用 Lucide/其他图标库图标占位（如 Layers、Diamond 等）
+- ❌ 使用外部 URL 引用 Logo
+- ❌ 使用非 `_assets/` 目录的图片资源
+- ❌ 自绘简化 SVG path 代替真实 Logo（即使视觉近似也不允许）
+- ❌ 多个页面使用相同的 clipPath id（会导致渲染冲突）
+
+---
+
+## 8. Sidebar Footer 用户信息区域
+
+> 侧边栏底部固定的用户身份展示区域。
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| padding | `12px 12px 16px 24px` | 展开态内边距 |
+| display | `flex` | 水平排列 |
+| align-items | `center` | 垂直居中 |
+| gap | `var(--button-gap)` (8px) | 元素间距 |
+
+### 8.1 头像（sidebar-avatar）
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| 尺寸 | `28px × 28px` | 固定圆形 |
+| border-radius | `50%` | 圆形 |
+| background | `hsl(var(--sidebar-active))` | 与菜单激活态背景一致 |
+| font-size | `var(--font-size-base)` (12px) | 头像内文字 |
+| font-weight | `600` | 半粗体 |
+| 内容 | 用户姓名**最后一个字** | 如「小王」→ 显示「王」 |
+
+### 8.2 用户名（sidebar-username）
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| font-size | `var(--font-size-lg)` (14px) | 用户名字号 |
+| font-weight | `var(--font-weight-medium)` (500) | 中等字重 |
+| color | `hsl(var(--sidebar-item))` | 与菜单项文字颜色一致 |
+| overflow | `hidden` + `text-overflow: ellipsis` | 超长截断 |
+| white-space | `nowrap` | 禁止换行 |
+| 默认值 | `小王` | 占位用户名 |
+
+### 8.3 更多按钮（sidebar-more）
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| 尺寸 | `28px × 28px` | 正方形点击区域 |
+| border-radius | `var(--radius-sm)` (4px) | 微圆角 |
+| 图标 | 三点竖排（MoreVertical） | `<circle cx="12" cy="5/12/19" r="2"/>` |
+| color | `hsl(var(--muted-foreground))` | hover → `hsl(var(--gray-primary))` |
+| hover background | `hsl(var(--sidebar-hover))` | 悬停底色 |
+
+### 8.4 收起态 Footer
+
+| 属性 | 值 | 说明 |
+|------|------|------|
+| padding | `12px 10px 16px` | 收窄内边距 |
+| justify-content | `center` | 居中显示头像 |
+| 用户名 | `display: none` | 隐藏 |
+| 更多按钮 | `display: none` | 隐藏 |

package/src/teamix-evo-design-opentrek/rules/styling.json

@@ -0,0 +1,188 @@
+{
+  "version": "7.0",
+  "description": "@teamix-evo/ui 样式规范 + TrekClaw 全局禁止事项。8条样式规则（S1-S8）+ 10条禁止事项（F1-F10），所有页面类型通用。",
+  "stylingRules": [
+    {
+      "id": "S1",
+      "rule": "className仅用于布局，不用于覆盖组件颜色/字体",
+      "severity": "ERROR",
+      "scope": "global",
+      "forbidden": "className=\"bg-blue-100 text-blue-900 font-bold\"",
+      "correct": "className=\"max-w-md mx-auto\"",
+      "fixPriority": 1
+    },
+    {
+      "id": "S2",
+      "rule": "不用 space-x-* / space-y-*，改用 flex + gap-*",
+      "severity": "ERROR",
+      "scope": "global",
+      "forbidden": "className=\"space-y-4\"",
+      "correct": "className=\"flex flex-col gap-4\"",
+      "fixPriority": 2
+    },
+    {
+      "id": "S3",
+      "rule": "等宽高用 size-*，不用 w-* h-*",
+      "severity": "WARN",
+      "scope": "global",
+      "forbidden": "className=\"w-10 h-10\"",
+      "correct": "className=\"size-10\"",
+      "fixPriority": 3
+    },
+    {
+      "id": "S4",
+      "rule": "用 truncate 简写文本截断",
+      "severity": "WARN",
+      "scope": "global",
+      "forbidden": "className=\"overflow-hidden text-ellipsis whitespace-nowrap\"",
+      "correct": "className=\"truncate\"",
+      "fixPriority": 4
+    },
+    {
+      "id": "S5",
+      "rule": "不用手动 dark: 颜色覆盖，用语义 token",
+      "severity": "ERROR",
+      "scope": "global",
+      "forbidden": "className=\"bg-white dark:bg-gray-950\"",
+      "correct": "className=\"bg-background text-foreground\"",
+      "fixPriority": 5
+    },
+    {
+      "id": "S6",
+      "rule": "用 cn() 处理条件类名，不用模板字符串三元表达式",
+      "severity": "ERROR",
+      "scope": "global",
+      "forbidden": "className={`flex ${isActive ? 'bg-primary' : 'bg-muted'}`}",
+      "correct": "className={cn('flex', isActive ? 'bg-primary text-primary-foreground' : 'bg-muted')}",
+      "fixPriority": 6
+    },
+    {
+      "id": "S7",
+      "rule": "overlay 组件不手动设置 z-index",
+      "severity": "ERROR",
+      "scope": "global",
+      "forbidden": "Dialog/Sheet/Popover/Tooltip 等加 className=\"z-50\"",
+      "correct": "移除 z-index，组件自带层级管理",
+      "fixPriority": 7
+    },
+    {
+      "id": "S8",
+      "rule": "不用原始色值表示状态/状态指示",
+      "severity": "ERROR",
+      "scope": "global",
+      "forbidden": "className=\"text-emerald-600\" / className=\"text-green-500\"",
+      "correct": "<Badge variant=\"secondary\">+20.1%</Badge> / <span className=\"text-destructive\">-3.2%</span>",
+      "fixPriority": 8
+    }
+  ],
+  "customizationPriority": [
+    "1. 内置 variants（variant=\"outline\"/\"destructive\" 等）",
+    "2. 语义色值（bg-primary / text-muted-foreground 等）",
+    "3. CSS 变量（在全局 CSS 文件中定义，见 customization.md）"
+  ],
+  "keyPatterns": {
+    "spacing": {
+      "correct": "flex flex-col gap-4",
+      "wrong": "space-y-4"
+    },
+    "dimensions": {
+      "correct": "size-10",
+      "wrong": "w-10 h-10"
+    },
+    "statusColor": {
+      "correct": "<Badge variant=\"secondary\">+20.1%</Badge>",
+      "wrong": "<span className=\"text-emerald-600\">+20.1%</span>"
+    },
+    "iconInButton": {
+      "correct": "<SearchIcon data-icon=\"inline-start\" />",
+      "wrong": "<SearchIcon className=\"mr-2 size-4\" />"
+    }
+  },
+  "forbiddenRules": [
+    {
+      "id": "F1",
+      "rule": "禁止硬编码色值（如 #333333、rgb(...)）",
+      "severity": "ERROR",
+      "scope": "global",
+      "correct": "使用 hsl(var(--gray-primary)) 等 CSS 变量引用，见 design-tokens.json colorMapping",
+      "fixPriority": 1
+    },
+    {
+      "id": "F2",
+      "rule": "禁止硬编码尺寸（如 h-8、text-xs）",
+      "severity": "ERROR",
+      "scope": "global",
+      "correct": "使用 CSS 变量（如 h-[var(--input-height)]），见 design-tokens.json componentDimensions",
+      "fixPriority": 2
+    },
+    {
+      "id": "F3",
+      "rule": "禁止按组件新增重复语义变量",
+      "severity": "ERROR",
+      "scope": "global",
+      "correct": "检索 design-tokens.css 中已有变量，找到语义匹配的变量直接复用；仅当完全没有可对应变量时才允许新增",
+      "fixPriority": 3
+    },
+    {
+      "id": "F4",
+      "rule": "禁止页头添加底色或下边框",
+      "severity": "ERROR",
+      "scope": "PageHeader",
+      "correct": "页头保持透明无底色",
+      "fixPriority": 4
+    },
+    {
+      "id": "F5",
+      "rule": "outline 按钮禁止使用 border-input",
+      "severity": "ERROR",
+      "scope": "Button",
+      "correct": "使用 border-gray-line",
+      "fixPriority": 5
+    },
+    {
+      "id": "F6",
+      "rule": "禁止直接在组件中写 font-size: 12px",
+      "severity": "ERROR",
+      "scope": "global",
+      "correct": "使用 var(--input-font-size)",
+      "fixPriority": 6
+    },
+    {
+      "id": "F7",
+      "rule": "禁止使用 gap-4 替代变量",
+      "severity": "ERROR",
+      "scope": "global",
+      "correct": "使用 gap-[var(--card-gap)]",
+      "fixPriority": 7
+    },
+    {
+      "id": "F8",
+      "rule": "禁止在 DialogTitle 中加图标",
+      "severity": "ERROR",
+      "scope": "Dialog",
+      "correct": "标题区只放纯文字",
+      "fixPriority": 8
+    },
+    {
+      "id": "F9",
+      "rule": "弹窗确定按钮禁止加 disabled 禁用态",
+      "severity": "ERROR",
+      "scope": "Dialog",
+      "correct": "始终可点击，校验后反馈错误信息",
+      "fixPriority": 9
+    },
+    {
+      "id": "F10",
+      "rule": "hover 时禁止将 boxShadow 设为 undefined",
+      "severity": "WARN",
+      "scope": "HoverCard",
+      "correct": "与 breathingGlow 0% 帧一致的初始值 + animation",
+      "fixPriority": 10
+    }
+  ],
+
+  "designPrinciplesRef": {
+    "reference": "foundations.md §1 + boundaries.md §自定义优先级",
+    "description": "设计原则集中定义在 foundations.md，本文件只关注样式规则（S1-S8）。"
+  }
+}