SharePoint’s new theming engine approach

What are themable annotations?

Annotations are special comment-style markup that tell the SharePoint theming engine how to theme properties in a CSS file. When a theme is applied to a site, the theming engine replaces the CSS property values with the appropriate theme values. In SharePoint 2013, you can use annotations to change the color, font, or background image. You can also recolor an image. If you are using custom CSS files, you must add these annotations to the CSS files if you want to use them with the SharePoint theming engine. If you apply a theme to a site that uses custom CSS files, and you haven’t added annotations, the CSS properties remain unchanged. This can result in a site that has a mismatched design.

So, what’s changed?
Traditionally, you would add special annotations to a CSS file that would then be run through SharePoints theming engine. For your custom elements to pick up the theme colours, you would need to upload or deploy the CSS followed by selecting / setting a new theme through the “change the look” settings.

Now, in first release tenants, Microsoft have updated SharePoint Online to improve how they render site pages. You’ll begin seeing this change starting February 26. More can be read about this here.

How can annotations be applied differently?
For a usual project, I would write a number of LESS / CSS files. For the custom styles, I would use the “@import” tag to collate all my LESS files into one larger minified version. Usually, my custom styles and themable styles are always kept independent. The custom styles are referenced in the master page, whilst the themable styles are referenced as the “alternate CSS” and are uploaded to the Style Library > en-us > Themable folder.

Now, we have a couple more options which are a touch quicker. Each are explained below:

  1. CSS registration in the master page
  2. Alternate CSS reference
  3. Javascript reference


CSS registration in the master page
The first option maintains one of the traditional ways of referencing a CSS file, and that’s in the master page using a CSS Registration tag

Once the CSS file has been referenced, you can continue to include themable CSS annotations. Once saved and uploaded, you will not need to reapply a new / current theme to re-trigger the themable styles.


Alternate CSS reference
The second option is to create the same master styles CSS file which includes both custom elements and themable annotations, then reference it as an alternate CSS file. Like above,  once saved and uploaded, you will not need to reapply a new / current theme to re-trigger the themable styles.


JavaScript reference
A third could be to add the CSS reference either within a content editor web part or within a page layout. However, this alone will not trigger the restyling of the themable annotations. When referencing the link tag, be sure to include an ID attribute. In the example below, an ID of “masterStyles” has been applied.

Next, you’ll need to load custom JavaScript to let SharePoint know which file needs to be themed.


I’ve noticed that these approaches cause the CSS file to be referenced twice in the DOM. Not entirely sure how to resolve that just yet…



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s