The U.S. Web Design System (USWDS) proposal process is the first phase of the USWDS component lifecycle.
The proposal process helps the USWDS core team understand community interest in new components. Anyone can contribute — community contribution is at the heart of this process. We encourage you to share your ideas, opinions, and votes.
This repo is where we store USWDS proposals and document our decisions about new components.
At this time, the proposal process is only for new component ideas.
To submit a request for a new feature, code enhancement, or bug fix, open an issue in the uswds repo instead. Visit our contribution page to learn more about all the ways you can contribute to USWDS.
The USWDS proposal process requires knowledge of GitHub discussions, branches, issues, and 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 are not able to sign up for a GitHub account.
Introduce new component ideas in the discussion board. The “Component proposals” discussion board is where 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 the community should work together to address the merits, risks, and design of a component.
The core team turns discussions into proposals. Once a component discussion makes a strong case for the suggested component, the USWDS core team will formalize the conversation. We will use the proposal template to create a proposal based on the detailed conversations and voting in the discussion board.
The USWDS community comments on proposals. The USWDS team will share each proposal on the original component suggestion discussion thread. The community will have 45 days to comment on the proposal before it is ready for evaluation. From there, the core team will formally review the idea for inclusion in USWDS and share a decision in the discussion.
The resources in this repo can guide you through contributing to the proposal process:
- Instructions for suggesting a new component
- Instructions for contributing to an existing discussion
- Information about proposal evaluation
- First, find out if the component has already been suggested. Search through the “New components” board in GitHub to see if a discussion has already been started for your component idea. If a discussion for your idea already exists, that’s great! You can contribute to the existing conversation by adding information, sharing your opinion, and upvoting. Learn more about how to contribute to an existing discussion in the next section.
- Start a discussion. If the component hasn’t been suggested yet, start a new discussion about your component idea. Name the discussion
Component proposal: [Component name]. In the body of the discussion, be sure to include at least the name of the component, a description of the component, and why it should be included in the design system. - Refine your discussion with the community. Once your discussion is open, reach out to peers on the uswds-public Slack channel for feedback and support. The discussion will need to cover every section of the USWDS component proposal template before USWDS can formally consider your suggestion.
- Comment on the proposal. When your discussion makes a strong case for the suggested component, the USWDS core team will create a formal proposal. We’ll share the proposal in your discussion. Then, you and the community will have 45 days for comments and additional voting before the proposal gets evaluated.
- Get the decision from USWDS. After we have evaluated the proposal, we will share the outcome with the community via your discussion thread.
Every discussion can benefit from community input. If you would like to contribute to existing component ideas, we encourage you to:
One of the easiest and most effective ways to express your interest in a component idea is to vote. Counting the number of votes on a component discussion is a quick way for the core team to understand the community's level of interest in a component. Components with many votes are more likely to be reviewed first by the USWDS core team.
Use the upvote functionality in the discussion board to vote for component ideas that you want to see in the design system. You can also upvote discussion comments that you agree with.
Once the USWDS core team has shared a formal proposal on a component discussion thread, a vote on the proposal will indicate that you approve of the proposal and believe it is ready for formal evaluation. Remember to vote in GitHub discussions, not in the proposal repo.
You can advance existing discussions by adding research, context, solutions, etc., in the comments. Any relevant information that you add to a discussion can help make the case for evaluating a component and including it in USWDS.
We encourage you to ask questions and share your thoughts in the component discussion. The community’s thoughts and opinions play a critical role in the proposal process. Please note that all discussions must follow our [https://designsystem.digital.gov/about/community/#community-conduct].
Once complete, every proposal will enter a final comment period that lasts a minimum of 45 business days. After the final comment period ends, the USWDS core team will evaluate the proposal based on community feedback and how it supports the mission, vision, and values of USWDS."
Final evaluation is led by the USWDS core team. The proposal will exit the evaluation with one of the following outcomes:
Approved: The proposed component is a good fit for the design system.Approved with notes: The proposed component would be a good fit for the design system after some revisions.Conditional approval: The proposed component is a good fit for the design system, but other work must be completed before development can be scheduled.Returned for revision: The proposal has not not yet made a compelling case, but with improvements it could be accepted. Proposals with this status will be sent back to the "Submitted" status and receive the "Needs: revision" label with suggestions for improvement.Will not pursue: The proposed component is not a good fit for the design system.
Both the core team and community members will:
- Start discussions
- Advance existing discussions by contributing information, research, and opinions
- Vote on discussions
The USWDS core team will:
- Create proposals
- Manage timelines
- Work with the community to ensure that discussions address all the required information
- Evaluate proposals
- Schedule the development of approved proposals and coordinate development efforts with the community