Roll-Your-Own vs Third-Party Design System Reference Website

A design system’s reference website (such as lightningdesignsystem.com, polaris.shopify.com, and a slew of others) serves as the center of gravity for the design system. It rounds up all the design system’s ingredients and serves a watering hole for different disciplines, teams, and stakeholders to come to learn about how to think about and use the design system.

A design system website is, uh, a website. And as it happens us design system people know how to build websites! There are different approaches for creating a reference website, but a big decision boils down to choose a third-party tool vs roll your own website. There are pros and cons to each, which I’ll describe below.

Third-party tools

There are different third-party tools to choose from for your reference website, but if you go the vendor route for a reference site solution, my recommendation would be to use Zeroheight. It’s worth stating that typically I am very, very skeptical of any third-party tool. So it’s saying something that I’m out here recommending anything. But we’ve used Zeroheight with a lot of our recent clients with impressive results (you can see a bunch of examples on their showcase page).

Here are the pros and cons of choosing Zeroheight for your reference website:

Zeroheight pros

• Hosted vendor solution. Get up and running with it right away without having to do any custom development. You benefit as Zeroheight releases new features.
• Cross-disciplinary contribution. Zeroheight provides an authoring interface, authentication, and admin capabilities, which makes it more accessible for less technical disciplines to contribute to the reference website.
• Embeddable code documentation. Zeroheight pull in embeds from component library tools like Storybook, which means the reference site can always be in sync with the library codebase.
• Integration with static design tools like Figma and Sketch. Zeroheight integrates with static design tools and can surface a component’s design specs on the reference website.

Zeroheight cons

• Limited customization. Because it’s a hosted third-party tool, the ability to customize the interface or add unique features is limited.
• Awkward code embeds. Zeroheight embeds Storybook demos and documentation in iframes, which is a weak reading experience. This can make code documentation feel like a second-class citizen.
• Can’t build the UI from the design system’s components. The UI is Zeroheight’s standard UI, which means the reference site can’t be built from the design system’s components. The reference site can often be a handy (and low risk!) pilot project for the design system.
• Vendor lock in. The flip side of getting new features for free is that you’re at the mercy of the vendor’s roadmap for missing features.

Self-hosted solution

A reference website is a website, which means you can use any tool you want to build that website. If you go the self-hosted route, I strongly recommend choosing a solution that is compatible with whatever templating engine you’re using in your design system. If your design system is implemented in React, perhaps React-powered Gatsby is worth looking into (we actually built an open source reference website boilerplate). If your design system uses Twig to power a bunch of Drupal sites, maybe you want to spin up Drupal to power your reference site.

Self-hosted pros

• Fully customizable and extensible. You can design and build whatever you want with it because it’s a custom website you have full control over. This gives lots of control over the style guide’s content and functionality.
• Environment control. Some organizations get huffy about security and stuff like that (which is largely an overreaction for something as basic as a reference website), but again because it’s just a regular-ol’ website you can appease your IT department’s requirements.
• You can build it with design system components. How cool is that! The reference site becomes a low-stakes pilot project that also gives the reference site a look and feel that matches the system itself.
• Integrated code documentation. Unlike Zeroheight’s awkward code embeds, it may be possible to pull in code documentation and component demos directly, making that content a first-class citizen.

Self-hosted cons

• You have to build and maintain it yourself. There’s a lot of custom design and development work to build the full reference site (even with something like our Style Guide Guide boilerplate as a starting point). There are a ton of things that need to get done in order to get a design system off the ground, and building a reference site from the ground up takes time and resources away from all of those other tasks.
• Less accessible to non-developers. When reference websites are built using static site tools (which is typical), content is often authored in Markdown and changes are managed via git. That incurs a steep learning curve for non-developer contributors. Tools like Netlify CMS can create a friendlier experience, but that entails even more custom work. What often happens is that the more tech-savvy team members become the gatekeepers of the reference website content, for better or worse.
• You’re on your own. There’s no community, support, or ongoing feature improvements without you rolling up your sleeves and getting to work.

Both vendor and self-hosted solutions are perfectly valid approaches to building a design system reference website. As time goes on, I’m increasingly finding myself nudging my clients toward Zeroheight, but so much depends on the organization’s culture, setup, and priorities. Hopefully this post helps you make the call on which approach is best.