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.