Living styleguides instantly with Runway

Edit: Version Two of Runway App lives at https://runwayapp.io/

http://runway-app.cfapps.io

More and more, designers at Pivotal Labs and elsewhere are playing an active role in writing front-end code on software projects. And out of this new responsibility has come the desire to build living styleguides — through the language of HTML & CSS — that catalog and detail our design decisions.

As Nico Hagenburger suggests in his fantastic talk, “Styleguide Driven Development,” the utility of a living styleguide is a function of how easily it can be set up and then automatically updated. And while styleguide tools and generators abound (see David Hund’s list, Styleguides.io, ad infinitum), I have struggled to find one that meets all of the following criteria:

  1. Is tech-stack agnostic (e.g., doesn’t depend on / require working knowledge of NPM + Gulp + NodeJS)
  2. Is beautiful and customizable, out of the box
  3. Automatically builds and deploys new changes to a shareable URL
  4. Keeps designers focused on writing HTML & CSS, not figuring out complex tooling and deployment strategies

All of that isn’t to say that the current tooling around living styleguides is inadequate or insufficient. On the contrary, I would contend that the majority of said tooling is too complex for designers whose express mission is to rapidly communicate design decisions through the language of code.

And while I cautioned in a previous post that designers are “blessed — and effectively cursed — by the myriad tools we have at our disposal,” I felt there was a missing need here. So, six weeks ago, I asked myself, “How can we make it simple for designers to go instantly from stylesheet to beautiful, living styleguide?” And I paired with two friends (thanks, Abhi Sharma and Mark McDonald) to build a tool that does just that.

Presenting, Runway.

Look, ma, our marketing page!

So, what is Runway?

Runway is a web-based tool that translates specially formatted comments in your stylesheet into a living styleguide. No dependencies or installation necessary!

How does it work?

Upload a stylesheet (CSS or SCSS only) and Runway will read those comments — complete with a name, description, and some sample HTML to render — and deploy a publicly sharable styleguide to the web. Edit the styleguide to your heart’s content through our interactive editor without its URL ever changing. For example:

@import "https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/css/bootstrap.min.css";
/*doc
name: Primary Button
description: Normal and disabled variants of our primary button. Pulls in Bootstrap styling via CDN, enabling use of the 'btn' class.
code: |
<button class="btn runway-button">Press Me!</button>
<button class="btn runway-button disabled" disabled>Disabled!</button>
*/
.runway-button {
background-color: #80c14f;
color: white;
letter-spacing: .5pt;
text-transform: uppercase;
transition: background .2s ease-out;
  &:hover {
background: darken(#80c14f, 10%);
}
  &.disabled {
background: transparentize(#80c14f, .3);
}
}
Automatically Generated Output

I get the “instant” part… What makes the styleguides beautiful?

As mentioned before, Runway’s goal is to get designers from stylesheet to styleguide, instantly. Other tools require you to roll your own theme, which can lead to clashes between the code you’re trying to document, and that of the theme itself.

We encapsulate your styles to prevent said clashes, and offer two styleguide layouts along with a variety of syntax highlighting themes. Not beautiful enough? Let us know what we can do to make Runway more customizable.

Neat. But tools like Hologram offer cool features like component groups, and support templating languages like Handlebars.

This is true. After all, we’re totally embarrassed by the first version of our product.

Our overarching mission is to make it simple for designers to build living styleguides. And we need your feedback to feel confident that we’ve succeeded in this endeavor. Please send any and all feedback to us on Twitter, and share your styleguides using the hashtag #StyleguidesForAll.

We look forward to seeing what you come up with!


Check us out on ProductHunt