Herman Style Guides

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.

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.

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…

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 (normal, 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/

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;
}

[View the documentation of CSS selectors and markup patterns]

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.

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’re always excited to collaborate, and we’ve provided some “contributing” documentation to help you get involved.

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, or talk to @OddBird on Twitter. We’re excited to hear from you!