@components

Design System Doc Components

The Top 8 Reusable Components to Document a Library

Masthead

Every time, we use our library’s toolkit to build web-based doc of the library. A bit meta, for sure. The documentation is just another product made and maintained with the kit, only made by the team that made the kit itself.

Building an experience, even doc, sensitizes that team to what it feels like to use the kit, reinforcing the setup and build that their users have. During the process, a simple truth reveals itself, predictably:

The system never provides all the parts for you.

The library gives you Colors and Buttons. Maybe a Nav Bar. Certainly a Footer. However, a library serving online shopping doesn’t need a code viewer or color swatch. So some key components you need to document a library are in fact not in the library. So you build them, just for yourself, separate from and extending the library shared with everyone else.

What do you build? Get ready to tool up! Here’s my eight favorite documentation components, why to build each, and special ingredients you can add to make each even more useful.


#8. Spec & Token Tables

Well documented libraries proliferate tabular spec tables throughout, whether a reference table of CSS modifiers, a token set, or something else. So make a component (or three) for those you repeat over and over.

Design token names and values in a table
Token table, with available variable and corresponding values, as displayed in a section describing the “squished inset” convention.

Automating tabular displays helps authors use simpler syntax, promotes consistent table structure and headings, and eases maintenance for embedded data like tokens.

Special Features:


#7. Release Details

Let’s face it, you’re a product with users to reading release notes and keeping abreast of changes. While boringly administrative, release details summarize change and rout users to new additions.

Sophisticated release history with types of changes per release
Netapp.com LUCI Library release details

So design the content well and don’t skimp on details. Ease authoring, diminish drudgery, and publish a consistent summary per release.

Special Features:


#6. Page-Level Table of Contents

Each component page needs a local table of contents to to scan available variations, specs and guidelines, and then navigate to each quickly. Wikipedia does it. So does Salesforce. Why can’t you?

Local navigation within a page
Sticky local navigation, with variations (above line) and additional documentation (below line)

System users need to know what’s there, and some components — even simple ones like Buttons — have many variants. Local navigation improves awareness of and navigation to what’s available below the fold.

Special Features:


#5. Tint Stack

A tint stack vertically arranges many colors in a group, such as a single color across brightness values or a relevant subsystem of colors like Feedback’s red, yellow and green.

Stack of colors
Google Material Design Color tint stack

Tint stacks display many colors compactly, offering a playground to visualize additional properties of each color.

Special Features:

Stack of colors with values and accessibility scores
Tint stack of neutrals with names (95), hex codes, and text/background accessibility contrast score

#4. Do & Don’t

In libraries full of atomic bits, apply each in a full-page composition can take innumerable forms. So while systems must support a product’s autonomy, nothing beats sensitizing your users to intended and effective uses that comparative do’s and don’ts images.

Do and don't contrasted side by side
Gorgeous diagrams and well written content about Google Material Design’s Card component.

Pictures — especially comparative pictures — are far easier to scan, learn from, and recall than verbose textual guidelines. While more expensive to produce, having a do & don’t component memorably reinforces the value of this display to system authors digging in to compose doc.

Special Features:


All of your system’s customers — designers, devs, product managers, execs — must believe it’s easy to build things that look great. Nothing does that quicker than showing a diverse gallery of built pages, embedded (via iframes) and scaled down to shown in a single, scrolled view. They get it: we use this stuff to build things like this.

Page types built in html
Page gallery of embedded, fully composed page layouts, each displayed in an iFrame.

A scannable gallery of built things quickly sensitizes and builds belief in system validity. While a page rarely used, it’s powerful and easy to setup.

Special Features:


#2. Markdown Chunks

It’s gotta be simple to do the basics of long form content — headings, paragraphs, lists, images, the basics. We use Markdown, cleanly integrated into Nunjucks templating mixed with calls to other components like the Do/Don’t, spec tables, and TOCs described above.

Code snippet
Markdown interspersed with other content to form a documentation page.

Even if you don’t use a templating system like Nunjucks, is your long form content as cleanly input and stored? A clean approach for building doc can make or break easing in contributors and migrating copy from where it’s planned, composed & edited (for my teams, Google Docs).

Special Features: Nah, who needs ‘em? At this point, keep the tool — and your content — clean!


#1. Example — Code Pair

Nothing beats the utility of a visible, rendered example paired with it’s coded counterpart. While bells and whistles abound, it’s here where everyone can see it, and developers can take the thing and use it. Any self-respecting UI toolkit enables you to see the thing and use it effortlessly.

Example and code paired together
Example for the Feed component in the Salesforce Lightning Design System

Special Features:

Need help with your system?

EightShapes can energize your efforts to coach, workshop, assess or partner with you to design, code, document and manage a system.