Building a Front End Framework

At the end of 2016, I embarked on a goal to develop an in-house framework for Mercury to use on our internal websites and web apps, as well as client projects. This blog post is geared toward front-end developers looking to make their own framework, and in this post, I’ll talk about approaches I took and lessons I learned during development of the Mercury UI Framework.

Why Another Framework?

At Mercury, we utilize Bootstrap quite often. Many of our client sites use it under the hood. We’ve also dabbled with Foundation, and there are many more out there. The advantage to using a framework is quite obvious:

  • A well-architected UI layer
  • Lots of components
  • Nice documentation
  • Browser testing for free
  • Large ecosystem with examples, tutorials, and add-ons

While we’ve become experts at using Bootstrap, customizing it (tip: use the SASS version!), and extending it, over time I’ve found it lacking in areas and stagnant in new features. Version 4 has been promised for a long time now, but has yet to appear in its final form. After taking a look at the early alpha code, I also felt like it wasn’t pushing itself far enough (there are good things coming, though – flexbox first CSS, refactored cards components, and more). Better responsive components, like tabs and tables? Nope. An off-canvas nav? Nada. Mega menus? Zilch. So, I decided to create a framework that offered more while keeping the things we use most often.

Mercury UI Framework - Components 2

Plan Ahead

Browser Support

Before setting out creating a framework, the first thing you should do is plan what browsers you need to support. This will help inform approaches and effort once you start writing code. At Mercury, we support the latest two operation system and the latest two browsers. That means Windows 8.1, Windows 10, macOS 10.11, macOS 10.12, iOS 10, iOS 9, Android 6, and Android 7 for operating systems on desktop and mobile devices. For browsers, support includes IE11, Edge, Chrome, Firefox, Safari 9 & 10, Safari iOS 9 & 10, and Android Browser. As of late 2016, that covers about 95% of OS’s and browsers in the USA.

Identify Features

The next step in planning is to identify the features you want to build. For my framework, I wanted to create something on par with Bootstrap, but take it further too. This meant including:

  • Accordions
  • Alerts
  • Badges
  • Bands
  • Buttons
  • Button groups
  • Cards
  • Dropdowns
  • Grids
  • Heroes
  • Input
  • Input groups
  • Mega menus
  • Modals
  • Off canvas navs
  • Pagination
  • Tables
  • Tabs – Horizontal
  • Tabs – Vertical
  • Toolbars
  • Tooltips

I also know I wanted to have good documentation with code snippets to copy and paste, as well as a Kitchen Sink of one screen with all components that could be the basis of a projects’ style guide. The table component I created offers 3 different approaches to making tables friendly for small screen devices. Both tab components (horizontal and vertical) change to accordions as well for better mobile usability. I also wanted to make sure I provided breakpoint classes to turn on and off styling, if needed.

Mercury UI Framework - Brand Colors

While identifying features, it’s also a good point to brainstorm how you can make your framework unique. What feature(s) can I include that will set it apart from the rest and make somebody want to use it? How can I provide value for myself, my coworkers, my peers, and for clients? Where can I make things easier and better? Where can I save time for the things I do day to day?

Lastly, identify what you don’t need to create. For the Mercury UI Framework, I made the conscious decision to not include a rotator (also known as a carousel or slider). Much has been written about their poor accessibility, and because there’s more than enough plugins out there, I kept a rotator component off of my features list.

Create A Timeline

After choosing features, the next step is to create a timeline and estimate how much time you’ll need to complete it. The actual time it takes will be different depending on the skill level of the person writing the code, so this should be different for everybody. Also, finding a good MVP (minimal viable product) point for an alpha release is a good idea – you can always have more feature releases in the future. Make sure your timeline includes:

  • Research
  • Building the framework
  • Refactoring
  • Testing (Applause, manual, etc.)
  • Bug fixes
  • Dogfooding (using what you build)
  • Documentation
  • Testing the documentation
  • Setting up hosting, environments, etc.
  • Pipeline creation
  • Code quality analysis (SonarQube, linting, etc.)
  • Code reviews by peers
  • More testing, bug fixing, and refactoring time

Research Best Practices & Industry Trends

Even if you’re a seasoned front end developer, you should take some time to research. In my opinion, you’ll want to target where the industry is going, not where it is now or where it’s been. Is CSS Grid viable yet, or should I stick with Flexbox? What about responsive type? Should I use LESS or SASS? How can Gulp help me? Utilize resources like CSS-Tricks, Sitepoint, Smashing Magazine, and Codepen to gain inspiration and novel approaches. Collect these links and decisions somewhere, like a OneNote or text document, that you can refer back to later. While not everything made it into the Mercury UI Framework, doing this research will inform the code you write. Some decisions, like using the lobotomized owls selector for global margins, will impact the whole framework. Make sure to refer to Can I Use to make sure you’re providing support for the browsers you chose.

Make It Themeable

The framework I created is meant to be used by front-end developers who have the skills to use SASS, so the approach I took was simple: use SASS variables to theme the basic look and feel of the framework, such as colors, border styling, and sizing of elements. I also utilized SASS maps so that developers could easily add or remove breakpoints and alternate colors for components. If you have the time or need, you could go wild and create a theme generator like some frameworks offer. I’d recommend also keeping your CSS code specificity as low as possible so that other developers can easily override your styles with their own without accruing technical debt.

Make It Easy To Use

If you want other people to use your framework, you’re going to need to create good documentation that has examples, code snippets, and explains your architectural decisions. You’ll probably also want a roadmap with where you’re going with future versions, a place for keeping track of bugs, and several ways for people to get your code (repo, direct downloads, etc). One lesson learned is that documentation takes just as long as writing the framework code – don’t leave it until the end! Try and document your work as it’s completed so that nothing is left out or forgotten.

Hold A Code Review

If you’re the only one developing a framework, it’s a good idea to get an outside perspective to make sure your decisions and your code make sense to somebody else via a code review (also known as the number of WTF’s per minute). Another set of eyes and a different brain can help you point out confusion, poor code, or generate ideas for improving your framework. You can hold a code review with a coworker, a developer of a different discipline, or a development manager. If you want a truly outside opinion, find a peer via a front-end development Meetup group. Make sure to follow up a code review with actual action, such as refactoring or creating more documentation.

Test It

This may seem obvious, but sometimes designers and developers cut corners by skimping on testing. Be honest with yourself and really put your framework through its paces by testing it thoroughly. This includes browser testing, functional testing, code analysis, linting, and dogfooding your own work. At Mercury, we’ve adopted Applause for testing our websites and apps, and the Mercury UI Framework was run through this service just as any other project. It helped uncover 70+ issues that I was able to correct, giving peace of mind that the code I wrote would hold up on production sites and apps. Your timeline created earlier should include a healthy amount of time for testing and fixing bugs exposed during that process, as well as multiple rounds of testing if you undergo extensive refactoring during development.


If there’s one thing I want to impart in this blog post, it’s that creating a framework is a lot of work. I hope my time spent can help somebody else looking to do the same. By structuring the process into different segments, you’ll be better armed to complete your framework project and produce a better product as well. Also, remember that you’re never really done with a framework, or any development project for that matter. New needs and ideas arise, browser support changes, bugs will be exposed, and you’ll feel the need to refactor your work.

If you’re interested in checking out the Mercury UI Framework, visit the documentation for the site at (pretty URL coming soon).

Want brilliance sent straight to your inbox?