USWDS proposal process

The U.S. Web Design System (USWDS) proposal process is the first phase of the USWDS lifecycle.

The proposal process helps the USWDS core team understand community interest in new solutions. Everyone is welcome — community contribution is at the heart of this process. We encourage you to share your thoughts and vote on ideas.

This repository, or "repo" for short, is where we store USWDS team-created formal proposals and document our decisions about new solutions.

Important

Only USWDS core team members can create formal proposals. We will close any proposal pull request that does not come from the USWDS core team. If you'd like to help make the case for a new USWDS solution or comment on an existing proposal, use the USWDS component proposals discussion board instead.

Scope

At this time, the proposal process is only for new USWDS components or patterns.

Other ways to contribute

To request a new feature, code enhancement, or bug fix, open an issue in the uswds repo instead.

Learn more about the ways you can contribute to USWDS on the contribution page.

Help with GitHub

The USWDS proposal process requires knowledge of a few GitHub concepts:

• Branches
• Discussions
• Issues
• Pull requests

If you need help contributing to the proposal process, please reach out via email. We can add your contribution to a discussion if you can’t do so yourself.

Overview of the proposal process

Introduce new ideas in the discussion board. The “Proposals” discussion board is where the USWDS core team and community submit new ideas, share opinions about existing ideas, and vote to express support and interest. Discussions are informal conversations where we can all work together to address the merits, risks, and design of a solution.

The USWDS core team turns discussions into formal proposals. As a discussion makes its case for the suggested solution, the USWDS core team collects this information into a formal proposal based on the proposal template.

The USWDS community comments on proposals. The USWDS core team will share each complete proposal in the original discussion. We’ll welcome comments from the community for 45 days before the proposal moves into evaluation. In that phase, the core team will conduct a formal review of the proposal and share their decision in that discussion.

Suggesting a new solution

Anyone can suggest a new USWDS component or pattern. If you have a new idea, get a conversation started with a GitHub discussion. The USWDS team uses the information from these new solution discussions to create formal proposals.

1. First, review the proposals category in GitHub discussions to see if anyone has already suggested this solution. If the solution has been suggested, you can share ideas and add information or context to the discussion, or just express your interest.
2. If a discussion doesn’t exist, create a new discussion. This discussion is the place to discuss the merits of the new solution, in collaboration with the community and the USWDS team. What makes a good case for a USWDS component or pattern? We've outlined the criteria in our USWDS proposal template.
3. Use the uswds-public Slack channel or reach out to peers to get feedback and support.
4. If the discussion tends toward support for including the solution in the design system, the USWDS core team collects this information to create a formal proposal. The formal proposal will include all information necessary to publish it on the USWDS site.
5. The USWDS team will share the proposal in that discussion thread. When it's complete, there'll be a 45-day comment period where the community has an opportunity to provide feedback on the proposal.
6. Finally, the USWDS core team will evaluate the proposal and update you and the community about the outcome with comments in the GitHub discussion.

Proposal evaluation

Once each proposal is complete, it will enter a final comment period that lasts a minimum of 45 days. After the final comment period ends, the USWDS core team will evaluate the proposal based on community feedback and how the proposed component supports the USWDS mission, vision, polestar, product values, design principles, engineering values, and already-established architectural decisions.

The proposal will then move out of evaluation and into one of the following outcomes:

• Approved: The proposed solution could be a good fit for the design system. Solutions in this phase are ready for development but have not yet been assigned.
• Conditionally approved: The proposed solution could be a good fit for the design system, but other work must be completed before development can be scheduled. Development for these solutions will be put on hold until the needed work is finished. Once the related work is complete, the proposal will move to “approved.”
• Returned for revision: The proposed solution could be approved with revisions and improvements, but still needs support to make a successful case for inclusion.
• Will not pursue: The proposed solution is not a good fit for the design system. We will neither assign nor develop these proposals for USWDS.

Roles and responsibilities

Both the USWDS core team and community members can:

• Start discussions
• Advance existing discussions by contributing information, research, and opinions
• Vote on discussions

The USWDS core team will:

• Create formal proposals
• Manage timelines
• Work with the community to ensure that discussions address all the required proposal criteria
• Evaluate proposals
• Schedule the development of approved proposals and coordinate development efforts with the community