Creating a new theme for Plone: a real-world example (Plone 2.1, 2.5)

« Return to page index

In this tutorial, Alexander Limi will show you how to take a default Plone site and put a totally different look on it. (Not updated for Plone 3.0)

Introduction

Introduction to the tutorial, and the new theme approach made possible using Plone 2.1 and later versions.

[DEPRECATION WARNING: As of 3.0, this approach is no longer recommended. In Plone 3.0, we no longer use DIY Plone Style for creating themes. Instead, we use buildout for setting up a development environment, and paster and ZopeSkel for creating a theme product. Search for these items as well as for documentation on managing viewlets and managing portlets in 3.0 (found in the Visual Theming area of plone.org/documentation). More documentation on theming for 3.0 is coming soon.]

With Plone 2.1 and up, we have a new method of skinning Plone that makes it a lot easier than the approach used in earlier versions of Plone.

I won't dwell too much on how it was done earlier apart from saying that it was based on taking the existing Plone CSS, overriding the existing CSS rules and creating a new skin based on this. This approach had numerous problems:

- It was very complex if you didn't know much about CSS

- It was prone to breakage when upgrading to new versions of the Plone CSS (even minor changes would make your theme change

- It caused the CSS output files of Plone to be very large

The new approach

With Plone 2.1 and up, we have a new infrastructure component called ResourceRegistries. This component allows us to split up CSS and Javascript on the server side, so it can be managed in a sane way. We can attach conditional checks on parts of the CSS/JS, and merge it all to a single CSS/JS file on the way out, so that the browser only sees one CSS file to reduce the amount of file requests needed. In later versions, RR also added CSS and JS compression to keep file sizes down.

What this means for us when we want to create a Plone Theme, is that we can *selectively disable* parts of the Plone user interface CSS. A very common approach is to keep the CSS for authoring (the green border, the forms CSS), and customize only what people see when they are not logged in. This has several advantages:

- We can start with a blank slate, and apply our CSS without interference from Plone

- We can reduce the download size of the CSS to only what we need

- The theme becomes much more resilient to changes in Plone itself

The reason this approach is more robust when it comes to keeping compatibility with future Plone versions, is that it is only relying on HTML IDs and classes, which should rarely change. (Realistically, there are some changes now and then to the classes and IDs too - but these are much less frequent than other changes, and the Plone Team tries to leave them intact if possible)

There are three ways of changing Plone's appearance:

Simple changes --
Replacing the logo and adjusting the colors. I won't cover this here, but it's covered in most of the books and in a couple of how-tos.

Comprehensive --
Replacing all the styles that are visible to the public, but keeping the basic widget styles. May involve simple changes to main_template, but nothing radical.

Full --
Starting from scratch and replacing all the CSS and rewriting templates (not recommended, will be a maintenance nightmare)

I will cover the Comprehensive use case.

Why keep the Plone structure?

Accessibility -- Plone has been engineered to be friendly for users with motor or vision disabilities. This takes a lot of effort and testing — with Plone, you get it for free.

Search engine visibility -- Out-of-the-box, a blank Plone site has the potential for a very high Google Rank. For plone.org itself, we have a Google Rank of 9/10, the same as Microsoft, IBM and similar massive entities on the web. We have spent a lot of time optimizing Plone for search engines. Google loves Plone. Plone loves Google. (Trivia: the only site I have found out there with a 10/10 Page Rank is the W3C page — anybody know of others? :-)

A note about terminology

Throughout this tutorial, I use the word "theme" to describe the collection of visual modifications done. In other parts of the Plone literature, this is described as "skinning" and the end result a "skin". The reasons we're trying to move away from this terminology are several:

1. In Plone terminology, a "skin" can be both template, CSS and code modifications. We try to keep the visual themes separate from the code and template customization as far as possible, and use the word "theme" to convey that it is **only** about visual changes.

2. We encourage you to keep your other Plone modifications in a separate file system product, this makes the visual modifications / theme part of the equation much more reusable and simple.

For example, in our company we usually stick to the following product naming convention, with "Site" being the customer or project name:

SiteTheme -- Holds the visual theme, and the other visual elements that are general (logos, background images, etc).

SiteTweaks -- Holds small modifications to the templates, behavioral changes to the templates and Python scripts.

SiteSetup -- Using the GenericSetup infrastructure in Plone 2.5 or up (or CustomizationPolicies in Plone 2.1 and older), this product holds the stuff that needs to be set up when you instantiate a site — configuration changes, SQL connections, etc.

As for infrastructural components, we never name these after the customer/project, but try to come up with generic names (as we often end up open sourcing these solutions and want neutral names for these).

Toolchain

Quick walk-through of the different tools we have at our disposal to create and inspect CSS-based designs.

Preparing Zope & Plone

If you are creating the skin on the file system (recommended) rather than through the ZMI there are several methods you can use to make debugging simpler.

Zope Debug Mode

Running Zope in debug mode enables skin changes to be reflected on the site instantly. There are several ways to enable this:

in etc/zope.conf set:
```
 debug-mode on
```
then restart zope using the following (in order to display error log to your console)
```
zope_instance/bin/runzope
```
OR start zope using :
```
zopectl fg
```
If you installed using the Windows installer version of Plone there is an option to run in Debug mode in the Plone Program menu.

Reloading Products

If you are not using debug mode there is still a way to update changes to a skin product using the reload option. To enable this option you need to have a refresh.txt file inside your product folder (DIYPloneStyle's generator creates this by default).

In the ZMI, go to Control Panel -> Product Management -> Name of your skin product
load the Refresh tab and click the 'Refresh this Product button' to reload the product.

CSS Resource Registry

To help the performance of a Plone site, portal_css merges all the stylesheets for a page into just one CSS file. To make debugging you custom css simpler you can use its debug mode which prevents this merge:

In the ZMI go to Plone Site -> portal_css
Tick the Debug mode box and press the save button.

DOM Inspectors

Document Object Model or DOM for short, is a term used to describe how a html page (or xml document) is structured and provides an API to access. The browsers convert the raw text from the html/xml file into a DOM and then use it to apply CSS and other transformations.

So why is this useful for us? Well the HTML and CSS in Plone's default skin does a lot of things well – the downside of all this power is that its complicated. So sometimes you want to change just a simple element but you don't know how to get a handle on that item to write the relevant css.

This is where the DOM Inspectors come in...... You can see the structure of the page in a tree and receive visual feedback as you traverse all the elements. Once you've found it you can easily find out all the attributes such as class, id, and parent elements.

Firefox DOM Inspector

When you install firefox, make sure you enable the Web Developer tools option from the Custom installation menu.

Firefox comes with a very useful DOM inspector tool. To open it go to the Tools menu and look for it near the bottom. Alternatively in Windows Firefox press Ctrl + Shift I , or in Mac Firefox Apple key + Shift + I.

Firefox DOM Inspector

First thing you'll probably have to do is maximise the DOM Inspector – it works much better with a large screen.

Then go to the File menu and select Inspect a URL. Enter the address for the site you want to inspect and the page will load up in the bottom pane of the DOM Inspector.

There are two basic ways of using the Inspector :

Traversing the tree

In the tree pane in the top left, use the + icons to expand each node. Starting with #document, then HTML and BODY as you expand you reveal more and more of the elements; Notice that there are columns for id and class to help you find where you are.

As you click on each element you will see the the relevant visual element flashing below in the browser pane.

Now, Lets find the navigation tree elements:

Expand the DIV with id visual-portal-wrapper (the Plone specific container for all the page)

Locate and Expand TABLE with id portal-columns (this contains the central part of the page)
Expand TBODY, TR and then TD with the id portal-column-one (left column)
Finally expand the DIV with the class visualPadding to reveal the portlet items including the portlet-navigation-tree

Firefox DOM Inspector Tree

Select Element by Clicking

Go to the search menu and choose the last option 'Select Element by Click'

Now go to the browser pane and click on the element you want to highlight in the tree.

To find another element you need to repeat the first step again.

Firefox DOM Inspector Selected Element

Web Developer Extension for Firefox

The Web Developer Extension adds a very powerful & useful toolbar to your firefox browser which really helps while developing Plone Skins.

Here are some of the many features it offers:

Edit CSS instantly - no need to make changes in the ZMI or FileSystem and refresh.
View Style information - click on elements of the page to bring up the relevant CSS declarations.
Disable all/specific stylesheets
Apply new stylesheets
Display outlines of all/specific elements on the page (e.g all <div>, or <ul>)
Generate a list of all images on the page.
Resize the browser window to common or custom sizes e.g. 1024 x 768, 800 x 600 etc.
Display detailed information about Forms, Links, Meta Tags, HTTP Headers, Document Size and more.
Validation: for HTML / CSS / RSS / Accessibility / Links
Ruler - Measure how tall/wide parts of the page are. No need to guess how many pixels your CSS is out any more!

Firefox Web Developer Toolbar

FireBug extension for Firefox

FireBug is the DOM inspector on steroids, and is insanely useful for inspection of HTML, CSS and Javascript.

Once installed it sits quietly in Firefox's status bar (below the browser window). Everytime a page loads it checks for and logs any errors it finds into its console. If the page has no errors on it displays a green tick icon otherwise it displays a red cross with and lists the number of errors found.

To use all the cool features simply click on either of these icons to display the FireBug pane:

FireBug Screenshot

Legend

FireBug Icon (green tick)
Inspector tab - use to switch from console mode (list of errors and alerts) to inspection mode.
Inspect button - use this to enable/disable element selection using the mouse. When enabled you can hover over elements in the browser pane and select the elements you want to inspect.
Source & Style tabs - switch between these to view the HTML or the selected element's CSS attributes.

From here you can view errors in the Console or switch to the Inspector tab to display the pages HTML interactively. Click on the arrow icons to expand/collapse each tag and traverse to your required element. Alternatively use the inpector button to choose the element from the website itself.

View Source Chart Extension for Firefox

The View Source Chart Extension makes understanding the structure of an HTML document so much easier.

Once installed simply right click anywhere on the page you want to view and look for "View Source Chart". This will load the chart up in a new window:

View Source Chart Extension

You will notice that different elements have different colors for easy readability, and each container is collapsible by clicking on it which can really help you isolate the items you are interested in.

Now that you have the basic tools for looking up classes and IDs on the element you want to change, we can continue with putting a new look on Plone.

Real-world use case

For our purposes, we will show how to build a theme from a Photoshop mock-up.

"Plone.NET":http://plone.net is the network of professional Plone companies. It needed a different visual look than out-of-the-box Plone, something that looked a bit more corporate. Abstract Edge (a design agency with close ties to the Plone community) provided us with a Photoshop mock-up, and we converted it into a Plone skin. This is a very common process, and normally it works best this way — visual designers at design agencies very rarely know enough about the web to implement the design in HTML that Does Not Suck™ — so that part of the job is left to us. The design we are going to implement is shown below (click for full-screen view):

The starting point for our work is the excellent "DIYPloneStyle":/products/diyplonestyle product, which makes it easy to create a skeleton for your theme product. Big kudos to "David Convent":/author/davconvent for providing this handy piece of software that makes our job so much easier.

A proper foundation

Before we start adding our CSS styles, we need to create the basic foundation for our theme. This is essentially a blank skeleton product that we can put our images and CSS inside.

Creating a clean slate using DIYPloneStyle To get a clean product we can base our product on, we do the following: 1. "Download DIYPloneStyle":/products/diyplonestyle if you don't have it already. (Get the version that corresponds to your Plone version, this will be evident from the version numbering. If you have Plone 2.1.x, you're looking for the latest release in the DIYPloneStyle 2.1.y series, if you're on Plone 2.5, you want version 2.5.y etc.) 2. Unpack the file using tar or WinRAR or an equivalent tool (WinZip is not recommended, it has several bugs wrt. handling paths and empty files). 3. Place the product in your products directory. If you're not sure where your products directory is, it is listed in the same location as you install your Plone products when Plone is running. If you want to see what we will end up with, you can restart the Plone server process, go to Add/Remove Products and install DIYPloneStyle. This is approximately how it will look when we're done with this tutorial. That's cheating, though. ;) Make sure you uninstall it again if you did this, and then we create the empty skin product. From the terminal or command line, do the following (adjust for the platform you are on; Windows uses \ instead of /, and the Python binary might need to be explicitly called, for example 'C:\Program Files\Plone\Python\bin\python.exe') :: cd Products/DIYPloneStyle python bin/generator.py --productname MyTheme This will generate an empty skeleton product called 'MyTheme' where all our files can be placed in our Products directory. The directory structure (excluding some of the less relevant files, directories in bold) looks like this: - config.py (your theme configuration) - **Extensions** (the files needed to install the product in Plone) - Install.py (the install file) - utils.py (utility methods used when installing/removing) - refresh.txt (makes it possible to use the Refresh tab in ZMI when adding new files instead of restarting) - **skins** (directory where the skin layers are) - **mytheme_styles** (where you put your templates and CSS) - base.css.dtml (an empty css file that overrides its Plone equivalent) - base_properties.props (basic color properties; not used in this tutorial, but handy if you just want to do simple color changes) - generated.css.dtml (an empty css file that overrides its Plone equivalent) - mytheme.css.dtml (our CSS file) - portlets.css.dtml (an empty css file that overrides its Plone equivalent) - public.css.dtml (an empty css file that overrides its Plone equivalent) - **tests** (unit tests for your product) - version.txt (the version indicator that shows up in Plone) If you restart your Plone server process and go to the Add/Remove Products section, you will see MyTheme listed as an installable product. Install the product, and notice how you now have a mostly unstyled Plone when you view the front page: A Plone without any styles applied (click for full screen view)

This provides an excellent starting point for our theme.

Scaffolding

Before we can start writing CSS, we are going to do some structural changes and export the graphical elements.

Identify elements The first question you should ask yourself when looking at the original design is: What elements map to which Plone structures? In our case, most of the elements can stay in place, but the bar with the personalized actions and the logo should be moved. The row of global sections/tabs is also redundant. It's OK to touch main_template! In Plone, 'main_template' is the mother of all templates, the one that keeps all the structure in one place. It looks like a very complex template when you open it up ("what is all this 'metal:' stuff?"), but the secret is to scroll down to the first body tag (somewhere around line 40 in my version), and read it from there. It will then have lots of statements looking like this ::

The quicksearch box, normally placed at the top right

Skipping the details (but please learn ZPT if you are going to work with Plone on a more than casual level, "a tutorial on ZPT can be found here":/documentation/tutorial/zpt), this instruction essentially tells Plone to go get the file 'global_searchbox' and pull out the macro 'quick_search' from it, and apply it to the page. You can move these elements wherever you want on the page as long as you keep their contents/attributes intact. Most books recommend that you don't touch main_template for maintenance reasons. It's generally good advice, apart from that fact that you really can't realistically do cross-browser positioning that will match any design your client might give you, so I'll go on the record right here and say it: **My name is Alexander Limi, and I customize the main_template in my themes.** There, not so intimidating anymore, is it? ;-) The important point **if** you customize main_template to re-order elements is to be careful when you upgrade. The release notes in every Plone release **will** state whether changes were made to main_template, but you should always use a diff program (FileMerge for Mac, WinMerge for Windows) to see what changed between the original main_templates in two different versions of Plone, and re-apply these changes to your version of main_template when you upgrade. In our case, we are going to: - Remove the global nav bar (we have the navigation tree, no need to have duplicate navigation structures) - Move logo to top (there are ways to do this without re-ordering main_template, but this is so much easier) This is done by putting using the 'tal:replace' instruction around the content, and replacing it with the special instruction 'nothing', example :: Tutorial: Removing the global nav

The global sections tabs. (Welcome, News etc)

The way to get your own 'main_template' is to copy the one that exists in your 'CMFPlone/skins/plone_templates' directory to the template directory in the theme product you generated with DIYPloneStyle. Extract base colors that are going to be used The next step is to pull out the color values from the mock-up. These could be used for base_properties, but I'm not going to make use of that in this particular tutorial — it makes sense if you want some of the Plone default CSS remaining, though. Here are the color values we need for our theme :: border: #c9c4c0 navigation elements: #d3cebc red highlight color: #ec001a link color: #463229 text color: #7e7c7c Which style sheets are disabled? In our example (and by default in DIYPloneStyle), we have disabled the public-facing style sheets, which is what makes Plone look like Plone. The following style sheets are disabled: - base.css (basic tag styling - p, a etc) - public.css (all the "fluff", what the public site looks like) - portlets.css (contains portlet markup, the boxes in your Plone site) - generated.css (creates content type icons — I usually turn on generated.css for logged in users only — look in member.css for an example condition) Sometimes, I prefer keeping base.css and override the few things that are not the way we want them (like headlines), and adjust fonts etc in base_properties - but in our example we'll start from zero. This also makes it more future-proof. Export graphical elements Next up, you should export the graphical elements needed from the mock-up. If you have a Photoshop mock-up, make use of the layers functionality, and extract any backgrounds, logos and other graphics. Save these to the 'mytheme_images' directory. Now, let's get to the fun part: Adding the CSS and making Plone look like our mock-up.

Adding CSS styles

Finally, it's time to apply our CSS styles. Each step is illustrated by an image showing the progression of the theme.

Unmodified Plone design We start with the unmodified Plone theme for illustration purposes. Too many themes look like a horrible butchering of this, which is part of the reason why I wrote this tutorial. No more bright green variants of the default Plone theme, please! Have mercy! ;)

Unmodified theme After creating our MyTheme in the previous steps of the tutorial and installing it, we have the following:

Not too pretty, but that's what we're about to change. The thing that you should notice here is that it is using the standard Plone style for the View/Edit tabs, which we wanted to keep for this design.

Header styles

First up, the site header.

The first thing we'll do is to add in the header image. If we had kept the basic Plone stylesheets (base.css, plublic.css, …), we could have saved the header image as 'logo.jpg' in the 'mytheme_images' directory. It would have showd up automatically. In that case, if you wanted to name it differently, you should have edited 'base_properties.props' to reflect the change. In this tutorial, the header image is inserted in the layout by customizing the global_logo template and saving the header image itself as 'header.jpg'. In order to have the same effect than in the example, copy the file 'global_logo.pt' from 'DIYPloneStyle/skins/diystyle_example_templates/' to the 'mytheme_templates' directory. Also copy the file 'header.jpg' from 'DIYPloneStyle/skins/diystyle_example_images/' to the 'mytheme_images' directory.

Still doesn't look like much, but we have the logo in place, at least.

Basic styles

Adding the basic body styles.

It's time to break out your CSS chops! Open the 'mytheme.css.dtml' file and add the following :: /* The basics */ body { font: 69% Verdana, sans-serif; background-color: White; color: #7e7c7c; margin: 0; padding: 0; } Which gives us the following:

One step at a time, getting there eventually. :)

Background image styles

Adding a background image and locking the width of the design.

Next up, we'll add a background image to the site, as well as locking the width to 840 pixels. Add the following to your CSS and refresh: :: /* The background + logo styles */ body { background: url(bg_light.gif); width: 840px; margin: auto; } #visual-portal-wrapper { margin: 20px; background-color: white; padding: 0 20px 20px 20px; } #portal-logo { display: block; margin-bottom: 2em; } One of the things worth paying attention to here is the 'margin: auto' part. This is the way you generally center things in CSS, and a lot of people don't know that — they expect there to be a 'float: center' or something similar. Now you know how to do it, and if you refresh, your site will look like this:

Amazing what adding a simple background does to the design, isn't it? Onwards!

Headline and paragraph styles

Adding styles for headlines and paragraphs.

We have to get some more of the basics in there — the headlines and paragraphs should be styled to match the mock-up, and some browsers need image border removal. Add the following to your CSS: :: /* Headlines & other basics */ h1 { font-weight: normal; border-left: 4px solid #ec001a; padding: 0 5px; } p { padding-left: 9px; line-height: 1.5em; } a { color: #463229; } p a:link { color: #463229; text-decoration: none; border-bottom: 1px solid #463229; } img { border: none; } input { border: 1px solid #463229; } The main thing worth paying attention to here is that we style the 'a:link' element instead of just plain 'a'. This is to make sure that HTML anchors (they also use the a tag) don't get link styling — they are the receiving end of a link, not a link themselves. Save, reload your page, and you should see the following:

List styles

Making the lists be displayed inline and without bullets.

Now, there are a lot of bulleted (unordered) lists in the design that are used for structural (aka. semantic) purposes, and that shouldn't really look like that — but have all elements on the same line. CSS to the rescue: :: /* Site actions / search / personal bar */ #portal-siteactions { list-style-image: none; list-style-type: none; float: right; } #portal-siteactions li { display: inline; border-left: 1px solid #463229; padding-left: 0.5em; } #portal-siteactions li a { text-decoration: none; } #portal-searchbox { float: right; clear: right; } #portal-personaltools { float: right; margin: 0.5em 0; padding: 0; } #portal-personaltools li { display: inline; list-style: none; list-style-image: none; } #portal-personaltools li a { text-decoration: none; margin-right: 1em; } .documentActions { float: right; margin: 0.4em 0 0 0.5em; padding: 0; } .documentActions li { display: inline; list-style: none; list-style-image: none; } .documentActions { display: none; } Note that while this is quite a mouthful, it's essentially just setting the same properties on all the different structures - causing them to be rendered 'inline' instead of under each other, and removing the bullets in front. (This may already be fixed for you in Plone 2.5 and up, as part of the 'invisibles.css' file) Reload, and you have:

Wow, that really cleaned up things, didn't it?

Portlet and navigation styles

Adding proper styles to the portlets and the navigation tree in particular.

One of the hardest things to get right is always the navigation. It is an inherently complex structure, especially since you might want different stylings on the different levels — for example different colors on the second-level navigation and third-level navigation. Luckily, Plone gives you a lot of CSS classes to latch on to, and my best advice when creating your own schemes is to use the DOM Inspector religiously to find which classes to manipulate. We chose to go for a simpler style for demonstration purposes. First, some basic portlet/breadcrumb styling — add the following to your CSS: :: /* Navigation */ #portal-breadcrumbs { margin: 1em 1em 1em 19em; } #portal-breadcrumbs { display: none; } .portlet dt { background-color: #d3cebc; margin-bottom: 0.5em; display: block; padding: 0.2em 0.5em; } .portlet dd { margin-left: 0; } .portlet a { text-decoration: none; } .portletItem { padding: 0.5em; } .portletFooter { border-bottom: 1px dashed #c9c4c0; padding: 0.5em; text-align: right; } .portletItemDetails { text-align: right; display: block; color: black; } Then we add the navigation-specific elements: :: .portletNavigationTree { padding-left: 0; } #portlet-navigation-tree .portletHeader { display: none; } .portletNavigationTree a { background-color: #d3cebc; margin-bottom: 0.5em; display: block; padding: 0.2em 0.5em; } .navTreeItem { display: inline; list-style: none; list-style-image: none; } .navTreeItem a, .navTreeItem a:visited { text-decoration: none; color: #463229; } .portletNavigationTree a:hover, .navTreeCurrentItem { color: #d3cebc !important; background-color: #463229 !important; } Whew, this looks a bit complex if you haven't seen CSS before, but if you add the rules one at a time, you can see the progression, and what each rules does. If you reload, you should now have the following:

Wow, now we're talking. It's starting to look like the proper design now, just needs some tightening of the margins and positioning.

Re-positioning the navigation

Removing redundant margins on the portlets and navigation tree.

One of the most common problems people encounter when they skin Plone is the mysterious margin/padding around the portlets. It is caused by the infamous 'visualPadding' element, and is easy to get rid of when you know how — but almost impossible to track down, even with the DOM Inspector. It's one of the elements that cause most trouble for people, and ~~hopefully we'll remove it in Plone 2.5~~ was moved to 'public.css' in Plone 2.1.3, so should not be a problem if you're using that version or a later one. Add the following to your CSS file to reduce the padding to zero (we want some padding on the right, though): :: /* The mythical, infamous visualPadding */ #portal-column-one .visualPadding { padding: 0 1em 0 0; } And while we're here, let's pull up the navigation a little bit, since it's too far down on the page right now: :: #portlet-navigation-tree { position: relative; top: -6.4em; } There — reload, and you should have:

Almost there! Can you see what's missing? That's right, the footer.

Footer styles

Final element, styling the footer.

The footer doesn't really do any magic, so without further ado: :: /* Footer */ #portal-footer { border-top: 1px dashed #c9c4c0; } #portal-footer a, #portal-footer a:visited { text-decoration: none; } #portal-colophon { display: none; } We hide the colophon, which is the place that has all the validation links etc. There we go, and we have the final design — reload and see the finished design:

Now, that wasn't too bad, was it? Of course, if you haven't ever done CSS, this is probably a bit overwhelming, but fortunately there are lots of good CSS resources on the web. Go forth and create — or port existing — beautiful themes for Plone and upload them in the "products area":/products!

Tips for creating your own Plone Themes

Some useful tips for making your site designs stand out and work well with future versions of Plone.

Do's and don'ts for themes:

Don't add behaviour --
You never know what kind of site you're going to live inside — keep Javascript and template changes (apart from changes to the purely structural templates like 'main_template' or 'global_logo') outside the theme product.

Don't create external dependencies --
If you have a portlet that pulls data from an SQL database, that portlet should live in a separate product, not in the theme product

Do reuse markup --
The headers in our example look very different from the original ones, but are still h1 tags.

Do change the design slightly --
Don't be afraid to deviate a little bit from the designer's mock-up if it goes against good web usability rules — but be ready to defend it in front of the customer, and tell him why you did it differently.