Branding issues that may occur when upgrading to SharePoint 2013

SharePoint 2013 introduces a new user interface that is lightweight, fast, and fluid. This UI is built by using new CSS styles, themes, and master pages. To get this new experience, you need to upgrade to the new UI. However, the significant changes made to support the new UI may break the upgrade story for some scenarios where you use custom branding.

In SharePoint 2010, you may have branded your site in one of several different ways. For example, you may have branded your site by:

  • Applying a custom style sheet to your site that overrides the SharePoint default styles.
  • Applying a custom theme (THMX file) to your site.
  • Copying and modifying one of the out-of-box SharePoint master pages.
  • Creating a completely new custom master page in a publishing site, where the custom master page uses custom styles and is referenced by custom page layouts.

When you upgrade your site collection to SharePoint 2013, these types of customizations will not work as is because the default CSS styles, themes, and master pages have changed. Instead, you must re-create your custom branding by using the new styles, themes, or master pages available in SharePoint 2013, and then apply the newly re-created design to the upgraded site collection.

Changes to the default SharePoint styles, themes, and master pages were necessary to create a faster and more fluid user interface, and to make subsequent upgrades more predictable moving forward.

For this reason, if your site collection contains custom branding, we strongly recommend that, before you upgrade, you first create an evaluation site collection where you can test and re-create your custom branding in a SharePoint 2013 environment. For more information on an evaluation site collection, see Upgrade a site collection.

The following sections list branding issues that may occur when you upgrade to SharePoint Online 2013.

Top of Page Top of Page

Custom CSS

The most common way to apply custom branding to a SharePoint 2010 site is to create a new CSS file that contains styles that override the default SharePoint styles.

However, to make the new UI faster and more fluid, SharePoint 2013 introduces fundamental changes in how CSS is implemented:

  • CSS file sizes are reduced.
  • Nesting of CSS selectors is limited.
  • CSS inheritance is used whenever possible.
  • Classes are defined in only one place.
  • Related classes are grouped in the CSS file.
  • Inline styles and the !mportant declaration are not used because they cannot be overridden.
  • Styles use a consistent structure and naming convention.

In SharePoint 2013, styles use a consistent structure and naming convention.

Naming part ms- <feature>- <name>
Explanation Indicates this is a Microsoft class. The name of the feature that this item is associated with, or “core” if it’s used as part of the core UI. A descriptive name of the item, such as title, link, etc.

Because of these changes in how SharePoint 2013 implements CSS, when you upgrade, custom CSS styles will not be applied to your site. To resolve this, you should first create an evaluation site collection, and then use that site as the environment where you can identify the new SharePoint 2013 styles that you need to override. Create a new CSS file for these styles, and then apply that CSS to your upgraded site.

Top of Page Top of Page

Custom theme

In SharePoint 2010, you can use an Office program such as PowerPoint 2010 to create a THMX file. Then you can upload that theme file into SharePoint 2010 and apply the theme to your site.

In SharePoint 2013, the theming engine has been improved so that theming is faster and more flexible, and so that themes can be more easily upgraded moving forward. The theming model uses comment-style markup in the CSS and then replaces parts of the CSS based on parameters such as fonts and color schemes that end users select. Themes in SharePoint 2013 are defined by XML files:

  • SPColor.xml defines the color palette, in which slots now have semantic names so that it’s more clear what UI elements will be affected when you change a color value. Also, themes now support setting opacity.
  • SPFont.xml defines the font scheme and supports multiple languages, web-safe fonts, and web fonts.

However, there is no support for upgrading a THMX file from SharePoint 2010 to SharePoint 2013. If you applied a custom theme to your SharePoint 2010 site, when you upgrade to SharePoint 2013, the theme files remain in place, but the theme is no longer applied to the site, and the site reverts to the default theme.

To resolve this, you should first create an evaluation site collection, and then re-create the theme by using the new theming features in SharePoint 2013. For more information about the new themes, see the following articles:

 Important    Moving forward, if you want to use custom branding, and if you want that branding to work after future upgrades, we recommend that you use themes to implement your design. Themes will have upgrade support when future updates occur to Office 365.If themes don’t work for your scenario or you require more extensive branding, we recommend using a publishing site with Design Manager. However, understand that if you invest in building custom master pages and page layouts, you may be required to rework or update your design files during and after each upgrade to Office 365.

Top of Page Top of Page

Copy and modify one of the out-of-box master pages

In SharePoint 2010, a common way to make minor customizations to the UI is to copy and modify one of the out-of-the-box master pages. For example, you might modify the master page to remove or hide capabilities from end users.

However, when you upgrade your SharePoint 2010 site to SharePoint 2013, the master page is reset to use the default master page in SharePoint 2013. Therefore, after upgrade, your site will not appear with its custom branding. The custom master page created in SharePoint 2010 still resides in the site, but you should not apply the old master page to the new site because the new site will not render as expected.

To support the new UI in SharePoint 2013, changes have been made to the default master pages. For this reason, you cannot apply a master page created in SharePoint 2010 to a site in SharePoint 2013.

To resolve this, you should first create an evaluation site collection, and then re-create the master page in the SharePoint 2013 site. After you verify that the new master page works as expected, move the master page to the new site collection and apply it to the site. If the sites are publishing sites, you can use Design Manager to export and then import the master page as part of a design package; otherwise, you can move the master page as part of a sandbox solution or by uploading the file to the Master Page gallery.

Top of Page Top of Page

Custom master page in a publishing site

If you want a fully branded site such as a corporate communications intranet site, you use a publishing site with a fully custom master page and custom page layouts that are attached to the custom master page.

However, when you upgrade your SharePoint 2010 site to SharePoint 2013, the master page is reset to use the default master page in SharePoint 2013. Therefore, after upgrade, your site will not appear with its custom branding. The custom master page and page layouts created in SharePoint 2010 still reside in the site, but you should not apply the old master page to the new site because the new site will not render as expected.

To resolve this, you should first create an evaluation site collection that is a publishing site, and then re-create the master page in the SharePoint 2013 site. After you verify that the new master page works as expected, export the master page as part of a design package, import the design package into the new site collection, and then apply the new master page to the site.

Custom content placeholders on a custom master page

 Important    If your custom master page contains a custom content placeholder, and if custom page layouts also contain this custom content placeholder, then an error may prevent the home page of your site from rendering at all after upgrade. Instead, after upgrade, you may see the error message “An unexpected error has occurred.”

To determine if you have this issue, you can create an evaluation site collection that is also a publishing site, and then set the master page to the out-of-the-box SharePoint 2013 master page. If the site still renders, you don’t have this issue. If the site doesn’t render and instead you get an “unexpected error” with a correlation ID, you likely have this issue.

To resolve this issue, do the following:

  1. Create an evaluation site collection that is a publishing site collection.
  2. Create a new SharePoint 2013 master page.
  3. Add the custom content placeholder to the 2013 master page.
  4. Apply the new master page to the site.
  5. Create a page layout that does not contain the custom content placeholder. The page layout will be associated with the new master page that has been applied to the site.
  6. Change all the pages that use the old page layout to use the new page layout. You can do this manually by editing each page individually in the browser and using the option on the Ribbon, or you can do this programmatically by using the client-side object model that also works for Office 365.
  7. Delete the old page layout that contains the custom content placeholder.

We recommend that you do not add custom content placeholders to your custom master page or page layouts.

See also

Plan to upgrade a site collection

Configure site collection version and upgrade settings

Upgrade a site collection

Customized files found during site collection health check

Conflicting content types were found during site collection health check

Parent content types missing during site collection health check

Missing site templates found during site collection health check

Troubleshoot site collection upgrade issues

Top of Page Top of Page

 
 
Applies to:
SharePoint admin center, SharePoint Online Enterprise (E1), SharePoint Online Enterprise (E3 & E4), SharePoint Online Midsized Business, SharePoint Online Small Business, SharePoint Server 2013 Enterprise, SharePoint Server 2013 Standard