Component Examples

Showcase your component’s quality, depth and versatility

Nathan Curtis
Mar 24, 2018 · 12 min read

#3 of 7 of the Documenting Components series:
Overview | Intros | Examples | Design | Code | Authoring | Myths


Visual examples are the most essential element of effective component doc. How do you best render, arrange, label, and order each one to with effective content (but not embedded guidelines!) to enable quick use and experimentation? There are many questions to answer as you set about composing examples spread widely across a library. What follows are 15 tips of how to best showcase components in your system documentation.


#1. Lead by Example

A component example, either as static screenshot or rendered via code.

The visualized example is the most effective teaching moment on the page. Even better is the visualized example paired with code needed to render it.

Example/code pair, rendered via templates using library code

As teams tool up, it’s easy to be seduced by the alluring component explorer, adding a control panel beside the example/code pair. Revealing many (but not necessarily all) properties, component explorers invite experimentation and teach a ton in a tight space. However, that power comes at a cost: build the UI, build the logic layer, and implement per component.

Component explorer panel (on the right) beside the example/code pair. For inspiration: GE Predix and Morningstar

For a design-only library, paired code— let alone an explorer — is impossible. Instead, an image will have to do. I’ve never heard anyone disparage Google Material’s design spec, which is full of images and inline demos.

If limited to images, consider depicting the component’s elemental anatomy. Such imagery expose the need for a visual language of annotations (often, we’ll use orange) distinct from the component’s themselves, and a template for producing consistently sized and styled images en masse.

Image annotating a component’s anatomy, saved as PNG as content for documentation site

Takeaway: For libraries with code, enable live examples pairing picture and code early in your process. Component explorers are alluring, but setup can painstaking and distracting to a team early on. Consider saving explorer for a splashy followup to your 1.0.0.

If relying on images, stabilize a visual language for annotations — color, type, image size, image scale — as you document a first few components.


#2. Sensitize the Reader

Christopher Alexander’s “A Pattern Language (1977)”: Every pattern title is followed by a picture.

For UI components, the best sensitizing example depends on component. For atomic primitives, pick the most oft-used case such as a primary button or generic input. For components composed of many elements, the choice is less clear. Do you opt for…

  • the most essential, with only required elements?
  • the most common, mixing required and popular optional elements?
  • the most exhaustive, combining as many useful elements as possible?
Sensitizing examples exhibiting element variety, from a simplistic Essential to rich Exhaustive.

I love the highly versatile List Group component. But a glance at the essential — “Um, a stack of labels, linked?” — in unconvincing. The exhaustive case? Exhaustingly busy, unrealistic, even repellant. In this case, the best sensitizing example showcases elements like an heading, identifying icons, and maybe actions per row.

Takeaway: The best sensitizing example is obvious for primitives. Yet, for composed components, it’s a delicate balance: exhaustive examples can be too complex and not what users typically encounter. yet plain essentials may be obscure it’s power and adaptability.


#3. Order Examples by Type or Composibility

Ordering atomic component by variant priority

For composed components, it may progress from a default with required elements to successive examples overlaying each additional element. For example, you may express list group options with successive examples illustrating actions, headings, subheadings, metadata, badges, and avatars.

Examples ordered property-by-property, associating guidelines with each along the way.

This may maps to Props or CSS modifiers, but don’t get stuck thinking this is mapping is one-to-one. I’ve seen teams seek to shoehorn the succession of examples to the list of Props. It takes a few components to acknowledge that there’s more to teach via examples than just Props by varying states, content, behaviors, and other cases.

As your library grows, some properties may be repeated across many components, such as sizing (small, medium and large) or theming concerns. Consider including those examples last as a convention that recurring controls are explained after features unique to that component.


#4. Limit Hierarchy

Slide from my 2010 design systems workshop, based on Sun.com’s component library convention.

In the early 2010s, such rigorous hierarchy gave way — usually — to a flat example list per component. For simple components with a few examples, flat is fine. Armed with a good sensitizing example, users scroll to scan and find the closest approximation of what they need.

Does this section actually need a label? Maybe a “Variations” heading in local nav, though you can omit it from page content.

Takeaway: Don’t overlay a deep hierarchy couched in vague, misinterpreted levels unless forced to. You could establish one, perhaps aligned with Sketch symbols or Props that necessitate hierarchy. But welcome hierarchy in a design tool’s UI muddle understanding a web page’s documentation. Instead, keep it flat and rely on the scrolling page to reveal variations progressively so customers can find what they need.


#5. Don’t Go Wild with Combinations

While there are approaches to avoid needing to test every possible combination, don’t feel compelled to show every combination on the doc page. It’d overwhelm the reader and vastly reduce the relevance of each case.

Takeaway: Save combinatoric displays for testing environments. For doc, display to a progression of orderly examples to show how it works. Got a zany example? Go for it. But don’t strive to depict every possible instance.


#6. Reveal States Without Requiring Interaction

DO Stack states, one by one

So display each state visibly, labeled and adjacent to one another, without requiring the reader to interact with the page. This usually means a little extra effort within the code, such as an extra documentation-only CSS class like .system__button--doc-hover.

DON’T Arrange examples by state in a single example

Many libraries choose to take a shortcut and display states horizontally adjacent to one another. While more compact, the practice relies on components that are narrow and have just one label, embedding the annotation (“Active”) inside the art. The practice doesn’t scale.

Takeaway: Documentation shouldn’t be a treasure hunt. Don’t make readers work hard to see what’s important. Instead, show an example’s many states by default on the page without requiring interaction.


#7. Prove Theming via Live Demos

Predix Design System light/dark toggle in the page’s upper right swaps the whole page.

GE’s Predix documentation fully embraces the reversal of foreground / background colors, providing a toggle to the “light” and “dark” theme in the viewport’s upper corner.

Theming toggle adjacent to example. Inspiration: Morningstar.

You can localizes this toggle to the component itself, insulating the display shift from the rest of the page and exposing more than a binary option.

Semantic UI’s theming proof, toggled right on the homepage. I’m convinced!

Semantic UI’s proves themability with a menu-driven demo in a row of the homepage. By shifting the style of essential components, prospective adopters are convinced quickly of the library’s potential.

Takeaway: Got themable components? Prove it by demonstrating it. Expose it via tools adjacent to it. Empower it with inspectable code that triggers it.


#8. Embed Content, Not Guidelines

DON’T use Dummy, Symbolic or Lorem Ipsum content

Instead, opt for real content (“Mary Smith”) or labeled data (“[Full Name]”).

DO Use real or labeled copy within component examples.

While it may seem tempting to reveal editorial guidelines or data requirements inside examples, it doesn’t scale and muddles design and annotation. The biggest culprit? Buttons with labels: Default, Hover, Active, and Disabled. Better to use a real label consistently like “Save Profile” so that button state displays mirror other, more complicated components.

DON’T Embed guidelines into example content

Those editorial tips for “Key Benefits” feel convenient. But what if your list can’t exceed three bullets? Can I change the title? What about link labels? Imagine: how would you document editorial tips for a button component? The approach breaks down.

Takeaway: Avoid the embedded guidance. Keep content real, and fall back to labeled data, especially for conditions where implementers focused on authoring and managing content.


#9. Reveal Layered Items In-Page and In-Context

DON’T Just show code and require the user to open each example individually.

The easiest path to provide access to these components is adding a trigger in place of where the sample would go. Usually a button or link, it either invokes (akwardly?) the component in the doc page itself or navigates to a separate page’s demonstration. However, that too is a treasure hunt.

DO Reveal layered content without interaction and offer a trigger of display in context.

Embedding the layered display into the page’s canvas does require incremental effort. However, it’s essential to reveal the layered content – often via many examples—without pogosticking from one to another.

Takeaway: Tool up templating to show layered components in a page’s flow. Readers must easily see it, including variations of features and content, before figuring out how to configure it. Nobody I know wants to hunt and peck, and opening and closing example after example gets tiresome.


#10. Cope with Examples Exceeding Content Width

Sites like Lonely Planet, Shopify and Netapp apply a max width, whereas Buzzfeed, Vue, IBM Carbon, and Salesforce Lightning do not.

Components like horizontal navigation bars and toolbars require more width than 700px or 800px to mimic results users see. Expanding available width creates tensions with competing elements in the overall page layout (usually, navigation on the left and right) as well as excessive line measure (characters per line) of content above and below the example.

Discovery Education Comet’s horizontal Product Bar, displayed in a sometimes too-narrow width.

If the overall layout constrains width, you can augment rendered code examples with screenshots (Example: Morningstar) or present components embedded in an iframe to scale down a display (Example: NetApp).

NetApp examples embedded in iFrames and (optionally) scaled to size to fit the containing viewer.

Takeaway: If your library has wide components, consider alternatives so that those examples display effectively in the default presentation of the page. Widening the content’s main column — or even having example/code viewers exceed that boundary — is the first option to pursue.


#11. Demonstrate Responsiveness

NetApp’s LUCI library embeds scaled down examples in iFrame viewers.

Takeaway: If you want the oohs and ahhs, this will do it. The UI design can be tricky, however, and the implementation – and managing examples shown therein – can get costly. Some teams choose to pass.


#12. Copy to Clipboard


#13. Enable Experimentation

Actions to experiment on Codepen and view code in the system Github repo adjacent to Copy.

#14. Offer Code Alternatives

For example, Hudl’s Uniform unifies component code across web and native, clearly expressing an intent to unify the experience across all platforms.

Hudl’s Uniform, offering code snippets for the same component across platforms.

#15. Limit Captured Scrolling within Code Blocks

If it’s an issue, consider collapsing code by default and providing individual or page-level switches toggle to open it.

Takeaway: Tooling up a viewer requires non-trivial feature development, so balance the extra sauce — Codepens, automated direct links, rendered examples across framework types — as needs require.


EightShapes

A collection of stories, studies, and deep thinking from…

Thanks to James Melzer

Nathan Curtis

Written by

Founded UX firm @eightshapes, contributing to the design systems field through consulting and workshops. VT & @uchicago grad.

EightShapes

A collection of stories, studies, and deep thinking from EightShapes

Nathan Curtis

Written by

Founded UX firm @eightshapes, contributing to the design systems field through consulting and workshops. VT & @uchicago grad.

EightShapes

A collection of stories, studies, and deep thinking from EightShapes

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

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