A blog by the Brick Factory The Brick Factory
design system

How to generate a style guide using Hologram & Gulp

Why do I need a style guide?

Let’s be honest, I code differently than you.  And you code differently than the guy sitting next to you with Cheez-it crumb fingers playing Pokemon Go when no one is looking.  So how can we (front end developers) make sure we are providing consistent high quality code across a team?  Enter the style guide!  This post will walk you through how to setup a build system using Gulp.js, Sass and Hologram to generate a living style guide.

Where we started

When our Brick Factory team first began using style guides they consisted of 4-5 HTML files that we maintained separate from the site itself.  We would set up the style guide statically at the beginning of a project to make sure it contained all of the base components and HTML elements . This was all fine and dandy, but after a few months (or weeks) it became out-of-date simply because it was “separate” from the code we were writing.

I started doing some research on how we could get a style guide that generates automatically, and lives somewhere easily accessible.  There are some great options in this space, but after much deliberation and testing we landed on Hologram by Trulia.

What is Hologram

Hologram is a Ruby gem that parses your Sass and looks for special comments to generate a set of structured HTML files.  This means you no longer have to create HTML files manually and the example code lives right within your Sass.  This was a game-changer for our team simply because it makes keeping the style guide up-to-date much easier.

Now we no longer have this separate ambiguous document that no one dares go near.  We have a living, breathing document that not only shows example code, but can output the code directly in the browser.

Installing dependencies

In order to follow the rest of this tutorial, you’ll need to have Node.js and Gulp.js installed globally on your machine.   Let’s start with verifying you have Node.js installed by running the following command:

If this command comes back as “command not found”, you’ll need to install Node.js globally before moving on.  Download Node.js here for your specific operating system and follow all of the prompts.  Once you finish installing it, run the command above again to verify it installed successfully.

Now that you have Node.js installed, verify that Gulp.js is installed by running the following command:

If this command comes back as “command not found”, you’ll need to install Gulp.js globally by running the following command:

Some of you may have to run sudo  if you run into permission errors. If you have to use sudo there are probably other permission issues on your system, but for the sake of this tutorial just use it if you have to.

Let’s get to the code

I’ve created a quick front end starter kit specifically for this tutorial that uses Gulp.js to compile Sass. We’re going to start by downloading the files from the repo and then we’ll get into installing Hologram.

  1. Download the zip file
  2. Create a project directory somewhere on your computer and extract the zip file into that directory.  Keep in mind the zip file already contains a folder so make sure you’re only moving the contents of the folder into your new project directory.

Installing node packages

Since we are using Gulp to compile Sass we need to install a few node packages to get our build system up and running.  If you open package.json in your project folder you’ll see what packages/plugins I’m including for our system.  To install these packages run the following command via terminal from your project directory:

Installing Hologram

Once you have the packages installed you’ll need to install Hologram (Ruby Gem).  Run the following command to install it on your local machine:

Once the gem is done installing you’ll need to initialize Hologram inside of your project directory.  For this example I created a separate “styleguide” directory because I like to keep my root project folder clean.   To initialize Hologram in your project open your command line tool (iTerm, Terminal, etc).  Change directories into your newly created project directory using the “cd” command.  You’ll then want to “cd” into your “styleguide” directory.   Once inside run the following command:

This will create all of the configuration files you need to get your style guide working the way you want it to.

Tweaking the hologram_config.yml file

Now we have all of the technology we need to compile Sass and generate a dynamic style guide, but first we need to make some configuration changes.  Go into the style guide directory and open hologram_config.yml in the text editor of your choice.  Copy and paste the following code into that file overwriting its existing contents.

Here are a list of changes I made in this file from the default file hologram provides:

  1. Changed the source to use the correct folder name and path
  2. Updated documentation_assets to point to the GitHub theme we downloaded in our packages earlier (theme of style guide)
  3. Added css_include to dynamically add our main site css to our style guide.  For you this could be multiple files, but for this example we’re only compiling one Sass file for demo purposes.
  4. Updated dependencies to include our processed folder needed to dynamically grab the site css.
  5. Changed the index option to use styleguide.md which is located in our scss folder.  This sets the style guide home page.
  6. Added global_title to output the title of the style guide in the top left corner (needed for GitHub theme).

Testing our build system

Now that we have everything installed we want to make sure our build system is working properly without errors. In yor command line navigate to your project directory (if you aren’t already there) and run the following command:

To verify everything is working properly navigate to the processed folder and see if there is a CSS file in there (for this demo you should see processed/css/app.css).  If it’s there you’re in business, if not you’ll need to make sure you followed all of the previous steps.

Add hologram comments to the Sass

I’ve already included a few Hologram comments in the scss/app.scss file for you to take a look at, but here is a breakdown of a basic Hologram comment.

  • Title: Title of the style guide component.  Shows directly above description and and code snippets
  • Name: machine name that dictates how things are ordered
  • Category: This let’s you group style guide components into categories.  It also outputs each category as a main navigation item
  • html_example:  Outputs the code snippet so you can copy and paste it, as well as showing the rendered output.

Adding a variation to the style guide

Open up app.scss and we’re going to add a blue variation to our list.  Starting at line 38 you’ll see the opening comment for our lists component.  Then on lines 47 and 58 we’ve defined two different types of lists, purple and green.  Place your cursor on line 67 hit enter and follow the same syntax as the purple example above.   Make sure you change the title, desc, and the html_example to match the new blue class. Finally add the CSS which makes the list blue using the class c-list—blue.

When complete your code should look like the following:

You can also list the output of the code to the left and the code snippet to the right.  It works great with buttons.  All you have to do is change html_example to html_example_table in your comment.  Each row needs to be separated with a space in order for this to work correctly.  I’ve added an example in app.scss of tabular output and here is the code to achieve that:


You should now have a simple build system that compiles Sass and generates an awesome style guide!  It’s really helped our team write consistent code across the board as well as provided a launching pad for getting new people integrated into projects quickly.  This is not a complete system by any means, but it should get you up and running with some of these new concepts.

Next Steps

There are a few things we are exploring such as dynamically injecting content into our style guide from Drupal and using PhantomCSS to run diffs on the style guide to catch any major changes.  Let us know in the comments or on social media what cool things you’re doing with your style guides.



How to create a members only section that people will actually use

If you work at a membership-based organization such as a professional society, trade association or nonprofit, the situation below may sound familiar:

Your members have periodically asked you to provide them with ways to collaborate with each other.  You decide to act on the request and build a new members only section on your website with frequently requested features such as a member directory, member profiles, message boards, group chat and document library.  You launch the new section and get good initial feedback.  But after a few weeks it becomes clear that no one is using the new tools and after a few few months it is a complete ghost town.

You bought the groceries and cooked the meal, but no one is coming for dinner.

In my experience, this is the rule rather than the exception.  The features that sound the most exciting in theory are often quite different from the ones members will actually use on a daily basis.  Perhaps more importantly, your member’s only section is competing for attention against the likes of Facebook, Slack, LinkedIn and Pokemon Go.  Getting people to make your site a part of their daily or weekly routine is a tough ask.  

To help prevent you from wasting blood, sweat and tears building something no one will use, below are some lessons I’ve learned building members only sections for clients.  

(1) Listen to your members

A lot of expensive and unneeded features that get included in members only sections are the result of anecdotal requests (“Board Member A thinks Feature X would be really cool”) and/or poorly constructed membership surveys.  Asking members what features they want is a vital part of the planning process, but you have to ask the right way.  You need the right mix of quantitative and qualitative research.

Don’t just send an open ended email survey asking members what features they would like to see.  Instead, develop a list of features you are thinking of adding and ask members to rank them in order of importance and/or to tell you how often they would use each of them.  You need to a way to prioritize features into “must” and “nice to” haves.  

Be sure to send the survey to all your members, and not just a small subsection.  The needs of your most involved members are going to be different from those who are less active.  Don’t let the loudest voices drive your development priorities.

Lastly, supplement the email survey data with qualitative research.  Interview a few members over the phone or in person to get a sense of how they are using your current members only section (if you have one) and/or how they would use the new features you are contemplating.  Interview members from a variety of backgrounds and engagement levels.  These interviews can be really helpful in understanding how members actually use your site and fine tuning requirements.

(2) Don’t recreate Facebook and LinkedIn

I have worked with a lot of clients who want to build advanced social networking functionality into their members-only site.  They basically want to create a “private” LinkedIn or Facebook for their organization, with groups, status updates, chat, message boards, etc.  

In my experience this approach is nearly always a mistake.  These types of social features sound cutting edge and exciting, but are rarely used in the context of a members only section.  Most of your members aren’t going to spend enough time on your site to support features like chat or message boards.  

If you do want to experiment with social features, a better approach is to try to leverage social networks your members are already using.  Start a private group on LinkedIn or Facebook.  Experiment with Slack.  Start an email discussion list.  These tools are more cost effective and likely to success than trying to build your own walled garden on your site.

Fish where fish are.

(3) Start small and expand

In software development, “the minimum viable product (MVP) is a product with just enough features to gather validated learning about the product and its continued development.”  In the context of a members only section, the MVP should consist only of the “must have” features you and your members have identified.  Start out by building just these features and then expand later based on your site analytics and member feedback.  This approach allows you to move quickly, and saves you time and money that might have been spent building features people won’t actually use.

As an example, we recently built out a members-only section for a professional society.  They started out with a long list of feature requests that included expensive social features.  After research and a series of discussions, their MVP consisted of the following features:

  • User accounts for members with different permissions based on membership level.
  • Members-only document library
  • Listing of members-only events and continued learning opportunities
  • Access to proprietary database showing overall industry trends
  • A really good search of all the members-only materials.

The professional society had a wealth of proprietary content that their members rely on in their day-to-day work.  Providing their members with a way to quickly and easily access this content was far and away the most important feature for the new members only section.  So for phase one of the project, we focused on doing that one thing really, really well.  We focused on the area where the professional society could provide its members with real value.  

project management pitfalls

How to avoid three common project management pitfalls

A few weeks ago I wrote a post about how important it is for project and account managers at web development firms to have empathy.  If you are able to see the world as your client does, chances are you are going to do a great job for them.  You will be able to anticipate problems before they happen.

As a follow up, I wanted to share some real-world examples of client communication problems we’ve run into at the Brick Factory and explain how they could have been prevented.  The underlying theme is that most issues can be prevented with good communication that comes from understanding.  

(1) Hidden Requirements

Project management problem

You have been working on a site redesign project for three months and are a week from launch.  While reviewing the beta version of the site, the client points out that a members-only section that was present on their old site is missing and must be built prior to launch.  This is the first you have heard of this feature.  Your launch date is now in peril and you have to have a difficult conversation with the client since the work isn’t in your original Scope of Work.

How it could have been prevented

No matter what project management methodology you use (Agile, Waterfall, etc.) or how small a project is, every engagement should begin with a discovery phase aimed at surfacing requirements.  Write out the features and functionality of the site/feature you are building and get the client to review and approve to make sure nothing is missing.  

Skipping the discovery phase is sort of like heading out on a cross country, family road trip without a map or GPS.  You will probably get there eventually, but it is going to take a long time and there will probably be tears.

(2) Misinterpreted Designs

Project management problem

Your team has produced a series of design comps for a new site that you are ready to show the client for the first time.  Language and photography are still being finalized, so you use placeholders in the initial comp.  You send the client the designs via email and don’t hear back for a week.   When they finally do get back to you most of the feedback is on the placeholder images and text, and it becomes clear that the client is confused by parts of the interface.   You are able to clear up the confusion with a phone call, but you have wasted a week.

How it could have been prevented

This one is pretty simple: you should always present your first big design deliverable either in person or via a screen sharing service where you can control the experience.  You should only send a link to the design after you have presented the work first.

By presenting the work you are able to explain the decisions you made, fully demo how the interface works and clearly define what kind of feedback you are looking for.  It gives you the opportunity to make sure your work is properly understood.  No matter how thorough or well written an explanatory email, it can’t take the place of a conversation.

(3) Misunderstood Deliverables

Project management problem

You create a series of wireframes for a new website you are building.  The wireframes are in black and white, and intended to demonstrate overall page structure and content priorities.  After sending the wires to the client, you get a short response asking why the new site design is completely black and white.

Later on in the project, you send the client a complete, full color design comp that is in PSD format and optimized for widescreen desktop computers.  The comp is posted in Invision so that the client can see what it will look like in a browser and provide feedback before you build it out in HTML/CSS/JS.  The client calls you five minutes after receiving the comp in a panic, asking why the new site draft doesn’t work on mobile phones.

How it could have been prevented

In both of these scenarios the client misunderstood the deliverable you sent.  In the first scenario they thought the wireframe was a full site design and in the second scenario they thought the design comp was a full working site draft.  

If you are like us, your clients are smart people who are true experts at their jobs. But for a lot of them web development isn’t their primary job.  They count on us to walk them through the process of building a site.  It is a mistake for us to assume that all of our clients know what things like wireframes, design comps, mood boards, prototypes, etc. are.  

One of the first things a project manager should do when onboarding a new client is explain the process that will be used to build the new site or feature.  Walk them through each of the deliverables you are going to produce in detail, explaining what they are for, what their limitations are and what type of feedback you are looking for.  I know this sounds obvious, but I personally have skipped this step and ended up confusing the client more times than I care to admit.


Empathy: a project manager’s secret weapon

Our Brick Factory team recently moved into a new office in the McPherson Square area of Washington, DC.   Our new space was previously occupied by a law firm with an affinity for wood paneling, ship drawings and 80s style carpet.  Thankfully, as part of our lease we were given the opportunity to completely gut the space and rebuild to our exact specification.  This involved a pretty extensive construction project with deadlines, budgets and a team of contractors.  As the client on the project, my job was to oversee the process and to make a million small and large decisions.

I had never been involved in a construction project before and it was quite a trip.  I pretty much felt confused and incompetent the entire time.  I didn’t know speak the language or truly understand the process. I asked many, many stupid questions and had to have things explained to me 2-3 times before I was able to “get it”.  I lived in fear that I would make an expensive mistake.  Despite my extremely shaky performance, the new office turned out great due to the wonderful job done by the team we worked with.

Managing the construction of our new office increased my appreciation for our clients.  Being the client is hard.  By playing the role, I was able to gain a greater understanding of the stress and emotions our clients feel when working with us on web development projects.

At the Brick Factory our clients are smart, busy people who spend their days fighting important policy battles, running successful businesses and/or trying to make the world a better place.  Their jobs are hard and stressful, with deadlines and goals they rely on us to help them meet.   While the web is critical to what they do, building websites is rarely their primary job and not all of them have a deep understanding of the web development process.  

In order to do right by your client, I think one of the most important traits you can have is empathy.  There is a lot of good content on the web about empathy (go watch this video right now), but this definition sums it up pretty well:

The ability to step into the shoes of another person, aiming to understand their feelings and perspectives, and to use that understanding to guide our actions. 

If you think about it, that is a pretty good description of what a project manager does.  If you are able to see the world as your client does, chances are you are going to do a great job for them.  You will have a deep understanding of their needs, and will be able to prevent most problems and resolve the ones that do pop up quickly and amicably.   

While certainly incomplete, to be an empathetic project manager you have to do the following:

  • Understand your client’s background and experience level.  The way you work with a client that is managing their first web development project is going to be fundamentally different from a client with a wealth of experience.  Understand your client’s experience level and adjust your process accordingly.
  • Know how your client likes to work.  Some clients want to be involved in every decision while others want to provide overall direction and let you handle the details. Sometimes it is a mistake to ask for feedback too often. Other times it is a mistake to not ask often enough.  If you understand your client you’ll know what to do.
  • Get to know your client’s company culture.  Is the organization fast paced or laid back?  Who does your client contact report to?  Does your client email you late or night or just during the business day?  Understanding the environment your client is working in will help you provide them with better service.
  • Understand what is keeping your client awake at night.  Is there a big conference they are preparing for?  A vote on a big bill that is fast approaching?  A fundraising number they need to hit?  If you truly understand the client’s pain points you’ll be able to provide better counsel.   
  • Always figure out the “why” behind a request.  As a project manager you have undoubtedly received an out-of-the blue request to move a deadline or to implement a new feature ASAP.  Take the time to understand the context.  This will allow you to distill the request down to its core, providing  you the information you need  to solve the problem.  
  • Actually talk to your client now and then.  A lot of work today is done via emails and collaboration tools such as Basecamp.  Make the time to talk to your client on the phone and/or in person now and then.  You will undoubtedly learn something you wouldn’t have known if you’d stuck exclusively to electronic communication.  This will build connection and understanding.

When you are a project manager at a web development firm, it is very easy to turn into a robot programmed to complete tasks as quickly and efficiently as possible.  But being able to put yourself in the client’s shoes is just as important as efficiency.   Indeed, empathy is often the difference between a great project manager and one that is merely good.


In Defense of the Single Page Website

Like all things that become popular and overused, there is a backlash  against the once revered single page, long-scrolling bootstrap template website.  It is safe to say that a good percentage of the design community is eager to bid it farewell.  While I am as bored as my counterparts with the army of single page sites that all look pretty much exactly the same, I’m not as quick to dismiss the entire concept as passé.

single page site layoutFrom a design point of view, the concern is the saturation of bootstrap style layouts for every agency, PR shop and freelancer needing an easy template.  A design can lose its impact if visitors have seen it a million times already.  Hero image, intro statement, services icons and links, news and blog, CTA and footer. Mix and match if you wanted but most take the template straight out of the box and call it a day. It is bought, used and copied because it works. A one-person shop can produce work as  polished as a a lot of decent-sized agencies.

The single-page layout can still work well, however, if you approach your single page website as a completely fresh design build. The fact that the page can be simple to lay out doesn’t mean it should be considered a template. If anything, with the abundance of single-page scrolling sites, designers need to give more care in creating original designs within this framework.

The reasons a long scroller still gets plenty of play here at the Brick Factory are:

Immediacy.  A single page scroll eliminates confusion as the user interface (UI) is immediately understandable.

Mobile. Obviously, a single, long page scales to mobile fairly easily.  I don’t have to spend time developing custom layouts for different phontes, tablets, widescreens, etc.  This cuts down design time and results in sites that work well on all devices.

Parallax Scrolling is still kind of cool. If you have professional photography, single page sites can still look remarkable.

Scroll-activated animations and transitions. These events can work within a variety of layouts, but we find they work best on a vertical scroll and can become a meaningful component of the narrative.

Maps, Graphics, etc. Integration of graphical elements presents less of a design challenge when you have the luxury of a blank canvas to work with.

Less distraction. For some sites we build, a singular narrative is preferred.  This is particularly true for focused sites that have one overall message to convey or call-to-action to complete. A long scrolling site is perfect because it allows for a distraction-free user experience.

Modules. If you design systems rather than pages (cough, like we do, cough), then a single, deep site works perfectly and can be reworked easily through rounds of internal and client edits.  Components can easily be moved around and reused.

In summary, although a bit labor-intensive on the front end, if designed with a creative approach one-page scrolling sites can still work.  A conscious effort to create a unique design that doesn’t look like every other site on the Internet just needs to be made.  If you do that, the single page site can provide a friendly, consistent experience for virtually all levels of user on just about any device.