Design System Features, Step-by-Step
A Workflow to Design, Build and Document Each Part
Some teams barely organize how things get done. They’ll add a dash of design here, dive deep into code there, and maybe sprinkle on documentation as an afterthought. “Should we make this? What should it be? When do we QA?” For less disciplined teams, who the heck knows.
Lacking a workflow, a team litters a backlog with heterogeneous, overlapping tasks. From afar, you can’t learn or remember task objective and outcome(s). It’s impossible to relate one task to another. Friction and uncertainty ensue as a team drifts through day to day collaboration.
On the other hand, a defined workflow helps a team mutually understand the scope, reviewers, tools, and the definition of done at each step. With a workflow, collaboration tightens, delivery quickens, and the team predictably delivers features that products love.
My system teams make most features — visual style, UI components, documentation tooling, UX patterns, and more — by following simple, identified steps of discover, design, build, documentation, and publish. I can’t imagine building a design system without it.
#1. Discover
Discovery clarifies the potential and the relevance of a new feature and decides whether or not to pursue it.
Assigned To: Anyone on the team, although usually a designer, front-end developer or product manager.
Activities: Triaging requests, interviews, products and system analysis, discussions with influential partners in the community, and even formal proposal processes like a contributor’s Request for Comment.
Definition of Done:
- As a system team, we understand the scope and cost of making this feature and who may do each step.
- As a system team (or product manager), we’ve (or I’ve) agreed or declined to or pursue this feature and prioritized it in our backlog.
#2. Design
Design finalizes a range of variations, states, and other dimensions at high fidelity so that Build can be completed, whether for visual style (e.g., new icons!), UI components (like a button), or documentation displays (like a Color page’s swatches).
Assigned To: A designer.
Activities: Iterative design work and critique.
Tools: We’ll employ tools like Sketch, InVision, or Photoshop, finalizing work at a high-fidelity consistent with system conventions.
Definition of Done:
- As a design director (or similar role), I’ve approved the final design.
- As system designer(s) and in the community, we’ve agreed that the design solves the problem and is suitable for use across products.
- As the assigned system engineer, I have the sufficient level of variations, states, and other details to complete a build.
#3. Build
Build results in the codification of HTML, CSS, JavaScript, and other code.
Assigned To: Usually a front-end developer, although at times a designer.
Activities: Front end development and testing, often in the context of a “kitchen sink” pages (not documentation site pages) that demonstrates the range of the feature’s capabilities isolated from other system concerns.
Tools: Code and assets, git to manage within prescribed branches, and pull requests to comment and task corrections.
Definition of Done: To merge the feature into a release…
- As the assigned system designer, I’ve reviewed the build’s quality and confirmed it properly implemented scoped features.
- As a peer system engineer (or QA specialist), I’ve reviewed that the build functions properly, meets all quality criteria (accessibility, browser support, etc), and adheres to system’s code styles and conventions.
#4. Doc
Ah, Doc, the task often conflated with Design or Build or ignored until the last minute. To our teams, Doc is different, focused on communicating not what to build, but instead what’s built and how to use it. Doc is a separate task so that our authors focus on the quality and depth that system users crave.
Assigned To: The designer and/or front-end developer doing the work.
Activities:
- Author documentation copy for topics like Use When, Behaviors, Editorial, and other guidelines relevant to the feature and it’s variations.
- Identify if not create final code/example demonstrations.
- Compose illustrations, interactive demos, and screenshots.
Tools: Author in Google Docs, NOT Pull Requests! This collaboration includes a designer, engineer, reviewer(s), and ideally a technical editor too. Pull requests are primitive, limiting comments to lines.
Google Docs is made for collaborative authoring in which you can comment on any word or image as well as suggest and manage changes inline.
Definition of Done:
- As a system user, I’ll have sufficient design guidance (use when, behaviors, visual style, content, & more) and code specs (reference tables, variables, code/example demos) to use the feature correctly.
- As a systems technical editor, the documentation reflects the content models and editorial standards for our documentation.
#5. Publish
Once documentation is complete, it must be migrated to the publishing platform for release.
Assigned To: Front-end developer or designer capable of working in code.
Tools: Most system teams I’ve come across use some form of HTML templating (ours: Nunjucks weaving Markdown and homegrown Documentation Components together), while others hand-code HTML page-by-page (Ack!) or have a more formal CMS (Wordpress or Drupal, anyone?).
Activities:
- Migrating copy from Google Docs to the publishing platform.
- Uploading assets like images, design templates, and interactive demos.
- Finalizing live code/example demos.
- Testing page display, links, and other publishing QA.
Tools: Usually an assortment of assets that weave into a system’s site experience, the rubber meets the road with the composed and published page(s), achieved via however content is managed.
Definition of Done:
- As a system team collaborator, I’ve reviewed committed page changes and tested page displays and links.
- As a system user, I have access to in-depth documentation of a complete feature I can use.
Steps Aren’t a Waterfall, But Do End Sequentially
While the workflow suggests a strict sequence, that doesn’t necessarily imply a waterfall where subsequent steps don’t begin until their predecessor ends. Instead, it’s very common to conduct steps — Design, Build, and Doc — simultaneously, even if the intensity of one is driving the work.
For example, as design solidifies, we’ll start our Google Doc to itemize requirements and collaborate on naming and also start to build prototype HTML and CSS to validate the design. Later on, we’ll review of draft of fully coded designs and shortly thereafter close the design step as a result.
That’s why we’ll have top-level JIRA tasks for each step, since different people may be working different steps at the same time, and each task has different reviewers (for which we use subtasks). There are other ways to model this in JIRA, but this setup works for us.
Nevertheless, the steps end sequentially, such that Design closes before Build, and Build closes before Doc. Publish, at the end, is the only task that doesn’t begin until all the other steps have concluded.
Not All Features Require Every Step
Discovery is unnecessary for many features of any self-respecting design system such as color, buttons, or form controls. Instead, each starts with design and progress through remaining steps.
However, many other tasks use a subset of the workflow to make things. A helpful Getting Started page or description of a Contribution process requires only documentation and thus omits Design and Build:
Similarly, UX patterns don’t result in reusable code, but can require discovery to assess cross-product relevance and needs and iterate through design ideas before being formally documented and published on a system site.
For Trivial Tasks, Combine Steps
Our team will also classify Sketch symbol library development as a Design task that’s followed by combination of Doc (change the version number, describe the change in one line in the release history) and Publish as a single task:
In another case where a feature — like a disabled state — is documented sufficiently by a coded example and requires no further elaboration, we’ll skip the Doc step and combine Build / Publish step.
In any case where steps are combined into a single task, the completion criteria for all steps still apply to the task.
Reflect the Steps in Task or Subtask Titles
Naming conventions — or lack thereof — within a backlog can reflect a level of predictability and rigor of a team.
As I’ve instituted this workflow across many teams over the past few years, our backlogs have become a scannable set of titled tasks for which we can accurately predict the outcomes, reviewers, and relationships of each one.
We’ll use the ticket’s title to reflect a feature’s name and workflow step, and leave the acceptance criteria and deeper descriptions to the details.
Structure Reports to Visualize Doneness
Using a well-modeled workflow, the system team can report on progress across features in a structured fashion, helping stakeholders (and sponsors!) see how the team progresses towards the goals of a first release or beyond.
At the beginning of every sprint leading up to a first release, I’ll include this table of visual style and UI component features progressing across steps. This gives stakeholders a sense of progress, both item-by-item as well as for the overall release scope.
About to embark on a design system, or need to dive deeper to discuss products and players? EightShapes conducts systems planning workshops and coaches clients on design systems. Let’s talk!
