Introduction to Topcoat

By Chris Griffith

Topcoat is a brand new open source component library built entirely on web standards (CSS and HTML) and is available at It was designed to assist developers and designers in creating high-performance web and PhoneGap applications. This project was announced shortly before the 2013 Adobe MAX conference and, in fact, the official 2013 Adobe MAX conference app was built using Topcoat for its user interface.


The Topcoat project originally grew out a need from several teams within Adobe (most notably the Edge Reflow and Brackets teams), as well as feedback from the PhoneGap developer community for component set that was light-weight, fast, and easily themeable. Lead by Kristofer Joseph, along with Garth Braithwaite and Brian LeRoux, this project is being driven by a great group of developers and designers.

Getting Started with Topcoat

The out of the box installation of Topcoat is incredibly simple:

  • Download Topcoat
  • Open index.html to view the usage guides.
  • Copy your desired theme CSS from the css/ folder into your project
  • Copy the img/ and font/ folders into your project (eel free to only copy the images and font weights you intend to use )
  • Link the CSS into your page. For instance, if you want to use the mobile light theme use:
    <link  rel="stylesheet" type="text/css"  href="css/topcoat-mobile-light.min.css">
  • Done.

However, you probably will want to create a custom build of only the components that your app is using.

One important thing to remember about Topcoat is that it is not a framework. Topcoat’s library can be used along with any JavaScript framework (Backbone, Angular, etc). It just a collection of CSS and HTML.

Exploring the Components

As of version 0.5.1, the library consists of:

  • Button
  • Quiet Button
  • Large Button
  • Large Quiet Button
  • Call To Action Button
  • Large Call To Action Button
  • Icon Button
  • Quiet Icon Button
  • Large Icon Button
  • Large Quiet Icon Button
  • List
  • Navigation Bar
  • Search Input
  • Large Search Input
  • Text Input
  • Large Text Input
  • TopCoat Textarea
  • Topcoat Large Textarea

The List component

The library ships with both a mobile-friendly set of components, as well as a desktop-friendly version. Each of these versions is also available in both a light or dark style. Each control lives in its own GitHub repository and has no dependencies (not even jQuery), so you can easily assemble just what your app will need (more on that later in this article). When creating mobile apps (or PhoneGap apps) in particular, having lightweight components can greatly improve the performance (and thus the user experience).

As an example, let’s look at how to implement a list component:

<div class="topcoat-list__container">
    <h3 class="topcoat-list__header">Category</h3>
    <ul class="topcoat-list">
        <li class="topcoat-list__item">
        Item 1
        <li class="topcoat-list__item">
        Item 2
        <li class="topcoat-list__item">
        Item 3

As you can see there is not a lot of additional markup to create our Topcoat list component. A containing div and few additional CSS classes on the ul and li elements. The accompanying CSS is also fairly straightforward. Here is generated CSS for the dark theme:

.topcoat-list__container {
  padding: 0;
  margin: 0;
  font: inherit;
  color: inherit;
  background: transparent;
  border: none;
  cursor: default;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
  overflow: auto;
  -webkit-overflow-scrolling: touch;
  border-top: 1px solid #2f3234;
  border-bottom: 1px solid #eff1f1;
  background-color: #444849;
.topcoat-list__header {
  margin: 0;
  padding: 0.3rem 1.6rem;
  font-size: 0.9em;
  font-weight: 400;
  background-color: #3b3e40;
  color: #868888;
  text-shadow: 0 -1px 0 rgba(0,0,0,0.3);
  border-top: solid 1px rgba(255,255,255,0.1);
  border-bottom: solid 1px rgba(255,255,255,0.05);
.topcoat-list {
  padding: 0;
  margin: 0;
  list-style-type: none;
  border-top: 1px solid #2f3234;
  color: #c6c8c8;
.topcoat-list__item {
  margin: 0;
  padding: 0;
  padding: 1.16rem;
  border-top: 1px solid #5e6061;
  border-bottom: 1px solid #2f3234;
.topcoat-list__item:first-child {
  border-top: 1px solid rgba(0,0,0,0.05);

The structure of the CSS follows the BEM (Block, Element, Modifier) model. If you are unfamiliar with BEM, take a look at this article. This structure greatly helps in understanding where and how the CSS attributes are being applied to the HTML. The components in Topcoat CSS are authored in Stylus, and utilizes many of its features to allow for a clean separation of resets, from layout, from aesthetic, and between platforms. I personally had not worked with Stylus before, but was able to quickly pick up their stylesheet language.

Performance first!

Although, the team has taken great efforts enable easy customization of each component, the heart of the project is the actual performance of each component. The team has set up a complete benchmarking suite to measure the performance.



If fact, this system is also totally open source and can be used as a stand alone tool for teams looking to find ways to measure their own application’s performance.


What would a component library be complete without an icon set? Topcoat has included them as SVG, PNG or as a semantic icon font. And, yes, they are also open source.


Transitions and Animations

Recently, the team behind Effeckt.css, a new mobile friendly library for performant transitions and animations, began exploring possible collaboration with the Topcoat team. Components and transitions are tightly coupled from an actual user interface perspective. Often, it is the transitional portion of the component, for example how an overlay appears, that creates the value of the component to the application. This effort just got underway, so keep an eye out for improvements down the road.

Custom Builds

Although the minified version of currently clocks in about 13K, you might wish to trim the library down to just the components that your application uses. Since Topcoat is built using Grunt, it is relatively easy to edit the build script to generate your custom library. Here are the steps:

  • Fork Topcoat from
  • Install Node and run npm install -g grunt-cli and npm install in the Topcoat directory.
  • Modify the package.json to point to only the controls you need
  • Run grunt to generate your custom build

Custom Themes

Generating custom themes is also done through the use of Grunt. Here are the steps:

  • Fork
  • Modify various variables files to make your changes
  • Modify ./topcoat-X.X.X/package.json to point to your theme and run grunt

What’s Next?

Remember, Topcoat is totally open source software. There are bugs, and the team is still solidifying their architecture, so there are many ways to contribute! Here are some additional links to get you started:


How Putting Ads on Mobile Apps Can Lose Money – A Case Study

Animating with AngularJS