Add a component or pattern once approved

Add the component or pattern

Create a pull request in GitHub in order to add your component or pattern:

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. 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.

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.

Validate your design

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.