ux-theming

This skill covers color registration, CSS variable usage, widget style patterns, focus indicators, and high-contrast theme requirements.

---

1. Registering Colors

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

Rules:

• Provide defaults for all four theme types: light, dark, hcDark, hcLight.
• HC themes must use solid colors (avoid transparency) and set explicit borders via contrastBorder.
• Use color transforms for derived colors: transparent(), darken(), lighten(), oneOf().
• Reference existing colors when possible instead of hardcoding hex values.

2. Color Categories

File	Colors
src/vs/platform/theme/common/colors/baseColors.ts	foreground, focusBorder, contrastBorder, text links
src/vs/platform/theme/common/colors/editorColors.ts	Editor widgets, find match, errors/warnings
src/vs/platform/theme/common/colors/inputColors.ts	Input, toggle, validation
src/vs/platform/theme/common/colors/listColors.ts	List/tree selection, focus, hover, drop
src/vs/platform/theme/common/colors/miscColors.ts	Badge, scrollbar, progress bar, sash
src/vs/workbench/common/theme.ts	Tabs, sidebar, status bar, panels, editor groups, banner

3. Using Colors in CSS

Colors are injected as CSS custom properties on .monaco-workbench:

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

Conversion functions in colorUtils.ts:

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

In CSS files, reference directly:

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

Trace the rendered control before choosing a token or selector; custom editor overlays may not use native input pseudo-elements. Inspect inherited and nested styles as well as the component's own declarations.

Contrast and Interaction States

• Treat foreground and background as a semantic pair. A background change requires checking text, placeholders, links, operable inactive icons, hover, selection, and focus against the final composited surface.
• Resolve defaults, opacity, and user overrides before measuring contrast. For example, an opaque icon color may meet contrast requirements while its translucent inactive variant does not.
• Normal-size text and placeholders need at least 4.5:1 contrast; visual information needed to identify controls and focus needs at least 3:1 against adjacent colors. Apply the relevant accessibility criteria rather than extending these thresholds to decorative or disabled content. Unselected but operable controls are not disabled.
• Check nested labels and descriptions in combined states; an explicit child foreground can defeat a correctly paired selection background.

4. Widget Styles Pattern

File: src/vs/platform/theme/browser/defaultStyles.ts

Every widget type has a default style object and an override factory:

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

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

Available defaults: defaultButtonStyles, defaultInputBoxStyles, defaultCheckboxStyles, defaultToggleStyles, defaultDialogStyles, defaultListStyles, defaultSelectBoxStyles, defaultMenuStyles, defaultProgressBarStyles, defaultCountBadgeStyles, defaultBreadcrumbsWidgetStyles, defaultKeybindingLabelStyles, defaultFindWidgetStyles.

Transient Theme Overrides

Use the owning theme service for temporary palettes so CSS variables and programmatic color consumers remain consistent. Keep overrides scoped to the intended window and preserve the base theme and user customizations.

Verify enabling, disabling, replacement, disposal, and theme changes, including stale asynchronous results. Clearing an override must restore the original colors without persisting generated values or changing another window's theme or startup colors.

5. Focus Indicators

Defined in src/vs/workbench/browser/media/style.css:

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

Rules:

• Use var(--vscode-focusBorder) — never hardcode a focus color.
• Default outline-offset: -1px (inset). Exception: checkboxes use 2px.
• Active elements suppress focus ring: .my-widget:active { outline: 0 !important; }
• Use .synthetic-focus class for programmatic focus indication.
• Toggle buttons use border: 1px dashed var(--vscode-focusBorder) instead of outline.
• Check keyboard focus independently from selection and hover, including ordinary links without explicit tabindex and icon-only controls. Inspect computed outlines and pseudo-elements under production styles; token registration alone does not establish visibility.
• Preserve a clear focus boundary through clipping and modal wrappers. Resolve competing border/outline ownership rather than adding duplicate rings or removing focus visibility.

Focus Trapping

Modal dialogs must trap focus within the dialog until dismissed. Use dom.trackFocus() and handle Tab/Shift+Tab cycling.

6. High Contrast Theme Rules

• Always provide hcDark and hcLight defaults when registering colors.
• HC backgrounds: Color.black (hcDark), Color.white (hcLight).
• HC borders: reference contrastBorder — it is null in normal themes, visible in HC.
• HC focus: use activeContrastBorder (derived from focusBorder).
• In CSS, use .hc-black / .hc-light class selectors for HC-specific overrides:

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

• In TypeScript, check isHighContrast(theme.type) for runtime behavior changes.
• Box shadows must be removed or replaced in HC mode (shadows are invisible/distracting with high contrast borders):

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

Validate both HC themes explicitly when changing borders, focus, or theme-dependent visibility; default dark/light screenshots do not cover them. Render through the production state-owning services so intentionally omitted decoration remains absent.

Test runtime theme changes and custom color overrides, including transitions where a previously defined token becomes absent. Clear stale inline colors or classes rather than leaving the previous theme's state behind. Include competing workbench styles when inspecting the cascade.

7. No Hardcoded Visual Values

Reviewers will always flag hardcoded colors, shadows, sizes that should use theme tokens or CSS variables.

Hardcoded (flagged)	Correct
rgba(0, 0, 0, 0.12)	var(--vscode-widget-shadow) or theme-aware variable
#252526	var(--vscode-editor-background)
color: white	var(--vscode-button-foreground)
border: 1px solid #ccc	var(--vscode-editorWidget-border)
border: 1px solid … (width)	var(--vscode-strokeThickness) for the 1px width
border-radius: 6px	var(--vscode-cornerRadius-medium) (radius ramp)
padding: 8px 12px (off-scale)	spacing ramp (--vscode-spacing-size*)
font-size: 14px (arbitrary)	size ramp (--vscode-fontSize-*)
font-weight: 500	--vscode-fontWeight-semiBold (no 500)
codicon font-size: 14px	--vscode-codiconFontSize (16) / -compact (12)

Rule: If a value relates to color, shadow, or border — it must come from a CSS variable or registered color token. The only exception is 0 (zero) values and purely structural measurements like 100%.

Size, spacing, radius, font and stroke values have their own design-system size tokens (and decision logic — snap maps, the pill→circle rule, and the compact-glyph convention). Those live in the ux-css-layout skill (§10 Design-System Size Tokens) and the auto-injected .github/instructions/design-tokens.instructions.md. Reach for those when a flag is about how big / how round / how bold something is rather than what color.

---

Key Files

Area	File
Color registration	src/vs/platform/theme/common/colorUtils.ts
Color registry (barrel)	src/vs/platform/theme/common/colorRegistry.ts
Base colors	src/vs/platform/theme/common/colors/baseColors.ts
Workbench colors	src/vs/workbench/common/theme.ts
Default widget styles	src/vs/platform/theme/browser/defaultStyles.ts
Global workbench styles	src/vs/workbench/browser/media/style.css