@teamix-evo/skills 0.12.1 → 0.13.0

package/src/teamix-evo-design-opentrek/rules/common-components.json

@@ -1,47 +1,9 @@
 {
-  "version": "4.0",
-  "description": "页面通用业务组件注册表。以 name 为唯一标识，子技能通过组件名引用。v4.0: 移除 G-C 编号系统，合并双层架构，shadcn 实现层不再独立注册。",
+  "version": "6.0",
+  "description": "页面通用业务组件注册表。以 name 为唯一标识，子技能通过组件名引用。v6.0: 合并 page-header-spec.md（generationChecklist/commonErrors）和 sidebar-spec.md（OpSidebar 完整规格），两份独立 spec 文件已删除。",
   "shadcnComponents": "@teamix-evo/ui 组件通过 shadcnComponent 字段直接引用组件名（如 \"Button\"、\"Dialog\"），不再独立注册条目。完整 shadcn 组件列表见 src/atoms/*.md + src/composites/*.md。",
+  "bizComponents": "OpenTrek 业务整装件（OpSidebar / OpPageContainer / ListCard / OpDetailHeader）定义在 packages/biz-ui/variants/opentrek/*.meta.md，通过 @/components/business/* 导入。",
   "components": [
-    {
-      "name": "TopNavigation",
-      "nameZh": "全局导航栏",
-      "level": "ORGANISM",
-      "universal": true,
-      "description": "全局导航栏，所有页面必需。包含Logo+产品名称(12px/500)、搜索框(胶囊形152px/border-radius:16px)、用户图标按钮组。高度48px，固定顶部。背景色为固定值#141414（非设计系统token）。Logo区域177px宽。无环境选择器。",
-      "layer": "business",
-      "children": [
-        "Logo",
-        "ProductName",
-        "SearchBar",
-        "UserMenu"
-      ],
-      "props": {
-        "fixed": "boolean, 默认true",
-        "height": "number, 默认48",
-        "backgroundColor": "string, 默认#141414(非设计系统token)"
-      },
-      "shadcnComponent": null
-    },
-    {
-      "name": "Sidebar",
-      "nameZh": "侧边导航",
-      "level": "ORGANISM",
-      "universal": true,
-      "layer": "business",
-      "description": "左侧导航，TWO_COL布局必需。包含品牌区（Logo+产品名）和导航分组菜单。展开宽度240px，收起宽度68px（详见 design-tokens.json sidebarRules）。768px响应式折叠为抽屉。色彩全部引用 --sidebar-* token。容器禁止任何外边框（右侧/底部分割线），品牌区与菜单区之间无分割线。",
-      "children": [
-        "NavGroup",
-        "MenuItem"
-      ],
-      "props": {
-        "collapsed": "boolean, 默认false",
-        "mode": "\"inline\" | \"vertical\"",
-        "width": "number, 默认240（收起态68，详见 design-tokens.json sidebarRules）"
-      },
-      "shadcnComponent": "Sidebar",
-      "shadcnRef": "boundaries.md(I2)"
-    },
     {
       "name": "Breadcrumb",
       "nameZh": "面包屑基础组件",
@@ -83,10 +45,10 @@
       "level": "ORGANISM",
       "universal": true,
       "layer": "business",
-      "description": "页头业务组件，所有页面必需。统一封装标题基础组件和面包屑基础组件，根据页面级别自动选择展示形态。L1一级页面使用标题基础组件，L2二级页面使用面包屑基础组件。必须在白卡容器内顶部渲染。",
+      "description": "页头业务组件，所有页面必需。统一封装标题基础组件和面包屑基础组件，根据页面级别自动选择展示形态。L1一级页面使用标题基础组件，L2二级页面使用面包屑基础组件。在 OpPageContainer 内置白卡顶部渲染。",
       "visualSpec": {
         "height": "64px (h-16)",
-        "padding": "0 (水平对齐由 Card.paddingX = var(--card-padding-x) = 20px 提供；禁止重复设置）",
+        "padding": "0 (水平对齐由 OpPageContainer 内置白卡 p-6 = 24px 提供；禁止重复设置）",
         "background": "transparent (默认态无底色)",
         "border": "无 (默认态无底边框)"
       },
@@ -109,7 +71,7 @@
           "scenario": "二级页面（详情页、独占式配置页）",
           "spec": {
             "containerHeight": "64px (h-16)",
-            "containerPadding": "0（水平对齐由 Card.paddingX = var(--card-padding-x) = 20px 提供）",
+            "containerPadding": "0（水平对齐由 OpPageContainer 内置白卡 p-6 = 24px 提供）",
             "itemFontSize": "18px（与标题同字号）",
             "itemFontWeight": "500 (medium)",
             "parentItem": {
@@ -131,29 +93,6 @@
           }
         }
       },
-      "breadcrumbVisualSpec": {
-        "description": "面包屑导航视觉规范。引用 design-tokens.json typographyTokens 和 colorMapping。",
-        "itemFontSize": "18px（与标题同字号）",
-        "itemFontWeight": "500 (medium)",
-        "parentItem": {
-          "color": "hsl(var(--gray-secondary))",
-          "hover": "hsl(var(--gray-primary))",
-          "clickable": true,
-          "note": "父级项本身即可点击返回"
-        },
-        "currentItem": {
-          "color": "hsl(var(--gray-title))",
-          "clickable": false,
-          "note": "最后一项不可点击（cursor-default）"
-        },
-        "separator": {
-          "icon": "ChevronRight",
-          "size": "20px (w-5 h-5)",
-          "color": "hsl(var(--muted-foreground))"
-        },
-        "itemGap": "4px (gap-1)",
-        "constraint": "有面包屑时禁止同时显示 showBack 返回箭头。面包屑父级项本身即可点击返回。"
-      },
       "stickyBehavior": {
         "description": "PageHeader 的 sticky 行为由白卡容器层包裹实现，不在 PageHeader 组件内部实现。",
         "position": "PageHeader 必须在 Card 白卡容器内顶部，由 Card 的滚动容器包裹 sticky 外壳",
@@ -186,7 +125,35 @@
         "description": "string, 页面描述（可选，默认不显示）",
         "actions": "node, 右侧操作按钮组"
       },
-      "relatedSpec": "完整约束见 pages/detail-page/SKILL.md §4.0",
+      "dividerClarification": "PageHeader 容器自身不设置 border/background/box-shadow；与内容区之间可选 border-bottom: 1px solid hsl(var(--gray-line)) 实现功能性分割线（默认不加）。",
+      "generationChecklist": [
+        { "id": 1, "check": "容器高度", "correct": "height: 64px", "commonError": "56px / 48px / 72px" },
+        { "id": 2, "check": "容器 padding", "correct": "padding: 0", "commonError": "padding: 0 16px / 0 20px" },
+        { "id": 3, "check": "容器外框 border", "correct": "无（不设置 border-top/left/right）", "commonError": "border: 1px solid / 四边框" },
+        { "id": 4, "check": "容器 background", "correct": "transparent（不设置）", "commonError": "background: white / hsl(...)" },
+        { "id": 5, "check": "容器 box-shadow", "correct": "无", "commonError": "box-shadow: 0 1px ..." },
+        { "id": 6, "check": "面包屑字号", "correct": "font-size: var(--font-size-2xl) (18px)", "commonError": "--font-size-base / --font-size-lg / 12px / 14px" },
+        { "id": 7, "check": "面包屑字重", "correct": "font-weight: var(--font-weight-medium) (500)", "commonError": "400 / 600 / --font-weight-normal" },
+        { "id": 8, "check": "面包屑 gap", "correct": "gap: 4px", "commonError": "6px / 8px / 12px" },
+        { "id": 9, "check": "分隔符类型", "correct": "ChevronRight SVG <polyline points='9 18 15 12 9 6'/>", "commonError": "文本 / > ›" },
+        { "id": 10, "check": "分隔符尺寸", "correct": "width: 20px; height: 20px", "commonError": "14px / 16px / 24px" },
+        { "id": 11, "check": "分隔符颜色", "correct": "hsl(var(--muted-foreground))", "commonError": "--gray-line / --gray-primary / 硬编码色值" },
+        { "id": 12, "check": "父项颜色", "correct": "hsl(var(--gray-secondary))", "commonError": "--muted-foreground / --gray-primary" },
+        { "id": 13, "check": "当前项颜色", "correct": "hsl(var(--gray-title))", "commonError": "--gray-secondary / --muted-foreground" },
+        { "id": 14, "check": "PageHeader 位置", "correct": "OpPageContainer 内置白卡内部（第一个子元素）", "commonError": "白卡外部 / body 直接子元素" },
+        { "id": 15, "check": "标题与面包屑互斥", "correct": "L1/L2 必须二选一", "commonError": "两者同时出现" },
+        { "id": 16, "check": "L1 标题文本", "correct": "font-size:18px; font-weight:500; color:hsl(var(--gray-primary))", "commonError": "字号偏大 / 颜色用 secondary / 追加副标题" }
+      ],
+      "commonErrors": [
+        { "error": "separator 颜色用 --gray-tertiary 或硬编码", "correct": "hsl(var(--muted-foreground))", "cause": "legacy 别名未废弃" },
+        { "error": "容器四边框 border: 1px solid", "correct": "仅可选下方分割线 border-bottom，容器自身无 border", "cause": "与 ContentCard 边框规则混淆" },
+        { "error": "高度设为 48px / 56px", "correct": "必须 height: 64px", "cause": "与 Toolbar / AppBar 混淆" },
+        { "error": "字号用 --font-size-base / --font-size-lg", "correct": "var(--font-size-2xl) (18px)", "cause": "Token scale 理解不足" },
+        { "error": "gap 设为 6px / 8px / 12px", "correct": "gap: 4px", "cause": "与 button-gap 混淆" },
+        { "error": "分隔符用文本 / > ›", "correct": "SVG ChevronRight 20×20px", "cause": "旧版文本习惯" },
+        { "error": "PageHeader 放在白卡外部", "correct": "必须在 OpPageContainer 内置白卡内部（第一个子元素）", "cause": "布局层级误解" },
+        { "error": "padding 设为 0 16px / 0 20px", "correct": "padding: 0（水平由 OpPageContainer 内置白卡 p-6 提供）", "cause": "重复设置水平间距" }
+      ],
       "shadcnComponent": null
     },
     {
@@ -425,7 +392,7 @@
       "level": "ORGANISM",
       "universal": false,
       "layer": "business",
-      "description": "下拉维度选择 + 文本输入的组合搜索控件，位于 ActionToolbar 右侧。容器式 border，内部 select + divider + input + button。",
+      "description": "下拉维度选择 + 文本输入的组合搜索控件，位于 ActionToolbar 中。容器式 border，内部 select + divider + input + button。v6.1: 从独立 search-combo-spec.md 合并至此。",
       "children": [
         "SearchDimension",
         "SearchDivider",
@@ -433,11 +400,174 @@
         "SearchButton"
       ],
       "props": {
-        "dimensions": "array, 搜索维度选项",
+        "dimensions": "array, 搜索维度选项 [{label, value}]",
         "defaultDimension": "string, 默认维度",
         "placeholder": "string, 输入框占位符"
       },
-      "specRef": "pages/list-page/_shared/search-combo-spec.md"
+      "placement": {
+        "parent": "ActionToolbar（直接子元素）",
+        "position": "位于 .left-actions 之后、.right-tools 之前",
+        "gap": "20px (var(--action-toolbar-search-combo-gap))",
+        "css": "margin-left: calc(var(--action-toolbar-search-combo-gap) - var(--button-gap))"
+      },
+      "visualSpec": {
+        "container": {
+          "border": "1px solid hsl(var(--gray-line))",
+          "borderRadius": "8px (--input-radius)",
+          "display": "flex",
+          "alignItems": "center",
+          "height": "32px",
+          "minWidth": "200px"
+        },
+        "innerElements": {
+          "select": "border:none; padding-left:8px; font-size:var(--font-size-base); color:hsl(var(--gray-primary)); outline:none; appearance:none; background:transparent",
+          "input": "border:none; padding:0 8px; font-size:var(--font-size-base); color:hsl(var(--gray-primary)); outline:none; flex:1; min-width:80px",
+          "divider": "width:1px; height:20px; background:hsl(var(--gray-line)); flex-shrink:0",
+          "button": "border:none; background:transparent; padding:0 8px; cursor:pointer; display:flex; align-items:center"
+        },
+        "states": {
+          "focus": "border-color: hsl(var(--primary)); box-shadow: 0 0 0 2px hsl(var(--ring) / 0.2)",
+          "hover": "border-color: hsl(var(--gray-tertiary))"
+        },
+        "filterTag": {
+          "height": "24px",
+          "padding": "0 8px",
+          "borderRadius": "4px",
+          "background": "hsl(var(--gray-fill))",
+          "border": "1px solid transparent",
+          "labelColor": "hsl(var(--gray-secondary))",
+          "valueColor": "hsl(var(--primary))",
+          "fontSize": "var(--font-size-base) (12px)",
+          "closeIconSize": "12px",
+          "closeHoverColor": "hsl(var(--gray-primary))",
+          "gap": "8px（多 Tag 横排间距）"
+        }
+      },
+      "interactions": {
+        "dimensionSwitch": "切换维度时清空输入框并重新聚焦",
+        "search": "点击搜索按钮或 Enter → 构建筛选条件 → 刷新列表 → 重置到第 1 页",
+        "clear": "点击 × 清空输入框 → 维度切回「全部」→ 刷新列表 → 重置分页",
+        "emptySearch": "输入为空时点击搜索 → 清除搜索条件 → 刷新列表 → 重置分页",
+        "filterTagClose": "点击 FilterTag × → 移除该条件 → 刷新列表 → 重置分页",
+        "filterTagClearAll": "多条件时提供「清空全部」链接"
+      },
+      "defaultDimensions": [
+        { "label": "全部", "value": "all" },
+        { "label": "名称", "value": "name" },
+        { "label": "ID", "value": "id" }
+      ],
+      "forbidden": [
+        "嵌套在 .right-tools 内（会被 margin-left:auto 推到最右）",
+        "嵌套在 .left-actions 内（间距被 gap=8px 控制，而非 20px）",
+        "与 .left-actions 间距为 8px / 12px / 16px / 24px 等非 20 值"
+      ],
+      "tokens": {
+        "--action-toolbar-search-combo-gap": "20px（与 left-actions 间距）",
+        "--font-size-base": "12px（输入/维度/FilterTag 字号）",
+        "--gray-line": "容器边框、分隔线",
+        "--gray-primary": "输入文字颜色",
+        "--gray-secondary": "FilterTag label 颜色",
+        "--gray-tertiary": "hover 态边框",
+        "--gray-fill": "FilterTag 背景",
+        "--primary": "focus 边框、FilterTag value 颜色",
+        "--ring": "focus 外发光"
+      }
+    },
+    {
+      "name": "OpSidebar",
+      "nameZh": "OpenTrek 侧边导航（整装件）",
+      "level": "ORGANISM",
+      "universal": true,
+      "layer": "business",
+      "description": "OpenTrek 全局侧边栏整装件，替代原始 Sidebar primitives。内置 SidebarProvider，TWO_COL 布局时显示，SINGLE_COL/fullscreen 时隐藏。所有 L1/L2 页面自动继承。",
+      "importPath": "@/components/business/op-sidebar",
+      "container": {
+        "position": "fixed",
+        "expandedWidth": "240px (var(--layout-sidebar-width))",
+        "collapsedWidth": "68px",
+        "background": "hsl(var(--sidebar))",
+        "zIndex": 100,
+        "display": "flex flex-col",
+        "transition": "width 0.2s ease",
+        "noBorderRight": true,
+        "responsive": "768px 断点折叠为抽屉（Sheet 模式）"
+      },
+      "header": {
+        "height": "由内容撑开（禁止硬编码固定高度）",
+        "padding": "16px 16px 0",
+        "display": "flex",
+        "alignItems": "center",
+        "gap": "var(--gap-xs) (4px)",
+        "collapsedPadding": "16px 0 0",
+        "collapsedFlexDirection": "column",
+        "collapsedAlignItems": "center"
+      },
+      "logo": {
+        "containerHeight": "32px",
+        "expandedLogo": { "file": "_assets/OP_DEV-2.svg", "width": "154px", "height": "32px", "viewBox": "0 0 404 84" },
+        "collapsedLogo": { "file": "_assets/OP_LOGO.svg", "width": "30px", "height": "30px", "viewBox": "0 0 84 84" },
+        "inlineSvgRequired": true,
+        "inlineSvgRules": [
+          "外层 <rect> 使用 fill='currentColor'，内层图案使用 fill='white'，容器通过 text-foreground 类控色",
+          "<clipPath> 的 id 必须全局唯一（如 opai-logo-clip-{page-name}），避免同 DOM 多个 SVG id 冲突",
+          "Logo 组件尺寸：size-8（32×32px）",
+          "path 数据必须来自 _assets/ 中对应 SVG 文件的真实内容，禁止简化或自绘近似图形"
+        ]
+      },
+      "brandAssets": [
+        { "product": "AI Gateway", "file": "_assets/OP_AI GATEWAY.svg" },
+        { "product": "AI Studio", "file": "_assets/OP_AI STUDIO.svg" },
+        { "product": "Agent Runtime", "file": "_assets/OP_AGENT RUNTIME.svg" },
+        { "product": "DEV", "file": "_assets/OP_DEV-2.svg" },
+        { "product": "OPS", "file": "_assets/OP_OPS.svg" },
+        { "product": "通用 Logo（产品线未明确）", "file": "_assets/OP_LOGO.svg" }
+      ],
+      "content": {
+        "flex": 1,
+        "paddingTop": "24px",
+        "paddingBottom": "12px",
+        "overflowY": "auto",
+        "menuItemHeight": "40px"
+      },
+      "collapseToggle": {
+        "collapseButton": { "icon": "Lucide PanelLeftClose（箭头朝左）", "visible": "展开态", "position": "sidebar-header 右侧 margin-left:auto" },
+        "expandButton": { "icon": "Lucide PanelLeftOpen（箭头朝右）", "visible": "收起态", "position": "Logo 下方居中 margin-top:8px" },
+        "size": "18px × 18px",
+        "color": "hsl(var(--muted-foreground))",
+        "hoverColor": "hsl(var(--gray-primary))"
+      },
+      "footer": {
+        "padding": "12px 12px 16px 24px",
+        "display": "flex",
+        "alignItems": "center",
+        "gap": "var(--button-gap) (8px)",
+        "avatar": { "size": "28px", "borderRadius": "50%", "background": "hsl(var(--sidebar-active))", "fontSize": "var(--font-size-base) (12px)", "fontWeight": 600, "content": "用户姓名最后一个字" },
+        "username": { "fontSize": "var(--font-size-lg) (14px)", "fontWeight": "500 (medium)", "color": "hsl(var(--sidebar-item))", "overflow": "hidden + text-overflow: ellipsis", "whiteSpace": "nowrap" },
+        "moreButton": { "size": "28px", "icon": "MoreVertical", "color": "hsl(var(--muted-foreground))", "hoverBg": "hsl(var(--sidebar-hover))" },
+        "collapsedState": { "padding": "12px 10px 16px", "justifyContent": "center", "usernameHidden": true, "moreButtonHidden": true }
+      },
+      "props": {
+        "brand": "ReactNode, 品牌区域（Logo + 产品名）",
+        "brandCollapsed": "ReactNode, 收起态品牌区域",
+        "headerAction": "ReactNode, 品牌区下方操作插槽（如 ContextSwitcher）",
+        "navSections": "SidebarSection[], 导航分组",
+        "bottomSections": "SidebarSection[], 贴底分组",
+        "footer": "ReactNode, 底部用户信息区域",
+        "collapsible": "'offcanvas' | 'icon' | 'none'",
+        "variant": "'sidebar' | 'floating' | 'inset'"
+      },
+      "forbidden": [
+        "使用纯文字模拟 Logo（如用 div + font-weight:bold 模拟品牌标识）",
+        "使用 Lucide/其他图标库图标占位 Logo（如 Layers、Diamond 等）",
+        "使用外部 URL 引用 Logo（<img src>）",
+        "使用非 _assets/ 目录的图片资源",
+        "自绘简化 SVG path 代替真实 Logo（即使视觉近似也不允许）",
+        "多个页面使用相同的 clipPath id（会导致渲染冲突）",
+        "容器右侧/底部添加 border 分割线",
+        "品牌区与菜单区之间添加分割线",
+        "硬编码 sidebar-header 高度（必须由内容撑开）"
+      ],
+      "shadcnComponent": "Sidebar"
     },
     {
       "name": "ContextSwitcher",
@@ -445,7 +575,7 @@
       "level": "ORGANISM",
       "universal": false,
       "layer": "business",
-      "description": "全局上下文切换器（组织/资源集），位于 TopNavigation 右侧（用户菜单前）。切换后影响全局数据范围。",
+      "description": "全局上下文切换器（组织/资源集），位于 OpSidebar headerAction 插槽。切换后影响全局数据范围。",
       "children": [],
       "props": {
         "type": "\"organization\" | \"resourceSet\"",
@@ -454,7 +584,7 @@
         "loading": "boolean, 加载中状态",
         "onChange": "(value: string) => void"
       },
-      "placement": "TopNavigation 右侧，用户图标前，与用户图标间距 16px"
+      "placement": "OpSidebar headerAction 插槽"
     },
     {
       "name": "Steps",
@@ -503,7 +633,7 @@
         "data": "object, 数据项（与 products/{产品}/cards.json slot 映射）",
         "actions": "Array<{ label, onClick, destructive? }>"
       },
-      "specRef": "pages/list-page/patterns/card-list.md §9.1",
+      "specRef": "pages/list-page/_shared/item-card-spec.md §1",
       "relatedPageType": "ListPage(pure-card / standard-card / view-toggle), Dashboard, Workspace, Overview",
       "shadcnComponent": "Card",
       "shadcnRef": "boundaries.md(C3), rules/styling.json(S1)"
@@ -524,7 +654,7 @@
         "gap": "number, 卡片间距，默认 16",
         "alignContent": "'start'，防止卡片拉伸"
       },
-      "specRef": "pages/list-page/patterns/card-list.md §9.2",
+      "specRef": "pages/list-page/_shared/item-card-spec.md §2",
       "shadcnComponent": null
     },
     {
@@ -540,7 +670,7 @@
         "mode": "'hover-slidebar' | 'hover-fade' | 'always-visible'（v7.2 三态收敛）",
         "rows": "1 | 2，complex 模式可分行"
       },
-      "specRef": "pages/list-page/patterns/card-list.md §9.3",
+      "specRef": "pages/list-page/_shared/item-card-spec.md §3",
       "shadcnComponent": null
     },
     {

package/src/teamix-evo-design-opentrek/rules/component-specs.json

@@ -194,8 +194,8 @@
           "tabSpacing": "40px",
           "containerBorder": "底贯穿 1px --gray-line",
           "trigger": "h-8 leading-[22px] pt-0 pb-2.5",
-          "activeText": "--primary + medium + 2px 底部蓝色指示线",
-          "normalText": "--gray-secondary + regular"
+          "activeText": "--foreground + semibold + 2px 底部 --tab-indicator 指示线",
+          "normalText": "--muted-foreground + regular"
         }
       ]
     },