@teamix-evo/skills 0.4.0 → 0.6.0

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

@@ -0,0 +1,1083 @@
+{
+  "version": "1.0",
+  "description": "TrekClaw 组件级精确尺寸约束。来源：OP-DesignTokens-V5.md Part C（C1~C25）。生成/翻新页面时必须遵守。",
+  "source": {
+    "path": "../../design token进展/4.1/迭代/OP-DesignTokens-V5.md",
+    "section": "Part C — 组件级规则",
+    "lastSynced": "2026-05-15"
+  },
+
+  "components": {
+    "C1-Button": {
+      "name": "Button",
+      "file": "button.tsx",
+      "sizes": [
+        { "name": "default", "height": "32px (h-8)" },
+        { "name": "sm", "height": "28px (h-7)" },
+        { "name": "lg", "height": "40px (h-10)" },
+        { "name": "icon", "height": "32px, width: 32px (h-8 w-8)" }
+      ],
+      "iconGap": "4px (--gap-xs)，全尺寸统一，禁止页面层覆盖",
+      "radius": "8px (--input-radius / --radius-md)",
+      "outlineBorder": "使用 border-gray-line（不使用 border-input）",
+      "variants": "default / destructive / outline / secondary / ghost / link / gradient / success",
+      "spotlight": "内置 Spotlight 光效（鼠标追踪），default 变体色 rgba(100,230,255,0.45)，其他变体 rgba(255,255,255,0.25)"
+    },
+
+    "C2-Input": {
+      "name": "Input",
+      "file": "input.tsx",
+      "height": "32px (--input-height)",
+      "borderRadius": "8px (--input-radius)",
+      "padding": "7px 8px (--input-padding-y --input-padding-x)",
+      "fontSize": "12px (--input-font-size)",
+      "border": "border-input (--gray-border #D4D6DB)",
+      "background": "bg-card (白色)",
+      "textColor": "--gray-primary",
+      "placeholder": "hsl(var(--input-placeholder)) (#AAAAAA)",
+      "focus": "仅改变 border 颜色，不使用 ring；过渡 200ms"
+    },
+
+    "C3-Textarea": {
+      "name": "Textarea",
+      "file": "textarea.tsx",
+      "note": "与 Input 同套 token：borderRadius/fontSize/lineHeight/padding 均从 --input-* 变量",
+      "background": "bg-card + disabled:opacity-50",
+      "transition": "transition-colors 200ms"
+    },
+
+    "C4-InputGroup": {
+      "name": "InputGroup",
+      "file": "input-group.tsx",
+      "structure": "InputGroup > InputGroupAddon + InputGroupInput（可选 InputGroupButton/InputGroupText/InputGroupTextarea）",
+      "height": "--input-height (32px)",
+      "borderRadius": "--input-radius (8px)",
+      "border": "默认 --gray-line，focus-within 变 --primary",
+      "searchAddon": "必须使用 InputGroup 结构，Addon 默认 align=inline-end（搜索图标在右侧），禁止改为 inline-start",
+      "searchIconSize": "--input-icon-size (16px)",
+      "searchIconColor": "--gray-tertiary",
+      "innerInput": "flex-1 rounded-none border-0 bg-transparent shadow-none ring-0"
+    },
+
+    "C5-Label": {
+      "name": "Label",
+      "file": "label.tsx",
+      "default": "text-sm（表单场景需手动覆盖为 text-xs）",
+      "dialog": "弹窗内 Label 必须使用 text-xs（12px）"
+    },
+
+    "C6-Badge": {
+      "name": "Badge",
+      "file": "badge.tsx",
+      "radius": "4px (--radius-sm)",
+      "_comment_legacyTopLevel": "以下顶层 padding / fontSize 字段对应 sizes.sm，保留以向后兼容；新使用方请优先引用 sizes 字段",
+      "padding": "3px 8px",
+      "gap": "2px",
+      "fontSize": "12px",
+      "variants": "default / secondary / destructive / status / outline / success / warning / inactive / info(API) / purple(MCP)",
+      "colorPalette": "12 色相 × 2 值（--badge-*-text 13阶 + --badge-*-bg 20阶），见 design-tokens.json → glossy.badge10",
+      "sizes": {
+        "sm": {
+          "fontSize": "12px",
+          "padding": "3px 8px",
+          "height": "auto (~18px)",
+          "useCase": "表格内状态标签、列表项标签"
+        },
+        "default": {
+          "fontSize": "14px",
+          "padding": "4px 10px",
+          "height": "24px",
+          "lineHeight": "16px",
+          "useCase": "跟随页面标题使用的大尺寸标签（如 PageHeader 面包屑后的分类标签）"
+        }
+      }
+    },
+
+    "C7-Card": {
+      "name": "Card",
+      "file": "card.tsx",
+      "default": "rounded-xl border bg-card text-card-foreground shadow-card card-hover",
+      "contentCardOverride": "【v7.6】作为内容区大卡片容器（ContentCard）使用时：`rounded-xl border-0 bg-card text-card-foreground shadow-sm` — 去掉 1px border，使用最弱阴影 shadow-sm。详见 design-tokens.json · componentSpacing.Card.surface。",
+      "padding": "shadcn 默认 24px (p-6)；ContentCard 作为白卡容器使用时 override 为 0 var(--card-padding-x) = 0 20px（v7.5 由 24px → 20px）",
+      "structure": "CardHeader / CardTitle / CardDescription / CardContent / CardFooter",
+      "cardFooter": {
+        "description": "页面级 Card 内 SubmitBar/Footer 定位规则（适用于 FormPage）",
+        "height": "auto（内容决定，典型值 72px = 24px padding-top + 36px button-height + 12px padding-bottom）",
+        "positioning": "智能定位：Footer 作为 Card 直接子元素（非 scrollable 内），flex-shrink: 0",
+        "behavior": {
+          "contentFits": "Card 高度 = 内容高度，Footer 跟随表单自然展示",
+          "contentOverflows": "Card 高度 = max-height，内容区 overflow-y: auto 滚动，Footer 固定在 Card 底部"
+        },
+        "maxHeight": "calc(100vh - 2 × --page-container-padding)",
+        "zIndex": 10,
+        "background": "hsl(var(--card))",
+        "borderTop": "1px solid hsl(var(--gray-line))",
+        "reference": "与 DialogFooter(C18) / DrawerFooter(C19) 固定底部策略一致"
+      }
+    },
+
+    "C8-SpotlightCard": {
+      "name": "SpotlightCard",
+      "file": "SpotlightCard.tsx",
+      "outer": "relative overflow-hidden",
+      "effect": "鼠标追踪 + radial-gradient 层，opacity 在 hover/focus 上升至 0.6",
+      "spotlightColor": "rgba(255,255,255,0.25)",
+      "transition": "opacity 500ms ease-in-out"
+    },
+
+    "C9-Checkbox": {
+      "name": "Checkbox",
+      "file": "checkbox.tsx",
+      "size": "16x16 (--input-icon-size)",
+      "radius": "4px (--radius-sm)",
+      "border": "--gray-border",
+      "background": "--card",
+      "checked": "bg-primary + border-primary + text-primary-foreground",
+      "states": "unchecked / checked / indeterminate（Minus 图标 strokeWidth=3）"
+    },
+
+    "C10-RadioGroup": {
+      "name": "RadioGroup",
+      "file": "radio-group.tsx",
+      "itemSize": "16x16 (size-4)",
+      "border": "--gray-border",
+      "checked": "border-primary + bg-primary，内部 Circle 2px、填充 primary-foreground"
+    },
+
+    "C11-Switch": {
+      "name": "Switch",
+      "file": "switch.tsx",
+      "pillSize": "28x16, borderRadius 8px",
+      "handleSize": "12x12, borderRadius 50%",
+      "offset": "top:2 / left:2 (off) / left:14 (on)",
+      "enabledPill": "--success（不是 primary）",
+      "disabledPill": "--gray-border",
+      "handle": "--card",
+      "animation": "0.2s"
+    },
+
+    "C12-Slider": {
+      "name": "Slider",
+      "file": "slider.tsx",
+      "trackHeight": "h-1 (4px)",
+      "trackRadius": "rounded-full",
+      "trackBg": "bg-gray-border",
+      "rangeBg": "bg-primary",
+      "thumbSize": "14x14 (size-3.5)",
+      "thumbBorder": "border-2 border-primary",
+      "thumbBg": "白色 + ring-primary/20",
+      "thumbHover": "ring-4"
+    },
+
+    "C13-Progress": {
+      "name": "Progress",
+      "file": "progress.tsx",
+      "height": "h-2 (8px)",
+      "radius": "全圆角",
+      "trackBg": "bg-muted",
+      "fillBg": "bg-primary",
+      "transition": "transition-all duration-500 ease-out"
+    },
+
+    "C14-Tabs": {
+      "name": "Tabs",
+      "file": "tabs.tsx",
+      "variants": [
+        {
+          "name": "default（胶囊）",
+          "container": "h-10 rounded-lg bg-muted p-1",
+          "selected": "bg-background text-foreground shadow-sm"
+        },
+        {
+          "name": "underline（下划线）",
+          "containerHeight": "32px (h-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"
+        }
+      ]
+    },
+
+    "C15-ToggleGroup": {
+      "name": "ToggleGroup / Toggle",
+      "file": "toggle-group.tsx / toggle.tsx",
+      "variants": "default / outline / capsule（快筛胶囊）",
+      "sizes": "default(h-8) / sm(h-7) / lg(h-9) / capsule(h-8 px-4 text-xs)",
+      "capsuleBorder": "--gray-line",
+      "normalText": "--gray-secondary",
+      "selectedText": "--primary + font-medium",
+      "spacing0": "颈部圆角与边框折叠：first:rounded-l、last:rounded-r、[&:not(:first-child)]:border-l-0"
+    },
+
+    "C16-Pagination": {
+      "name": "Pagination",
+      "file": "pagination.tsx",
+      "layout": "两段布局：左侧（总条数）/ 右侧（页码导航，间距 12px + 前往跳转，间距 8px + 每页选择器）",
+      "buttonSize": "32x32",
+      "arrowIconSize": "20x20 (size-5)",
+      "ellipsisSize": "16x16 (size-4)",
+      "tokenReuse": "禁止新增 --pagination-* 变量，必须复用：尺寸→--input-height、圆角→--input-radius、间距→--button-gap、字号→--input-font-size",
+      "activePage": "--primary + medium",
+      "normalPage": "--gray-secondary + regular",
+      "hoverBg": "--gray-fill",
+      "gotoJump": {
+        "position": "右侧区域最右，紧邻页码导航（间距 12px）",
+        "structure": "「前往」文字 + input[type=text]（宽度约 40px，高度 --button-sm-height）+「页」文字 + 「确定」按钮（ghost/outline，高度 --button-sm-height）",
+        "inputStyle": "复用 Input 规范：--button-sm-height (28px), --radius-md, --input-font-size, padding-x 4px, 居中文字, focus 变 --primary",
+        "buttonStyle": "小按钮，高度 --button-sm-height (28px)，圆角 --radius-md，文字「确定」，无图标"
+      }
+    },
+
+    "C17-Table": {
+      "name": "Table",
+      "file": "table.tsx",
+      "header": {
+        "bg": "--gray-bg",
+        "textColor": "--gray-tertiary",
+        "fontSize": "--input-font-size (12px)",
+        "fontWeight": "medium (500)",
+        "whiteSpace": "nowrap（强制不折行）",
+        "padding": "12px 12px【上下 12px / 左右 12px】；仅供列间内部呼吸；外侧呼吸由 Card.paddingX (20px) 提供"
+      },
+      "cell": {
+        "bg": "--card",
+        "textColor": "--gray-primary",
+        "fontSize": "--input-font-size (12px)",
+        "fontWeight": "regular (400)",
+        "lineHeight": "--input-line-height (18px)",
+        "padding": "12px 12px【上下 12px / 左右 12px】；仅供列间内部呼吸；外侧呼吸由 Card.paddingX (20px) 提供",
+        "firstChild": "padding-left: 20px（表格作为密集数据区，首列额外享有 20px 缩进）",
+        "lastChild": "padding-right: 20px（末列同样额外享有 20px 缩进）",
+        "border": "--gray-line (1px bottom)",
+        "outerBorder": "无"
+      },
+      "horizontalPaddingRule": {
+        "model": "分层 padding v7.5：Card.paddingX (20px) 提供非 Table 子组件外侧呼吸；td.paddingX (12px) 提供中间列间内部呼吸；首末列 padding-left/right = 20px 提供表格首末列额外视觉缩进",
+        "middleColumns": "padding: 12px 12px",
+        "firstColumn": "padding-left: 20px",
+        "lastColumn": "padding-right: 20px",
+        "description": "【分层模型 v7.5】Table 的水平 padding 分为三层职责：\n  1) 非 Table 子组件与 Card 外侧边缘的 20px 呼吸→ 由 Card.paddingX 提供\n  2) 中间列与列之间的 24px 内部呼吸→ 由中间 td 的 12+12 paddingX 提供\n  3) 表格首末列额外的 20px 视觉缩进→ 由首末列 td 的 padding-left/right = 20px 提供\n首列内容 X = Card 外缘 + 40px，末列右缘 X = Card 右缘 - 40px。",
+        "forbidden": [
+          "禁止中间列 td paddingX 不为 12px（列间距不为 24px，与设计不一致）",
+          "禁止首列 padding-left 为非 20 值（0 / 12 / 16 / 24 都不适用；20px 是唯一权威值）",
+          "禁止末列 padding-right 为非 20 值（同上）",
+          "禁止使用 px-4 / px-6 等字面量。Tailwind 中唯一接受模式：`px-3 first:pl-5 last:pr-5`\uff0820px = pl-5 / pr-5\uff09",
+          "禁止在 Card 与 Table 之间插入额外的 paddingX 包裹层"
+        ],
+        "firstAndLastColumn": "首列 (col-checkbox 或首字段列) 内容左边缘 = Card 左边缘 + 20 + 20 = 40px；末列内容右边缘 = Card 右边缘 - 40px。表格首末列不与 PageHeader / ActionToolbar / Pagination 起始线对齐，这是设计预期。"
+      },
+      "hoverBg": "--gray-bg / 0.5",
+      "actionColumn": "纯文字按钮 + 竖线分隔，可用 --primary，禁用 --gray-disabled",
+      "actionColumnAlignment": {
+        "rule": "表头与表体均需显式 text-align: left，使「操作」标题与操作列左侧第一个字段左边缘对齐",
+        "css": [
+          ".data-table .col-action { width: 140px; text-align: left; position: sticky; right: 0; background: hsl(var(--card)); }",
+          ".data-table thead th.col-action { background: hsl(var(--gray-bg)); text-align: left; }",
+          ".data-table tbody td.col-action { text-align: left; }"
+        ],
+        "reason": "操作列标题与左侧第一个操作字段（如「详情」链接）左边缘对齐，保持视觉一致性",
+        "forbidden": [
+          "禁止只在 .col-action 设 text-align: left 而不重复声明",
+          "禁止表头「操作」与表体操作内容对齐方式不一致",
+          "禁止操作列内容居中"
+        ],
+        "verification": "表头「操作」左边缘 X = 表体「详情」链接左边缘 X"
+      },
+      "globalRules": [
+        "内容文字统一 --gray-primary，禁止页面层覆盖为 --gray-secondary",
+        "表头与内容严格左对齐，禁止 text-center / justify-center",
+        "hover 背景 --gray-bg / 0.5",
+        "操作列：纯文字按钮 + 竖线分隔（表头与表体均 text-align: left，左边缘对齐）",
+        "纯文案不设独立颜色，继承 TableCell 的 --gray-primary",
+        "表头文字强制不折行",
+        "th/td 的水平 padding 分层 v7.5：中间列 12px 提供列间呼吸；首列 padding-left = 20px / 末列 padding-right = 20px（表格额外享有 20px 视觉缩进）；Card.paddingX (20px) 提供非 Table 子组件的外侧呼吸"
+      ]
+    },
+
+    "C18-Dialog": {
+      "name": "Dialog",
+      "file": "dialog.tsx",
+      "structure": "Dialog > DialogContent > [DialogHeader + DialogBody | 自由内容 + DialogFooter]",
+      "globalRules": [
+        "标题区纯文字，禁止任何 icon；禁止 flex items-center gap-2 图标布局类；禁止 text-destructive / text-warning 颜色类",
+        "必须有关闭按钮：传入 onClose 回调，右侧自动渲染 X",
+        "行动点区默认不加图标（特殊业务需求除外）",
+        "确定/提交按钮始终可点击，禁用 disabled；点击后再触发校验、反馈错误信息",
+        "字段 Label 默认 text-xs（12px），不得使用 Label 默认的 text-sm",
+        "简单弹窗使用 <DialogBody>，仅复杂分栏弹窗可用自定义 div",
+        "宽度四档变量约束：禁止 max-w-* 硬编码，必须 style={{ width: 'var(--dialog-width-*)' }}（s=400/m=600/l=800/xl=1000）",
+        "通过 ReactDOM.createPortal 渲染到 document.body，不受祖先 overflow-hidden 裁剪",
+        "遮罩层 bg-black/50，禁止 backdrop-blur / backdrop-filter 等背景模糊"
+      ],
+      "headerHeight": "46px (--dialog-header-height)",
+      "padding": "12px 20px",
+      "titleSize": "14px medium --gray-title",
+      "closeIcon": "16x16 --gray-tertiary hover --gray-primary",
+      "bodyPadding": "16px 20px",
+      "footerHeight": "64px (--dialog-footer-height)",
+      "footerPadding": "0 20px",
+      "radius": "--radius (16px)",
+      "shadow": "--dialog-shadow"
+    },
+
+    "C19-Sheet": {
+      "name": "Sheet",
+      "file": "drawer.tsx",
+      "note": "基于 vaul，direction=right，右侧滑入三段式结构（DrawerHeader / DrawerBody / DrawerFooter）",
+      "rules": [
+        "标题区纯文字，禁止 icon",
+        "必须有关闭按钮（onClose）",
+        "Footer 按钮默认不加图标",
+        "宽度四档：style={{ width: 'var(--drawer-width-*)' }}（s=400/m=600/l=800/xl=1200）"
+      ],
+      "headerHeight": "46px (--dialog-header-height)",
+      "titleSize": "14px medium --gray-title",
+      "bodyPadding": "flex-1 overflow-y-auto py-4 px-[var(--dialog-body-padding-x)]",
+      "footerHeight": "64px (--dialog-footer-height)",
+      "footerPadding": "0 20px",
+      "radius": "var(--radius) 0 0 var(--radius)（仅左上+左下）",
+      "shadow": "--dialog-shadow",
+      "overlay": "bg-black/50"
+    },
+
+    "C20-Sheet": {
+      "name": "Sheet",
+      "file": "sheet.tsx",
+      "note": "基于 @base-ui/react/dialog，默认 side=right",
+      "overlay": "bg-black/10 + supports-backdrop-filter:backdrop-blur-xs",
+      "closeButton": "右上角默认 Button variant=ghost size=icon-sm 关闭按钮"
+    },
+
+    "C21-Popover": {
+      "name": "Popover",
+      "file": "popover.tsx",
+      "library": "@radix-ui/react-popover",
+      "defaultAlign": "center",
+      "sideOffset": "4px",
+      "container": "rounded-md border border-gray-line bg-popover p-4 text-popover-foreground shadow-md"
+    },
+
+    "C22-Tooltip": {
+      "name": "Tooltip",
+      "file": "tooltip.tsx",
+      "library": "@base-ui/react/tooltip",
+      "defaultDelay": "0",
+      "defaultSide": "top",
+      "sideOffset": "4px",
+      "container": "深色底 bg-foreground + text-background，rounded-md，px-3 py-1.5 text-xs，携 Arrow"
+    },
+
+    "C23-Select": {
+      "name": "Select",
+      "file": "select.tsx",
+      "trigger": {
+        "height": "32px (h-8)",
+        "radius": "8px (--radius-md)",
+        "fontSize": "12px (text-xs)",
+        "border": "--gray-line",
+        "bg": "--card",
+        "arrow": "14px chevron-down --gray-title opacity 80"
+      },
+      "content": {
+        "bg": "--card",
+        "radius": "rounded-md",
+        "shadow": "0 6px 24px rgba(0,0,0,0.1)",
+        "padding": "p-2"
+      },
+      "item": {
+        "height": "32px (h-8)",
+        "radius": "4px (rounded-sm)",
+        "padding": "px-2 text-xs",
+        "normalText": "--foreground",
+        "disabledText": "--gray-disabled",
+        "hoverBg": "--gray-bg",
+        "selected": "data-[state=checked]:text-primary + font-medium"
+      },
+      "label": "text-xs font-medium text-[hsl(var(--gray-disabled))]",
+      "separator": "bg-[hsl(var(--gray-line))]"
+    },
+
+    "C24-DropdownMenu": {
+      "name": "DropdownMenu",
+      "file": "dropdown-menu.tsx",
+      "library": "@base-ui/react/menu",
+      "content": {
+        "radius": "rounded-md",
+        "bg": "bg-card",
+        "padding": "p-1",
+        "border": "border-gray-line",
+        "shadow": "0 6px 24px rgba(0,0,0,0.1)（与 Select 一致）",
+        "minWidth": "min-w-32",
+        "fontSize": "text-xs"
+      },
+      "item": {
+        "height": "32px (h-8)",
+        "radius": "rounded-sm",
+        "padding": "px-2",
+        "fontSize": "text-xs",
+        "focusBg": "--gray-bg",
+        "iconSize": "16x16 (size-4)"
+      },
+      "destructiveItem": "text-destructive，focus bg-destructive/10",
+      "shortcut": "右对齐，text-xs tracking-widest text-[hsl(var(--gray-disabled))]",
+      "sub": "SubTrigger 右侧 ChevronRightIcon；SubContent 默认 align-start、alignOffset=-3、side=right、sideOffset=0",
+      "separator": "bg-[hsl(var(--gray-line))]"
+    },
+
+    "C25-Misc": {
+      "name": "Notice / Separator / Skeleton / Sidebar",
+      "notice": {
+        "background": "渐变 Gradient-3（linear-gradient(90deg, hsl(var(--info-light)), hsl(var(--info-border)))）",
+        "icon": "Info --primary",
+        "text": "--gray-secondary",
+        "padding": "var(--input-padding-y) var(--input-padding-x)",
+        "radius": "--input-radius",
+        "fontSize/lineHeight": "同 Input"
+      },
+      "separator": {
+        "color": "--gray-line（禁止硬编码）"
+      },
+      "skeleton": {
+        "bg": "bg-muted",
+        "animation": "animate-pulse rounded-md"
+      },
+      "sidebar": {
+        "width": "--layout-sidebar-width (240px)",
+        "collapsedWidth": "68px (= --sidebar-collapsed-width)",
+        "colors": "全部走 --sidebar-* token（详见 design-tokens.json colorMapping）",
+        "collapseBehavior": "菜单项 40x40px 居中于 34px 中轴，gap:0，flyout z-index:200（详见 design-tokens.json sidebarRules.collapseBehavior）",
+        "note": "v4.1 后项目已移除顶栏，用户信息与全局功能入口均收纳于侧边栏"
+      }
+    },
+
+    "C26-Stepper": {
+      "description": "数值增减器组件，用于配置有范围限制的数字值（如节点数）",
+      "structure": "display: flex; align-items: center; gap: 0; 三部分: 减按钮 + 输入框 + 加按钮",
+      "button": {
+        "width": "32px",
+        "height": "32px",
+        "border": "1px solid hsl(var(--gray-line))",
+        "background": "hsl(var(--card))",
+        "fontSize": "18px",
+        "color": "hsl(var(--gray-primary))",
+        "cursor": "pointer",
+        "hoverBackground": "hsl(var(--gray-fill))",
+        "disabledOpacity": "0.45",
+        "leftBorderRadius": "var(--radius-md) 0 0 var(--radius-md)",
+        "rightBorderRadius": "0 var(--radius-md) var(--radius-md) 0"
+      },
+      "input": {
+        "width": "60px",
+        "height": "32px",
+        "border": "1px solid hsl(var(--gray-line))",
+        "borderLeft": "none",
+        "borderRight": "none",
+        "textAlign": "center",
+        "fontSize": "var(--font-size-base) (12px)",
+        "color": "hsl(var(--gray-primary))",
+        "background": "hsl(var(--card))"
+      },
+      "borderRadius": "var(--radius-md) (8px) — 仅外侧两端有圆角",
+      "usage": "实例节点数、副本数等整数配置项"
+    },
+
+    "C27-Steps": {
+      "id": "C27",
+      "component": "Steps",
+      "description": "流程步骤条组件，用于多步骤向导/表单的进度指示，区别于 C26-Stepper 数值增减器",
+      "usage": "WizardPage / 多步骤表单 / 分步向导流程",
+      "orientation": ["horizontal", "vertical"],
+      "states": {
+        "inactive": "未到达的步骤，灰色边框圆形 + 灰色数字/文字",
+        "active": "当前步骤，品牌色填充圆形 + 白色数字 + 加粗标签",
+        "completed": "已完成步骤，品牌色填充圆形 + 白色对勾图标",
+        "loading": "异步加载中，Spinner 动画替代数字（可选）"
+      },
+      "specs": {
+        "stepCircle": {
+          "width": "30px",
+          "height": "30px",
+          "borderRadius": "50%",
+          "border": "2px solid",
+          "fontSize": "var(--font-size-lg)",
+          "fontWeight": "var(--font-weight-semibold)",
+          "colors": {
+            "inactive": {
+              "borderColor": "hsl(var(--gray-border))",
+              "background": "hsl(var(--card))",
+              "color": "hsl(var(--gray-secondary))"
+            },
+            "active": {
+              "borderColor": "hsl(var(--brand-primary))",
+              "background": "hsl(var(--brand-primary))",
+              "color": "hsl(var(--primary-foreground))"
+            },
+            "completed": {
+              "borderColor": "hsl(var(--brand-primary))",
+              "background": "hsl(var(--brand-primary))",
+              "color": "hsl(var(--primary-foreground))",
+              "content": "SVG checkmark icon"
+            }
+          }
+        },
+        "stepConnector": {
+          "height": "2px",
+          "margin": "0 var(--gap-lg)",
+          "colors": {
+            "default": "hsl(var(--gray-border))",
+            "completed": "hsl(var(--brand-primary))"
+          },
+          "borderRadius": "9999px"
+        },
+        "stepLabel": {
+          "fontSize": "var(--font-size-lg)",
+          "gap": "var(--gap-sm)",
+          "colors": {
+            "inactive": {
+              "color": "hsl(var(--gray-secondary))",
+              "fontWeight": "var(--font-weight-normal)"
+            },
+            "active": {
+              "color": "hsl(var(--gray-title))",
+              "fontWeight": "var(--font-weight-semibold)"
+            },
+            "completed": {
+              "color": "hsl(var(--gray-primary))",
+              "fontWeight": "var(--font-weight-medium)"
+            }
+          }
+        },
+        "stepDescription": {
+          "fontSize": "var(--font-size-sm)",
+          "color": "hsl(var(--gray-secondary))",
+          "marginTop": "2px",
+          "note": "可选，用于补充说明每步内容"
+        },
+        "container": {
+          "padding": "var(--gap-2xl) 0",
+          "maxWidth": "600px",
+          "margin": "0 auto",
+          "display": "flex",
+          "alignItems": "center",
+          "justifyContent": "center"
+        }
+      },
+      "accessibility": {
+        "role": "group (container), tablist (steps)",
+        "ariaLabel": "步骤指示器需提供 aria-label",
+        "ariaSelected": "当前步骤 aria-selected=true",
+        "keyboard": {
+          "Tab": "聚焦步骤条",
+          "ArrowRight": "下一步（horizontal）",
+          "ArrowLeft": "上一步（horizontal）",
+          "ArrowDown": "下一步（vertical）",
+          "ArrowUp": "上一步（vertical）",
+          "Enter/Space": "选择当前步骤（非线性模式）"
+        }
+      },
+      "constraints": [
+        "所有色值必须引用 CSS 变量，禁止硬编码",
+        "圆形指示器与标签间距使用 var(--gap-sm) = 8px",
+        "连接线左右间距使用 var(--gap-lg) = 12px",
+        "容器上下 padding 使用 var(--gap-2xl) = 24px",
+        "步骤条下方不带分割线（与表单内容区无 border 分隔）",
+        "Footer 行动点（取消/上一步/下一步/提交）全部居右排列 justify-content: flex-end"
+      ],
+      "examples": "page-rule-examples/wizard-form-page.html"
+    },
+    "C26-DescriptionList": {
+      "component": "DescriptionList",
+      "description": "详情页核心展示组件 — 键值对列表容器，支持多列布局与响应式降级",
+      "dimensions": {
+        "columns": {
+          "default": 2,
+          "options": [2, 3, 4],
+          "responsive": {
+            ">=1200px": "使用配置列数",
+            "768px-1199px": "最多 2 列",
+            "<768px": "强制 1 列（vertical 布局）"
+          }
+        },
+        "label": {
+          "width": "auto（由最长 label 决定）或固定值",
+          "minWidth": "80px",
+          "maxWidth": "180px",
+          "color": "hsl(var(--gray-secondary))",
+          "fontSize": "var(--font-size-base) = 12px",
+          "fontWeight": "400"
+        },
+        "value": {
+          "color": "hsl(var(--gray-primary))",
+          "fontSize": "var(--font-size-base) = 12px",
+          "fontWeight": "400",
+          "truncate": "single-line ellipsis + Tooltip，超过容器宽度时截断"
+        },
+        "row": {
+          "height": "36px（含 padding）",
+          "paddingY": "8px",
+          "gap": "var(--gap-md) = 12px（label 与 value 间距）"
+        },
+        "section": {
+          "titleFontSize": "14px",
+          "titleFontWeight": "600",
+          "titleColor": "hsl(var(--gray-title))",
+          "titleMarginBottom": "12px",
+          "sectionGap": "24px（分组间距，v7.6.1 对齐 design-tokens.json Detail.groupGap）",
+          "borderTop": "1px solid hsl(var(--gray-line))（非首个分组）— 属「功能性分组分割线」，不受 v7.6 surface 规则约束"
+        },
+        "container": {
+          "paddingX": "0（继承 Card 内边距 var(--card-padding-x) = 20px）",
+          "paddingY": "0"
+        }
+      },
+      "interactions": {
+        "copyable": "点击复制图标 → 复制到剪贴板 + Sonner '已复制'",
+        "editable": "点击编辑图标 → value 切换为 inline Input，失焦/Enter 保存",
+        "link": "蓝色文字 + hover 下划线，点击跳转关联资源",
+        "status": "Badge 颜色展示（运行中=绿、已停止=灰、异常=红）",
+        "tooltip": "截断文本 hover 展示完整内容"
+      },
+      "emptyValue": "字段为空时展示 '-' 占位，使用 var(--gray-disabled) 色值",
+      "constraints": [
+        "label 和 value 必须使用 CSS 变量色值，禁止硬编码",
+        "bordered 模式下使用 1px solid hsl(var(--gray-line)) 边框",
+        "响应式降级必须按 768px 断点强制转为单列",
+        "可复制字段的 icon 使用 Copy (16x16)，hover 色 var(--primary)",
+        "可编辑字段切换为 Input 时高度保持 32px（与表单组件一致）"
+      ]
+    },
+
+    "C26-CodeBlock": {
+      "id": "C26",
+      "ref": "CodeBlock",
+      "name": "CodeBlock",
+      "category": "ORGANISM",
+      "description": "代码/配置片段只读展示，支持语法高亮、行号、复制",
+      "dimensions": {
+        "minHeight": 120,
+        "maxHeight": 480,
+        "padding": 16
+      },
+      "typography": {
+        "fontFamily": "'SF Mono', 'Fira Code', 'Cascadia Code', monospace",
+        "fontSize": 13,
+        "lineHeight": 1.6
+      },
+      "visual": {
+        "background": "hsl(var(--gray-muted))",
+        "borderRadius": "var(--radius-md)",
+        "lineNumberWidth": 40,
+        "lineNumberColor": "hsl(var(--muted-foreground))"
+      },
+      "variants": [
+        {
+          "name": "default",
+          "description": "标准代码展示",
+          "props": ["language", "lineNumbers", "copyable"]
+        },
+        {
+          "name": "collapsible",
+          "description": "可折叠模式（超长内容）",
+          "props": ["maxLines", "expandLabel"],
+          "trigger": "内容超过 maxHeight"
+        },
+        {
+          "name": "multi-language",
+          "description": "多语言Tab切换",
+          "props": ["languages[]", "activeLanguage"],
+          "extraUI": "顶部语言Tab栏"
+        }
+      ],
+      "responsive": {
+        "768": { "padding": 12, "fontSize": 12 }
+      },
+      "interactions": {
+        "copy": "右上角复制按钮，hover显示，点击复制全文",
+        "collapse": "底部渐变遮罩 + '展开全部(N行)' 按钮",
+        "languageSwitch": "顶部Tab切换不同语言展示"
+      }
+    },
+
+    "C27-ConfigDiff": {
+      "id": "C27",
+      "ref": "ConfigDiff",
+      "name": "ConfigDiff",
+      "category": "ORGANISM",
+      "description": "配置版本双栏对比展示，标记新增/删除/修改行",
+      "dimensions": {
+        "maxHeight": 600,
+        "headerHeight": 36,
+        "padding": 0
+      },
+      "typography": {
+        "fontFamily": "'SF Mono', 'Fira Code', monospace",
+        "fontSize": 13,
+        "lineHeight": 1.6
+      },
+      "visual": {
+        "addedLineBg": "hsl(152 82% 96%)",
+        "removedLineBg": "hsl(0 72% 96%)",
+        "unchangedBg": "transparent",
+        "borderRadius": "var(--radius-md)",
+        "headerBg": "hsl(var(--gray-muted))"
+      },
+      "variants": [
+        {
+          "name": "split",
+          "description": "双栏并排对比（默认）",
+          "layout": "左旧版本 | 右新版本，各占50%"
+        },
+        {
+          "name": "inline",
+          "description": "单栏标记差异",
+          "layout": "合并展示，添加行绿色背景，删除行红色背景"
+        }
+      ],
+      "responsive": {
+        "768": { "defaultMode": "inline", "description": "窄屏自动切换为inline模式" }
+      },
+      "interactions": {
+        "modeSwitch": "顶部切换 split/inline 模式",
+        "scrollSync": "split模式下双栏同步滚动",
+        "stats": "底部统计 '+N行 / -M行'"
+      }
+    },
+
+    "C28-VersionHistory": {
+      "id": "C28",
+      "ref": "VersionHistory",
+      "name": "VersionHistory",
+      "category": "ORGANISM",
+      "description": "版本变更时间线，展示版本记录与回滚操作",
+      "dimensions": {
+        "itemMinHeight": 56,
+        "itemMinHeightCompact": 40,
+        "dotSize": 8,
+        "lineWidth": 1
+      },
+      "typography": {
+        "versionLabel": { "fontSize": 14, "fontWeight": 500 },
+        "timestamp": { "fontSize": 12, "color": "hsl(var(--muted-foreground))" },
+        "summary": { "fontSize": 12, "color": "hsl(var(--gray-secondary-foreground))" }
+      },
+      "visual": {
+        "dotColorCurrent": "hsl(var(--primary))",
+        "dotColorHistory": "hsl(var(--gray-line))",
+        "lineColor": "hsl(var(--gray-line))",
+        "currentBadge": "primary"
+      },
+      "variants": [
+        {
+          "name": "default",
+          "description": "标准时间线（含变更摘要）"
+        },
+        {
+          "name": "compact",
+          "description": "紧凑模式（隐藏变更摘要）",
+          "itemHeight": 40
+        }
+      ],
+      "interactions": {
+        "select": "点击条目选中，触发版本对比",
+        "rollback": "hover显示回滚按钮，点击触发Dialog确认",
+        "expand": "点击条目展开变更摘要详情"
+      }
+    },
+
+    "C29-ApiEndpoint": {
+      "id": "C29",
+      "ref": "ApiEndpoint",
+      "name": "ApiEndpoint",
+      "category": "MOLECULE",
+      "description": "API端点信息概览卡（HTTP方法 + 路径 + 状态）",
+      "dimensions": {
+        "height": 48,
+        "padding": "0 16px"
+      },
+      "typography": {
+        "path": { "fontFamily": "monospace", "fontSize": 14, "fontWeight": 500 },
+        "method": { "fontSize": 12, "fontWeight": 600 }
+      },
+      "visual": {
+        "background": "hsl(var(--gray-muted))",
+        "borderRadius": "var(--radius-md)",
+        "methodColors": {
+          "GET": "hsl(218 100% 47%)",
+          "POST": "hsl(142 76% 36%)",
+          "PUT": "hsl(40 88% 48%)",
+          "DELETE": "hsl(0 72% 51%)",
+          "PATCH": "hsl(262 83% 58%)"
+        },
+        "statusColors": {
+          "published": "hsl(var(--success))",
+          "draft": "hsl(var(--muted-foreground))",
+          "deprecated": "hsl(var(--destructive))"
+        }
+      },
+      "variants": [
+        {
+          "name": "default",
+          "description": "单端点展示"
+        },
+        {
+          "name": "with-base-url",
+          "description": "含基础URL前缀",
+          "extraUI": "baseUrl(灰色) + path(主色)"
+        }
+      ],
+      "interactions": {
+        "copy": "路径右侧复制图标，hover显示，复制完整URL",
+        "click": "可选：点击路径跳转到API调试"
+      }
+    },
+
+    "C30-ParameterTable": {
+      "id": "C30",
+      "ref": "ParameterTable",
+      "name": "ParameterTable",
+      "category": "ORGANISM",
+      "description": "API参数结构化表格，支持嵌套展开",
+      "dimensions": {
+        "headerHeight": 36,
+        "rowHeight": 40,
+        "indentPerLevel": 24,
+        "maxNestLevel": 3
+      },
+      "typography": {
+        "paramName": { "fontFamily": "monospace", "fontSize": 13 },
+        "description": { "fontSize": 12, "color": "hsl(var(--gray-secondary-foreground))" }
+      },
+      "visual": {
+        "headerBg": "hsl(var(--gray-muted))",
+        "borderColor": "hsl(var(--gray-line))",
+        "typeColors": {
+          "string": "hsl(218 100% 47%)",
+          "number": "hsl(142 76% 36%)",
+          "boolean": "hsl(40 88% 48%)",
+          "object": "hsl(262 83% 58%)",
+          "array": "hsl(180 60% 40%)"
+        },
+        "requiredMark": "hsl(var(--destructive))",
+        "nestLine": "1px solid hsl(var(--gray-line))"
+      },
+      "variants": [
+        {
+          "name": "request",
+          "description": "请求参数表",
+          "columns": ["参数名", "类型", "必填", "说明"]
+        },
+        {
+          "name": "response",
+          "description": "响应参数表",
+          "columns": ["参数名", "类型", "说明"]
+        },
+        {
+          "name": "header",
+          "description": "请求头参数表",
+          "columns": ["参数名", "类型", "必填", "说明"]
+        }
+      ],
+      "interactions": {
+        "expand": "左侧箭头▶/▼展开子参数",
+        "hover": "行hover高亮",
+        "collapse-optional": "参数>30时默认折叠选填参数 + '展示全部'"
+      }
+    },
+
+    "C31-MetricCard": {
+      "id": "C31",
+      "ref": "MetricCard",
+      "name": "MetricCard",
+      "category": "MOLECULE",
+      "description": "单指标数值展示卡片，含趋势与迷你图",
+      "dimensions": {
+        "height": 96,
+        "minWidth": 200,
+        "padding": "16px 20px",
+        "sparklineHeight": 24
+      },
+      "typography": {
+        "title": { "fontSize": 12, "fontWeight": 400, "color": "hsl(var(--muted-foreground))" },
+        "value": { "fontSize": 24, "fontWeight": 600, "color": "hsl(var(--gray-primary))" },
+        "unit": { "fontSize": 14, "fontWeight": 400, "color": "hsl(var(--muted-foreground))" },
+        "trend": { "fontSize": 12 }
+      },
+      "visual": {
+        "background": "hsl(var(--gray-muted))",
+        "borderRadius": "var(--radius-md)",
+        "trendColors": {
+          "up": "hsl(var(--success))",
+          "down": "hsl(var(--destructive))",
+          "flat": "hsl(var(--muted-foreground))"
+        },
+        "sparklineWidth": 1.5
+      },
+      "layout": {
+        "grid": "repeat(4, 1fr)",
+        "gap": 12
+      },
+      "responsive": {
+        "1200": { "grid": "repeat(2, 1fr)" },
+        "768": { "grid": "1fr" }
+      },
+      "variants": [
+        {
+          "name": "default",
+          "description": "标准指标卡（标题+数值+趋势）"
+        },
+        {
+          "name": "with-sparkline",
+          "description": "含底部迷你趋势图"
+        },
+        {
+          "name": "compact",
+          "description": "紧凑模式（高度 72px，无迷你图）",
+          "height": 72
+        }
+      ]
+    },
+
+    "C32-ChartPanel": {
+      "id": "C32",
+      "ref": "ChartPanel",
+      "name": "ChartPanel",
+      "category": "ORGANISM",
+      "description": "图表面板容器，支持折线图/柱状图/面积图",
+      "dimensions": {
+        "heightFull": 280,
+        "heightGrid": 220,
+        "padding": 16,
+        "titleBarHeight": 32
+      },
+      "typography": {
+        "title": { "fontSize": 14, "fontWeight": 500 },
+        "axisLabel": { "fontSize": 11, "color": "hsl(var(--muted-foreground))" },
+        "tooltip": { "fontSize": 12 }
+      },
+      "visual": {
+        "background": "transparent",
+        "borderRadius": "var(--radius-md)",
+        "gridLineColor": "hsl(var(--gray-line))",
+        "gridLineStyle": "dashed",
+        "gridLineWidth": 0.5,
+        "primaryLineColor": "hsl(var(--primary))",
+        "lineWidth": 2,
+        "dotRadius": 3
+      },
+      "layout": {
+        "gridColumns": "repeat(2, 1fr)",
+        "gridGap": 16
+      },
+      "responsive": {
+        "768": { "gridColumns": "1fr", "heightGrid": 200 }
+      },
+      "variants": [
+        {
+          "name": "line",
+          "description": "折线图"
+        },
+        {
+          "name": "bar",
+          "description": "柱状图"
+        },
+        {
+          "name": "area",
+          "description": "面积图（折线+填充）"
+        }
+      ],
+      "states": {
+        "loading": "Skeleton脉冲动画占位",
+        "empty": "居中'暂无数据'+图表图标",
+        "error": "居中'加载失败'+重试按钮"
+      }
+    },
+
+    "C33-AlertList": {
+      "id": "C33",
+      "ref": "AlertList",
+      "name": "AlertList",
+      "category": "ORGANISM",
+      "description": "告警事件列表，按严重度分级展示",
+      "dimensions": {
+        "itemMinHeight": 56,
+        "itemPadding": "12px 16px",
+        "dotSize": 20,
+        "gap": 0
+      },
+      "typography": {
+        "title": { "fontSize": 13, "fontWeight": 500, "color": "hsl(var(--gray-primary))" },
+        "timestamp": { "fontSize": 12, "color": "hsl(var(--muted-foreground))" },
+        "description": { "fontSize": 12, "color": "hsl(var(--gray-secondary-foreground))", "maxLines": 2 }
+      },
+      "visual": {
+        "borderBottom": "1px solid hsl(var(--gray-line))",
+        "severityColors": {
+          "critical": "hsl(var(--destructive))",
+          "warning": "hsl(var(--warning))",
+          "info": "hsl(var(--primary))"
+        },
+        "hoverBg": "hsl(var(--gray-muted))"
+      },
+      "variants": [
+        {
+          "name": "default",
+          "description": "标准告警列表"
+        },
+        {
+          "name": "compact",
+          "description": "紧凑模式（隐藏描述，高度 40px）"
+        }
+      ],
+      "states": {
+        "empty": "'暂无告警，系统运行正常' + 绿色✓图标",
+        "loading": "Skeleton条目占位"
+      },
+      "interactions": {
+        "acknowledge": "右侧确认按钮(Ghost)，hover显示",
+        "expand": "点击条目展开详细描述",
+        "filter": "顶部可选严重度筛选Tab"
+      }
+    },
+
+    "C34-TimeRangeSelector": {
+      "id": "C34",
+      "ref": "TimeRangeSelector",
+      "name": "TimeRangeSelector",
+      "category": "MOLECULE",
+      "description": "时间范围快捷选择器，SegmentedControl样式",
+      "dimensions": {
+        "height": 32,
+        "itemPadding": "0 12px"
+      },
+      "typography": {
+        "label": { "fontSize": 12, "fontWeight": 500 }
+      },
+      "visual": {
+        "borderRadius": "var(--radius-md)",
+        "selectedBg": "hsl(var(--primary))",
+        "selectedColor": "hsl(var(--primary-foreground))",
+        "unselectedBg": "transparent",
+        "unselectedColor": "hsl(var(--gray-secondary-foreground))",
+        "border": "1px solid hsl(var(--gray-line))"
+      },
+      "presets": ["1h", "6h", "24h", "7d", "30d"],
+      "variants": [
+        {
+          "name": "default",
+          "description": "预设时间范围选择"
+        },
+        {
+          "name": "with-custom",
+          "description": "含自定义范围（日历图标）",
+          "extraUI": "右侧日历图标，点击弹出DateRangePicker"
+        }
+      ],
+      "interactions": {
+        "select": "点击预设项切换，触发全局数据刷新",
+        "custom": "点击日历图标打开DateRangePicker弹层"
+      }
+    }
+  }
+}