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. 😉

13 thoughts on “When to use a SharePoint 2013 Composed Look (a.k.a. Theme)”

  1. This is a great article on why not to use a custom theme/composed look for a large organization with many site collections, subsites, etc; however, what approach do you recommend in place of the master page/theme solution to keep those sites with the same look globally and easy to manage in one place for the entire farm (or web application level)?

    1. If you have a custom layout then you need to use a custom master page, which can be globally deployed using a Feature. Otherwise and in addition to that, use CSS! CSS files can be stored on the web server so there is one, central location for you to make changes that would affect any site using that CSS.

  2. Our SharePoint 2010 CSS of course doesn’t work now in 2013. I haven’t had much luck fining a master list of 2013’s CSS including a description and purpose. Have you come across an easy way to either 1) understand the new CSS or 2) map 2010 CSS to 2013 CSS?

    1. With any version of SharePoint CSS one of the best ways to discover it and learn it is through using DOM inspection tools such as Firebug in Firefox. All the (latest) browsers have inspection tools now.

  3. Hi Heather – great article. You mention in the article that Composed Looks do no inherit, however, Composed Looks do inherit in Publishing Sites (which is possibly expected given how differently Publishing Sites work with branding).

    1. Yes, applying a composed look will allow you to push it to the child sites, but when you create a composed look at the parent it will not be available to apply in child sites (without first applying to the parent and pushing down to children). So you can’t create a library of composed looks at the parent level (say in a top level site) that is available for your child site end users to select from unless the composed looks are deployed to each of their child sites.

      1. Hi Heather – yep, just checked that out for myself and you’re absolutely right. While the Composed Look does get pushed down, the design gallery is localised to every site/sub-site which therefore means whatever custom theme you put together you have to add into each design gallery at every level! Ever get the feeling of being given something, and at the same time had it taken away?

        It’s not so bad I guess in a Publishing scenario, as the likelihood is that a single theme will be used throughout a single site collection and Composed Looks can fit that requirement. But when a Team Site is used across an organisation that might present quite a nightmare! It’s crazy to think that while the whole theming side of SharePoint has been opened up in the way it has, that there is still such a big requirement for development to make things happen with minimal fuss.

        1. More and more publishing sites are used internally for large Intranets and people often have the site requirement to do design variations per company department/area/whatever. Luckily Alt CSS in Master Page settings can handle this as composed looks are not set up well to do it!

  4. Great post. Our university is struggling with these issues right now. My $.02:

    “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.”

    Unless you have a single composed look, and users don’t have a choice of others in their local gallery. The all you have to do is remove all OOB composed looks upon site creation, and rely on inheritance in the Mater Page settings, which applies all components of the composed look from the parent. This, of course, only applies to publishing sites.

    For collab sites, which have no master page settings, and therefore no inheritance model, the composed look must be applied each and every time a collab site is created, using something like the feature stapler. In our case, this is where the issues you’ve raised are much more apparent. Cheers. Scott.

  5. I have recently been introduced to Sharepoint 2013, i have used the sharepoint palette download to change set colours in an .spcolor file. I have uploaded these and all worked fine however I now dont seem to be able to change the look it just hangs and when clicking Try this out i get an error message.

    I am using Oslo if that makes difference.

    I even tried just altered the .spcolor file and replaced it in the Themes folder 15. When I go to change the look the current theme shows the updates in the small preview thumbnail however the page does not.

    Does anyone know if this error is becasue ive uploaded my own .spcolor?

    1. I haven’t heard of this issue. I have used custom .spcolor files so that shouldn’t be the problem. You can replace the contents of your custom .spcolor file with a copy of a SharePoint one and test again to see if the issue is within the .spcolor file. If the problem persists you will know it isn’t the custom .spcolor file.

  6. Hi Heather,
    This is a great article and very helpful you just saved my time I was looking for an error into my Feature for adding a theme and I was thinking that this them will show up in every site 🙁 but not it will show up only in the root site, too bad that for those who need to manage a long list of sub sites we don’t have a good way to manage this Look and feel globally. Anyway thank you for this great article!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.