---
version: beta
name: Skill Flow Desktop
description: A compact macOS operations workspace built from layered neutral surfaces, user-selectable accents, reusable group cards, and explicit selection and runtime states.

colors:
  light-page: "#f2f2f2"
  light-surface: "#fdfdfd"
  light-surface-nested: "#f9f9f9"
  light-surface-strong: "#e6e6e6"
  dark-page: "#222222"
  dark-surface: "#0e0e0e"
  dark-surface-nested: "#151515"
  dark-surface-strong: "#353535"
  light-ink: "#262626"
  dark-ink: "#efeff1"
  light-muted: "rgba(38, 38, 38, 0.62)"
  dark-muted: "rgba(229, 229, 231, 0.68)"
  light-border: "rgba(0, 0, 0, 0.12)"
  dark-border: "rgba(255, 255, 255, 0.12)"
  light-glass: "rgba(255, 255, 255, 0.44)"
  dark-glass: "rgba(255, 255, 255, 0.08)"
  accent-blue-light: "#3b82f6"
  accent-blue-dark: "#7db0ff"
  accent-green-light: "#22c55e"
  accent-green-dark: "#4ade80"
  accent-yellow-light: "#eab308"
  accent-yellow-dark: "#facc15"
  accent-pink-light: "#ec4899"
  accent-pink-dark: "#f472b6"
  accent-orange-light: "#f97316"
  accent-orange-dark: "#fb923c"
  accent-purple-light: "#8b5cf6"
  accent-purple-dark: "#a78bfa"
  semantic-success-light: "#22c55e"
  semantic-success-dark: "#4ade80"
  semantic-warning-light: "#eab308"
  semantic-warning-dark: "#facc15"
  semantic-error-light: "#f97316"
  semantic-error-dark: "#fca5a5"
  toast-success-light: "#dcfce7"
  toast-success-dark: "#14532d"
  toast-error-light: "#fef2f2"
  toast-error-dark: "#7f1d1d"

typography:
  dialog-title:
    fontFamily: "SF Pro / system-ui"
    fontSize: "20px"
    fontWeight: 600
    lineHeight: "platform-default"
    letterSpacing: "0"
  group-title:
    fontFamily: "SF Pro / system-ui"
    fontSize: "21px"
    fontWeight: 400
    lineHeight: "platform-default"
    letterSpacing: "0"
  page-title:
    fontFamily: "SF Pro / system-ui"
    fontSize: "17px"
    fontWeight: 600
    lineHeight: "platform-default"
    letterSpacing: "0"
  section-title:
    fontFamily: "SF Pro / system-ui"
    fontSize: "14px"
    fontWeight: 600
    lineHeight: "platform-default"
    letterSpacing: "0"
  row-title:
    fontFamily: "SF Pro / system-ui"
    fontSize: "13px"
    fontWeight: 600
    lineHeight: "platform-default"
    letterSpacing: "0"
  body:
    fontFamily: "SF Pro / system-ui"
    fontSize: "12px"
    fontWeight: 400
    lineHeight: "platform-default"
    letterSpacing: "0"
  body-strong:
    fontFamily: "SF Pro / system-ui"
    fontSize: "12px"
    fontWeight: 600
    lineHeight: "platform-default"
    letterSpacing: "0"
  caption:
    fontFamily: "SF Pro / system-ui"
    fontSize: "11px"
    fontWeight: 400
    lineHeight: "platform-default"
    letterSpacing: "0"
  micro:
    fontFamily: "SF Pro / system-ui"
    fontSize: "10px"
    fontWeight: 600
    lineHeight: "platform-default"
    letterSpacing: "0"
  mono-body:
    fontFamily: "SF Mono / ui-monospace"
    fontSize: "11px"
    fontWeight: 400
    lineHeight: "platform-default"
    letterSpacing: "0"
  mono-label:
    fontFamily: "SF Mono / ui-monospace"
    fontSize: "11px"
    fontWeight: 600
    lineHeight: "platform-default"
    letterSpacing: "0"

rounded:
  xs: "4px"
  sm: "6px"
  row: "7px"
  control: "8px"
  card: "10px"
  section: "12px"
  large: "14px"
  pill: "999px"

spacing:
  xxs: "2px"
  xs: "4px"
  sm: "6px"
  md: "8px"
  lg: "10px"
  xl: "12px"
  xxl: "14px"
  xxxl: "16px"
  loose: "20px"
  page: "32px"

motion:
  hover-duration: "140ms"
  press-duration: "100ms"
  compact-transition: "180ms"
  state-transition: "240-280ms"
  spinner-cycle: "900ms"
  button-press-scale: "0.97"
  chip-press-scale: "0.985"
  hover-overlay-opacity: "0.06"

components:
  top-bar:
    backgroundColor: "{colors.light-page} / {colors.dark-page}"
    textColor: "{colors.light-ink} / {colors.dark-ink}"
    typography: "{typography.page-title}"
    height: "52px"
  search-field:
    backgroundColor: "{colors.light-surface} / {colors.dark-surface}"
    textColor: "{colors.light-ink} / {colors.dark-ink}"
    typography: "{typography.body}"
    rounded: "{rounded.control}"
    width: "384px maximum"
    height: "34px"
    padding: "0 12px"
  toolbar-icon-button:
    backgroundColor: "{colors.light-surface} / {colors.dark-surface}"
    textColor: "{colors.light-ink} / {colors.dark-ink}"
    rounded: "{rounded.control}"
    width: "34px"
    height: "34px"
  group-card:
    backgroundColor: "{colors.light-surface} / {colors.dark-surface}"
    textColor: "{colors.light-ink} / {colors.dark-ink}"
    rounded: "{rounded.card}"
    width: "304px"
    minHeight: "206px in comfortable home mode"
    padding: "12px"
  group-card-title:
    textColor: "active accent"
    typography: "{typography.group-title}"
  selection-control:
    backgroundColor: "neutral / warning-soft / success-soft"
    textColor: "neutral / warning / success"
    rounded: "{rounded.control}"
    width: "34px"
    height: "34px"
  project-pill:
    backgroundColor: "{colors.light-surface} / {colors.dark-surface}"
    typography: "{typography.body-strong}"
    rounded: "{rounded.control}"
    height: "28px"
  tag-label:
    textColor: "tag accent"
    typography: "{typography.body}"
    height: "16px"
  settings-section:
    backgroundColor: "{colors.light-surface} / {colors.dark-surface}"
    rounded: "{rounded.section}"
    padding: "14px"
  detail-pane:
    backgroundColor: "{colors.light-surface-nested} / {colors.dark-surface-nested}"
    rounded: "{rounded.card}"
    padding: "14px"
  menu-bar-shell:
    backgroundColor: "{colors.light-page} / {colors.dark-page}"
    rounded: "{rounded.section}"
    width: "360px"
  toast:
    typography: "{typography.body-strong}"
    rounded: "{rounded.pill}"
    padding: "10px 14px"
---

# Design System: Skill Flow Desktop

## Overview

**Creative North Star: “The Skill Operations Board”**

Skill Flow Desktop 是一个用于检查、导入、分组、部署和维护 agent skills 的 macOS 工作台。视觉上应像安静、精密的运维面板：信息密度高，但状态边界清楚；交互紧凑，但不会挤成传统管理后台；强调真实对象、当前选择和下一步操作，而不是装饰性指标。

主界面使用四级中性灰建立层次，用户选择的 accent 只负责当前对象、选中状态、主操作和局部身份。卡片、列表与详情页共享同一套 8–12px 圆角、0.5px 边框和 11–13px 信息字体。阴影只用于输入控件、浮层和独立空状态，不用于制造卡片墙。

**Key Characteristics**

- macOS 原生系统字体与紧凑控件节奏。
- light / dark 双主题，结构一致，只调整明度与对比度。
- 六种用户可选 accent，但单个界面上下文只使用一种主 accent。
- Group Card 是 Home、Import 和 menu bar 的共享核心组件。
- 状态通过颜色、图标、计数和文字共同表达。
- 边框优先、阴影克制、无装饰性渐变。
- 整卡点击关闭；详情导航限定在标题、署名和统计等明确区域。

## Scope

覆盖：

- macOS desktop 主窗口。
- Home、Import、Detail、Settings 页面。
- menu bar quick config。
- Group Card、标签、选择控件、浮层、toast、空状态和 Markdown 文档呈现。

不覆盖：

- CLI / TUI 的终端排版规范。
- README、官网或发布截图的 marketing 风格。
- App Icon、第三方 agent icon 和内容图片本身的绘制规范。

## Colors

### Surface Ladder

界面使用四级无彩色 surface。层级由相邻 surface 的明度差和 0.5–1px 边界建立，不依赖大面积阴影。

| Role | Light | Dark | Use |
| --- | --- | --- | --- |
| Page | `{colors.light-page}` #f2f2f2 | `{colors.dark-page}` #222222 | 主页面底色、header、menu bar 背景、文档 block |
| Surface | `{colors.light-surface}` #fdfdfd | `{colors.dark-surface}` #0e0e0e | Group Card、详情 header、设置 section、输入控件 |
| Nested Surface | `{colors.light-surface-nested}` #f9f9f9 | `{colors.dark-surface-nested}` #151515 | Detail body、一级嵌套工作区 |
| Strong Neutral | `{colors.light-surface-strong}` #e6e6e6 | `{colors.dark-surface-strong}` #353535 | 选中边界、scope pill 边框、较强分隔 |

Surface mapping：

- Page background 使用 Page，不直接使用纯白或纯黑。
- Page 上的卡片使用 Surface。
- 卡片内部的可编辑块、文件内容块和未选控件通常回落到 Page。
- Detail 主内容区域使用 Nested Surface，内部文档内容块再使用 Page。
- 同一层级不通过随机灰度制造差异；优先复用上述四级结构。

### Text

- **Primary Ink**：light `{colors.light-ink}`，dark `{colors.dark-ink}`。用于标题、控件文本、主要数据。
- **Muted Ink**：light `{colors.light-muted}`，dark `{colors.dark-muted}`。用于署名、路径、说明、统计和未选状态。
- 深色模式的搜索 placeholder 比普通 muted 更亮，避免输入框内提示失去可读性。
- 禁用态通过 muted、透明度和不可交互状态共同表达，不能只降低透明度到难以阅读。

### Accent Palette

用户可在 Settings 中选择一种主 accent。light / dark 使用独立色值，避免机械复用同一 RGB。

| Accent | Light | Dark |
| --- | --- | --- |
| Blue | `{colors.accent-blue-light}` #3b82f6 | `{colors.accent-blue-dark}` #7db0ff |
| Green | `{colors.accent-green-light}` #22c55e | `{colors.accent-green-dark}` #4ade80 |
| Yellow | `{colors.accent-yellow-light}` #eab308 | `{colors.accent-yellow-dark}` #facc15 |
| Pink | `{colors.accent-pink-light}` #ec4899 | `{colors.accent-pink-dark}` #f472b6 |
| Orange | `{colors.accent-orange-light}` #f97316 | `{colors.accent-orange-dark}` #fb923c |
| Purple | `{colors.accent-purple-light}` #8b5cf6 | `{colors.accent-purple-dark}` #a78bfa |

**The Single Accent Rule.** 同一 screen context 只激活一个全局 accent。自定义标签可使用自己的 accent，但标签色不能替代页面的主操作色。

Accent 用于：

- Group Card 标题和当前对象标识。
- 选中 scope、sidebar indicator、active tab 和 checked state。
- 主操作、可操作文字和 focus tint。
- 拖拽插入线、最近选择的强调和局部 tag identity。

Accent 不用于：

- 大面积页面背景。
- 普通说明文字。
- 所有图标的默认着色。
- 健康、警告和错误语义的替代色。

### Agent Identity Colors

- Agent identity color 用于 Usage「每日趋势」中代表 Agent 的数据系列，以及「最常用 Agent」排名圆点；图例、面积、曲线、tooltip 和排名圆点保持同一颜色映射。
- 每日趋势显示 Skill 系列时使用普通图表色板；未知与 Custom Agent 同样回退到该色板。
- 「最常用 Agent」中的未知与 Custom Agent 回退到中性色；Group Card 及其他界面不展示 Agent identity color，图标与辅助圆点使用中性前景色。
- Agent identity color 不替代页面 accent，也不修改第三方 logo 原始资产。选中背景、focus 和主操作继续使用当前用户 accent。
- 色值、证据等级和官方来源记录见 [Agent identity colors](references/REF_agent-identity-colors.md)。

### Semantic Color

- **Success / healthy / fully selected**：green。
- **Warning / partial / needs review**：yellow。
- **Error / destructive / failed**：orange-red；dark 模式使用更浅的 red 以保证对比度。
- **Neutral / loading / unknown**：neutral surface + primary or muted ink。

状态不能只靠颜色：warning 与 error 使用图标和计数；选择状态使用 `OFF / PARTIAL / ON`；loading 使用 ProgressView 与文案；toast 使用背景、边框和文字共同表达。

### Glass, Borders, and Scrims

- Header glass：light white 44% / dark white 8%。只用于工具栏的轻微层次。
- Toolbar button fill：light white 55% / dark white 10%。
- 通用结构边界：light black 12% / dark white 12%。
- 卡片常用 0.5px border；pane divider 和 metadata row divider 使用 1px。
- Modal scrim：light black 18% / dark black 35%。
- Busy card scrim 必须保留底层结构可辨识，但阻止误以为仍可操作。

## Typography

### Font Family

- **UI Sans**：SwiftUI `.system`，在 macOS 上解析为 SF Pro 系列。
- **Technical Mono**：SwiftUI `.monospaced` / SF Mono，用于路径、版本、数量、metadata、搜索提示中的固定技术片段和 fallback agent abbreviation。
- 不引入 Geist、Inter 或自定义 display font。当前产品的视觉语言依赖 macOS 原生字形与控件比例。

### Hierarchy

| Token | Size | Weight | Use |
| --- | --- | --- | --- |
| `{typography.dialog-title}` | 20px | 600 | 大型编辑 sheet 标题 |
| `{typography.group-title}` | 21px | 400 | Group Card 与 Detail 主对象标题 |
| `{typography.page-title}` | 17px | 600 | Top bar 页面标题、App 名称 |
| `{typography.section-title}` | 14px | 600 | Dialog 标题、空状态标题、局部 section 标题 |
| `{typography.row-title}` | 13px | 600 | Settings row、sidebar 主要条目 |
| `{typography.body}` | 12px | 400 | 搜索、说明、卡片 metadata、普通控件 |
| `{typography.body-strong}` | 12px | 600 | 按钮、toast、强调型小标题 |
| `{typography.caption}` | 11px | 400 | 路径、次要说明、compact metadata |
| `{typography.micro}` | 10px | 600 | 状态计数、窄控件、fallback 标识 |
| `{typography.mono-body}` | 11px | 400 mono | 文档 metadata、路径、版本和原始内容 |
| `{typography.mono-label}` | 11px | 600 mono | Metadata key、技术标签 |

### Principles

- 21px Group 标题保持 regular，避免每张卡都产生过强视觉重量。
- 17px page title 与 13px row title 使用 semibold 建立结构。
- 11–12px 是主要信息密度区间；不要随意降到 9px 以下。
- Uppercase 只用于搜索提示和短 section label，不用于长句或本地化正文。
- Mono 只标记技术内容，不用于全部产品 UI。
- 行高和字距沿用平台默认；若未来引入显式 token，必须同时验证中、英、日三种语言。

## Layout

### Spacing System

基础节奏以 2px / 4px 为微调单位，以 8px / 12px / 14px / 16px 为结构单位。

- 2–4px：标题与 metadata、标签内部、紧凑对齐。
- 6–8px：同组控件、icon 与 label、chip 间距。
- 10–12px：卡片内部 section、列表项、top bar item。
- 14px：Grid 横向 gap、Detail pane gap、Detail content padding。
- 16px：页面边距、Import 内容 padding、modal 基础 padding。
- 20–32px：仅用于大型 sheet 或页面外层，不用于 Group Card 内部。

### Main Window Grid

- Group Card 固定列宽 304px。
- 横向 grid gap 14px，纵向 gap 12px。
- Home 根据扣除 sidebar 后的可用宽度计算 1–4 列。
- Import 使用窗口断点：≤620px 为 1 列，621–860px 为 2 列，861–1120px 为 3 列，>1120px 为 4 列。
- Import grid 最大宽度 1260px；内容在可用空间内居中。
- Home 主内容左右总 padding 32px。

### Sidebar and Header Geometry

- Home sidebar：常规 244px，窗口 ≤760px 时 208px。
- Home sidebar header：52px；traffic-light leading inset 68px。
- Top bar：52px；窗口 ≤860px 时 Home header 可拆成上下两行。
- Search field：最大 384px，最小可用宽度由当前 header 的固定按钮动态扣除。
- Toolbar icon button：34 × 34px。
- Project / filter pill：28px 高。

### Detail Workspace

- Detail 外层 padding 16px，sidebar 与 main pane 间距 14px。
- Sidebar 常规宽 280px；窗口 ≤860px 时 230px。
- Sidebar 与 main pane 使用 10px radius、0.5px border。
- Detail header 最小高度 84px，内部 padding 14px。
- Group sidebar row 64px，skill row 60px，分组间隔 10px。
- Selected indicator 为 4 × 36px accent bar，并使用 spring 过渡。
- File tree row 高 28px，guide column 16px，icon column 14px。

### Menu Bar Geometry

- menu shell 固定宽度 360px，圆角 12px。
- 卡片列表可视高度 360–440px。
- 顶部搜索区域 44px，底部 action bar 30px。
- 列表水平 padding 8px，卡片间距 8px。
- 卡片技能列表在 hover 500ms 后展开，离开时以 180ms 收起。

### Whitespace Philosophy

空白服务于对象边界，不服务于展示感。Page 外层保持 16px；卡片内部保持 12px；信息行通常保持 6–10px。不要在同一页面混入 40px 以上的大段营销留白，也不要用多层卡片 padding 叠加制造过厚边缘。

## Elevation and Depth

Skill Flow 使用 **surface + border first** 的深度语言。

| Level | Treatment | Use |
| --- | --- | --- |
| Page | Page neutral，无 shadow | 主窗口、menu bar canvas |
| Card / Pane | Surface + 0.5px border | Group Card、Settings section、Detail pane |
| Control | Surface + 0.5px border + `0 2px 4px` compact shadow | Search、toolbar icon button |
| Empty state | Glass surface + `0 6px 10px` soft shadow | 需要独立识别的空状态 |
| Modal | Surface + 0.5px border + `0 8–10px 18–20px` shadow | Rename、Group Editor、Custom Agent sheet |

### Shadow Vocabulary

- **Control Lift**：radius 4px，y 2px；仅用于 header 和 menu bar 的精密控件。
- **Empty Lift**：radius 10px，y 6px；仅用于启用 chrome 的空状态。
- **Modal Lift**：radius 18–20px，y 8–10px；配合 scrim 表示独立操作层。
- Group Card、Settings section、Detail pane 默认无 drop shadow。
- dark 模式 shadow 使用低透明白色，避免黑色阴影在深色表面完全消失。

## Shapes

### Border Radius Scale

| Token | Value | Use |
| --- | --- | --- |
| `{rounded.xs}` | 4px | Skeleton、极小 metadata block |
| `{rounded.sm}` | 6px | menu chip、compact control |
| `{rounded.row}` | 7px | Popover row、subtle button |
| `{rounded.control}` | 8px | 默认按钮、输入框、selection control、pill-like scope |
| `{rounded.card}` | 10px | Group Card、Detail pane、文档 block、dropdown shell |
| `{rounded.section}` | 12px | Settings section、menu shell、custom agent sheet |
| `{rounded.large}` | 14px | 少量大容器；不得作为默认卡片半径 |
| `{rounded.pill}` | 999px | Toast capsule、selection indicator 端点 |

**The 8/10/12 Rule.** 8px 表示 control，10px 表示工作对象或 pane，12px 表示更高一级的 section 或 shell。不要为相邻组件随意新增 9px、11px、13px 半径。

## Components

### Top Bar

**`top-bar`** — 52px 高，背景使用 Page surface。左侧呈现 App identity 或 back + page title；中间可放 search；右侧放导入、分组编辑、更新和设置等操作。Header 不使用独立大阴影，层级来自 Page 与下方内容的 surface 差。

**`toolbar-icon-button`** — 34 × 34px，8px radius，Surface fill、0.5px border、Control Lift。图标通常 14px，默认使用 Primary Ink，active 或 identity 状态才使用 accent。

### Search

**`search-field`** — 最大宽 384px、高 34px、水平 padding 12px、8px radius。leading search icon 为 11px；clear action 为 22px 可点击区。Home 使用普通 UI sans；Import 的固定提示片段使用 mono。

Rules：

- 未聚焦且 query 为空时显示 placeholder。
- Query 非空时提供明确 clear action。
- Enter 触发搜索或导航；清除后恢复 idle 状态。
- Import 搜索 action 的出现使用 opacity + 0.92 scale transition。

### Home Sidebar

Sidebar 负责 Status、Source Type、Tags、Agents 和 Projects 等筛选。Section header 使用 11px semibold uppercase；row title 使用 12–13px。选中项使用 accent soft fill 与明确文字/数量，不用单纯改变文字颜色。

Sidebar 可折叠；折叠控制保持 28 × 28px。自定义标签支持拖拽排序，drag handle 与 insertion indicator 使用 accent。

### Group Card

**`group-card`** 是 Home、Import 和 menu bar 的共享交互单元。

- 固定 grid 宽 304px。
- comfortable home 模式最小高度 206px。
- 默认 padding 12px、section spacing 10px、radius 10px、0.5px border。
- 标题 21px regular + accent；署名和统计 12px muted。
- Agent / Skill 区域使用水平 fade scroll，避免强制压缩 chip。
- Header、Agents、Skills、Summary 的显示由 display mode 决定，不复制出平行卡片实现。

Display modes：

| Mode | Purpose | Density behavior |
| --- | --- | --- |
| Home Comfortable | 主窗口完整管理 | subtitle、meta、section title、divider、最小高度 |
| Home Compact | 主窗口快速扫描 | 移除部分 meta、section title 和 divider |
| Menu Comfortable | menu bar 快速配置 | 0.8 visual scale，skills 可 hover 展开 |
| Menu Compact | menu bar 高密度 | 进一步减少辅助信息 |
| Import Search | 搜索导入 | 强调选择与 import action |
| Import Recommendation | 推荐导入 | 增加推荐 badge 与说明 |

**Click Policy.** 整卡点击始终关闭。只有标题、署名、统计或明确按钮可触发详情、外部链接、路径打开和 mutation，避免误点 Agent、Skill、Tag 或 tri-state control。

### Group Card Header and Actions

- 标题区域可显示 recently-updated 6px green dot、warning icon + count、error icon + count、original-name info。
- More / Pin action 使用 22 × 22px 内容区；popover 宽 176px，row 高 30px、radius 7px。
- destructive action 使用 error semantic，不使用 accent。
- Import 主操作在 enabled 时使用 accent fill 或 accent soft fill；disabled 时回到 neutral surface + muted ink。

### Selection Controls

Tri-state selection 必须保持三种明确语义：

| State | Fill | Text | Label |
| --- | --- | --- | --- |
| Empty | neutral Page block | primary/muted | `OFF` |
| Partial | warning at 32–38% opacity | warning | `PARTIAL` |
| Full | success at 30–36% opacity | success | `ON` |

Home / Detail 的 selection control 基准为 34 × 34px。选择行为同时改变 fill、text 和 label；加载时保留同一 control geometry，内部替换为 ProgressView，避免布局跳动。

### Agent and Skill Chips

- Agent target cell：34px 高，短标签或 agent icon，selected 使用 accent soft fill。
- Skill chip：34px 高、12px regular；长文本允许横向滚动，不压缩到不可读。
- Group tag：16px 高、12px regular，以文字和 accent 表达 identity，不绘制厚重胶囊背景。
- Tag editor 的 add/delete control 仅在相关 hover / edit context 出现，避免常驻噪声。

### Import Surface

Import 复用 Group Card，不创建第二套卡片语言。搜索、推荐和 local scan 只改变 header action、badge、说明和本地 variant selector。

- 空结果、失败和 loading 在无 card 时居中呈现，最小高度 200–220px。
- Loading 使用 regular ProgressView + 12px muted message。
- 本地 variant 使用 segmented Picker，置于卡片下方，水平 inset 2px。
- 多个 import 可进入 queue；queued、running、disabled 必须有可辨识状态。

### Busy and Loading State

Group Card busy 时：

- 内容 opacity 降至 0.34。
- 内容 blur 0.8px。
- 顶层 scrim 覆盖卡片。
- 中心显示 small ProgressView + semibold message。
- 禁止 card、menu 和 selection mutation。

Loading placeholder 保持最终内容几何：stats、agent tiles、document tabs 和 text lines 使用固定宽度 skeleton，减少完成加载后的跳动。

### Detail Workspace

Detail 采用 sidebar + main 双 pane：

- Sidebar 选择 Group Overview 或某个 Skill。
- Main header 始终保留对象 title、author、stats 和 action。
- Main body 使用 Nested Surface；文档内容使用 Page block。
- Group Overview 先展示 tags、agents，再展示 group documents。
- Skill Overview 先展示 document tabs，再展示 Markdown / raw content。
- File tree selected row 使用 accent soft fill + 2px leading accent marker。

Detail sidebar selection indicator 使用 spring response 220ms、damping 0.82；其他内容切换保持 180–240ms，不能出现大幅滑动。

### Markdown and Technical Content

- Markdown 使用 GitHub-like structured text style，并允许 text selection。
- Metadata table 使用 11px mono；key semibold、固定宽 120px，value regular。
- Metadata row 水平 padding 12px、垂直 padding 10px，row 间 1px divider，container radius 10px。
- Path、version、word count 和 raw fallback content 使用 mono。
- 外部链接交由系统默认浏览器打开。

### Settings

Settings content 最大宽度 900px。每个 section 使用 14px padding、12px radius、0.5px border；section 间距 12px，页面 section stack 间距 16px。

- Section label：11px bold uppercase muted。
- Row title：13px semibold；description：11px regular muted。
- 控制列固定 168px；dropdown 宽 148px、高 32px。
- Dropdown option 高 30px、radius 7px；shell radius 10px。
- Agent row 使用 10px vertical / 12px horizontal padding、10px radius。
- Drag handle 32 × 32px，agent icon 28 × 28px。
- 不可见 agent row 保持可读，但 content opacity 降至 0.45，surface opacity 降至 0.55。

### Dialogs, Popovers, and Sheets

- Rename dialog：最大宽 360px、padding 16px、8px radius。
- Group Editor：560 × 520px、padding 16px、8px radius；内部使用 segmented tabs、search 和 selectable rows。
- Custom Agent sheet：最小宽 560px、padding 20px、12px radius。
- Modal 使用 light 18% / dark 35% scrim；点击 scrim 可关闭非破坏性编辑。
- 浮层 action row 统一使用 30–34px 高和 7–8px radius。

### Menu Bar Quick Config

Menu bar 保留完整 Group Card 的 Agent / Skill selection 能力，但去除详情跳转。顶部为 search + close，底部只保留 Import 和 Settings 入口。

- Shell 固定 360px，不做可变宽 popover。
- Top / bottom overlay 与 menu canvas 使用同一 Page surface，避免形成三段式重边框。
- Scroll indicator 默认隐藏。
- Hover 展开只影响 skill content，不改变 card ownership 或 selection state。

### Toasts and Feedback

Toast 使用 capsule，12px semibold，padding 10 × 14px，最多两行。

| Style | Background | Extra signal |
| --- | --- | --- |
| Loading | neutral Surface | small ProgressView |
| Success | green soft surface | green foreground / border |
| Neutral | neutral Surface | neutral border |
| Error | red soft surface | error border；text 保持可读 |

非 loading toast 默认约 2 秒后消失；点击可提前关闭。Toast 文案必须使用用户可理解的 presentation copy，不直接暴露 bridge 内部错误码。

### Empty States

空状态由 title + subtitle 构成，通常 14px semibold + 12px regular muted，最小高度 200px。只有需要从背景中独立识别时才启用 glass chrome 与 soft shadow；Import 的 standalone empty / loading 默认保持无额外 chrome。

## Interaction and Motion

Motion 用于确认 hover、press、selection、loading 和层级变化，不用于装饰。

| Token | Value | Use |
| --- | --- | --- |
| `{motion.hover-duration}` | 140ms | Button / chip hover overlay |
| `{motion.press-duration}` | 100ms | Press scale |
| `{motion.compact-transition}` | 180ms | Card collapse、sidebar toggle、menu hover collapse |
| `{motion.state-transition}` | 240–280ms | Header action、update completion、placeholder change |
| `{motion.spinner-cycle}` | 900ms | Refresh / update icon rotation |

Rules：

- Button press scale 0.97；chip press scale 0.985。
- Hover overlay opacity 0.06；selected chip hover 可降至 0.03。
- Disabled controls不缩放、不显示 active hover。
- Card 本身不做 press scale，因为整卡不是 action。
- Skill collapse 使用 180ms easeInOut。
- Menu skill hover expand 延迟 500ms，避免掠过时闪烁。
- Tag hover editor 可延迟 1s 收起，给精密指针操作留出容错。
- Update / refresh 旋转 900ms linear repeat，结束回位 280ms。
- Import rotating prompt 每 2.2s 切换，transition 280ms；不能抢过真实搜索结果的注意力。

## State Language

### Selection

- `empty`：没有任何 child 被启用。
- `partial`：部分 child 被启用。
- `full`：全部 child 被启用。

### Runtime

- `idle`：可操作，无进行中任务。
- `queued`：已进入 Group Operation Queue，等待执行。
- `saving / updating / downloading`：禁止冲突 mutation，显示 busy overlay。
- `recently updated`：短时 green dot，仅表示刚完成，不写入长期 health。
- `warning / error`：显示 icon + count，不用 badge 文字堆叠替代问题详情。

### Health

Menu bar health 只使用 `unknown / healthy / warnings / error` 四级 icon。Group Card 不重复绘制一整套 health badge；优先展示具体 warning / error count 和可操作入口。

## Accessibility

- 所有核心 action 必须可通过 keyboard focus 到达；TextField 支持 Enter submit。
- 纯 icon control 必须提供 accessibility label 或 help text。
- 状态不能只靠颜色：同时提供图标、文字、计数、形状或 ProgressView。
- Card detail navigation 限定在明确区域，避免嵌套 control 产生误触。
- 技术内容和 Markdown 文档允许 text selection。
- 未选、禁用和 loading 状态仍需保持可读对比度。
- Desktop precision control 基准为 28–34px；核心 selection 与 toolbar control 使用 34px。不得将可点击图标缩成视觉 glyph 本身的 10–14px hit area。
- 支持 system、简体中文、English、日本語；新增固定宽度、uppercase 或截断规则时必须验证三种语言。
- 减少动态效果时，重复旋转、自动 placeholder 和非必要 transition 应能够被关闭或降级。

## Content Tone

产品文案使用“状态 → 原因 → 下一步”的工具型语言。

Do：

- 明确对象：group、skill、agent、project、document。
- 明确动作：Import、Update、Enable、Disable、Restore、Open。
- 对失败提供下一步，而不是只给内部错误。
- 路径、版本和原始标识保留技术准确性。

Don't：

- 不使用营销口号或拟人化成功文案。
- 不直接向用户显示 `BRIDGE_REQUEST_INVALID` 一类内部代码。
- 不用 `Something went wrong` 取代可定位原因。
- 不在按钮中混入完整说明句；说明放在 subtitle、help 或 issue detail。

## Do's and Don'ts

### Do

- 使用四级 neutral surface 建立 Page、Card、Nested content 和 Strong border。
- 同一 screen context 只使用一个主 accent。
- 默认使用 8px control、10px card、12px section 半径。
- 复用 Shared Group Card 的 display mode，而不是复制 Home / Import / Menu 卡片。
- 使用 0.5px card border 和 1px divider 保持 macOS 精密感。
- 将 destructive action 固定映射到 error semantic。
- 在 selection、loading、warning 和 error 中保留文字或图标信号。
- 让布局变化优先通过信息裁剪和 display mode 降密度，再考虑缩小字体。

### Don't

- 不把 accent 铺满 page、card 或大面积 header。
- 不在普通 Group Card 上添加 drop shadow。
- 不把整张 Group Card 变成点击目标。
- 不新增与 8 / 10 / 12px 冲突的随机半径。
- 不把正常正文压到 10px 以下。
- 不用 decorative gradient、glow 或玻璃拟态替代真实层级。
- 不让 dark mode 只是 light RGB 的机械反转。
- 不为 Home、Import、Detail 和 menu bar 创建不同的 selection 语义。

## Responsive Behavior

### Breakpoints

| Width | Key Changes |
| --- | --- |
| ≤620px | Import 1 列；detail sidebar 使用接近可用宽度的窄窗策略 |
| 621–760px | Import 2 列；Home sidebar 使用 208px narrow width |
| 761–860px | Home sidebar 回到 244px；Home top bar 可使用窄布局；Detail sidebar 230px |
| 861–1120px | Import 3 列；常规单行 top bar；Detail sidebar 280px |
| >1120px | Import 4 列；Home 依据主列可用宽度最多 4 列 |

### Density Strategy

- 窄窗口先减少 meta line、section title、divider 和辅助说明。
- Group title、selection control 和核心 action 尺寸保持稳定。
- Grid 从 4 → 3 → 2 → 1 列，不压缩 304px card 到不可维护宽度。
- Header search 先缩短到最小宽度，再切换两行布局。
- Menu bar 固定宽 360px，不参与主窗口 breakpoint。

## Implementation Map

| Design area | Current source |
| --- | --- |
| Theme、accent、surface、text、semantic color | `apps/desktop-mac/Sources/DesktopApp/Screens/Home/MainView.swift` 中的 `AppTheme` |
| Header、grid、sidebar、responsive geometry | `apps/desktop-mac/Sources/DesktopApp/Screens/Home/MainView.swift` 中的 `MainView` / `LayoutMetrics` |
| Group Card geometry and display modes | `apps/desktop-mac/Sources/DesktopApp/Components/GroupCardComponents.swift` |
| Tag editing and tag presentation | `apps/desktop-mac/Sources/DesktopApp/Components/GroupTagComponents.swift` |
| Hover and press motion | `apps/desktop-mac/Sources/DesktopApp/Components/DesktopInteractionMotion.swift` |
| Menu bar quick config | `apps/desktop-mac/Sources/DesktopApp/Components/MenuBar/MenuBarQuickConfigView.swift` |
| Detail pane and file tree geometry | `apps/desktop-mac/Sources/DesktopApp/Screens/Detail/DetailScreen.swift` |
| Settings sections and controls | `apps/desktop-mac/Sources/DesktopApp/Screens/Settings/SettingsView.swift` |
| Markdown presentation | `apps/desktop-mac/Sources/DesktopApp/Components/MarkdownDocumentView.swift` |

## Iteration Guide

1. 先确定改动属于 Page、Control、Card、Section 还是 Modal 层级。
2. 优先引用现有 color / typography / rounded / spacing token，不在单个 view 内新增近似值。
3. 新 Group Card 需求先扩展 display mode profile，不复制整个组件。
4. 新状态至少定义 default、hover、pressed、disabled、loading、selected 和 error 中适用的部分。
5. 每个视觉状态都检查 light / dark 与六种 accent，尤其 yellow 在 light surface 上的对比度。
6. 每个布局变化验证中文、英文、日文长度和 mono path 截断。
7. 结构变化后同步本文件与对应 snapshot / layout test；纯实现重构不得无故改变已记录 token。

## Known Gaps

- `AppTheme`、layout metrics 和 component metrics 仍分散在多个 Swift 文件中，尚未形成独立 token module。
- 字体 line height 与 letter spacing 依赖 SwiftUI 平台默认值，未建立显式 typography renderer。
- Keyboard focus ring 主要依赖系统行为与 tint，尚未定义统一的自绘 focus halo。
- Reduce Motion 降级策略尚未在所有自动旋转和 placeholder animation 中集中实现。
- Detail 在极窄窗口下的 pane collapse 仍需进一步统一；当前主要通过 sidebar 宽度与内容压缩适配。
- Group Card、Settings、Detail 的部分 8 / 10 / 12px 值仍直接写在 view 中，文档是规范事实源，但实现尚未全部 token 化。
- Menu bar 固定 360px，尚未定义超大字体或极端本地化长度下的替代布局。

## Related Verification

- [Group Card state matrix](verification/GROUP_CARD_STATE_MATRIX.md)
- [Group Card usage context](references/REF_group-card-usage-context.md)
- [Group Card element visibility matrix](references/REF_group-card-element-visibility-matrix.md)