Getting started with USWDS component discussions

[thisisdano]

Welcome to the component proposal discussion board! Use this space to suggest and discuss new components for USWDS.

Who can contribute

Anyone can suggest a component and contribute to component discussions. To participate in these discussions, you must agree to follow our community guidelines.

Participating in GitHub Discussions requires a GitHub account. If you're not able to get a GitHub account, reach out to us via email, and we will add your contribution to the discussion board.

How to contribute

Opening a new component discussion

If you have a new component idea, get a conversation started with a new discussion. The USWDS team uses 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.

Contributing to an existing discussion

Every discussion can benefit from community input. If you’d like to contribute to existing component ideas, we encourage you to:

• Vote for component ideas
• Add information, research, and solutions
• Share opinions and ask questions

Vote for component ideas

One of the easiest and most effective ways to express your interest in a component idea is to vote. Components with more votes are likely to be reviewed more quickly by the USWDS core team.

How to vote

Use the upvote feature 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 agree with the proposal and believe it’s ready for formal evaluation. Remember to vote here in GitHub discussions, not in the proposal repo.

Add information, research, and solutions

You can help 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. See the discussion topics below to understand the types of information we are looking for.

Share opinions and ask questions

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 this process. Please note that all discussions must follow our community guidelines. You can participate in any discussion before or during the 45-day comment period.

What your discussion needs

Any component suggestion should address the points below before the USWDS core team will evaluate it. It helps if you link to supporting evidence and research wherever you can. We ask for a lot of detail, but it’s okay to start with basic information — whatever you have available. You can work with the community to add more detail over time.

• Why USWDS needs this component: Include key interactions, current gaps in USWDS, and the problems this component solves. Explain how the component supports federal laws, guidance, or policies.
• How the component works: Include any interactive states and variants. Diagrams, images, wireframes, and prototypes can help you make your case.
• Real-life examples: Link to examples of other sites — preferably government sites — that use this kind of component.
• When to use this component and when to consider something else: For example, what kind of content works best with this component, and what kind of content would work poorly with it? What are common misuses of this type of component?
• Usability considerations: Include conditions that would make this component more usable or less usable. Also include common pitfalls or implementation mistakes associated with this component.
• Accessibility considerations: Include how this component interacts with assistive technologies such as keyboard navigation, screen readers, zoom magnification, and voice command. Are there audiences that might struggle with this component? How might the component become inaccessible?
• Who’s involved: Please tag volunteers who may be willing to help design, develop or test this component. Note agencies that can offer significant support for the component, and tag any stakeholders. Be sure to share a list of those who helped research and prepare this proposal. Include your name and/or GitHub username if you’d like credit as a contributor.

Once a component discussion has addressed all of these, the USWDS core team will create a formal proposal, open the proposal for community comment, then evaluate it. We’ll share our decision with the community on the relevant discussion page.

Helpful resources

• Contributing to USWDS
• Code of conduct for this discussion board