ux-theming

此技能涵盖颜色注册、CSS 变量用法、控件样式模式、焦点指示器和高对比度主题要求。

---

1. 注册颜色

文件：src/vs/platform/theme/common/colorUtils.ts

export const myWidgetBackground = registerColor('myWidget.background',
    { light: '#ffffff', dark: '#252526', hcDark: Color.black, hcLight: Color.white },
    nls.localize('myWidgetBackground', "Background color of My Widget."));

规则：

• 为所有四种主题类型提供默认值：light、dark、hcDark、hcLight。
• HC 主题必须使用纯色（避免透明度），并通过 contrastBorder 设置明确的边框。
• 使用颜色变换函数派生颜色：transparent()、darken()、lighten()、oneOf()。
• 尽可能引用现有颜色，而非硬编码十六进制值。

2. 颜色类别

文件	颜色
src/vs/platform/theme/common/colors/baseColors.ts	foreground、focusBorder、contrastBorder、文本链接
src/vs/platform/theme/common/colors/editorColors.ts	编辑器控件、查找匹配项、错误/警告
src/vs/platform/theme/common/colors/inputColors.ts	输入框、切换控件、验证
src/vs/platform/theme/common/colors/listColors.ts	列表/树选择、焦点、悬停、拖放
src/vs/platform/theme/common/colors/miscColors.ts	徽标、滚动条、进度条、分隔条
src/vs/workbench/common/theme.ts	标签页、侧边栏、状态栏、面板、编辑器组、横幅

3. 在 CSS 中使用颜色

颜色会作为 CSS 自定义属性注入到 .monaco-workbench 上：

Color ID: editor.background
CSS variable: --vscode-editor-background
Usage: var(--vscode-editor-background)

colorUtils.ts 中的转换函数：

• asCssVariable(colorId) → 'var(--vscode-editor-background)'
• asCssVariableName(colorId) → '--vscode-editor-background'

在 CSS 文件中，直接引用：

.my-widget {
    background-color: var(--vscode-editor-background);
    color: var(--vscode-foreground);
    border: 1px solid var(--vscode-contrastBorder);
}

4. 控件样式模式

文件：src/vs/platform/theme/browser/defaultStyles.ts

每种控件类型都有一个默认样式对象和一个覆盖工厂：

// Use defaults:
const button = new Button(container, defaultButtonStyles);

// Override specific colors:
const button = new Button(container, getButtonStyles({
    buttonBackground: myCustomBackgroundColor
}));

可用的默认样式：defaultButtonStyles、defaultInputBoxStyles、defaultCheckboxStyles、defaultToggleStyles、defaultDialogStyles、defaultListStyles、defaultSelectBoxStyles、defaultMenuStyles、defaultProgressBarStyles、defaultCountBadgeStyles、defaultBreadcrumbsWidgetStyles、defaultKeybindingLabelStyles、defaultFindWidgetStyles。

5. 焦点指示器

定义于 src/vs/workbench/browser/media/style.css：

.my-widget:focus {
    outline-width: 1px;
    outline-style: solid;
    outline-offset: -1px;
    outline-color: var(--vscode-focusBorder);
}

规则：

• 使用 var(--vscode-focusBorder)，绝不硬编码焦点颜色。
• 默认 outline-offset: -1px（内缩）。复选框例外，使用 2px。
• 活动元素应禁用焦点环：.my-widget:active { outline: 0 !important; }
• 使用 .synthetic-focus 类来指示程序化焦点。
• 切换按钮使用 border: 1px dashed var(--vscode-focusBorder)，而非 outline。

焦点捕获

模态对话框必须将焦点限制在对话框内，直到对话框关闭。使用 dom.trackFocus() 并处理 Tab/Shift+Tab 循环切换。

6. 高对比度主题规则

• 注册颜色时，始终为 hcDark 和 hcLight 提供默认值。
• HC 背景：Color.black（hcDark）、Color.white（hcLight）。
• HC 边框：引用 contrastBorder；它在普通主题中为 null，在 HC 主题中可见。
• HC 焦点：使用 activeContrastBorder（派生自 focusBorder）。
• 在 CSS 中，使用 .hc-black / .hc-light 类选择器添加 HC 专用覆盖：

  .hc-black .my-widget { border: 1px solid var(--vscode-contrastBorder); }
  

• 在 TypeScript 中，使用 isHighContrast(theme.type) 检查并执行运行时行为变更。
• 在 HC 模式下，必须移除或替换盒阴影（高对比度边框下，阴影不可见或会造成干扰）：

  .my-widget {
      box-shadow: 0 1px 3px var(--vscode-widget-shadow);
  }
  .vscode-high-contrast .my-widget {
      box-shadow: none;
      border: 1px solid var(--vscode-contrastBorder);
  }
  

7. 不要硬编码视觉值

审查者总会标记应该使用主题令牌或 CSS 变量的硬编码颜色、阴影和尺寸。

硬编码（会被标记）	正确写法
rgba(0, 0, 0, 0.12)	var(--vscode-widget-shadow) 或适配主题的变量
#252526	var(--vscode-editor-background)
color: white	var(--vscode-button-foreground)
border: 1px solid #ccc	var(--vscode-editorWidget-border)
border: 1px solid …（宽度）	1px 宽度使用 var(--vscode-strokeThickness)
border-radius: 6px	var(--vscode-cornerRadius-medium)（圆角阶梯）
padding: 8px 12px（不符合比例）	间距阶梯（--vscode-spacing-size*）
font-size: 14px（任意值）	尺寸阶梯（--vscode-fontSize-*）
font-weight: 500	--vscode-fontWeight-semiBold（没有 500）
codicon font-size: 14px	--vscode-codiconFontSize（16）/ -compact（12）

规则： 如果某个值与颜色、阴影或边框有关，就必须来自 CSS 变量或已注册的颜色令牌。唯一例外是值为 0（零）的情况，以及 100% 这类纯结构尺寸。

尺寸、间距、圆角、字体和描边值都有各自的设计系统尺寸令牌（以及相应的决策逻辑——吸附映射、胶囊形状→circle 规则，以及紧凑字形约定）。这些内容见 ux-css-layout 技能（§10 设计系统尺寸令牌）和自动注入的 .github/instructions/design-tokens.instructions.md。如果标记针对的是有多大/有多圆/有多粗，而不是是什么颜色，请参考这些内容。

---

关键文件

区域	文件
颜色注册	src/vs/platform/theme/common/colorUtils.ts
颜色注册表（barrel）	src/vs/platform/theme/common/colorRegistry.ts
基础颜色	src/vs/platform/theme/common/colors/baseColors.ts
工作台颜色	src/vs/workbench/common/theme.ts
默认工具样式	src/vs/platform/theme/browser/defaultStyles.ts
全局工作台样式	src/vs/workbench/browser/media/style.css