Umbraco Theme

What is it?

Themes in Umbraco allow you to customize the visual appearance of the backoffice. They can override CSS custom properties to change colors, typography, and other visual elements. This enables dark mode, high contrast, custom branding, or any other visual theme. Users can select themes from their profile settings.

Documentation

Always fetch the latest docs before implementing:

Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation
Extension Registry: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-registry
Themes: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types

Related Foundation Skills

Extension Registry: When registering themes
- Reference skill: umbraco-extension-registry

Workflow

Fetch docs - Use WebFetch on the URLs above
Ask questions - What colors? Dark/light? Brand colors?
Generate files - Create manifest + CSS based on latest docs
Explain - Show what was created and how to test

Minimal Examples

Manifest (manifests.ts)

import type { ManifestTheme } from '@umbraco-cms/backoffice/extension-registry';

export const manifests: Array<ManifestTheme> = [
  {
    type: 'theme',
    alias: 'My.Theme.Dark',
    name: 'My Dark Theme',
    css: () => import('./dark-theme.css?inline'),
  },
];

CSS Theme File (dark-theme.css)

:root {
  /* Background colors */
  --uui-color-surface: #1e1e1e;
  --uui-color-surface-alt: #252526;
  --uui-color-surface-emphasis: #2d2d30;

  /* Text colors */
  --uui-color-text: #d4d4d4;
  --uui-color-text-alt: #9d9d9d;

  /* Primary/accent colors */
  --uui-color-default: #3c3c3c;
  --uui-color-positive: #4ec9b0;
  --uui-color-warning: #dcdcaa;
  --uui-color-danger: #f14c4c;

  /* Interactive colors */
  --uui-color-interactive: #569cd6;
  --uui-color-interactive-emphasis: #9cdcfe;

  /* Border colors */
  --uui-color-border: #3c3c3c;
  --uui-color-border-standalone: #454545;

  /* Header */
  --uui-color-header-surface: #1e1e1e;
  --uui-color-header-contrast: #d4d4d4;

  /* Selected states */
  --uui-color-selected: #264f78;
  --uui-color-selected-contrast: #ffffff;
}

High Contrast Theme (high-contrast-theme.css)

:root {
  /* High contrast for accessibility */
  --uui-color-surface: #000000;
  --uui-color-surface-alt: #0a0a0a;

  --uui-color-text: #ffffff;
  --uui-color-text-alt: #e0e0e0;

  --uui-color-border: #ffffff;
  --uui-color-border-standalone: #ffffff;

  --uui-color-interactive: #ffff00;
  --uui-color-interactive-emphasis: #00ffff;

  --uui-color-focus: #ff00ff;
}

Brand Theme (brand-theme.css)

:root {
  /* Custom brand colors */
  --uui-color-current: #your-brand-primary;
  --uui-color-current-contrast: #ffffff;
  --uui-color-current-standalone: #your-brand-darker;

  /* Header with brand color */
  --uui-color-header-surface: #your-brand-primary;
  --uui-color-header-contrast: #ffffff;

  /* Interactive elements use brand */
  --uui-color-interactive: #your-brand-primary;
  --uui-color-interactive-emphasis: #your-brand-lighter;
}

Interface Reference

interface ManifestTheme extends ManifestPlainCss {
  type: 'theme';
}

interface ManifestPlainCss {
  type: string;
  alias: string;
  name: string;
  css: () => Promise<{ default: string } | string>;
}

Common CSS Custom Properties

Surfaces

--uui-color-surface - Main background
--uui-color-surface-alt - Alternative background
--uui-color-surface-emphasis - Emphasized background

Text

--uui-color-text - Primary text
--uui-color-text-alt - Secondary text

Status Colors

--uui-color-positive - Success states
--uui-color-warning - Warning states
--uui-color-danger - Error/danger states

Interactive

--uui-color-interactive - Links, buttons
--uui-color-interactive-emphasis - Hover states
--uui-color-selected - Selected items

Header

--uui-color-header-surface - Header background
--uui-color-header-contrast - Header text

Best Practices

Test themes with all UI components
Ensure sufficient contrast for accessibility
Consider dark/light mode variants
Use CSS custom properties for consistency

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.

umbraco-theme