Theme developer usage

Integrating Skins into your theme involves writing a .yml file that overrides or extends the theme's default templates, CSS, or JavaScript. Skins can be provided by themes or modules and there is an event triggered that allows modules to alter existing skins or add new ones.

Preparing the skin files

Each skin consists of a set of files which can include pretty much anything that you might put into a subtheme. The paths to files in a skin are defined in a *.skins.yml file (more on that below) so there's no set directory structure to use. A common approach might be to create a skins directory in the root directory of your theme and, withing that directory, create one child directory per skin. The following might be the the structure for a skin called "bluify":

skins
--bluify
----bluify.css
----screenshot.png
----templates
------page.html.twig
 

Once you've assembled the files, you can create the file that will register the skins.

The *.skins.yml file

Skins are registered via a .yml format file that's included in a theme's or a module's base directory. The format for skins is based on that of the theme *.info.yml file--see the relevant documentation. Technically, a skin's YML is merged into the applicable theme's YML. This makes it possible for a skin to override or extend pretty much anything that's in the theme.

To provide twig templates for your skin, you will need to install the Components module and include a relevant section in your skin definition. See that module's project page for documentation.

For example, if your theme's name is mytheme, to add skins, you add a file called mytheme.skins.yml to the theme's directory. The following would add two skins:

# A skin called 'bluify'.
bluify:
  # Everything in a regular theme .info.yml file is supported.
  # Values are merged in.
  # @see https://www.drupal.org/docs/8/theming-drupal-8/defining-a-theme-with-an-infoyml-file
  name: 'Bluify'
  description: 'A blue look'
  # The path for the screenshot is relative to the providing extension's directory.
  screenshot: 'skins/bluify/screenshot.png'
  # If providing a skin from a module, you can specify the theme or themes the skin applies to.
  # themes:
  #   - mytheme
  # In this case, we override the main .css file from the theme.
  libraries-override:
    mytheme/global:
      css:
        base:
          dist/css/original.css: skins/bluify/bluify.css
orangify:
  name: 'Orangify'
  description: 'Rhymes with orange'
  screenshot: 'skins/orangify/screenshot.png'
  libraries-override:
    mytheme/global:
      css:
        base:
          dist/css/original.css: skins/orangify/orangify.css

Skin-specific templates

The Skins module adds theme suggestions for the currently active skin. Suggestions are in the form *--themename-skinname.html.twig where themename is the name of the theme and skinname is the name of the skin. For example, on a site where the home page is set to /node/1 and the active theme is mytheme and the "bluify" skin is selected, the following suggestions might be available for the home page template:

• page--front--mytheme-bluify.html.twig
• page--front.html.twig
• page--node--1--mytheme-bluify.html.twig
• page--node--1.html.twig
• page--node--%--mytheme-bluify.html.twig
• page--node--%.html.twig
• page--node--mytheme-bluify.html.twig
• page--node.html.twig
• page--mytheme-bluify.html.twig
• page.html.twig

When you add a template that includes the theme and skin names, that template will be used only when the given skin is active.

If you're placing your templates in a directory that's outside the default 'templates' directory, you may wish to add the skin's template directory to the theme's namespace by integrating with the Components module. See that module's project page for relevant documentation.