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

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

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.

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.

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

7. No Hardcoded Visual Values

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

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