USWDS component proposal process

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

The component proposal process helps the USWDS core team understand community interest in new components. 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 proposals and document our decisions about new components.

Important

Only USWDS core team members can create 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 component 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 component ideas.

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 component 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 component proposal process

Introduce new component ideas in the discussion board. The “Component proposals” discussion board is where the USWDS core team and community submit new component 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 component.

The USWDS core team turns discussions into proposals. As a component discussion makes its case for the suggested component, 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 component suggestion 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 the discussion.

Suggesting a new component

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

1. First, review the component proposals category in GitHub discussions to see if anyone has already suggested the component. If the component 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 component discussion. This discussion is the place to discuss the merits of the new component, in collaboration with the community and the USWDS team. What makes a good case for a USWDS component? 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 component in the design system, the USWDS core team collects this information to create a formal component proposal.
5. The USWDS team will share the proposal on the 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, product values, and design principles.

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

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

The USWDS core team will:

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