design-philosophy

VS Code 设计理念

这项技能是VS Code 设计理念的权威依据——是开发者和 Agent 思考 UI 时唯一可信的来源。

越来越多的 UI 由 Agent 和工具实现，像素层面的工作也越来越能自行完成，而稀缺的人类工作则变成了背后的设计判断。

这关乎左移——用设计术语讨论 UI，而不是讨论像素，并尽早展开这种对话。发现某处看起来不对劲时，说“这里是 8px，应该改成 6px”只能修正一个数字；说“这个表面的圆角属于错误的层级档位”则指出了规则，因此修复会覆盖所有地方，而且我们能在设计稿或截图中发现问题，而不是等到代码审查时才发现。我们的目标是用设计师和工程师都能理解的语言，就UI 应该是什么样，以及为什么达成共识——设计确定后，实现细节（使用哪个令牌、哪个文件）通常就会随之而来。

---

如何阅读：三个层次

任何设计语言中最难的部分，都是把*“感觉不对”*变成清晰一致、人人认同的修复方案。本文分三步搭起这座桥，每一层都解释下一层：

层次	含义	示例
价值	我们希望人们感受到什么，以及为何这一点至关重要	专注
原则	可用于评估设计的规则，以问题的形式表述	“一项内容引领，其余内容辅助”——视线首先落在哪里？
手法	具体的实现机制，每种手法都说明选哪种以及为什么	将次要面板降级为凹陷背景令牌／更轻柔的字体角色

学习这套体系时从上往下读，修复问题时从下往上读：先指出感受，再找出违背的原则，最后采用能恢复这种感受的手法。

示例——繁杂的面板

• **观察：**面板显得繁杂，总是把视线从编辑器上拉开。
• **感受：**既不平静，也不专注。
• **原则：**违背了静止时保持安静（它带有不该有的常驻填充色）和一项内容引领（次要的界面装饰元素与编辑器争夺注意力）。
• **手法：**将面板改为凹陷／透明背景令牌，仅在悬停时显示边框，并将其标签降级为更轻柔的字体角色。

---

价值：我们设计所追求的体验

这四项价值描述了我们希望人们使用 VS Code 时感受到什么——它们是最高层次，是下文每条原则和每种手法最终服务的目标。掌握它们，你就能描述几乎所有问题。每项都是 UI 应带给人的一种感受；每项都由下文的一条或多条原则来支撑。先从价值入手，再看原则，最后选择手法。

价值	含义	违背时的感受……	原则
平静	静止时保持安静、整洁；留有呼吸空间；柔和而不尖锐；表达朴实自然	繁杂、嘈杂、局促、参差、晦涩、刺耳
专注	层级清晰；一项内容引领，其余内容辅助	扁平、千篇一律，视线无处可落
一致	一切遵循相同的尺度和层级	随意、偏离网格、逐渐走样
愉悦	能发挥作用的小惊喜——引导、确认、定位	缺乏生气、突兀或哗众取宠

先说*“这感觉很吵，不够平静”，再说“背景应该透明”*。价值能让所有人聚焦于同一条原则。

为什么是这四项？

有人会问：谁会想要一个不够平静、专注、一致、令人愉悦的 UI？这正是重点。这些并非我们声称相较于其他产品的差异化优势——它们是在我们这类工具中最容易受到威胁的品质，而将它们明确提出，正是我们捍卫这些品质的方式。我们之所以选择它们，是因为 VS Code 在结构上最容易失去这些价值：

• 平静是 IDE 最先牺牲的品质。VS Code 信息密集，人们一用就是几个小时；每个功能团队都有充分理由再增加一个操作入口，累积起来就成了噪声。平静这一价值能抵御我们自身的惯性。
• 专注很重要，因为我们的界面层次很深。在一个强大工具中，满屏都是权重相同、同样合理的控件，是默认的失败模式。明确提出专注，能迫使我们决定什么才是主角。
• 一致是最需要捍卫、覆盖面也最大的品质。VS Code 由许多人历经多年构建；偏差是自然状态。一致与其说是一种愿景，不如说是一种维护纪律。
• 令人愉悦是我们刻意限量使用的品质。只有真正发挥作用时，它才值得保留（原则 7）。我们提出它，不是为了增添更多修饰，而是为了让它保持真诚：让愉悦感起到引导和确认作用，而不是装饰。

每个价值都体现了一种真实的权衡，而不是毫无代价的好处——这正是它们值得明确提出、而非沦为陈词滥调的原因：

• 平静与信息密度相权衡——在静止状态下，我们要展示多少内容？
• 专注与平等访问相权衡——我们要弱化什么，才能让一项内容成为主角？
• 一致与真正特殊的情况相权衡——什么时候差异是有依据的，而非偏差？
• 令人愉悦与克制相权衡——什么时候点缀会变成噪声？

因此，真正有用的问题不是“我们会不想要这些品质吗？”，而是“这个界面牺牲了哪项价值，我们是有意这样做的吗？”当某项价值确实必须让步时——例如，一条重要警告应该打破平静以吸引注意——这就是经过深思熟虑、明确标注的例外，而不是放弃这项价值的理由。

---

原则

原则是评估标准：每条原则都提出一个可以用来审视任何界面的问题，答案会告诉你设计是否恰当——与任何像素值无关。它们按所维护的价值分组。

---

平静

1. 静时安静，交互时显现

提问： 没有任何操作时，有什么东西在大声喧哗吗？

除非用户与之交互，否则界面元素应退居幕后。一个常驻填充色、边框或焦点环，却没有充分理由的界面，会和用户内容争夺本不需要的注意力。现代风格是克制的：元素在用户有意操作时——悬停、聚焦、交互——才显现，其他时候则安静待命。

如果这条原则没有落实，人们会说“静止时太醒目了／应该等到悬停时再显现”或“点击时触发了焦点环”——这是对行为的描述，而非颜色值。

通过以下方式落实： 按需显现的行为、单线条、主题颜色。

2. 留出呼吸空间

提问： 这里是否显得拥挤、局促或杂乱？

平静的 UI 应当宽松、柔和。留白不是浪费；它能让视线休息，并在不画任何线条的情况下将内容分组。边缘应圆润而非尖锐。当界面让人感到封闭或繁杂时，通常应在间距阶梯上增加留白，而不是缩小内容。

通过以下方式落实： 间距阶梯、层级（圆润而非尖锐）。

3. 界面应直白、友善地说明自身

提问： 用户能否一眼看懂，而不必猜测？

UI 的表达应像人与人交谈。优先使用文字，而不是含义不明的字形；采用句首字母大写的格式；保持语气亲切自然。一个没有标签的孤立图标，或一个标题格式的营销口号，都会让用户付出不必要的精力——表达绝不晦涩，也绝不大声喧哗。

通过以下方式落实： 文字与大小写。

让不可用的功能一目了然

用户会寻找他们在发行说明、文档或宣传内容中看到的功能。如果策略、账户权限、设置或版本要求导致某个相关选项无法使用，悄悄将其移除会让用户觉得产品出了问题。最好保留该选项供用户发现，但将其禁用，并简洁、如实地说明原因和有用的下一步操作。

• 使用权威状态区分受组织策略限制、需要登录／升级／更新、此处不支持和仍在加载；仅仅未出现在列表中，并不能证明它受策略限制。
• 沿用现有的禁用行样式，并使用公文包指示器表示受管理策略限制。提供可见的原因说明或可独立操作的了解原因链接；不要只通过悬停才能查看说明。
• 展示方式不得授予访问权限：阻止指针、键盘和过期菜单触发操作，同时确保说明链接仍可操作。请遵循无障碍指南。
• 这并不意味着一律公开所有内容。保留明确隐藏功能的选项（包括禁用 AI）、不受支持的提供商能力以及尚未发布的功能门控。在相关位置说明不可用的功能，但不要凭空声称支持，也不要暴露敏感的策略值。

重用以下模式，而不是复制整个实现：

界面	示例
设置	受管理设置指示器和无障碍策略文本
模型选择器	不可用模型及针对管理员、升级和更新的不同说明
Harness 选择器	可用性说明和策略帮助链接
权限选择器	共享的权限级别策略展示和选择器集成，以及运行时策略边界

示例——被挤满的工具栏

• **看到：**工具栏放在一条实心填充的栏上，每个按钮之间都有分隔线，按钮彼此紧贴。
• **感受：**并不宁静——显得繁杂、局促。
• **原则：**违背了静止时保持安静（填充和分隔线成了永久的装饰，却没有存在的必要）和留出呼吸空间（按钮挤在一起）。
• **做法：**让工具栏静止时呈现透明效果，去掉分隔线（一道线——在这里答案是不需要），并在渐变过程中拉开按钮间距。

聚焦

4. 突出一项，其余内容辅助

**思考：**视线首先会落在哪里——有没有次要内容在争抢注意力？

每个视图都应有明确的视觉焦点——视线首先应该落到的那一项。让次要信息避开这个位置：为其采用更低调的字体角色、凹陷的表面或更小的图标来弱化，让重要内容突出，其余内容提供辅助。如果所有内容的视觉权重都相同，视图就会显得平淡——视线无处可落。

通过以下方式实现：字体角色、层级、按上下文设置图标大小。

5. 层级通过编码表达，而非凭感觉判断

提问： 这个表面的圆角程度，是否与它相对下方内容的悬浮高度相匹配？

表面的圆润程度和凸起高度都有意义：它们能说明表面在层级中的位置。浮动覆盖层看起来会比平放在窗格中的控件更圆润。圆角取决于表面在层级中的角色，而非个人喜好。（这同时体现了聚焦和一致。）

通过以下方式落实： 层级、按需显示（滚动阴影）。

示例——扁平的设置行

• **观察：**设置行中的标签、帮助文本和“重置”操作，大小和字重都一样。
• **感受：**不够聚焦——显得扁平；视线不知道该落在哪里。
• **原则：**违背了突出一个重点——没有任何内容是关注中心。
• **调整：**将标签提升为首要文本角色，将帮助文本降为 body2，并将“重置”设为低调的次要操作，让设置行按从上到下的顺序呈现。

一致

6. 相同之物应看起来相同

提问： 两个相似的事物看起来是否完全一致——这里的任何差异是否都是有意为之？

相同的元素必须看起来相同，因为它们使用同一套命名尺度。两个相似的事物若有差异，这种差异就应该有意义；意外的偏差是大忌。这就是为什么每个尺寸、圆角、字重和颜色都是带有角色的命名令牌，而不是具体数值——具体数值只是对应令牌的替代写法。

通过以下方式落实：下文中的每项做法——它们就是共享尺度。尤其参见设计令牌、间距阶梯、字号阶梯、图标尺寸、统一描边。

示例——两个不匹配的对话框

• **观察：**两个对话框并排打开；一个圆角为 8px，另一个为 6px——它们都是浮动覆盖层。
• **感受：**不够一致——界面显得前后不一。
• **原则：**违背了相同之物应看起来相同（两个等效表面无故看起来不同），也违背了层级通过编码表达（覆盖层应属于 Outer 层级）。
• **调整：**让两者都使用 Outer 圆角令牌；6px 是某人直接输入的具体数值，而非通过命名层级来选用。

愉悦

7. 愉悦设计必须物有所值

提问： 这能帮助用户做什么？

动效、渐显效果和润饰细节都值得采用——但每一项都必须发挥作用：引导视线、确认操作、帮助用户定位，或让跳转更平顺。如果无法回答这个问题，那它就是装饰，而装饰看起来只会像噪声（回到平静）。保持细腻、短暂且可中断；遵循 prefers-reduced-motion；绝不为动画而动画。

动效的问题应当是*“这个过渡对我毫无帮助”（删掉它），或“这个跳转让人摸不着方向——需要一个有实际作用的过渡”*（加上一个），而不是纠结时长或缓动值。

通过以下方式落实：按需显示行为。

示例——弹跳面板

• **观察：**每次切换侧面板时，它都会以 600ms 的弹跳效果滑入。
• **感受：**不够愉悦（显得花哨），也不够平静（缓慢而张扬）。
• **原则：**违背了愉悦设计必须物有所值——弹跳没有发挥作用，而且切换操作本身已经很明显。
• **调整：**如果无需帮助用户定位，就删掉动画；如果面板出现时确实需要帮助用户理解位置变化，就用短暂、细腻且可中断的淡入效果替代，并遵循 prefers-reduced-motion。

---

具体做法：机械工具箱

具体做法是具体的机制——令牌、递增阶梯和层级。单独来看，它们只是允许值的列表；让每项具体做法真正可用的，是说明选哪个值，以及为什么的决策规则，以及它所服务的原则。采用某项具体做法时，先讲规则，而不是照搬字面值。

本节是唯一涉及实现的部分——即便如此，目标仍是让对话围绕设计展开。应将具体做法视为让已达成共识的设计得以一致实现的共享词汇，而不是评审的开场白。先明确感受和原则，再采用具体做法，绝不能用它们取而代之。

尺寸和字体令牌位于 baseSizes.ts；完整参考请见 design-tokens.instructions.md。

令牌才是事实来源，而不是像素

设计系统中的间距、圆角、字体角色和颜色，在有对应命名令牌或递增阶梯时，应使用它们。结构性尺寸仍可使用原始字面值。

• **决策规则：**发现某处看起来不对时，找到它应该表达的令牌，并围绕令牌进行推理，而不是围绕字面值。
• **服务于：**相同之处应体现相同（6）。

一个 8px 的圆角并不是“8px”。它是有人直接输入字面值的外层表面圆角。明确角色后，修复方法自然就清楚了。

高度层级——按角色取整，而不是按字面值

圆角半径表达一个表面相对于其下方表面的悬浮高度。每个带圆角的元素都恰好属于一个层级：

层级	半径	令牌	含义
控件	4px	--vscode-cornerRadius-small	可交互元素——按钮、输入框、列表行、标签页
内部	6px	--vscode-cornerRadius-medium	位于表面内部的非控件容器
外层	8px	--vscode-cornerRadius-large	悬浮／覆盖层表面——菜单、悬停提示、对话框、提示气泡

胶囊形元素（半径约为高度的一半）应为全圆形（--vscode-cornerRadius-circle），而不是“一个很大的半径”。

• 决策规则：根据表面在层叠结构中的角色选择层级，而不是看圆角的外观。此处的错误应描述为*“这个覆盖层使用了控件层级的圆角”，而不是“这里需要更大的 border-radius”*。
• **服务于：**高度通过视觉编码（5）、留出呼吸空间（2）。

间距递增阶梯——符合阶梯或不符合阶梯

内边距、外边距和间隙应取自间距递增阶梯（0、2、4、6、8、10、12、16、20、24、28、32、36、40）。

• 决策规则：一个值要么符合阶梯，要么不符合。不符合阶梯的值（3、5、7、14、26……）会破坏节奏；应调整到最近的步长，距离相同时向上取整。描述节奏问题时，应说“这个值不符合间距递增阶梯”，而不是“加几个像素”。
• **服务于：**留出呼吸空间（2）、相同之处应体现相同（6）。

字体递增阶梯——明确角色和两种字重，而非随意设定字号

文本样式是角色，不是任意字号：heading1–3、body1–2、label1–3。字重恰好有两种——regular（400）和 semiBold（600）。没有 medium（500）。所谓“强调”不是放大字号，而是使用相同角色令牌并设为 semiBold。

• 决策规则：根据文本在层级中的位置选择角色，而不是凭目测字号。看起来不够醒目的标题，问题应描述为*“字体角色不对”或“缺少 semiBold 字重”，而不是“把字体调到 14”*。任何地方出现 500 都表示不符合递增阶梯。
• **服务于：**突出一个重点（4）、相同之处应体现相同（6）。

图标尺寸 - 两种尺寸，按上下文选择

Codicon 的尺寸为 **16px（基础）**或 12px（紧凑），没有其他尺寸；14px 始终是错误。在紧凑尺寸下，还要改用 *Compact 字形（Codicon.close → Codicon.closeCompact），让图标经过视觉优化，而不只是缩放。

• 决策规则：尺寸取决于上下文的密度和层级。独立显示或用于主要操作、需要舒适点击区域时，使用基础尺寸（16px）；用于密集行、行内字形，以及与文本并列的次要界面元素时，使用紧凑尺寸（12px）。因此，对于“用 16 还是 12？”这个问题，答案是*“这个图标在此处扮演什么角色？”，而不是个人喜好。应说“这个图标应使用紧凑尺寸”，而不是“把它稍微缩小一点”*。
• 服务于： 突出一项内容（4）、一致性传达一致性（6）。

单一线宽

标准边框／分隔线宽度为 1px（--vscode-strokeThickness）。

• 决策规则：是否显示普通边框是一个是／否的决定。保留较粗的语义性或无障碍线条，例如焦点指示器。
• 服务于： 静止时保持安静（1）、一致性传达一致性（6）。

颜色来自主题

所有颜色都是 --vscode-* 主题令牌，因此 UI 会适配当前主题和高对比度模式。

• 决策规则：硬编码十六进制颜色本身就是错误。颜色问题应描述为“主题令牌错误”（或“令牌在浅色／HC 模式下不可见”），而不是需要微调的十六进制值。
• 服务于： 静止时保持安静（1）、一致性传达一致性（6）。

按需显示的行为

过去一直带有填充色的界面元素现在在静止时显示为透明，只在交互时显现。每种行为也各司其职，因此一举两得：

• commandCenter - 静止时透明；悬停时显示背景／边框，让指针确认自己所指向的对象。

• statusBar - 与窗口融为一体；悬停时只有背景变化，前景保持不变。

• keyboardFocusOnly - 仅在键盘聚焦（:focus-visible）时显示焦点环，鼠标点击时不会显示，因此只在有用时才呈现相应提示。

• scrollShadows - 内容在表面边缘下方渐隐，而不是被硬边界截断，让人感受到折叠区域之外还有更多内容。

• 服务于： 静止时保持安静（1）、恰到好处的惊喜才有价值（7），以及（滚动阴影）用高度变化编码层级（5）。

文案与大小写

优先使用文字标签，而不是图标。文字一看便知；图标则需要猜测。只有在含义近乎普遍（关闭、搜索）或空间确实有限时才使用字形，否则就用文字标注，或者在需要兼顾识别与记忆时搭配图标和标签。单独出现的神秘字形才是问题，而不是图标选得不够好：应说“这个操作没有标签——给它加上文字”，而不是“找个更清晰的图标”。

使用句首字母大写格式。标签、按钮、菜单和消息只将首词和专有名词首字母大写——“Start new session”，而不是“Start New Session”。这种格式更平和、亲切，也更便于快速浏览。应将问题描述为“这是标题式大小写——改为句首字母大写”，这是语气上的调整，而不是改写文案。

⚠️ 已知冲突 - 后续协调。此处的句首字母大写规范是现代 UI 的预期方向，但它与仓库级编码指南相矛盾；该指南要求命令标签、按钮和菜单项使用标题式大小写（参见 coding-guidelines.instructions.md 中的“UI labels”）。这两种规范尚未协调。在协调完成前，已发布的非实验性 UI 应遵循现有的标题式大小写规则，句首字母大写仅适用于已明确采用现代 UI 方向的界面。TODO：确定统一的大小写规范，并更新相应文档。

• 服务于： 界面能自我说明（3）。

---

措辞手册：描述问题，指出原则

先说角色 / 层级 / 阶梯，而不是数值——然后指出原则，让修复能应用到所有地方，而不只是眼前这一处。数值只是症状。

❌ 不要这样说	✅ 应该这样说	原则
“圆角半径应该是 6，而不是 8”	“这是一个 Inner 表面，应使用 Outer 层级的圆角”	5 · Elevation
“这个菜单的圆角太尖了”	“这个叠加层应该使用 Outer 圆角层级”	5 · Elevation
“增加 2px 内边距”	“此内容偏离间距阶梯 / 需要留出阶梯间距”	2 · 留出呼吸空间
“把这个改成 14px”	“这里应该使用 label1 / body1 字体角色”	4 · 以一为先
“标题看起来太细了”	“标题缺少 semiBold 字重”	4 · 以一为先
“这里用 font-weight 500”	“500 不在阶梯上——应改为 semiBold（600）”	6 · 一致性
“把这个图标稍微缩小一点”	“这个图标应该使用紧凑（12px）尺寸 + *Compact 字形”	4 · 以一为先
“这个图标是 14px”	“codicon 只有 16 或 12 两种尺寸——选标准尺寸或紧凑尺寸”	6 · 一致性
“这个普通边框太粗了”	“标准边框是单像素描边（1px）——这里应该 / 不应该有边框；较粗的焦点 / 语义描边应保留”	1 · 静止时保持低调
“换掉这个灰色十六进制值”	“这是错误的主题令牌 / 在浅色 / HC 模式下会消失”	6 · 一致性
“命令中心周围有个方框”	“界面装饰在静止时应保持低调，悬停时再显现”	1 · 静止时保持低调
“我点击时会显示焦点轮廓”	“焦点环只应在键盘焦点时显示（:focus-visible）”	1 · 静止时保持低调
“列表底部被截断了”	“这个表面缺少滚动阴影渐隐效果”	7 · 愉悦感 / 5 · Elevation
“窗格标题有条线 / 硬边”	“窗格标题应是圆角、无分隔线的分区标题”	1 · 静止时保持低调

---

提出和接收反馈

描述设计，而不是像素。 指出被违反的规则后，修复就能应用到所有出问题的地方，而不只是你碰巧注意到的那一处。

发现问题时，按以下顺序说明：

1. 感受——缺少四种价值中的哪一种？平静、专注、一致、愉悦。
2. 界面表面——是什么，在哪里？“侧边栏窗格标题”，“保存对话框”。
3. 违反的原则——导致这种感受的规则。
4. 修复方式——能够恢复这种感受的具体做法。
5. 最后才说数值（如有帮助）——“现在是 4px，看起来应该是 6px。”

示例 “活动栏让人感觉不够平静——静止时太过抢眼。图标一直带有填充色，和编辑器争夺注意力（静止时保持低调，有交互意图时再显现）。能否改为悬停时再显示填充色？它看起来也差不多紧了 2px，不过填充色才是主要问题。”

先说感受，而不是修复方式

这个词能让所有人想到同一个原则，即使大家还没就具体像素达成一致：

先这样说	不要这样说
“这让人感觉不够平静——静止时太吵了”	“把背景设为透明”
“这不够专注——视线无处落点”	“把标题做大一点”
“这让人感觉不一致——这两个对话框不匹配”	“把圆角改为 6”
“这个过渡不够愉悦，只是装饰而已”	“把动画调快一点”

为什么反馈难以落实

这些反馈并没有错，只是不够完整——它们修好了一个地方，却又渐渐偏离了统一标准：

• 只给出一个数字。 “这里应该是 6px。” 是哪个令牌？为什么？说明用途，修复才能应用到所有地方。
• 只表达喜好，没有规则。 “我不喜欢这个圆角。” 把它与某个值或原则联系起来，这样它才是共同标准，而不是个人偏好。
• 只说怎么改，没有说明感受。 “把它设为透明。” 也许可以——但先说清楚问题是什么（“它在静止时太抢眼”），这样我们修复的是根因，而不只是这个实例。
• 一次提出多件事。 把 “这个面板太杂乱、不符合网格，而且图标也不对” 拆成三条，每条都对应一个值。

实用建议

• 标明界面区域。 一张截图或一段短视频（用于说明动态效果），再加上视图名称，胜过一大段描述。圈出问题位置。
• 每个讨论串只讨论一条观察。 每条反馈只针对一个界面区域和一个值，这样就能单独讨论并解决。
• 浅色、深色与高对比度主题。 如果问题只在某个主题下出现，请说明——这通常意味着是主题令牌的问题，而不是颜色选择的问题。
• 减少动态效果。 对于动画反馈，请说明是否启用了 prefers-reduced-motion；即使没有动态效果，过渡也应该合理。