Herman Style Guides

Miriam Suzanne
Jan 3, 2018 · 8 min read

An agile approach to design systems on a budget

Image for post
Image for post

Design systems streamline development, communication, and consistency — but often rely on dedicated teams and extended budgets. We wanted a tool to create and maintain living style guides andpattern libraries in an agile process, and on a budget. Herman helps keep our development flow simple and our UX consistent as we iterate on patterns and scale over time.

We’ve just launched Herman 1.0 as a free, open source project for anyone to use and make contributions. Check out the full documentation, or contact us for help putting your design system in place.

I spent the week after Thanksgiving in San Francisco, attending (and accidentally speaking at) Clarity — a “Design Systems” conference organized by the wonderful Jina Anne. If you don’t have experience with design systems, I highly recommend the Handbook which Jina co-authored — available free online.

I’m always curious how many attendees at a conference are working on enterprise projects over a long period of time vs. those of us who do consulting for multiple clients each year. These different contexts can lead to very different solutions — affecting team size, budget, process, architecture, and technical requirements.

I don’t know the exact mix at Clarity, but I think that design systems generally skew towards the enterprise projects for one reason: budget. Creating the beautiful Salesforce Lightning Design System requires an ongoing full-time dedicated team. Those of us doing agency work don’t often have that luxury, but our clients still need a system that will work for them.

So how can we make design systems part of an agile process — growing slowly along-side the application, the same way we write and maintain test-coverage as part of any project? How do we make documentation and design consistency the path of least resistance?

If it’s not documented, it doesn’t exist. Documentation should become the default — an integrated part of the development process.

— Miriam Suzanne (me)

Design Systems can include a wide array of features, more than just a pattern library, and Herman does not cover the full gamut — but it doesn’t have to. With Herman we start small, documenting brand design tokens — colors, fonts, sizes, ratios, and icons — before expanding into practical patterns and components, with automation to help us scale.

Shared Problems, Unique Constraints

The term “design system” refers generally to documenting & distributing isolated patterns and components that can be used across one or more applications for consistent user experience. That usually involves some combination of “style guides” and/or “pattern libraries” — the detailed documentation of design tokens, UI patterns, components, and overall system guidelines.

Lightning Design and other massive projects can make this goal feel daunting, but we’ve found it useful to build what we can, as we go, even when the results are incomplete by comparison. These problems aren’t all-or-nothing. There is room for flexibility in our approaches, from one project to the next. The important question is where can I start improving design communication, clarity, and consistency?

At OddBird, our first style guide attempts failed because they required too much maintenance and attention. So we scaled back to automating color-palettes, and not much else. Over time we’ve added support for a wide array of features integrating with our Sass tooling, and Herman has evolved into a full-featured tool for agile design systems.

Now we use Herman across a range of products, from large client applications to our own internal toolkits. While there are a number of possible configuration options, the initial setup can be streamlined to make sense on even the smallest projects. We’ve even used Herman to begin documenting itself — from design language to components and API.

The project is not complete — and never will be — but that’s the point. As time goes on, we’ll keep adding features that allow our systems to become larger, more complex, and more automated — with support for additional languages.

Integrated Syntax, Built on SassDoc

Style documentation tools have existed for some time, providing a great place to start without re-inventing the wheel. As a design-driven team using Sass/CSS, we love keeping our style documentation directly in with our stylesheets, using tools like KSS and SassDoc. When developers add a pattern in the stylesheet, they can document their work right at the source. When a pattern changes, all the edits can be made in a single location, so documentation is more likely to stay up-to-date.

Those tools are great, but neither one is built to handle more complex design systems, integrated with markup templates and other languages. On the other side, many of the existing “style guide generators” are too intrinsically tied to specific JavaScript frameworks, separating documentation and styles. That may be a good solution for some, but it didn’t feel right for the way we work.

We decided to extend SassDoc, using their framework as a jumping-off point for something larger. The SassDoc syntax uses a variant on Sass line-comments to explicitly mark documentation for parsing:

// Normal Sass comments are ignored by SassDoc/// Comments that begin with 3 slashes 
/// will be parsed as SassDoc documentation.

In addition to allowing prose descriptions (parsed as markdown), SassDoc includes a number of explicit annotations, using an @annotation syntax. Here are just a few of their options:

/// @group buttons 
/// @access public
/// @param {color} $color [green] - The background color for the button
/// @example scss
/// .button {
/// @include call-to-action(red);
/// }

Herman supports all SassDoc annotations, and we’ve added style guide features of our own…

Visualizing Design Tokens

A “design token” is an abstract bit of design language that normally becomes visible only when applied to more explicit patterns and components. Colors, fonts, scales, and grid-configurations act as “sub-atomic” aspects of a design system — often stemming directly from the brand, before any UI components have been built. This is a good place to start defining your system, and Herman can help you visualize these abstractions.

Herman provides display annotations for colors (@colors), fonts (@fonts), sizes (@sizes), and ratios (@ratios):

/// @colors brand-primaries 
/// @font my-font (regular, bold)
/// <any html head required for CDN font imports>
/// @sizes my-spacing
/// @ratios my-modular-scale

In order to display that data, you will need to export all your Sass tokens to json, using our provided Sass export utilities. We’re working to make this step even more simple and automatic.

We also provide an @icons annotation to display all the SVG icons in a given folder:

/// @icons path-to/my-assets/svg/

Rendered Output & Examples

At the pattern level, we include more robust tools for rendering code examples and live patterns. While SassDoc only documents Sass abstractions, Herman allows documentation of CSS selectors and markup patterns.

We’ve extended SassDoc’s @example annotation for languages like Sass and Nunjucks (we’re working on support for Vue components). Herman will display both input and compiled code, along with the rendered output when necessary:

/// Add default button styles to an element. 
/// @group buttons
/// @example html - submit button
/// {% import 'content.macros.j2' as content %}
/// {{ content.button('Submit', attrs={'type': 'submit'}) }} [data-btn] {
border: 1px solid currentColor;
border-radius: 3em;
color: pink;
display: inline-block;
padding: 0.25em 1em;

Prose, Pages, and Third-Party Links

In building documentation — from basic reference docs to extensive design systems — we often find it useful to include additional prose and links to third-party docs for dependencies. There are several ways to do this in Herman:

Free-floating Prose

Any SassDoc comments (///) that are not attached to a specific Sass/CSS objects will appear as free-floating prose, and can be given generic annotations – such as @group, @example, @link, etc. – including the Herman design-token annotations.

Additional Markdown Pages

You can add any number of markdown documents to your style guide navigation, by defining extraDocs in your Herman configuration. We use this to create an introduction to our design systems, provide quick access to a changelog, or document patterns that are not directly attached to Sass code.

Third-party Links

You can also add external links to third-party dependencies — so all relevant documentation is accessible in one place. Define extraLinks in your Herman configuration, and we’ll add links to the bottom of the sidebar.

Open Source & Actively Developed

We’re using Herman on many of our production projects, and we have big plans for Herman’s future. We’ll keep adding features, and we invite you to do the same. The Herman code is available on GitHub, and we’d love to hear your thoughts. File issues for bug-reports, feature requests, or help getting started — or send us your pull requests.

We’ll keep providing our own tutorials and demos based on the questions we hear most, but we’d also love to list any style guides or pattern libraries you build with Herman, or any tutorials you’ve written.

We’re always excited to collaborate, and we’ve provided some “contributing” documentation to help you get involved.

Need help with your design system?

At OddBird, we care deeply about test-coverage and documentation, accessibility, performance, and UX clarity. Herman is one part of our solution, but no tool can provide the magic bullet.

If you need help with a refactor to improve design systems, performance, testing, documentation, or accessibility — eliminate technical debt, and put better processes in place — we’re here for you. Our team of experts can provide a range of support, training, and consulting across the full stack of product design & development — helping find the solution that best fits your team. Don’t hesitate to reach out.

You can use our handy contact form, talk to @OddBird on Twitter, or join our public Slack (with a dedicated #herman channel). We’re excited to hear from you!

Originally published at oddbird.net on January 3, 2018.


OddBird helps companies develop, design, and refactor…

Miriam Suzanne

Written by

Author, artist, musician, dev, queer—at miriamsuzanne.com, ridingsidesaddle.com, @OddBird, @SassSusy, @Real_CSS_Tricks, and @teacupgorilla.



OddBird helps companies develop, design, and refactor custom mobile and web applications. We’re a tight-knit team of designers and developers ready to integrate with companies, scale applications, and improve results. We don’t just follow best-practice — we help define it.

Miriam Suzanne

Written by

Author, artist, musician, dev, queer—at miriamsuzanne.com, ridingsidesaddle.com, @OddBird, @SassSusy, @Real_CSS_Tricks, and @teacupgorilla.



OddBird helps companies develop, design, and refactor custom mobile and web applications. We’re a tight-knit team of designers and developers ready to integrate with companies, scale applications, and improve results. We don’t just follow best-practice — we help define it.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store