Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Experimental design content updates #3616

Merged
merged 9 commits into from
Dec 20, 2024
Merged

Experimental design content updates #3616

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1cbbef1
Update "Add a component" content to match experimental design flow
briandeconinck Dec 13, 2024
9fab537
Update "Suggest an update" to match new experimental design flow
briandeconinck Dec 13, 2024
bea529c
Update "Contributing to the design system" to match new experimental …
briandeconinck Dec 13, 2024
fb47ccc
Fix Slack link
briandeconinck Dec 18, 2024
855c056
Clarify providing research findings
briandeconinck Dec 18, 2024
8d8492d
Edit further to clarify sharing research results
briandeconinck Dec 18, 2024
a0f987b
Re-word instructions for providing research findings
briandeconinck Dec 18, 2024
5580199
Merge branch 'main' into experimental-design-content-updates
briandeconinck Dec 18, 2024
6e4a61b
Merge branch 'main' into experimental-design-content-updates
humancompanion-usds Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 38 additions & 11 deletions src/_about/contributing/add-a-component-or-pattern-once-approved.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,50 @@

<va-process-list>
<li>
<h3 id="add">Add the component or pattern</h3>
<h2 id="add">Contribute to the Design System yourself</h2>
<p>
Create a pull request in GitHub in order to add your component or pattern:
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.
</p>
<ol>
<li>Go to <a href="https://github.com/department-of-veterans-affairs/vets-design-system-documentation/tree/main/src/_components">src/_components/</a> or <a href="https://github.com/department-of-veterans-affairs/vets-design-system-documentation/tree/main/src/_patterns">src/_patterns/</a> depending upon which you intend to add.
<li>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.</li>
<li>Add the component or pattern to the Design System repo.
<ol>
<li>Go to <a href="https://github.com/department-of-veterans-affairs/vets-design-system-documentation/tree/main/src/_components">src/_components/</a> or <a href="https://github.com/department-of-veterans-affairs/vets-design-system-documentation/tree/main/src/_patterns">src/_patterns/</a> depending upon which you intend to add.
</li>
<li>Open the <code>Add file</code> menu</li>
<li>Copy the contents of the <a href="{{ site.new_component_template_raw_link }}">component</a> or <a href="{{ site.new_pattern_template_raw_link }}">pattern</a> template and fill in the sections as best you can. See the guidance on <a href="#document">documenting your component or pattern.</a> Don't worry: The Design System Team will review and ask questions about your contribution to help provide the best possible documentation.</li>
<li>When you're ready, commit the changes to a branch, and create a pull request for peer review.</li>
<li>After your pull request has been created, assign it to {{ site.experimental_reviewer_1 }} to review and merge your request.</li>
</ol>
</li>
<li>Open the <code>Add file</code> menu</li>
<li>Copy the contents of the <a href="{{ site.new_component_template_raw_link }}">component</a> or <a href="{{ site.new_pattern_template_raw_link }}">pattern</a> 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.</li>
<li>When you're ready, commit the changes to a branch, and create a pull request for peer review.</li>
<li>After your pull request has been created, assign it to {{ site.experimental_reviewer_1 }} to review and merge your request.</li>
</ol>

</li>
<li>
<h3 id="document">Document your component or pattern</h3>
<h2 id="dst">Contribute to the Design System via the Design System Team</h2>
<p>
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:
</p>
<ol>
<li>Review your supporting research.</li>
<li>Add your component or pattern to the team’s backlog and begin working on it when able to do so.</li>
<li>Contact you for supporting documentation. This may include:
<ol>
<li>A link to the research in the Research repo</li>
<li>Any guidance updates that you recommend</li>
<li>Figma artifacts</li>
<li><a href="{{ site.baseurl }}/about/developers/contributing">Code</a></li>
</ol>
</li>
<li>Complete preparation of the component or pattern, including a Collaboration Cycle Staging Review.</li>
</ol>
</li>
<li>
<h2 id="document">Document your component or pattern</h2>
<p>
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.
</p>
<h4>Artifacts (mockups, wireframes, or prototypes)</h4>
<h3>Artifacts (mockups, wireframes, or prototypes)</h3>
<ul>
<li>If you need to embed images, videos, or other assets in your markdown file, add them to the <a href="https://github.com/department-of-veterans-affairs/vets-design-system-documentation/tree/main/src/images/experimental-design">assets folder</a></li>
<li>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.</li>
Expand All @@ -37,7 +62,7 @@ <h4>Artifacts (mockups, wireframes, or prototypes)</h4>
</p>
</li>
<li>
<h3 id="validate">Validate your design</h3>
<h2 id="validate">Component maturity</h2>
<p>
New components will enter at the start of the <a href="{{ site.baseurl }}/about/maturity-scale#use-with-caution-candidate">maturity scale at "Use with caution: Candidate"</a>. This signals to others that the candidate exists and be something they could consider using.
</p>
Expand All @@ -47,7 +72,7 @@ <h3 id="validate">Validate your design</h3>
<p>
If an experimental component or pattern sits in the <a href="{{ site.baseurl }}/about/maturity-scale#use-with-caution-candidate">"Use with caution: Candidate"</a> status for 6 months with no validation research documented, it will be removed by the design system team.
</p>
</li>
<ul>
<li>
<h3 id="update">Update your component or pattern</h3>
<p>
Expand All @@ -70,4 +95,6 @@ <h3 id="update">Update your component or pattern</h3>
href="https://depo-platform-documentation.scrollhelp.site/research-design/figma-accounts-at-va#FigmaaccountsatVA-Requestingaccess">request access to Figma</a>.
</p>
</li>
</ul>
</li>
</va-process-list>
27 changes: 21 additions & 6 deletions src/_about/contributing/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,27 +12,42 @@ sub-pages:

## Overview

Veteran-facing teams are expected to use design system patterns and components when possible. If existing components or patterns will not work to address needed designs, VFS teams can suggest new components or patterns by going through our Experimental Design process outlined below.
Veteran-facing teams are expected to use design system patterns and components when possible. If existing components or patterns will not work to address needed designs, VFS teams can suggest new components or patterns by going through our Experimental Design process outlined below.

All new components or patterns should go through this process. We recommend starting this process before sharing new designs widely with stakeholders.
All new components or patterns should go through this process. We recommend starting this process before sharing new designs widely with stakeholders.

This process works best if started before development begins, during the design phase.

## Experimental design decision tree

When considering if a component or pattern should be added to the design system there are a few criteria that define a “good” candidate:

1. The component or pattern is already being used on more than one page on VA.gov, or the designer can give examples of multiple places the component could be used.
2. The component or pattern is different in more than one major way than existing components in the design system, if the component is only different in color or format, for instance, then it would be better as a variant of the existing component. Note that variants of existing components should also go through this experimental process.
1. The component or pattern will be useful in multiple products on VA.gov. It may be new or it may already be used somewhere on VA.gov, but the designer should be prepared to give examples of possible use cases beyond just their product.
2. The component or pattern is different in more than one major way than existing components in the design system.
a. If the component is only different in color or format, for instance, then it may be a good candidate as a variant of the existing component. Variants of existing components should also go through this experimental process.
3. Our existing components and patterns will not solve the user problems sufficiently.

<va-link-action
href="https://app.mural.co/t/departmentofveteransaffairs9999/m/departmentofveteransaffairs9999/1715279885465/a8a7701ed5948be8cd98f972ee930a16b9e7444b?wid=0-1733852499418"
text="Open the experimental design decision tree in Mural"
/>

### Experimental design decision tree and process

{% include component-example.html alt="A thumbnail image of experimental design decision tree and process Mural" file="/images/about/experimental-design.png" caption="A thumbnail image of experimental design decision tree and process Mural" %}
If you believe your component or pattern will be a good candidate for inclusion in the design system, then you may [suggest an addition or update](https://design.va.gov/about/contributing-to-the-design-system/suggest-an-addition-or-update) to begin the experimental design process. This process may begin with feedback received at a Collaboration Cycle touchpoint, and will include:

- Conducting research to validate your design
- Presenting your design work and your research to the Design System Council
- Receiving approval from the Design System Council to be added to the design system

If your component or pattern are approved by the Design System Council, you may then [add a component or pattern to the design system](https://design.va.gov/about/contributing-to-the-design-system/add-a-component-or-pattern-once-approved).

<va-link-action
href="https://app.mural.co/t/departmentofveteransaffairs9999/m/departmentofveteransaffairs9999/1715279885465/a8a7701ed5948be8cd98f972ee930a16b9e7444b"
text="Open experimental design Mural file"
/>

<a href="https://app.mural.co/t/departmentofveteransaffairs9999/m/departmentofveteransaffairs9999/1715279885465/a8a7701ed5948be8cd98f972ee930a16b9e7444b">View the experimental design decision tree and process Mural.</a>
{% include component-example.html alt="A thumbnail image of experimental design decision tree and process Mural" file="/images/about/experimental-design.png" caption="A thumbnail image of experimental design decision tree and process Mural" %}


{% include _site-in-this-section.html %}
Loading
Loading