Components

USWDS component lifecycle

How USWDS components mature from discussions and proposals to stable production releases, or are deprecated and retired

The USWDS component lifecycle outlines how new components enter the design system, and how we communicate our level of confidence that a component is suitable for use. USWDS adds new components, refines existing ones, and retires those that have become obsolete to adapt to the most current research, new technology, and evolving user needs.

There are opportunities for community contribution at each stage of the component lifecycle. We hope you’ll get involved.

  1. Phase 1: Proposal

    Components under consideration for development through public discussion and a formal proposal.

    Visit the proposal process overview to learn more about how to contribute.

    Discussion started

    A component idea has been submitted to the discussion board.

    Starts when: Anyone starts a discussion about a potential new component.
    Ends when: The USWDS core team begins drafting a proposal for the component.

    Contribute by:

    Find all active component discussions at the USWDS component proposal discussion board.

    Proposal in progress

    The USWDS core team collects community discussion in a formal proposal for the component.

    Starts when: The USWDS core team begins drafting the proposal for the component.
    Ends when: The USWDS core team shares the complete proposal with the community for final feedback.

    Contribute by:
    • Adding missing proposal information to the discussion
    • Adding additional information, context, or perspective to the discussion

    Note: Keep all questions and comments related to the component or the proposal in the public discussion. Don't add comments in the uswds-proposals repo.

    Find all components with proposals in progress on the discussion board.

    Proposal open for comment

    The community has a minimum of 45 days to comment on the complete proposal.

    Starts when: The USWDS core team shares the complete proposal with the community for final feedback.
    Ends when: The comment period closes and the core team starts evaluating feedback.

    Contribute by:
    • Sharing your thoughts about the proposal
    • Asking questions about the proposal
    • Voting for the related component discussion

    Note: Keep all questions and comments related to the the proposal in the public discussion. Don't add comments in the uswds-proposals repo.

    Find all components with proposals open for comment on the discussion board.

    Proposal evaluation

    The USWDS core team evaluates the proposal for inclusion in the design system. After evaluation, the core team will approve the proposal, return it for revision, or mark as “will not pursue.”

    Starts when: The USWDS core team starts evaluating the proposal.
    Ends when: The USWDS core team shares its decision with the community.

    Find the components with proposals under evaluation on the discussion board.

    Approved

    The USWDS core team determined that the component could be a good fit for the design system. Components in this phase are ready for development but have not yet been assigned.

    Starts when: The USWDS core team approves the component proposal.
    Ends when: The component is assigned for development.

    Contribute by: Volunteering to take the assignment and develop the component

    Find all approved components on the discussion board.

    Reach out to the USWDS core team if you are interested in building an approved component.

    Conditionally approved

    The USWDS core team determined that the 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 related work is finished. Once the related work is complete, the component will move to the “approved” state.

    Starts when: The USWDS core team approves the component proposal.
    Ends when: The dependent work is complete and the component moves to approved status.

    Find all conditionally approved components on the discussion board.

    Returned for revision

    The USWDS core team determined that the proposal for the component has not not yet made the case for inclusion, but could be approved with revisions and improvements.

    Starts when: The USWDS core team returns a proposal for revision.
    Ends when: Contributors to the component discussion address the gaps in the proposal, and the USWDS core team updates the proposal for re-evaluation.

    Contribute by: Adding missing information to the discussion.

    You can find all proposals returned for revision on the discussion board.

    Will not pursue

    The core team determined that the proposed component is not a good fit for the design system. We will neither assign nor develop these components for USWDS.

    You can find a list of “will not pursue” components on the discussion board.

  2. Phase 2: Development

    Components undergoing active design, development, testing, and documentation before public release.

    Assigned

    A team committed to building this component. The assignee might be the USWDS core team or a team from the USWDS community. Only approved components are available for assignment.

    Starts when: The component is assigned to a team for development.
    Ends when: Component development begins.

    You can find a list of all assigned components on the discussion board.

    In development

    The assigned team is designing, developing, testing, and documenting the component. This phase can include alpha and beta releases.

    Starts when: The component has been assigned to a team for development.
    Ends when: The component is ready for release.

    You can find a list of components in development on the discussion board.

  3. Phase 3: Released

    Components we've released to the public in our distribution package and documented on the USWDS website.

    Experimental

    The component is released for early access. These components pass accessibility tests, and have core functionality and production-quality code, but might need additional research, testing, documentation, or features.

    Experimental components are OK to use but will likely change more frequently than their stable counterparts.

    Starts when: The component is ready for release.
    Ends when: The component is fully tested, documented, and has an established history in production.

    Contribute by:
    • Testing the component
    • Documenting research findings
    • Adding documentation
    • Submitting bugs and feature requests

    In the future, all experimental components will be documented on our components page.

    Reach out to the USWDS core team if you want to create or contribute to an experimental component. You'll need to build any experimental component from an approved component proposal. If another team already has the assignment for an approved proposal, that team's work takes priority.

    Stable

    The component has an established history in production. These components must meet all USWDS requirements, have full functionality, and have complete documentation. The USWDS core team will audit these components regularly for accessibility and usability.

    Starts when: The component passes all tests and is fully documented.
    Ends when: The component moves to either "use with caution" or "deprecation."

    Contribute by:
    • Submitting bugs
    • Submitting feature requests
    • Creating pull requests

    All stable components will be documented on our components page.

    Use with caution

    The component does not currently meet requirements and needs significant rework. We advise against using components in this state.

    Starts when: The component fails to meet accessibility, usability, or development requirements.
    Ends when: The component returns to stable status or moves to deprecation.

    Contribute by: Suggesting or submitting fixes for the component

    Reach out to the USWDS core team if you want to contribute to “use with caution” components.

  4. Phase 4: Deprecated

    Components that do not meet requirements or are no longer needed.

    Deprecated

    The component is removed from active support. The component is still available in the code base, but it will not receive any updates. We recommend removing the component from your project.

    Starts when: The USWDS core team removes the component from maintenance.
    Ends when: The component is removed from the code base.

    Retired

    The component is removed from the code base. This is the end of the component lifecycle.

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date Description
2024-02-15

Added component lifecycle page. More information: uswds-site#2491