Cupper: An Inclusive Documentation Builder

Posted on Monday, 18 September 2017 by Heydon

cupper logo, picturing a teacup with a teabag's label folded over the rim

As accessibility and inclusive design specialists, we are paid for our expertise. But the form that expertise takes and how it is delivered varies depending on different clients’ needs. Some look for high-level reports, while others prefer issues to be addressed independently, in the midst of ongoing development.

As clients have gotten wise to the benefit of designing for accessibility from the ground up, the demand for our expertise at earlier stages of product lifecycles has increased. Accordingly, we’ve been investigating and developing new kinds of services and deliverables; ones more suited to design than design critique.

One area that has been of particular interest has been pattern libraries. Often, design issues can only be effectively addressed by creating entirely new patterns and components to solve those problems. These solutions can be detailed in reports, or in working code. A good pattern library contains both working code and its documentation — all in the same place.

To manage pattern libraries effectively, we needed a system for building and hosting them. This is why we built Cupper, and we’re happy to share it as a free and open tool with you.

Documentation sites as PWAs

Cupper is a high performance generator of rich and accessible documentation sites in the form of progressive web applications (PWAs). That means the documentation sites you create can be saved to your devices and read offline. Because Cupper instances exist as Github repositories, this is possible out of the box. When you commit and push changes to your content, your Github Pages site is updated and a new service worker is installed.

Cupper Docs icon

Cupper Docs icon, pictured on an Android homescreen

More than just markdown

“Pattern” files in Cupper are written in markdown. Markdown is the preferred format of static site generators because, as a text format, it is easy to version control. But Infusion allows you to include much richer content in your markdown via special shortcodesIncluded are shortcodes for expandable sections, file tree diagrams, WCAG references, browser support tables, and even working code demos encapsulated with Shadow DOM. These are all documented in Cupper’s own documentation site, which is built with Cupper.

Accessibility dogfooding

Cupper‘s name comes from the notion of “infusing” products and interfaces with inclusive design; transforming them irreversibly for the better. Regardless of what you are documenting using Infusion, the documentation you’ll be creating meets the highest accessibility standards and incorporates a wealth of inclusive design features.

For example, you might use Cupper to document a JavaScript library you’ve written. You can be confident that people using the documentation by keyboard will be able to read long code examples. That’s because Cupper makes scrollable regions focusable by keyboard. Infusion sites are lightweight, responsive, readable, and clearly structured both visually and semantically.

An anti-aesthetic

Cupper‘s visual design is almost entirely black and white. In fact, the only time it breaks into greyscale is for code syntax highlighting. The sparse, neutral aesthetic was chosen so that the branding and visual design of subject content would not come into conflict. Should you find a darker design kinder to the eyes, Cupper also offers a white-on-black “dark mode”, available from the footer of any instance.


If you are interested in using Cupper, please be our guest and fork the repository before following the installation and setup instructions. Below are all the resources you’ll need:

note: Cupper was, in it’s so far brief life, formerly known as Infusion.

About Heydon

Heydon is a designer, writer and speaker specializing in inclusive design. He writes and codes for inclusive-components.design and his book Inclusive Design Patterns is available from Smashing Magazine.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *