Add a component or pattern once approved

Contribute to the Design System yourself

If your team has the resources to contribute your component or pattern to the Design System, you can complete much of the work on your own.

1. Comment on your experimental design ticket to indicate that you will be contributing your component or pattern yourself. This avoids any duplication of effort between your team and the Design System Team.
2. Add the component or pattern to the Design System repo.
   1. Go to src/_components/ or src/_patterns/ depending upon which you intend to add.
   2. Open the Add file menu
   3. Copy the contents of the component or pattern template and fill in the sections as best you can. See the guidance on documenting your component or pattern. Don't worry: The Design System Team will review and ask questions about your contribution to help provide the best possible documentation.
   4. When you're ready, commit the changes to a branch, and create a pull request for peer review.
   5. After your pull request has been created, assign it to Matthew Dingee to review and merge your request.

Contribute to the Design System via the Design System Team

If your team does not have the resources to contribute your component or pattern to the Design System, the Design System Team will complete the work on your behalf. They will:

1. Review your supporting research.
2. Add your component or pattern to the team’s backlog and begin working on it when able to do so.
3. Contact you for supporting documentation. This may include:
   1. A link to the research in the Research repo
   2. Any guidance updates that you recommend
   3. Figma artifacts
   4. Code
4. Complete preparation of the component or pattern, including a Collaboration Cycle Staging Review.

Document your component or pattern

Your documentation should follow the component or pattern template to the best of your ability. Any sections you have trouble filling out simply leave a "TODO:" note for the Design System Team who will review your submission and make edits or ask you questions, as necessary.

Artifacts (mockups, wireframes, or prototypes)

• If you need to embed images, videos, or other assets in your markdown file, add them to the assets folder
• Be careful to add them directly to the folder rather than dragging and dropping into the Github markdown editor as while that creates a link it does not add the asset to the design system.
• When including an image in your page please create alt text.

Note that code is not required at this step in the process - the main point of documenting here is visibility to other teams. However, if you have code you can share, great! Contributing experimental design code covers how to contribute code.

Component maturity

New components will enter at the start of the maturity scale at "Use with caution: Candidate". This signals to others that the candidate exists and be something they could consider using.

In order to graduate your component or pattern up the maturity scale to "Use with caution: Available", you or your team need to do research or usability testing to validate. When you initially submit your design to the Design System Council, the council is happy to provide thoughts and feedback on your validation approach.

If an experimental component or pattern sits in the "Use with caution: Candidate" status for 6 months with no validation research documented, it will be removed by the design system team.

• Update your component or pattern

  Once you have data from your research, submit the results of the research to the Research repo and tag your research with the appropriate labels including the component or pattern (Design System labels are "va-[component/pattern name]").

  Then provide the Design System Team with the following in #platform-design-system:

  1. A link to the research in the Research repo
  2. Any guidance updates that you recommend
  3. Figma artifacts
  4. Code

  If you can provide a pull request to the Design System Team, you are encouraged to do so. Essentially, you can return to step 2 and fill in any blanks you left in the documentation you created.

  If you are including an example anatomy image for your component, please use the Web Annotation Kit for annotations. Learn how to request access to Figma.