# Agent Skills Hub · 原型设计规范（Design Spec） > 路径：`prototype/DESIGN.md` · 版本：1.20.45 > 本文档是原型设计的事实来源（Single Source of Truth），涵盖设计原则、设计系统、组件库、交互标准与响应式规范。 > 适用目录：`prototype/`（已重命名自 `site/`）。 > > **原型实现方式（v1.9.1 起，v1.12.0 对齐，v1.14.6 交互脚本拆分为 parts，v1.14.42 样式拆分为 tokens/base/layout/components/responsive，v1.17.x 交互/布局/可访问性系列改进）**：`prototype/prototype.html` 为纯 HTML 自包含单文件——由根目录 `npm run build`（=`node tools/build-skills-data.mjs && node tools/build.mjs`）将 `src/index.html` 模板内联 `src/styles/tokens.css` 及按序拼接的 `src/styles/base.css` + `src/styles/layout.css` + `src/styles/components.css` + `src/styles/responsive.css`、`src/i18n.js`、按序拼接的 `src/parts/*.js`（状态/渲染/详情/交互/启动五模块）与真实技能数据（合并 `data/skills-data.json` + `data/skills-metrics.json` 后注入）生成，双击即可离线预览，无 Next.js/Tailwind/React 构建。国际化由独立模块 `src/i18n.js` 驱动（`data-i18n` 占位 + `I18N.t()` 容错兜底）。源码在 `prototype/src/` 随仓库分发；`prototype/` 下的 `index.html`/`favicon.svg`/`banner-og.svg` 为构建产物（构建脚本 `tools/build.mjs`/`tools/build-skills-data.mjs` 置于仓库根 `tools/`，不混入原型目录）。 --- ## 1. 设计原则 | 原则 | 说明 | |------|------| | 极简（Minimal） | 克制的视觉语言，留白即设计；单一主色，避免渐变滥用与装饰性元素 | | 层级清晰（Hierarchy） | 通过字号、字重、色彩对比建立明确的信息层级，首屏 3 秒可读懂核心 | | 一致（Consistent） | 所有间距、圆角、阴影、动效遵循统一 Token，视觉基线参考 shadcn/ui（**仅为设计风格参考，原型无 shadcn/Tailwind/Radix 运行时**） | | 真实（Real Data） | 原型数据为构建期从磁盘 `skills//SKILL.md` 由根目录 `build-skills-data.mjs` 生成 `data/skills-data.json`，再由根目录 `build.mjs` 注入并预渲染进 `prototype/`，非占位假数据 | | 无障碍（Accessible） | 对比度 ≥ WCAG AA，键盘可达，支持 `prefers-reduced-motion` | --- ## 2. 设计系统（Design Tokens） 设计 Token 以 **shadcn/ui CSS 变量（HSL 通道）** 定义在 `prototype/src/styles/tokens.css` 的 `:root`（浅色）与 `html[data-theme="dark"]`（深色，主题由 `` 切换）中，由 `prototype/src/styles/base.css`/`layout.css`/`components.css`/`responsive.css` 直接消费（原型为纯原生 CSS，无 Tailwind/React 运行时）。这是全局唯一来源。 ### 2.1 色彩（HSL 通道，语义化命名） | Token | 浅色 | 深色 | 用途 | |-------|------|------|------| | `--background` | `0 0% 100%` | `224 28% 8%` | 页面背景 | | `--foreground` | `224 24% 12%` | `220 18% 92%` | 主文字 | | `--card` / `--card-foreground` | `0 0% 100%` / `224 24% 12%` | `224 24% 11%` / `220 18% 92%` | 卡片/弹窗表面 | | `--popover` / `--popover-foreground` | 同 card | 同 card（深） | 浮层表面 | | `--primary` / `--primary-foreground` | `152 56% 40%` / `0 0% 100%` | `146 52% 60%` / `224 32% 8%` | **主色（单一绿色，降饱和）** | | `--secondary` / `--secondary-foreground` | `220 16% 96%` / `224 24% 18%` | `224 18% 18%` / `220 18% 88%` | 次级表面（按钮、标签底） | | `--muted` / `--muted-foreground` | `220 16% 96%` / `220 9% 46%` | `224 18% 16%` / `220 12% 60%` | 辅助表面 / 辅助文字 | | `--accent` / `--accent-foreground` | `152 56% 95%` / `152 56% 33%` | `146 52% 22%` / `146 52% 82%` | 主色浅底（聚焦环、徽章） | | `--destructive` / `--destructive-foreground` | `0 72% 51%` / `0 0% 100%` | `0 62% 52%` / `0 0% 100%` | 破坏性操作 | | `--border` / `--input` / `--ring` | `220 14% 90%` / 同 border / `152 56% 40%` | `224 16% 22%` / `224 16% 24%` / `146 52% 60%` | 边框 / 输入 / 聚焦环 | | `--radius` | `0.75rem` | 同 | 默认圆角基准 | | `--shadow-color` | `224 32% 20%` | `0 0% 0%` | 阴影色相（中性低透明） | 色彩纪律：**主色仅用于主按钮、聚焦态、分类标识、选中态**；强调色仅用于 `scripts/references/assets` 等资源标签。禁止大面积渐变背景（Hero 仅保留极淡光晕 `radial-gradient`，透明度 ≤ 0.08）。 ### 2.2 字体 参考 Claude（Anthropic）官方品牌字体体系：标题使用衬线（Anthropic Serif，外部实现以 `Georgia` 为官方回退），正文/界面使用无衬线系统栈（Anthropic Sans，外部实现以 `system-ui` 为回退）。本项目为纯静态/Next.js 实现，不内嵌自定义字体，统一采用以下回退栈。 | Token | 值 | 用途 | |------|----|------| | `--font-display` | `Georgia, "Times New Roman", "Songti SC", "STSong", serif` | 标题/品牌名/卡片名（衬线，对标 Anthropic Serif） | | `--font-sans` | `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "PingFang SC", "Microsoft YaHei", system-ui, sans-serif` | 正文与界面（无衬线，对标 Anthropic Sans） | | `--font-en` | `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` | 英文 UI 文案 | | `--font-mono` | `ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace` | 代码/英文名等宽展示 | - 基础字号 `15px`，行高 `1.6` - 大标题 `clamp(34px, 5.5vw, 52px)`，字重 `700`，字距 `-0.02em`，字体 `--font-display` - 卡片标题 `15px`，字重 `600`，字距 `-0.01em`，字体 `--font-display` - 品牌名、弹窗标题、空状态标题均使用 `--font-display` 衬线，与正文无衬线形成层级对比 - 英文 UI 文案首字母大写，中文不加字距 ### 2.3 间距（4 的倍数尺度，取值约定参照 Tailwind 默认值） | 值 | 典型用途 | |----|---------| | `4px` (1) | 标签内边距微调 | | `8px` (2) | 元素间紧凑间距 | | `12px` (3) | chip/标签内边距 | | `16px` (4) | 卡片内边距基准 | | `24px` (6) | 区块/工具栏内边距 | | `32px` (8) | 容器/章节间距 | | `48px` (12) | Hero 内边距、弹窗内边距 | | `64px` (16) | 大区块间距 | ### 2.4 圆角（映射到 `--radius` 设计令牌） | Token | 值 | 用途 | |-------|----|------| | `rounded-sm` | `calc(--radius - 4px)` | 标签、输入框 | | `rounded-md` | `calc(--radius - 2px)` | 按钮、搜索框 | | `rounded-lg` | `--radius` (0.75rem) | 卡片（默认） | | `rounded-xl` | 1rem | 弹窗、统计条 | | `rounded-full` | 999px | chip、徽章、按钮胶囊 | ### 2.5 阴影（分层次，浅而柔，带 `--shadow-color`） | Token | 值 | |-------|----| | `--shadow-color` | `224 32% 20%`（浅）/ `0 0% 0%`（深）— 阴影色相，统一低透明 | | `shadow-xs` | `0 1px 2px hsl(var(--shadow-color)/.04), 0 1px 3px hsl(var(--shadow-color)/.06)` | | `shadow-sm` | `0 1px 2px hsl(var(--shadow-color)/.05), 0 2px 6px -1px hsl(var(--shadow-color)/.08)` | | `shadow-md` | `0 4px 12px -2px hsl(var(--shadow-color)/.10), 0 2px 6px -2px hsl(var(--shadow-color)/.06)` | | `shadow-lg` | `0 12px 32px -8px hsl(var(--shadow-color)/.16), 0 4px 10px -4px hsl(var(--shadow-color)/.08)` | | `shadow-pop` | `var(--shadow-lg)`（弹窗/浮层专用，桌面 Dialog 与卡片 hover 使用） | ### 2.6 图标 - 使用 **本地内联 SVG 图标集**（定义在 `prototype/src/index.html` 模板中，随 `prototype/src/` 源码分发），零外部依赖，统一 `24x24 viewBox` + `currentColor` 描边，等价于 lucide 风格。 - 图标尺寸统一 `16-20px`（`h-4 w-4` / `h-5 w-5`），颜色继承 `currentColor` 随状态变化。 - 业务图标语义：搜索 `Search`、主题 `Sun/Moon`、视图 `LayoutGrid/Rows3`、资源 `FileCode2/BookOpen/FolderOpen`、外链 `ExternalLink`、空态 `SlidersHorizontal`、品牌 `Boxes`、GitHub `Github`、关闭 `X`。 ### 2.7 动效（Motion） | Token | 值 | |-------|----| | `ease-out-quint` | `cubic-bezier(0.22, 1, 0.36, 1)`（顺滑收尾） | | `duration-200` | 200ms（交互反馈基准） | | `animate-fade-in` | `fade-in 0.3s easeOutQuint`（背景/遮罩） | | `animate-pop-in` | `pop-in 0.28s easeOutQuint`（弹窗卡片） | | `animate-slide-in-right` / `slide-out-right` | 移动端 Sheet 抽屉 | 动效纪律： - 交互反馈（hover/active）仅 200ms，位移 ≤ 3px（`active:scale-[0.98]`）。 - 弹窗：背景 `fade` + 卡片 `pop`。 - 必须尊重 `prefers-reduced-motion: reduce`——全局动画/过渡降为 `0.001ms`。 --- ## 3. 组件库（Component Library） 组件分三类：**基础（Base）**、**复合（Composite）**、**业务（Domain）**。视觉风格参考 shadcn/ui（new-york），原型以**纯原生 CSS/JS 实现**（无 Tailwind/React/Radix 运行时），禁止手写重复样式。 ### 3.1 基础组件（Base）— `components/ui/*`（构建期源码映射） > 以下组件为**原型源码结构映射**（源码在 `prototype/src/` 随仓库分发，由 `build.mjs` 内联为静态产物 `prototype/prototype.html`）；此处列出供理解静态产物的实现结构与评审对齐。注：当前实现为原生 HTML/CSS/JS（非 React 组件文件），交互脚本已按职责拆分到 `src/parts/`（01-state / 02-render / 03-detail / 04-interactions / 05-main），以下按职责对应到对应 parts 模块的渲染/交互函数。 | 组件 | 文件 | 变体/状态 | |------|------|-----------| | Button | `button.tsx` | `default/secondary/outline/ghost/destructive` × `default/sm/lg/icon`；`asChild` 支持 `a` 包装 | | Input | `input.tsx` | default / focus（ring） | | Badge | `badge.tsx` | `default/secondary/outline/muted/accent` | | Card | `card.tsx` | `Card/CardHeader/CardTitle/CardContent` | | Skeleton | `skeleton.tsx` | `animate-pulse` 占位 | | Separator | `separator.tsx` | horizontal / vertical | | Tabs | `parts/05-main.js` 视图切换 | 原生实现（Radix Tabs 风格的可访问性模式，无 Radix 依赖） | | Dialog | `parts/03-detail.js` `openDetail()` | 原生实现（Radix Dialog 风格焦点陷阱 + `aria-modal`，无 Radix 依赖） | | Sheet | `layout.css` 预留 `.sheet` | 移动端详情**复用居中 Dialog**（未启用独立抽屉；`.sheet`/`.sheet-grip` 为预留样式，标注保留未启用，无对应 DOM/JS） | ### 3.2 复合/业务组件（对应 `src/app.js` 渲染函数） | 职责 | 实现 | 说明 | |------|------|------| | ThemeToggle | `04-interactions.js` 的 `applyTheme()` | 深浅主题切换，写根节点 `data-theme` | | LangToggle | `i18n.js` 的 `I18N.toggleLang()` | 中英切换（受控），`I18N.syncDOM()` 同步 `data-lang` 与 `` | | ViewToggle | `01-state.js` 的 `state.view` + `02-render.js` 的 `renderGrid()` | 网格/列表切换（受控） | | ShareButton | `03-detail.js` 的 `shareSkill(name)` | 技能详情弹窗内的「分享」按钮；点击复制「技能链接 + 随机宣传文案」并 toast 反馈 | | SkillCard | `02-render.js` 的 `cardHTML()` | 网格/列表共用；**渲染为原生 `