Magento 1.x Software Support Notice

For Magento Commerce 1, Magento is providing software support through June 2020. Depending on your Magento Commerce 1 version, software support may include both quality fixes and security patches. Please review our Magento Software Lifecycle Policy to see how your version of Magento Commerce 1 is supported.

For Magento Open Source 1.5 to 1.9, Magento is providing software security patches through June 2020 to ensure those sites remain secure and compliant. Visit our information page for more details about our software maintenance policy and other considerations for your business.

Magento Community Edition (CE) 1.9 and Magento Enterprise Edition (EE) 1.14 Responsive Web Design Developer's Guide

by Erik Hansen

Edit this page on GitHub



Magento Enterprise Edition 1.14 and Magento Community Edition 1.9 come with a new theme named rwd that implements Responsive Web Design (RWD) practices. This guide discusses what you need to know when customizing your own responsive theme.

Magento CE's and EE's responsive theme uses a number of new technologies:

If you're not familiar with Sass or Compass, you should familiarize yourself with them before continuing with this guide.

The new responsive theme code is contained in the following directories (relative to your Magento installation directory):

See one of the following sections for more information:

Intended Audience

This guide assumes that you have a good understanding of Magento frontend development and Responsive Web Design techniques.

Documentation Conventions and Assumptions

This section discusses some basic information that applies to this guide.

Documentation Conventions

This guide uses the names custompackage and customtheme for the design package and theme. When you build your own responsive theme, use a more descriptive name, such as the name of your company.

The variable value [your Magento install dir] refers to the directory in which you installed Magento CE or EE. Typical values follow:

Assumption: How You Customize CSS

You have two choices to write your custom CSS styles:

Exceptions to Responsive Web Design

Responsive design was not implemented for the following:

noteNote: Magento still supports other non-responsive themes as well. You don't need to use this guide to customize those themes. For more information, see the Designer's Guide to Magento.

Supported Devices and Browsers

Magento's responsive theme was developed with full support for the following devices and browsers:

Basic compatibility should be expected on Android 2.3+ (and other mobile devices) and Internet Explorer 8, but full support is not guaranteed.

Understanding the Changes in the Responsive Theme

The new responsive theme in EE 1.14 and CE 1.9 is based on the existing base/default theme. The new responsive theme has about 130 template files that have been modified to better handle the needs of responsive development. Following are some of the changes that have been made in these template files:

Changes to Layout Files

A number of the core layout files (catalog.xml, customer.xml) were slightly modified to account for responsive changes. There are only a few notable changes to the layout files:

Using the New Theme/Layout Structure—Magento EE only

If you've worked with a previous version of Magento EE, you're aware that the enterprise/default theme contains copies of many of the layout and template files from base/default—some with very minor changes. This is not an optimal approach because as it results in duplicated content.

The Magento EE responsive theme's rwd/enterprise directory includes only template and layout files that contain Magento EE-only features.

Instead of copying layout files as the enterprise/default theme does, rwd/enterprise isolates changes in their own layout files in [your Magento install dir]app/design/frontend/rwd/enterprise/layout/enterprise

The rwd/enterprise theme replaces the enterprise/default theme and contains far fewer files than its predecessor (156 compared to 280). This new approach makes it easier for you to see what functionality is unique to Magento EE.

Changes to Magento Theme Fallback

Magento CE 1.9 and EE 1.14 both introduce a theme configuration file named theme.xml. This file allows theme developers to specify a parent theme which results in a more predictable and useful fallback than earlier versions.

For more information, see Alan Storm's Parent/Child Theme article.

Installing Compass and Sass

Sass is a powerful CSS pre-compiler that extends CSS supports variables, mixins, and placeholders. Compass is a library for Sass that adds hundreds of useful mixins and functions to Sass—everything from color blending to sprite generation.

Because the new Magento responsive theme uses the Compass library to compile its Sass files into CSS, you must install Compass in your development environment in any of the following ways:

Disabling the Magento Cache

A good practice during development on Magento is to disable Magento's cache. Although doing this adversely impacts performance, it frees you from having to manually clear the cache when you make changes to files or configuration settings that are being cached.

You should always enable the cache in a production environment.

To disable the cache:

  1. Log in to the Magento Admin Panel as an administrator.
  2. Click System > Configuration > Cache Management.
  3. On the Cache Management page, click Select All.
    Note: The Page Cache option at the bottom of the list is available only in Magento EE.
  4. From the Actions list in the upper right corner of the page, click Disable.
  5. Click Submit.
    The following figure shows an example.
  6. Click Submit.

    The following figures shows all cache types disabled.

Copying Files to Create Your Custom Theme

This section discusses how to start building a custom responsive theme.

See one of the following sections for more information:

Step 1: Creating a Directory Structure for Your Responsive Theme

You'll do your responsive theme development using a copy of the responsive theme provided with Magento CE and EE. This section discusses how to create new top-level directories for your theme and to copy files to those directories.

The rwd/default theme falls back directly to the base/default theme, so themes in the default package will never be included as a part of the fallback chain.

noteNote: Magento EE only. The enterprise/default theme is completely replaced by rwd/enterprise and therefore, enterprise/default is not included as a part of the fallback chain.

The top-level directories you'll need are:

To create those directories and to add your theme configuration:

  1. Using a command shell, log in to your Magento host as a user with privileges to write to the web server docroot. (Typically, this is the web server user.)
  2. Enter the following commands in the order shown:
    cd [your Magento install dir]
    mkdir -p app/design/frontend/custompackage/customtheme
    mkdir -p skin/frontend/custompackage/customtheme
  3. Create another directory for your theme configuration and change to that directory:
    mkdir app/design/frontend/custompackage/customtheme/etc
    cd app/design/frontend/custompackage/customtheme/etc
  4. Use vim or another text editor to create your theme configuration file named theme.xml there:
    vim theme.xml
  5. theme.xml must have different contents for Magento CE or Magento EE:
    • Magento CE:
      <?xml version="1.0"?>
    • Magento EE:
      <?xml version="1.0"?>
    • importantImportant: It's very important you have a theme.xml in the app/design/frontend/custompackage/customtheme/etc directory with exactly the contents shown. Failure to configure theme.xml correctly prevents Magento from loading your theme.

Step 2: Copying Files For Your Theme

Use the following commands to copy files for your custom theme:

cd [your Magento install dir]
cp -R skin/frontend/rwd/default/images skin/frontend/custompackage/customtheme
cp -R skin/frontend/rwd/default/scss skin/frontend/custompackage/customtheme

Copying the images directory is important because the CSS uses relative image paths. To avoid duplicating Sass files, review the information discussed in Sass Fallback Structure.

The following figure shows how your custom theme directory structure looks after copying these files and directories.

Step 3: Configuring a Compass Watcher

You can configure Compass to watch your skin directories for changes to CSS and JavaScript and to compile them when something changes.

You can do this in either of the following ways:

For more information, see Compass Command Line Documentation.

Success Messages

Messages similar to the following display to indicate the command completed successfully:

>>> Change detected at 09:57:12 to: madisonisland-ie8.scss
   create ./../css/madisonisland-ie8.css
   create ./../css/styles.css
   create ./../css/madisonisland.css
   create ./../css/styles-ie8.css
   create ./../css/scaffold-forms.css
>>> Compass is polling for changes. Press Ctrl-C to Stop.

Failure Message

If the following message displays, it likely indicates that config.rb is not in the correct location:

Nothing to compile. If you're trying to start a new project, you have left off the directory argument.

Enter the following commands to verify you have config.rb in the correct location:

cd [your Magento install dir]
ls skin/frontend/custompackage/customtheme/scss

If there is no config.rb in that location, enter the following command:

cp skin/frontend/rwd/default/scss/config.rb skin/frontend/custompackage/customtheme/scss

Compass requires a config.rb file located in the directory from which you run this command. The sample provided with Magento CE and EE follows:

# note: this should never truly be referenced since we are using relative assets
http_path = "/skin/frontend/rwd/default/"
css_dir = "../css"
sass_dir = "../scss"
images_dir = "../images"
javascripts_dir = "../js"
relative_assets = true

output_style = :expanded
environment = :production

After correcting the issue, try the compass watch commands discussed in Step 3: Configuring a Compass Watcher.

Step 4: Configuring Magento to Load Your Theme

This section discusses how to configure Magento to load your new theme.

  1. Log in to the Magento Admin Panel as an administrator.
  2. Click System > Configuration > GENERAL > Design.
  3. In the right pane, click Package to expand it.
  4. In the Current Package Name field, enter custompackage
  5. In the right pane, expand Themes.
  6. In the Default field, enter customtheme
    The following figure shows an example.
  7. In the top right corner of the page, click Save Config.
    If an error displays when you attempt to save the configuration, see Troubleshooting Theme Configuration.
  8. If prompted, flush the cache:
    1. Click System > Configuration > Cache Management.
    2. At the top of the page, click Flush Magento Cache.

Step 5: Verifying Your Custom Theme

To verify that Magento loads your theme:

  1. Navigate to your web store in a web browser.
  2. View the web page source.
  3. If you see a reference to /skin/frontend/custompackage/customtheme/css/styles.css, you are ready to begin building your new theme.
noteNote: If your theme fails to load properly, see the next section.

Troubleshooting Theme Configuration

See one of the following sections for troubleshooting assistance:

General Troubleshooting

The following sections assist you in determining the cause of errors you might experience after setting up your custom theme.

No formatting on the web store

Description: Most likely an issue with theme.xml. You can confirm this by viewing the page source and searching for styles.css. If styles.css is loading from a path similar to the following, theme.xml is most likely not loading.


Solution: Enter the following command:

cat [your Magento install dir]/app/design/frontend/custompackage/customtheme/etc/theme.xml

If the error No such file or directory displays, check your directory paths and create theme.xml as discussed in Step 2: Copying Files For Your Theme.

If you have a theme.xml, check to make sure it's configured exactly as shown here.

Error saving the custom package and theme in the Admin Panel

Symptom: The following error displays:

An error occurred while saving this configuration: package with this name does not exist and cannot be set.

Description: The package and theme names you entered in the Admin Panel must be directories in a specific location on the file system. These directories don't exist. (See the figure in Directory and File Reference.) Check the path and spelling.

Solution: Repeat the tasks discussed in Step 1: Creating a Directory Structure for Your Responsive Theme.

Wrong formatting in the web store

Symptom: Examples:

Description: There is a different theme.xml for CE and EE. You might have used an EE theme.xml with CE or vice versa.

You can verify this using a web browser inspector:

Solution: Review the information discussed in Step 2: Copying Files For Your Theme.

Make sure theme.xml for CE or EE is configured exactly as shown here.

Directory and File Reference

The following figure shows the directory structure in a properly configured system, as well as the location of theme.xml, the custom theme configuration file.

Responsive Theme Reference

This section discusses information you need to customize the responsive theme you started in Copying Files to Create Your Custom Theme.

See one of the following sections for more information:

Basic Recommendations for Development

We recommend you do the following things when you start developing your responsive theme:

Understanding the Sass Structure

In previous versions of Magento, all CSS styles were grouped into a massive styles.css file that was cumbersome and difficult to navigate. The CSS in the responsive theme is organized into individual files referred to as Sass partials.

When Compass compiles the Sass partials, the output is a set of CSS files that are loaded by the browser: styles-ie8.css is for Internet Explorer 8 and earlier, and styles.css is for all other browsers.

Following is the directory structure of the skin/frontend/custompackage/customtheme directory.

noteNote: This structure does not include the sample data assets that you will remove later in this guide.
├── css
│   ├── scaffold-forms.css
│   ├── styles-ie8.css
│   └── styles.css
├── images
│   ├── ajax-loader.gif
│   ├── bg_x.png
│   ├── demo-logo.png
│   ├── demo_logo.png
│   ├── icon_sprite.png
│   ├── [email protected]
│   ├── logo.png
│   ├── logo_small.png
│   ├── opc-ajax-loader.gif
│   ├── social_icons.png
│   └── [email protected]
└── scss
    ├── _core.scss
    ├── _framework.scss
    ├── _var.scss
    ├── config.rb
    ├── content
    │   ├── _category.scss
    │   ├── _home.scss
    ├── core
    │   ├── _common.scss
    │   ├── _form.scss
    │   ├── _reset.scss
    │   └── _table.scss
    ├── function
    │   ├── _black.scss
    │   └── _white.scss
    ├── layout
    │   ├── _footer.scss
    │   ├── _global.scss
    │   ├── _header-account.scss
    │   ├── _header-cart.scss
    │   ├── _header-nav.scss
    │   ├── _header-search.scss
    │   └── _header.scss
    ├── mixin
    │   ├── _breakpoint.scss
    │   ├── _clearfix.scss
    │   ├── _if-resolution.scss
    │   ├── _image-replacement.scss
    │   ├── _loading-overlay.scss
    │   ├── _menu.scss
    │   ├── _not-selectable.scss
    │   ├── _toggle-content.scss
    │   ├── _triangle.scss
    │   └── _typography.scss
    ├── module
    │   ├── _account-reviews.scss
    │   ├── _catalog-compare.scss
    │   ├── _catalog-msrp.scss
    │   ├── _catalog-product.scss
    │   ├── _checkout-cart-minicart.scss
    │   ├── _checkout-cart.scss
    │   ├── _checkout-onepage.scss
    │   ├── _checkout-success.scss
    │   ├── _cms.scss
    │   ├── _configurableswatches.scss
    │   ├── _contacts.scss
    │   ├── _cookies.scss
    │   ├── _customer.scss
    │   ├── _paypal.scss
    │   ├── _pricing_conditions.scss
    │   ├── _product-list.scss
    │   ├── _review.scss
    │   ├── _search.scss
    │   ├── _slideshow.scss
    │   └── _wishlist.scss
    ├── override
    │   └── _plugin.scss
    ├── scaffold-forms.scss
    ├── styles-ie8.scss
    ├── styles.scss
    └── vendor
        └── _normalize.scss

This is an explanation of the files in the preceding list:

Adding Your Own Sass Partials

To customize styles for an existing Magento theme, you should edit existing Sass partials. However, if you are building a highly custom theme, you will likely want to create new partial files to contain styles for new functionality that you are introducing. Here is how to do that:

  1. Add your partials to a new file named skin/frontend/custompackage/customtheme/scss/module/_new-module.scss.
  2. Create a new skin/frontend/custompackage/customtheme/scss/_custom_core.scss file with the following line to import your new partial:
    @import "module/new-module";
    Note: Although you could edit core.scss to import your new partials, you should create _custom_core.scss to clearly distinguish which partial files are custom versus native.
  3. Add this line to the bottom of styles.scss and styles-ie8.scss files:
    @import "custom_core";

The contents of your new Sass partial will now be included in the output CSS files.

Using Media Query Breakpoints

The responsive theme has a set of breakpoints it uses consistently (except for a few one-off breakpoints). These breakpoints are defined in both _var.scss and app.js so the CSS and JavaScript functionality stay in sync:

$bp-xsmall: 479px;
$bp-small: 599px;
$bp-medium: 770px;
$bp-large: 979px;
$bp-xlarge: 1199px;

A custom bp() mixin includes media query breakpoints.

For example, this Sass:

@include bp(max-width, $bp-medium) {
    /* These styles will only display on viewports smaller than or equal to 770px */
@include bp(min-width, $bp-medium+1) {
    /* These styles will only display on viewports larger than or equal to 771px (770px + 1px) */

generates this CSS:

@media only screen and (max-width: 770px) {
    /* These styles will only display on viewports smaller than or equal to 770px */
@media only screen and (min-width: 771px) {
    /* These styles will only display on viewports larger than or equal to 771px (770px + 1px) */

The breakpoint variables are intended to be used with max-width by default. When you use the breakpoint with min-width, you should add a pixel ($bp-medium+1) so the min-width and max-width styles don't both get applied to the same viewport size.

Using the bp() mixin for older Internet Explorer Browser Versions

It is important to use the bp() mixin for your media query breakpoints because Internet Explorer 8 and earlier do not support media queries. While you can use a polyfill like respond.js to add media query support to IE versions 6–8, doing so will impact performance. Additionally, using a polyfill doesn't add much value because nearly all IE 6–8 users view web pages on a large screen device (1024px or larger), so those users won't benefit from media queries anyway.

To address the fact that IE 6–8 doesn't support media queries, the styles-ie8.scss stylesheet defines a couple of variables:

$mq-support: false;
$mq-fixed-value: 1024px;

With those variables defined, the bp() mixin outputs only the styles that would be visible on a 1024px+ viewport and it does not wrap those styles in a media query so that the IE browsers always render those styles. Refer to _breakpoint.scss to see exactly how this is done.

While it is acceptable to use the breakpoint variables defined by the responsive theme, when building your own responsive theme, your breakpoints should be specifically tailored to the content of your site. For example, let's say your main navigation only has four links and it fits nicely in a horizontal layout on viewports larger than 400px.

The responsive theme changes the horizontal layout to a collapsed drop-down on viewports smaller than 771px. Rather than defaulting to how the theme collapses the navigation, you should change the navigation to break at about 400px so users on screens between 400px and 771px get to experience the benefit of viewing the horizontal navigation.

Working With Images

There are very few images in the responsive theme compared to the other Magento themes because CSS3 is used whenever possible to accomplish a visual effect.

The responsive theme enables you to specify two different logos: one optimized for small screens (narrower than 770px) and the other for large screens. Place your two logo files in skin/frontend/custompackage/customtheme/images and specify the path to both logos in the Magento Admin Panel:

  1. Log in to the Magento Admin Panel as an administrator.
  2. Click System > Configuration > GENERAL > Design.
  3. In the right pane, click Header to expand it.
  4. In the Logo Image Src field, enter the path of your primary logo. For example: images/logo.png.
  5. In the Small Logo Image Src field, enter the path of your logo for small viewports. For example: images/logo_small.png.
  6. In the top right corner of the page, click Save Config.
  7. If prompted, flush the cache:
    1. Click System > Configuration > Cache Management.
    2. At the top of the page, click Flush Magento Cache.

Working With Sprites

The responsive theme uses two sprites: one for general icons and the other for social icons.

Both sprite images output at 1x and 2x resolutions (for high-resolution screens). Because sprite files are very difficult to edit without the source files, you should use these Photoshop files to change these sprites: RWD_icon_sprite.psd and RWD_social_icons.psd

Compass provides support for generating sprites from individual image files, but it was not used to generate sprites for the responsive theme. However, you might want to take advantage of that feature for your custom theme. Using this method requires knowledge of Compass.

Working With JavaScript

All of the custom JavaScript in the responsive theme is contained in skin/frontend/rwd/default/js/app.js. To customize the responsive theme's JavaScript, copy app.js to skin/frontend/custompackage/customtheme/js and edit it there.

All custom JavaScript is based on jQuery (v1.10.2). In addition to jQuery, the following JavaScript libraries are included in the responsive theme:

Removing Sample Data Assets

The responsive theme includes several assets that are intended to power Magento's sample data. We recommend you remove them before you build your custom theme.

  1. Remove the following files and directories:
  2. In your custom layout file (for example, app/design/frontend/custompackage/customtheme/layout/local.xml), add this XML:
    <layout version="0.1.0">
            <reference name="head">
                <action method="removeItem"><type>skin_js</type><name>js/slideshow.js</name></action>
                <action method="removeItem"><type>skin_js</type><name>js/lib/jquery.cycle2.min.js</name></action>
                <action method="removeItem"><type>skin_js</type><name>js/lib/jquery.cycle2.swipe.min.js</name></action>
                <action method="removeItem"><type>skin_css</type><name>css/madisonisland.css</name></action>
                <action method="removeItem"><type>skin_css</type><name>css/madisonisland-ie8.css</name></action>
                <action method="removeItem"><type>link_rel</type><name>//fonts.googleapis.com/css?family=Raleway:300,400,500,700,600</name></action>
    The preceding XML:
    • Removes the Madison Island CSS files
    • Removes the Raleway font that is used as a part of the default theme
    • Removes the jQuery Cycle plugin and the slideshow.js file that activates Cycle.
  3. Update this line in skin/frontend/custompackage/customtheme/scss/_var.scss to reference whatever font you want to use for your custom site font:
    $f-stack-special: 'Raleway', 'Helvetica Neue', Verdana, Arial, sans-serif;

    If you want to use a custom web font for your theme (such as a Google Font, add XML like this to the <reference name="head"> section of layout.xml (see step 3). Customize the <href> value to the value that your custom web font provider gives you. It is recommended to include the same font weights that are referenced below (300,400,500,700,600) because the responsive theme uses each of those font weights.

    <action method="addLinkRel"><rel>stylesheet</rel><href>//fonts.googleapis.com/css?family=Raleway:300,400,500,700,600</href></action>

Advanced Topics

After you get familiar with the new structure, we encourage you to read these topics to fully take advantage of responsive web design.

Getting Your Theme Ready for Production

To prepare your responsive theme for production, you should update config.rb in your theme directory to use these values:

output_style = :compressed
environment = :production

After you do this, you should recompile all of your Sass files—you can do this on the command line by running these commands inside your theme directory: compass clean and then compass compile. Finally, deploy the compiled CSS to your production system.

Sass Fallback Structure

We recommend copying all of the Sass files from skin/frontend/rwd/default/scss to skin/frontend/custompackage/customtheme/scss to make it easy to get started with custom theme development. The downside of this approach is that it results in duplicating many files that you never edit directly.

In the end, your custom theme must include all Sass partials you want to override. There are at least two ways to do this:

Now you can set up a fallback structure:

  1. Add the following line to skin/frontend/rwd/default/config.rb (omit the first line if you're using CE):
    add_import_path "../../../rwd/enterprise/scss"
    add_import_path "../../../rwd/default/scss"
    The preceding causes Compass to look for Sass files in skin/frontend/rwd/enterprise/scss first and then in skin/frontend/rwd/default/scss if they can't be found in skin/frontend/custompackage/customtheme/scss.
  2. Following is what to do with copies of Sass files from rwd/default:
    • styles.scss, styles-ie8.scss: You must copy these files into your custom theme so that Compass knows which files to compile into CSS files.
    • _core.scss, framework.scss: You must copy these files into your custom theme so Compass looks in the custompackage/customtheme directory for any of the files imported by these two files.
    • _var.scss: You'll typically edit the values in this file for your custom theme.
      If you don't like the idea of editing this file and want to override its values with a _var_custom.scss file, make sure it gets imported immediately after _var.scss.
  3. As a reminder, to override Sass partials in rwd/default, you must copy them into your custom theme so they'll get included by Compass.
    Note: If you're using compass watch to recompile your Sass, you must stop and restart Compass any time you copy a new Sass file into your custom theme. Otherwise, the Compass compiler won't know about the existence of the new file.
    To avoid having to stop and restart compass watch, start your project by copying all Sass files from rwd/default into your custom theme, and then delete all unchanged Sass files at the end of your project.

Scaffold Forms

The Magento responsive theme ships with skin/frontend/rwd/default/scss/scaffold-forms.scss that has styles that cause the labels of long forms (for example, the Billing Information step of checkout) to display to the left of their associated input on larger viewports (as opposed to on top). This layout is intended to make long forms seem less intimidating to users.

However, these styles are not currently implemented because the Magento responsive theme must work well with internationalization (where the length of labels can vary greatly, thereby impacting the scaffold form layout).

It's up to you whether or not to use these styles. To do so, move skin/frontend/rwd/default/scss/scaffold-forms.scss to core/_scaffold-forms.scss and edit scss/_core.scss to include it.

High-Definition Images

The responsive theme has no high-resolution image solution for product listing pages. Refer to slides starting at 114 of Brendan Falkowski's Imagine 2013 talk for implementation suggestions. For a 2x solution, PictureFill (or similar polyfill) could be used, although it would need to be integrated with ElevateZoom.

noteNote: Category banners and product detail pages use a 1.5x image solution.

Magento does not resize the main product photo on product detail pages, so you must implement high-resolution support in your responsive theme. You must be careful with this if you have very large product photos because it could drastically impact performance.

To constrain the size of your main product photo, open app/design/frontend/rwd/default/template/catalog/product/view/media.phtml and modify this line:

<?php echo $this->helper('catalog/image')->init($_product, 'image') ?>
to something like:
src="<?php echo $this->helper('catalog/image')->init($_product, 'image')->constrainOnly(true)->resize(1800); ?>"

Getting Help With Your Theme

If you encounter issues building a custom responsive theme, you can post your question on the community magento.stackexchange.com site and tag it with rwd-theme.

To browse the list of questions, see http://magento.stackexchange.com/questions/tagged/rwd-theme.