About
Suggest an addition or update
New component or pattern
Proposing a new component or pattern is appropriate if you have an idea for something that should be included in the design system, or if you receive feedback in the Collaboration Cycle that your work may be useful for other teams. Note that the experimental design process is only necessary when a component or pattern will be useful for other VFS teams. Custom components and patterns that will be used only in your product do not need to go through this process.
Check the design system and the backlog
As you build your component or pattern, check the design system and ensure it does not already exist. If your addition overlaps with a current component or pattern, be sure to call that out when you file your request.
Next, check the backlog to see if your idea has already been suggested.
- If you do see your idea in the backlog, comment on that ticket indicating that you have a need for the component. You will need to wait until the Design System Team is able to continue work on this ticket. Do not file a new experimental design request.
- If you do not see your idea in the backlog, you may continue with filing your request.
Fill out a request
Fill out an Experimental Design System request issue. This should take no more than 10-15 minutes. In the issue you will need to provide justification for this new component or pattern, and link to any artifacts you want to include.
Request a new addition to the Design System
If you feel the addition is small and well explained in your issue, then you may request an asynchronous review.
Note that you do not need to have anything coded at this point, and in fact, we suggest not having anything coded since ideally ideas would be surfaced to the council before teams put effort into building new components.
Additionally, the artifacts you include do not need to be high fidelity. They only need to be able to illustrate your concept. We do, however, encourage some thoughts on how your component or pattern works on mobile.
Conduct research
You must validate the design of your new component or pattern with user research. Learn about conducting research at VA. You may conduct research before presenting your work to the Design System Council, or you may present to the Design System Council and receive feedback before you complete a research study.
Note that even if the Design System Council approves your component or pattern before you conduct research, you must still validate your work with user research and provide your findings to the Design System Council before it can be included in the design system. After research is complete, attach your findings to your Experimental Design request issue, post in the #platform-design-system Slack channel and tag Carol Wong to alert the team.
Present to Design System Council
You will present your work to the Design System Council at an upcoming meeting (unless you have requested an asynchronous review). The Design System Council meets every other Thursday at 11am Eastern. Experimental design requests will always be prioritized in this meeting, and teams can assume generally that they will be able to present the same week of the request.
When you are ready to present, post in the #platform-design-system Slack channel and tag Carol Wong to alert the team that you have filled out an issue and would like to get on the council's agenda. During the meeting, the Design System Council will evaluate the request and make a decision.
If your component or pattern request is rejected, the council will add notes as to why and what they suggest you do instead in the issue.
-
Asynchronous review
If you feel like the change is simple and does not need further explanation beyond what you have provided in your issue then you may ask to have asynchronous approval when creating the initial request.
- Your addition will still be discussed in the council meeting, but you do not have to attend.
- The Design System Council may still request additional information from you in order to properly handle your request.
Update an existing component or pattern
If you are suggesting a change to something that already exists in the VA.gov Design System, you should go through the New component or pattern process above.
- Minor cahnges: If you are requesting a minor change, a change which you feel would be a minor adjustment to current functionality, then you may request an asynchronous review. To do so, complete the process above and indicate in your request that you would like an asynchronous review by the Design System Council.
- Bugs: If the change you are requesting is a bug in a component or pattern file an issue. For example, if the behavior of the component does not match our documentation or a component is not behaving as expected. If the Design System Team feels the matter needs to be addressed by the Design System Council, we'll let you know in the issue.
Update documentation
For requesting more documentation or updating a piece of documentation on design.va.gov, please fill out a documentation request.