When to use a SharePoint 2013 Composed Look (a.k.a. Theme)

To be perfectly honest, I am not sure. From the demo perspective, Composed Looks have a lot of oohh ahhh sex appeal but when you drill down to the nitty gritty of development and deployment, the oohs and ahhs turn into, oh no and ah geez. 🙁

(The acronym OOTB, used several times in this post, stands for out-of-the-box)

Themes over time

One thing that SharePoint seems to do with every version is reboot the theming capabilities of the product. Here is the path we have taken over the years…

SharePoint 2007

Back in 2007 themes were added to SharePoint and allowed you to use/create a CSS file that was applied in addition to the regular SharePoint CSS. The theme CSS file would overwrite existing SharePoint CSS. You can think of it as repainting your house. SharePoint branding was still there, but the theme CSS changed up colors and images. You could actually do a good bit with themes because it was just a CSS file. If there was a class or ID in the code, you could use it in your theme CSS file and write style statements to do things like add images, move around page components or hide them.

SharePoint 2010

Themes take a different turn and still use CSS, but introduce theming comments which allow you to specify what in the CSS can be changed. So instead of adding entire style statements, you have to specify which CSS property can be changed. Here is an example:

/* [ReplaceColor(themeColor:"Dark2")] */ color:#204d89;

This was done because of THMX files, which are a part of the Office theming engine, which was utilized in this version. This is an Office theme file you create in an application like PowerPoint where you specify a color palette that can be used. This opened up theme creation to a broader audience but at the same time restricted the flexibility we once enjoyed in SP2007.

SharePoint 2013

New version, new approach. THMX files have been ditched but theming comments are still around. But this time you can customize them (which is nice) and pair it with a master page and background image. Management of colors and fonts has been shifted from THMX files to new, separate files stored in SharePoint.

One of the challenges over the years is that themes haven’t stayed the same. And when the technology changes, it makes it difficult to carry over existing work to the new version. Because of this I usually warn people to avoid themes unless they really hit the mark regarding meeting a project requirement. And I always warn that it will not (or in SP2013’s case) may not upgrade easily to the next version. There will always be rework involved.

What is a Composed Look?

The best way I can explain a Composed Look would be to compare it to a SharePoint content type. When you focus on the core function of a content type, it is a collection of metadata and settings. And the meta data is reusable. Composed Looks are very similar. It is a collection of branding files displayed as a list of settings. And the files are reusable.

The components of a Composed Look

When you create a Composed Look, you will be working with the following files:

  1. Master page, also referred to as site layout (required) – you point to a master page file that is stored in the site. It must be stored in the same site as the Composed Look. So no pointing to a master page stored in a parent or sibling site. I have seen some inaccurate info online that says you may only use an OOTB SharePoint master page (such as Seattle.master or Oslo.master) but this is NOT TRUE. You can use a custom master page.
  2. Master page preview file (required) – this is the silent partner to the master page that must exist or your Composed Look will never show up in the design gallery (Change the Look) when the user tries to switch designs. The preview file is stored along side the master page in the Master Page Gallery. It is a simplified version of your web page design (written in code). This is the only file you will not get prompted to point to when you create a new Composed Look.
  3. SharePoint color scheme file, also referred to as a theme (required) – list of 89 customizable properties for various things in the SharePoint design. For example, disabled button text color, dialog border color and page background color. The color scheme file allows you specify new values for existing properties in the CSS files, which have been tagged with theming comments, thus allowing them to be changed. Here is an example pairing:
    From corev15.css:

    body {
    /* [ReplaceColor(themeColor:"PageBackground")] */ background-color:#fff;

    From color scheme file:

    <s:color name="PageBackground" value="000000" />

    You can also add custom properties to this list. Let’s say you have a set of transparent PNG files being used as icons and you want the user to be able to set the background color for the icon (via selecting a pre-existing color palette). You can add your own theming comment to your custom CSS and a matching color property in the color scheme file.
    Your custom CSS file:

    .my-class {
    /* [ReplaceColor(themeColor:"IconBackground")] */ background-color:green;

    Added to color scheme file:

    <s:color name="IconBackground" value="blue" />

    Just remember you can’t delete any OOTB properties in the color scheme file.

  4. Background image file (optional) – an image that will be used as the background for the body of the web page. Please note that this image will not scroll with the page!
  5. SharePoint font scheme file (optional) – a bit bulkier than the color scheme file, the font scheme file does the same thing. It allows you to set the font face (but not size, weight, color) for given page components like the headings, navigation and body. You can even set the fonts per language.

Adding a new Composed Look screen

So that is it. All a Composed Look is a group of settings pointing to different files that come together to create new branding. Any of the components can be reused with other Composed Looks.

After you set up the Composed Look and when a user goes to apply it to a site, they do have the option to change up the settings for their site (it won’t allow them to modify the Composed Look directly – only affect the application of the Composed Look on their site). A Composed Look could be considered a Suggested Look, or a Starting Point Look. If there are other color/font schemes or other master pages available, the user could select them. They can also change out the background image.

User can modify applied Composed Look

If you are here for an instructional how-to for building a Composed Look, sorry this post won’t help you. This post focuses on the issues of using a Composed Look. For a good how to, check out Benjamin Niaulin’s post, Step by Step: Create a SharePoint 2013 Composed Look.

So why doesn’t Heather like Composed Looks?

Here is my laundry list of why I don’t care for Composed Looks. If you figure out something that conflicts with what I say below, by all means let me know in the comments! I am open to suggestions and other ways to do stuff!

File storage

I mentioned before that the master page that the Composed Look uses must be stored in the same site as the Composed Look. At first you think, no big deal. However when you start to consider larger implementations this is definitely a big deal. We are talking about potentially hundreds of copies of your master page depending on your site structure. Here is a copy of the master page library in a sub site that is nested 3 levels deep under the top level site.

Need master and preview files for Composed Look

Most organizations who would be interested in implementing design variations (possibly accomplished by Composed Looks) would be these same large SharePoint environments.

To be fair and round out our file storage discussion, color and font scheme files are stored in the top level site collection and not at the per site level. The background image can be stored anywhere.

No inheritance

A site can inherit the branding from the parent, and that is groovy, but sub sites don’t inherit the Composed Looks created and available at the parent. Not so groovy. So we have to deploy the master page to every sub site, and the Composed Look to every sub site (where it could be potentially used). Keep in mind the color and font schemes are only deployed at the top level site.

Rights at the parent

To sum it up, if a person applying the Composed Look is working with a sub site, then they need to have two sets of rights in the SharePoint environment:

  1. Designer rights for the sub site where they are applying the Composed Look.
  2. Read rights for the Theme Gallery located in the top level site since this is where the color and font scheme files are stored.

Not much else to say here. This may or may not pose a problem for you and your environment. Thanks to John Ross for previously sorting this out.

Background image

Earlier I noted that when you use the background image it is applied to the body. SharePoint disables scrolling of the web page and recreates it again via it’s own means (this is all for the ribbon) so any image set for the body won’t scroll when you scroll the page. This is pretty minor and just something to keep in mind when considering your background image content.

More important about the background image is when you let your users customize the look as they apply it to their site. As you create a new Composed Look, pointing to a background image is optional. If you use that setting, you can point to an image file that is stored anywhere… the web server, in a SharePoint library, etc.

Set background image from anywhere

But when the user is in charge and they select a background image, they have to upload the file from their local computer. There is no option to choose an existing file in SharePoint or even to paste in your own URL. The dialog box for adding an image immediately sends you to browse your computer and doesn’t allow anything else.

Set background image from local file

Most designers I know, including myself, are control freaks. Users picking their own images for upload and use on a web page make most designers clap their hands to their cheeks in horror. Major concerns are file size, image content and if it compliments the design. Rainbow ponies anyone?

No error love

I am just going to go ahead and quote MSDN on this one: “If there is an issue with the composed look values, the composed look is not added to the design gallery, and no message is recorded in the log files. The following are possible reasons why a composed look cannot be added: a file cannot be found, there is a formatting issue with one of the files, or SharePoint is unable to access the files.”

A little translation, the “design gallery” that they mention is the Change the Look screen (located at designgallery.aspx). Regardless of issues, your Composed Look will be saved as a new item to the design library (/_catalogs/design/AllItems.aspx). But if there are issues, it may not show up in the design gallery.

I have found all three reasons to be true. A Composed Look can break because…

  1. You pointed to a master page that is not saved at the current site level.
  2. You removed OOTB values from the color scheme file (for example: you delete s:color name=”PageBackground” value=”000000″).
  3. Your links to resources are bad (even when they really aren’t). Be sure to use the Verify option when linking up files. If the file won’t open when you select Verify, the Composed Look won’t show up in the design gallery.

Select Verify to confirm resource path

Wild wild west

Piggybacking on being a control freak, another concern is Composed Looks can’t be locked down. As long as you have more than one master page, color/font file and a user with an image saved on their desktop, your Composed Look can quickly morph into something that isn’t approved or what you intended. This is a carry over problem/concern from SharePoint 2010 and the use of THMX files.

If your user applies a Composed Look that is set to use a different master page, then the master page will be changed for the site – no matter what you have set in Master Page settings.

You can circumvent this with a little CSS. Here is a carryover trick from how I handled this issue with SharePoint 2010 themes… target the wrapping container around the customizable settings and set it to display: none.

form[action*="designbuilder.aspx"] #sideNavBox {
display: none;

With this in place, your screen now looks like this:

Hide settings that allow for customization

Clean up

Many people who dealt with themes in SharePoint 2007 or 2010 probably faced the question of, what do we do with all the OOTB themes? The same question still lives on in 2013. Unless you are not worried about your users selecting the wrong Composed Look, then you will need to clear out the Composed Looks available for the site. Also, if you are concerned about your users changing your Custom Look to use an OOTB color scheme, font scheme or master page, then you need to remove those as well. Refer to the second screenshot under “The components of a Composed Look” above.

Preview files

Oh the best is for last… I really dislike the master page preview file. I mean really really dislike it. Essentially you will code your master page file and everything is great, then for the preview file you have to code it all over again using different code bits and no SharePoint components. Anyone who creates a master page for SharePoint will say the last thing they want to do is make it all over again.

So what to do? Randy Drisgill mentioned to me his approach and I like it… Take a screenshot of your site and have the preview file point to that, essentially treating it like a giant thumbnail. You can include a message about how to view the live preview or where to see the master page in action. Perhaps a “move along, nothing to see here” message. 🙂 Luckily when you move to the “Try it out” page, it uses the regular master page and not the preview file.

Where the Preview file is used

As a side note, if you are using Design Manager to generate your master page, a preview file is NOT created for you. This is a manual process all the way. When you are ready to dive into this, you can check out the MSDN article, How to: Create a master page preview file in SharePoint 2013.

When do you use a Composed Look?

For me, Composed Looks come with a lot of baggage. Not to mention that creating a custom themed CSS file is a tedious process. I am going to have to stick with the same advice I have been telling folks for years… avoid Composed Looks (themes) unless it really meets the needs of your project. At the very least carefully consider the above concerns and make sure any caveats will be acceptable/workable in your environment. One thing I say so often I should get a tattoo of it, is a quote from Dustin, “what sucks for us may be great for you”. Composed Looks may be the ticket for your needs.

As of right now, I think they are best used for people who are fine with the OOTB site design (Seattle or Oslo) and just want to incorporate their custom colors. You can easily create a custom color scheme file and since the color scheme file is stored at the top level site and used by all the sub sites, you don’t have to worry about deploying it everywhere. I think Custom Looks are best for smaller SharePoint implementations and teams with limited branding resources.

Things to remember when building themed CSS

This is directly connected and worth mentioning. When you decide to build a theme (Composed Look) for SharePoint 2013 and you are working on your custom CSS, please be sure to do the following for your themed CSS file to actually work! Most of these rules are the same as SharePoint 2010.

  1. The themed CSS file must be stored in the Themable directory in the Style Library – not the Themable folder in the Master Page Gallery.
  2. You must use CSS Registration to call your themed CSS file in your master page.
    <SharePoint:CssRegistration name="/Style Library/INSERT_PATH.css" runat="server"/>

    Be sure that “%20” is not inserted between “Style” and “Library”. If so it could generate an error on your web page.

  3. Your themed CSS file must be checked in for you to see the styles.
  4. You must reapply the theme to see any file changes.

Thanks for sticking it out for this super long post about Composed Looks! I will get off my soapbox now. 😉