Back to blog home

LUSH - from Style Guide to a front-end Framework

The use of mobile and tablet devices for shopping is an increasing trend. So it is surprising that, according to the 2014 Sage Pay Payment Landscape report, only 40% of brands have a mobile optimised eCommerce site, potentially locking out over half your customers.

This article shares the challenges we faced and the solutions opted for to develop one of the best (and most complicated) responsive eCommerce website designs we had seen . . . ever (

The challenges that had to be overcome inc: 

    •    Six breakpoints (seven views) 
    •    Iterative design process running in parallel with development 
    •    Pre-compile styles directly for use in Drupal
    •    Permanent reference available for global sites and non-Drupal sites
    •    Cross browser testing before Drupal build
    •    Trial interaction design (at low cost)

This article is written specifically for; digital engagement and ecommerce managers, business analysts, project managers, Drupal themers and developers. Much of the document is written from a technical point as many of the challenges were deeply technical but if you make it to the end please do post comments as we would be delighted to continue the discussion and hear your thoughts.

Project Summary

Lush are a globally renowned, ethics driven, cosmetics brand – appearance and public image is everything. Setting trends and pushing industry boundaries is something that comes with the territory.

Initially Lush sought an eCommerce platform and looked at both open source and proprietary solutions seeking both a suitable platform and an expert vendor. Drupal Commerce was added to the list of possible technologies and Lush reached out to Commerce Guys UK to help them understand if this would be a good fit. Commerce Guys introduced several partners as potential vendors who were all given the chance to meet and impress. iKOS were ultimately selected as the lead agency to pitch Drupal Commerce, who along with Commerce Guys provided the winning pitch.

iKOS were tasked with dual roles – 1: deliver the build of the website and 2: deliver the front end. 

In this case study we are going to be looking at the delivery of the front end, what challenges and breakthroughs we faced and what we have learned from this experience. Challenges such as; work flow between designers and Drupal developers, planning the build of the style guide, design in the browser, fluid layouts, how Drupal played a part in our decision making processes and in some cases dictated the approach we took to theming the style guide and more.

Project Challenge

Constructing the front end in parallel with the designs being refined and the back end also being built presented some obvious issues. We predicted that we would need to update the development environment when a change was made to the design visuals. The sign off was happening in tandem with our implementation and in some cases some time after we had coded the objects. We had little control over the sign off process so we decided to focus on what we could control.

  1. The reusability of content objects
  2. How and where those objects were being used throughout the front end
  3. The structure of our Sass (Syntactically Awesome Stylesheets) – directory structure as well as keeping to the DRY (Don’t Repeat Yourself) approach.

As a result of the designs receiving tweaks along the way, the code that was being transferred into Drupal would soon become outdated. Managing the markup differences between the style guide and the site became a task in itself.

We opted for using Jekyll as a static site generation tool and compass for compiling our Sass into CSS. Our use of these two technologies allowed us to create the modular structure - breaking everything down into smaller component parts - an agile approach we wanted to work with.

Jekyll gave us the ability to use Liquid, a simple programming language, which allowed us to create HTML templates (or Modules) and inject them with variables on a per page basis. This meant that we never needed to repeat any code, we could create a page by assembling the appropriate modules and identify any unique areas where a module did not already exist. This turned out to be an extremely quick and efficient process.

Why the Style Guide approach?

In a move inspired, predominantly, by the team at Starbucks we began experimenting with the use of living style guides prior to getting involved with this project. We used our own site as a testing ground for this and hand coded the HTML and CSS for all objects and elements. 

This approach added additional time and effort initially but embraced the agile approach where we broke everything down into the component parts and ensured they worked before the more complex build. This way of working ensures the UX is considered and correct for the intended audience before being married up with the core Drupal build. 

The true value to Lush in having a ‘living’ style guide is two-fold; it is ready-to-use for the next site(s) and has already been used to re-theme legacy non-Drupal sites providing a tangible ROI. 

A style guide seemed to be the logical approach to take because it solved the majority of our problems:

  • It would give us standardised markup for our content objects
  • It would allow us to validate the designs prior to their move over to Drupal 
  • It allowed us to observe the design consistency and patterns objectively

Accommodating the style guide in Drupal

Using the base theme Omega 4 and view modes we were able to apply the same logic, used with the style guide, in Drupal. 

For each version of how a module appears in the style guide, there would be a view mode and template to match. This template would have data pulled from Drupal using a variety of methods:

  • Data already present as fields
  • Collected data from database using our custom styleguide_api module
  • Contrib modules, e.g. Fivestar or Commerce

The bonuses for us using this approach were that the majority of the code being presented in the browser would be exactly as it was in the style guide and, as that is where cross browser and responsive testing is usually handled, we could be sure that the output would match the style guide.


The initial challenge was the number of breakpoints that Lush and the design team required, ensuring the user experience was consistent on different browsers and devices. A straightforward website could use two or three breakpoints to make the site respond smoothly, LUSH required six.

This would prove to be the most challenging responsive site we had tackled to-date, so our initial investigation was to find a system that could handle the hard work and calculations for us. This is where the SUSY grid comes in.


Our first meetings and talks with Method were simply to help us understand why so many breakpoints were needed and where we could make our lives easier. Our main concern was the amount of time it would take to theme and test each object six times. If the site only consisted of 10 modules then the amount of testing required would be:

10 modules * 6 breakpoints * 8 browsers/devices = 480 tests

Its quite easy to see that the more breakpoints you add, the more tests are required.

The reason for the six breakpoints was explained to us in the following way: “this site must provide the best experience on the wide variety of devices, orientations and screen widths available.” So screen width, over device detection, was favoured. This was to provide some level of future-proofing and the number six was selected based on analysis of devices currently being used by customers.

Defining the grid

Using SUSY as our base grid, we configured the breakpoints set out by Method. We soon realised this was no small task because of the inherent complexity of the grid. Not only are there different breakpoints but each breakpoint has a different column count and different margins/spacings.

To help us, we built a grid overlay for the style guide and could enable or disable it using the [G] shortcut key. With this we could start to test some dummy modules. 

Using classes as our building blocks

Instead of theming the HTML to match the designs (Which is the usual approach), we wanted to have all the basic styles done as classes so that we did not have to reproduce the same code over and over. For example, if an item was 8 columns out of 20, which would happen often, we could simply give it a class and it would fit the grid. Easy huh?

Easy yes, but quick? Not on a website of this scale. We had to create  a grid.scss file in the styleguide to handle this and the amount of code this took was staggering. For each breakpoint you need to have a class which handles all the different grid options.

For example, At breakpoint 2 (4 columns) there can be:​

  1. A one column item
  2. A two column item, or half width
  3. A three column item
  4. A full width or 4 column item.

For each of these, they could be the last item in the row which means that they would also need to have the “omega” class which removes margin allowing them to all sit inline. So:

  1. A one column item can be last
  2. A two column item can be last
  3. A three column item can be last
  4. A four column item is already last.

At the last breakpoint (20 columns), you can see that this adds up to a lot of classes.

The solution we had was to name the classes in such a way that we didn’t need to check the code while building pages. What we ended up with was this:

.break-(breakpoint number)-grid-(number of columns) and .break-(breakpoint number)-omega


.break-4-grid-2 and .break-4-omega

This caused the final CSS to grow quite large from the start but gave us infinite flexibility as to what we could produce and we could be sure that the grid would be consistent.

Handling fonts

One of our sessions with Method, early on, was to discuss the use of fonts on the site. We wanted to use a font that was not standard across all browsers which brought up purchasing requirements which made sense that Lush handled these, and left us managing a larger issue around consistency.

Using a font which is not standard should be fine unless you are theming the fonts in such a way where it highlights the differences. These include:

  1. Containing the font in a border/button.
  2. Underlining the font.
  3. Vertical align images to the font

Unfortunately, we needed to do all of these things and it was quite late in the day when we realised that there was not an easy fix. The problem is that the line-height is not consistent between Windows and Mac operating systems. This causes issues where images do not line up, spaces between borders are not consistent, areas look ‘broken’ and you are not able to control underline spacing.

Our solution was to use a web safe font where the consistency of these items was most noticeable. The font we used was the closest match and is not noticeable to the average user. 

Another issue we had with the fonts is that text changes size over different breakpoints. For example, a title that was 24px at the first two breakpoints could be size 16 on smaller breakpoints. We handled this in the same way as the grid described previously. We set up a list of font size classes and used them like so:

.break-(breakpoint number)-size-(font size reference)



This meant it didn’t matter what size the font needed to be, we had a class to handle it. Another positive is that it also did not matter what markup was being used. An H1 with the same classes as a H3 will be the same size.

Responsive overview

The agile approach worked well as it exposed problems as the project evolved which were added to the backlog and solutions found as we progressed, rather than the traditional method of reaching the end and then discovering what does not work. Open communication between the design and development teams to find solutions is definitely the way forward as often small tweaks to a design could negate 2-3 days of coding. Decisions were made collaboratively as the project progressed ensuring deadlines were hit and teams respected each others decisions since they were discussed rather than dictated.

The Evolution

As the project evolved, it became clear that we would need to alter our approach if we were to hit the ‘go live’ date. We identified that the documentation of the style guide, objects and elements, was taking up large chunks of time so we decided to review this post live.

In true agile fashion we adapted quickly to this. What we were developing, at a rapid pace, was the framework of the site, its grid layout, objects and functionality. It became clear that building a style guide was not as straight forward as we had imagined. A deep understanding of the design, its objects and how they are applied throughout the site was needed but also the time to theme the objects over many breakpoints and browsers.

What we ended up with was not so much a style guide but an interactive visual guide (a prototype) which the clients could use and test theories on. Overall and in many respects, a better result.

When you are building a traditional style guide the best case scenario is to have all the designs signed off before, so you can document it efficiently without constantly making changes.

So we began looking at this, internally, as a framework rather than a style guide, largely due to the reasons mentioned above. Our process was along the lines of; building the designs as the designers created them, while not having a full view of signed-off designs, but also needing a way to decrease development time to meet the deadlines without compromising on quality – a project manager's nightmare.

It was based on our realisation of the above that we decided to begin referring to it internally as the Lush Framework and as such will refer to it as a framework from here on. This had great positive effects on the project as it provided a solution to a number of the issues we were facing.

In summary, there are many reasons why a framework was a good approach for us. Here are the key items:

  1. It allowed us to work in an agile way with the project designers, quickly responding to changes and in-browser design decisions.
  2. It allowed multiple people to work on the same files without conflict.
  3. We were able to work locally which meant that we were unable to overwrite other developers changes. This also speeds up the process by not having to push to a repository.
  4. The tools we used were straight forward, easy to learn and teach to others.
  5. The system we used (objects and templates) worked hand in hand with our approach in Drupal. Allowing us to speed up the integration process.
  6. We were able to construct entire sections of the site in a fraction of the time it would usually take due to the way we developed the templates.
  7. Utilising our multi-disciplined in-house team we were able to provide a front end that was more refined and true to the design earlier in the project.
  8. Users benefited from a more consistent browsing/shopping experience because we had perspective over the whole project rather than the traditional siloed approach.
  9. The stakeholder has a living document detailing interactions, responsiveness and ultimately the design rendered in the browser. (We hope most of you will sympathise with the challenges that come with going from flat or paper based visuals to the final browser rendered version)
  10. Better than a prototype - you don’t throw it away! 


Something we lacked from the outset was a simple, light-weight, bug tracking system. We used Jira heavily on this project for user story management, task and issue tracking and more, but we felt the workflow between us, the designers and client for the front end would benefit from a slightly different and more nimble and dare we say prettier approach.

Enter Wunderlist. Now we know what you are thinking… “Wunderlist, really? for issue tracking?”.

Wunderlist was not really intended for that use at the start of the project. Initially it was used to manage small sets of to-do’s between the iKOS teams – which it does really well. Recent updates like shared lists, assigning tasks, commenting and attaching files have added valuable functionality. Any large pieces of communication were managed through Basecamp or face to face workshops but Wunderlist became an excellent day-to-day communication tool.

We also needed a way to communicate an object or page status with the dev team and the designers at a quick glance so we created our own status labels. Which were:

Jekyll allows any file to have YAML front-matter at the start. Using this front-matter we could assign and display page information on the landing page framework for a quick overview of how the framework is progressing. You can learn more about YAML over at if you are interested. You can also find out more about how Jekyll uses it over here.

We used the front-matter to display information for each page such as JIRA ticket link, Drupal status, which browsers had been peer tested by iKOS, the page or sections title, the category it should appear in and the Lush layout that should be used. Below is a screenshot to show you how that looked.​

Managing the changes that were implemented between the framework and the code that had already moved to Drupal, was also problematic and is something that we are currently working to improve.​

Integration with Drupal

The first thing we tried, when testing out our theory in Drupal, was to build a page which we had already completed in the style guide. The “ingredient page” was almost completed so that is where we starter. We built an API module which would return data for the different sections of the page and a style guide module to put it all together. This would then run through a caching layer and the un-cacheable items (commerce cart - example right) were pinned on last.

See image below as a reference:

This system worked well in principle but it felt like we were doing a lot of manual work to get these pages together, mainly because of the complexity of the structure. An example is that on smaller breakpoints, most items break into an accordion, resulting in content having specific placement. 

This can quickly become time consuming and difficult to manage but we had a folder of templates, used by the theme layer, which were almost identical to the templates we were building in the Style Guide. We also changed the process slightly to use Display Suite layouts for the different variations that a node can appear in. For example: Full, Teaser, Hero, Related…We could still override the template for these display types in Display Suite and using a module called “Display Cache”  we could cache these view modes.

Final outcome

The delivered site has had overwhelmingly positive reviews and feedback both from the client and the public. We like it too and are proud of what we, Method, Commerce Guys and Lush have achieved.

Throughout the development Lush loved the ability to test and play with a functioning front-end representation of the site as we progressed from coding the components to example pages. 

  • Parallel design and development streams; also dual front-end and functionality builds; resulting in the project of being delivered quicker.
  • The client was able to interact with the front end, without being asked to imagine how it would look when themed - which everyone agreed saved time and ambiguity.
  • The ability to resize work in progress to the required breakpoints ensured the responsive aspect was at the forefront of development.

Huge reduction in duplicate work due to the way we approached the objects in the style-guide.

Lessons learned

  • This approach proved essential and fully supported the agile methodologies being used by Method (the design agency) and Lush Digital (the client). 
  • Six breakpoints, seven views, is a big project in its own right - and needs to be its own stream of work; albeit working within the design team (as this is where the changes and directions emanate) 
  • Having the guide (ed- framework) developed by experience Drupal developers is key to maintaining the integrity of the end user tasks (content management). As well as ensuring certain decisions are being made to support the build. 
  • Changing Drupal to output the exact code you want takes a lot of templates; having the style guide helped us plan this in advance. 
  • Solving potential cross browser, cross device issues here, at source, saves time for all subsequent sites.
  • With proper planning a new site could enable this theme and be up and running in a fraction of the time it takes to theme a site from scratch.
  • Being fully embedded with the designers meant live direction could be given, challenged and validated - rather than inviting bugs or long winded annotations to the traditional analogue workflow (e.g. pdf or PSDs)
  • The ability to play with the ‘real’ thing. Designers and clients can validate the designs in a browser at required breakpoints or use their tablet to really test the interactions.
  • Building before the designs are signed off is usually a recipe for disaster (or at least a lot of rework). Iterating a style guide alongside build made parallel development possible. 

The final legacy is the living style-guide being actively used for non-Drupal sites and at the point of writing the second Drupal site for Lush is being wire framed, built and localised using the same, refined, process.

The website features product reviews and instructional videos and attracts just over 600,000 visits per month, which generates 10 per cent of the overall sales – a figure we aim to increase to 25 per cent. The brand has launched a new version of the website this year with a more responsive design for mobile customers in a bid to achieve this goal.​

Jack Constantine, Managing Director LUSH Digital

Further reading

If you are struggling to understand style guides and why they are so effective you should read this article by Susan Robertson, which gives a great introductory overview.

Your questions

We would love to carry on the conversation and shall endeavor to answer all questions.


Article update
This article was originally published under iKOS Digital, which unified with Inviqa in June 2016. For more information about the unification visit