Skip to content

Theme Authoring

When to Use

Use this when shipping a sub-theme with its own UI Skins variables and themes. Covers the full sequence from CSS authoring to theme settings form appearance.

Pattern

  1. Author CSS that consumes the variables:
/* css/theme.css */
:root { --brand-primary: #0066cc; }
body.theme-dark { --brand-primary: #3399ff; }
.btn-primary { background: var(--brand-primary); }
  1. Attach CSS in {theme}.libraries.yml:
global-styling:
  css:
    theme:
      css/theme.css: {}
  1. Declare CSS variables in {theme}.ui_skins.css_variables.yml:
brand_primary:
  type: ui_skins_alpha_color
  label: "Brand primary"
  category: "Colors"
  default_values:
    ":root": "#0066ccff"
    ".theme-dark": "#3399ffff"
  1. Declare themes in {theme}.ui_skins.themes.yml:
dark:
  label: "Dark"
  target: body
  key: class
  value: theme-dark

  1. Clear cache so YamlDiscovery picks up the files.

  2. Site builder visits Appearance → Settings → {your theme}, sees a "Colors" fieldset with a color picker and a "Theme" select.

Subtheme Inheritance

Sub-themes inherit parent theme UI Skins plugin definitions automatically. Override by declaring the same plugin ID in the sub-theme's YAML, or disable with enabled: false.

Common Mistakes

  • Putting the YAML files in subdirectories → Discovery scans only the theme/module root for *.ui_skins.css_variables.yml and *.ui_skins.themes.yml
  • Forgetting to attach the CSS that uses the variables → The values inject correctly, but no CSS rules consume them
  • Hardcoding values in CSS instead of using var() → Variable values inject but have no effect. Always reference var(--brand-primary) in CSS

See Also