Contribution Guidelines: Design

Contribution guidelines: design

Welcome! We’re glad you’re interested in contributing to the Standards. Before contributing, please review these guidelines.

The Standards team is dedicated to maintaining a consistent, top-quality product; accordingly, we conduct a design review for every proposed design change we receive. (We don’t, however, review changes that affect only the underlying code — the dev team does that.)

Our design contribution and review process has six stages. As a contributor to the U.S. Web Design Standards, you’ll only need to participate in the first two stages — our team will handle the rest.

This document covers the six stages of the contribution process, what you can expect during each, and our definitions of done — that is, criteria that need to be met for a pattern to move to the next stage. If you have questions, let us know — we’re always happy to chat.

Design contribution process

0. Setting the stage

During this stage, you can review our documentation and contribution-related resources to better understand the types of contributions we’re looking for.

Here are some resources you can use as you make your contribution:

• Our product roadmap: Whenever possible, we’ll flag roadmap features (or GitHub issues) that need design work so you can find them more quickly; some of these may be written as user stories with acceptance criteria.
• Updated personas or user archetypes: These will let you know whom your designs should serve. (Coming soon to our wiki)
• Our design principles, which address visual design, UX, content, branding, and accessibility.
• Heuristic tests that you can run. (Coming soon to our wiki)
• Research guidelines that clarify our current priorities. These may also point to selected Design Method Cards as examples of approaches we prefer. (Coming soon to our wiki)
• Documentation — in plain language, and with minimal jargon — that describes how you can make contributions.
• Examples of good design and content submissions that follow our recommendations. (Coming soon to our wiki. For more insight into our content preferences, please check out the 18F Content Guide.)

1. Submission

The first step in contributing to the U.S. Web Design Standards is submitting your suggestion to the core team. We’ll review all proposed changes as quickly as we can, and we’ll also respond to every suggestion we receive. To submit your proposed contribution, either email us or open a GitHub issue in our repo. (If you’re not familiar with GitHub, here’s a tutorial blog post that may be helpful.) A member of our team will respond to your email within 24 hours. If you submit code, someone will respond to you within 48 hours.

After reviewing your submission, one of our team members will mark it as proposed.

Definitions of done

Each new submission should:

• Identify the user need your pattern solves.
• Let us know why your submitted pattern is the best choice (including its advantages over alternative patterns).
• Include your original design files; if you’re unable to include your original files, please include a rendering of the design: a wireframe, design mockup, interaction pattern, or prototype. We also ask that the files you submit contain only the components being added or modified. A member of our team will then take your artwork and make all corresponding updates to the master sticker sheet files.
• If you’re proposing a content change, please include a complete draft of the content you’re recommending and explain how it reflects the conventions of the 18F Content Guide. If you’re proposing minor changes —spelling corrections, corrections of typos, and so on — you can disregard this step.
• Describe any primary or secondary research that supports this pattern. This description should include the research methods used, description of participants, and links to supporting documentation, including interview protocols, prototype(s) used, and so on.

2. Heuristic review (Standards team only)

After you’ve submitted your proposed change, a member of our team will do a heuristic review. This review is to determine whether the contribution needs small fixes, or whether we need to reject it. During the assessment, the reviewer will jot down notes that will inform later documentation around the pattern.

During this stage, our team will also look for secondary research — other research supporting or refuting the pattern — and link this research to the issue. (Note: If you’re making a content contribution, please refer to the AP Stylebook and the 18F Content Guide; these are the sources we use for secondary research.)

Depending on the outcome of the assessment, our reviewer may ask you to make revisions before they move the pattern to alpha. If your pattern is good to go as is, our reviewer will move the pattern to alpha. If the pattern doesn’t pass the assessment, the reviewer will reject it and close the issue.

These steps are all part of our public, asynchronous review process. We strongly believe that conducting public reviews of contributions makes for stronger design.

And, if you’re curious, here are the criteria we use in our heuristic reviews:

• Usability (Is the pattern responsive? Is the interaction flow clearly documented?)
• Accessibility (Is the pattern accessible to all intended audiences?)
• Visual design (Is the contribution consistent with our visual style? Does it work with different typography pairings?)
• Content (Does the pattern have plain language, correct spelling, and grammar? Does the author clearly describe actions? * Does the author include the appropriate amount of contextual information, given the readers’ existing knowledge?

Definitions of done

The definitions of done for this stage include everything from the proposed stage. In addition, your pattern must:

• Pass all heuristic assessments
• Include secondary research
• Align with secondary research

3. Usability testing (Standards team only)

During this stage, our team will conduct primary usability testing on your pattern to assess its effectiveness. To start, a member of our team will create a prototype of your pattern (unless you already submitted one). They’ll then conduct usability test on your pattern in different contexts. Next, they’ll write the first draft of documentation, after which they’ll insert your pattern code into other configurations with the Standards to test its adaptability. Finally, our team member will either move your pattern as-is to beta; ask you for revisions; or, in some cases, reject your pattern and close the issue.

Definitions of done

The definitions of done for this stage Include everything in the proposed and alpha stages. In addition, your pattern must:

• Be generally usable (on multiple devices) for people with relatively typical digital literacy.
• Work in multiple configurations with other components in the Standards.
• Be accompanied by a first draft of documentation (written by us)
• (For content) Be suitable for all identified audiences, be readable on multiple devices, and follow 18F’s plain-language guidelines

If your pattern meets the above criteria, it will be available in beta as part of the U.S. Web Design Standards.

4. Accessibility usability testing & beta testing (Standards team only)

During this stage, your pattern or component will be available within the Standards as beta. Our team will be collecting feedback on your contribution.

To do this, we’ll do usability tests of your pattern in real-world products with hard-to-serve populations.

By this point, our team will have completed writing the documentation for your pattern. After we wrap up our testing, we’ll ask you for revisions (or make any revisions ourselves) and move your pattern to recommended; or we’ll reject the pattern and close the issue.

Definitions of done

The definitions of done for this stage include everything in the proposed, alpha, and beta stages. In addition, your pattern must:

• Be as easy-to-use as possible for any person with multiple disabilities (blindness, low vision, cognitive disabilities, motor disabilities, low literacy skills, and low digital literacy) on multiple devices.
• Have complete documentation.
• Have been in beta for a month, during which time external teams have had few issues with it.

5. Recommended (Standards team only)

In this stage, your pattern is considered recommended and a stable part of the U.S. Web Design Standards. The core team will conduct ongoing maintenance of your pattern (bug fixes, minor enhancements, and so on), and your pattern will be included in all available design stencils.

Definitions of done

The definitions of done for this stage include everything from the proposed, alpha, and beta stages. In addition, your pattern must have associated renderings available in the design stencils.

6. Deprecated (Standards team only)

Last but not least is the deprecated stage, which is less formal than those preceding it (but it important nonetheless). As technology changes, certain UI patterns will become less relevant or may be replaced by better patterns. Likewise, as conventions in plain-language writing evolve, certain pieces of content may need to be updated or removed from the Standards. As we become aware of such changes, we’ll remove patterns (and content) from the library.