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."));

ルール:

• 4 種類すべてのテーマ（light、dark、hcDark、hcLight）にデフォルトを指定します。
• HC テーマでは不透明色を使用し（透明色は避けてください）、contrastBorder で明示的に境界線を設定します。
• 派生色には色変換を使用します：transparent()、darken()、lighten()、oneOf()。
• 可能な場合は、16 進数値をハードコードするのではなく、既存の色を参照します。

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 での色の使用

色は .monaco-workbench 上の CSS カスタムプロパティとして注入されます：

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) を使用します。

フォーカストラップ

モーダルダイアログでは、閉じられるまでフォーカスをダイアログ内にとどめる必要があります。dom.trackFocus() を使用し、Tab／Shift+Tab による循環を処理します。

6. ハイコントラストテーマのルール

• 色を登録する際は、必ず hcDark と hcLight のデフォルトを指定します。
• HC の背景：Color.black（hcDark）、Color.white（hcLight）。
• HC の境界線：contrastBorder を参照します。通常のテーマでは null で、HC では表示されます。
• HC のフォーカス：focusBorder から派生する activeContrastBorder を使用します。
• CSS では、HC 固有のオーバーライドに .hc-black／.hc-light クラスセレクターを使用します：

  .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% などの純粋に構造上の寸法だけです。

サイズ、スペーシング、角丸、フォント、ストロークの値には、それぞれ独自のデザインシステムのサイズトークン（および判断ロジック――スナップマップ、pill→circle ルール、コンパクトグリフの規約）があります。これらは ux-css-layout スキル（§10 Design-System Size Tokens）と、自動挿入される .github/instructions/design-tokens.instructions.md に記載されています。指摘対象が「色」ではなく、「どのくらいの大きさ／丸み／太さか」に関するものであれば、こちらを参照してください。

---

主なファイル

領域	ファイル
色の登録	src/vs/platform/theme/common/colorUtils.ts
色レジストリ（バレル）	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