Pattern Lab Storefront View

[bradfrost]

The purpose of this post is to describe the vision for using Pattern Lab as a proper style guide website (a storefront) in addition to continuing to serve as a dev environment (a workshop) for designing/building UI design systems.

The Workshop and the Storefront

A while back, I wrote a post that laid out the differentiation between workshop and the storefront environments when it comes to design systems. I encourage you to read the post to get a full understanding of the terms "workshop" and "storefront", but here's the gist.

The workshop is an environment designed for the teams working on designing/building the system's components. Pattern Lab as it currently stands is a workshop environment. The Pattern Lab UI is muted, small, and skinny; it's designed to get out of the way so the working team can focus on the UI they're developing.

The storefront on the other hand is where all the ingredients of the design system (components, design guidelines, design principles, links to tools, resources, contribution guidelines, et al) are put out on the shelves for everyone to see. That place is the style guide website, which you can see in the wild with sites like Lightning Design System and Carbon Design System.

The purpose and audience for the style guide website is different than the dev environment in a number of ways:

• The purpose of a style guide is to tell a complete story of how the organization designs and builds products, whereas the workshop environment is there for the design/dev team to do effective work together.
• The UI for the style guide is more branded and pronounced to be attractive for the design system users, non-developer/designer team members, stakeholders, external vendors, and other people. The workshop UI should be efficient and understated to allow the working team to get things done.
• A style guide tends to contain things like design principles, high-level color guidelines, development principles, points of view on topics like accessibility, and so on. In essence, style guides include a lot of static HTML pages that include don't necessarily pertain to individual components. A good snapshot of all this stuff is the Style Guide Guide boilerplate.
• Only complete, "consumable" components are surfaced in the style guide, whereas work-in-progress components or sub-components should be visible to the working team.
• The organization of the components may follow different naming conventions between the workshop and storefront. For instance, the workshop may organize patterns using atomic design naming conventions (atoms, molecules, organisms, templates, pages), which is helpful for the working team, but may not make sense to the broader organization. The style guide therefore may want to organize components by component type (forms, blocks, media, etc) instead.
• The types of code that's surfaced can differ between the workshop and the storefront. The design system makers may need to reference template code, SCSS, and so on, while the design system users may only (or should only!) need the rendered markup.
• The IA of a component detail page can be fundamentally different between the workshop and storefront. How a component is framed depends on who's viewing the component and for what purpose.

The Problem

These differences between the workshop and storefront environments are real and justifiable. That's why many (most?) organizations maintain two separate environments for their workshops and storefronts. Teams will have an instance of Pattern Lab or Storybook or whatever to do their work, and then maintain a separate site where finished components are imported and documentation is written.

This workflow works for the most part, but at the same it creates duplication of effort, puts a burden on the team to figure out how to import the components into the style guide and keep everything in sync, and requires standing up and maintaining two separate UIs. Wouldn't it be nice to be able to manage a single source of truth for the design system's components and documentation, then have it build out both a workshop and a storefront?

The Proposal

I propose creating the ability to generate a storefront view from Pattern Lab in addition to continuing to support the current workshop view. This would create a true single source of truth for the design system's components and documentation, and would help teams stand up a fully-functional (and—notably— beautiful!) style guide with a snap of their fingers.

It's important to note this would be a different separate build process than the existing workshop process. It's using the same core ingredients to build two separate things that achieve different goals.

Making It Happen

Different templates?

We've done a big refactor of the Pattern Lab UI to clean up all the frontend code, create themes (such as switching between a top navigation bar and a side navigation), and so on. The thought is this could build upon this foundation to generate the style guide.

However, I think that trying to do it all within one template, especially one that involves a giant iframe, wouldn't yield the best results. I think it makes sense to have separate templates for the style guide views so that we have maximum flexibility to display storefront information in a way that makes the most sense. I suppose one way of thinking about this is running Pattern Lab's data, content, and patterns through something like Style Guide Guide's code and yielding a result.

Another interesting wrinkle to all this is that it would be cool if teams could dogfood their own UI components to build the style guide. That might be logistically crazy to accomplish, but it's worth pointing out that it's often a good idea to build the style guide from your own components.

Build Process

Using Node Gulp vernacular, the build process could look something like this:

gulp patternlab:build-style-guide

And it could generate the style guide website into the root of the project under the name /style-guide or something. (I realize though we're unfortunately using the name "styleguide" elsewhere in the codebase).

Keeping it a separate process means that it could get deployed and built to the style guide website using that command, while the working team can continue to use the normal build process to generate the default workshop view.

The Questions

So that's that. I don't want to wade too far into the implementation details just because that's out of my depths. I'm curious to hear how we'd go about achieving this, and even more curious to hear answers to these questions:

• Is this a good idea? Is it desirable to have a single source of truth for the design system, and have the same stuff build these different environments?
• What's the level of effort to make it happen?
• Do separate templates make sense?
• How would we handle static HTML pages for guidelines, design principles, and so on?
• How to keep this integrated enough to benefit from the shared data/content/patterns, but standalone enough where it doesn't disrupt or interfere with the workshop view?
• How can less-technical folks (UX designers, visual designers, copywriters, product owners, etc) easily contribute to the design system's documentation without stepping on the toes of the working team building the components?

So that's that! I'm curious to hear what people think about all this.

[bmuenzenmeyer]

This is great Brad! ⚡️ the workshop and the storefront is a great distillation of primary use cases for a design system.

I think your proposal captures the essence of what we've wanted to accomplish, and also explains the vision behind some of the actions we've made more recently - like theme customization, and changing the styleguidekit templates.

In PL Node 3.X I tried making the frontend more customizable by allowing users to override templates (some but not all) via configuration within patternlab-config.json.

With this storefront vs workshop concept taking on increasing weight, I think I can take this all a step further.

What I envision, from a technical level, is that a Pattern Lab Node Core "build" basically does all the pattern gathering and rendering to HTML as it does now, but DOESN'T write anything to disk. That writing to disk would be deferred to an enhanced ui_builder, which will build as many ui's as the user has configured. We would then pre-package Pattern Lab editions to ship with the current ui, let's call it patternlab-web-workshop for now, and the new patternlab-web-storefront. I know you mentioned making sure the both teams can still work effectively, even down to commands that they run. I am confident we can hit that mark. Keeping them separate allows us to develop them independently, AND allow users to add a third or a remove one at will. This achieves the grand-vision Dave had with the ui separation, but I hope in a better-executed fashion. I'd need to change a few things up to make this work, but I think it's the best way forward. Putting all the code in a single repository (monorepo) will help too - something @geoffp and I are doing during an upcoming Hackday. Another key will be documenting exactly what Pattern Lab has in memory post build and what data we expect people to write. We've never really documented this because we've had working code - but I think this will be an inevitable need.

I hope you like my idea to package storefront and workshop as separate build-able UIs, I think we can really hit the mark.

My vote: 👍

Next steps:

• I plan to task out some of this work as a project of issues inside patternlab-node

[bmuenzenmeyer]

@bradfrost I've started designing this within https://github.com/pattern-lab/patternlab-node/issues/811