Merge branch 'main' into remove-v1-example-2802

Gemfile.lock

@@ -64,14 +64,16 @@ GEM
     rb-fsevent (0.11.1)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.2.5)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
     rouge (3.29.0)
     safe_yaml (1.0.5)
     sass-embedded (1.0.21)
       google-protobuf (~> 3.19.0)
       rake (>= 12.3.0)
     sassc (2.4.0)
       ffi (~> 1.9)
+    strscan (3.1.0)
     terminal-table (2.0.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     unicode-display_width (1.8.0)

package.json

@@ -26,7 +26,7 @@
   },
   "homepage": "https://github.com/department-of-veterans-affairs/vets-design-system-documentation#readme",
   "devDependencies": {
-    "@department-of-veterans-affairs/component-library": "^41.0.0",
+    "@department-of-veterans-affairs/component-library": "^41.1.0",
     "gulp": "^4.0.2",
     "gulp-clean": "^0.4.0",
     "gulp-rename": "^2.0.0",

src/_about/contributing/suggest-an-addition-or-update.html

@@ -56,7 +56,7 @@ <h3 id="present-to-design-system-council">
       Present to Design System Council
     </h3>
     <p>
-      You will present your work to the Design System Council at an upcoming meeting (unless you have requested an <a href="#async-review">asynchronous review</a>). The Design System Council meets every Friday at 1pm 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. In order to kick off this step:
+      You will present your work to the Design System Council at an upcoming meeting (unless you have requested an <a href="#async-review">asynchronous review</a>). 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. In order to kick off this step:
     </p>
     <ul>
       <li>
@@ -102,4 +102,4 @@ <h2 id="update-documentation">
 </h2>
 <p>
   For requesting more documentation or updating a piece of documentation on design.va.gov, please fill out a <a href="{{ site.update_documentation_link }}">documentation request</a>.
-</p>
+</p>

src/_components/button/button-group.md

@@ -5,7 +5,7 @@ has-parent: /components/button/
 title: Button group
 aka: Button pair
 research-link: Buttons
-figma-link: https://www.figma.com/file/JDFpGLIojfuQwANXScQjqe/VADS-Example-Library?type=design&node-id=35%3A153&mode=design&t=jMcVWkPlFhZu3RTh-1
+figma-link: https://www.figma.com/file/JDFpGLIojfuQwANXScQjqe/VADS-Component-Examples?type=design&node-id=3109%3A381&mode=design&t=HPTk6DwbG1oCM61n-1
 intro-text: The default button group arranges each button as a separate element with a gap between them. On mobile devices, the buttons are arranged vertically. 
 status: use-deployed
 uswds-v3: default

src/_components/button/button-icon.md

@@ -0,0 +1,54 @@
+---
+layout: component
+permalink: /components/button/button-icon
+redirect_from:
+  - /components/button-icon
+has-parent: /components/button/
+title: Button - Icon
+aka: Button - Tertiary
+research-link: Buttons
+figma-link: https://www.figma.com/file/afurtw4iqQe6y4gXfNfkkk/VADS-Component-Library?type=design&node-id=6554%3A11058&mode=design&t=4Zo01aEkp6l4faTn-1
+intro-text: The button icon variation acts as a tertiary button which has equal visual prominence to Link - Action and thus can be used in contexts that require a mix of links and buttons. 
+status: use-with-caution-candidate
+uswds-v3: default
+web-component: va-button-pair
+anchors:
+  - anchor: Examples
+  - anchor: Usage
+  - anchor: Code usage
+  - anchor: Accessibility considerations
+---
+
+## Examples
+
+### Change file
+
+{% include storybook-preview.html story="components-va-button-icon--change-file" link_text="Change file, used in the File input component" height="75px" %}
+
+### Delete
+
+{% include storybook-preview.html story="components-va-button-icon--delete" link_text="Delete, used in the File input component" height="75px" %}
+
+### Cancel
+
+{% include storybook-preview.html story="components-va-button-icon--cancel" link_text="va-button-icon cancel variation" height="75px" %}
+
+## Usage
+
+### When to use Button - Icon
+
+* **In a Card or other container alongside a primary link.** This component is mainly intended to sit alongside a primary link, typically a [Link - Active]({{ site.baseurl }}/components/link#active) variation, within a [Card]({{ site.baseurl }}/components/card). This allows the link to visually have the affordance as the primary action and the Button - Icon the affordance of a secondary action.
+
+### When to consider something else
+
+* **When a secondary button will suffice.** Button - Icon does not replace the [Button - Secondary]({{ site.baseurl }}/components/button#default---secondary). Only use Button - Icon when Button - Secondary would visually dwarf a link primary action.
+
+## Content considerations
+
+* **Button labels as verbs.** This component represents an action and thus the button label needs to be a verb that describes the action the user is taking.
+* **Be concise - one or two words only.** Because the visual style of this button uses uppercase text, labels must be very concise actions and thus are limited to one or two words only.
+* **Delete is preferred to remove.** We prefer words that describe exactly what will happen when you tap or click.
+
+## Accessibility considerations
+
+* **Follow button considerations.** This component should follow the same considerations as a [typical button]({{ site.baseurl }}/components/button#accessibility-considerations).

src/_components/button/index.md

@@ -8,6 +8,7 @@ figma-link: https://www.figma.com/file/JDFpGLIojfuQwANXScQjqe/VADS-Example-Libra
 status: use-deployed
 sub-pages:
   - sub-page: Button group
+  - sub-page: Button icon
 uswds-v3: primary
 web-component: va-button
 anchors:
@@ -63,11 +64,12 @@ anchors:
 
 * **Avoid using many primary buttons on a single page or section.** Pages with many primary buttons reduces their impact and make it harder for users to know what to do next.
 * **Arrows are reserved.** Arrow icons should only appear for "Back" and "Continue" buttons that appear in forms.
+* **Use icons only when necessary.** [Icons]({{ site.baseurl }}/foundation/icons) can be used in buttons when additional clarity is required and the icon is highly relevant to the action. Icons should not be used for decoration. Note that va-button does not support iconography, but has some variations that use an icon. Use of icons in buttons will be made on a case-by-case basis. If you feel you need an icon for a button, [follow the process for requesting a new icon]({{ site.baseurl }}/foundation/icons#requesting-a-new-icon) .
 * **Avoid disabling buttons.** [Disabling buttons is strongly discouraged.](#do-not-disable-buttons)
 
 ### Choosing between variations
 
-* **Use primary for the most important action.** Use the primary button for the most important action that you want the user to take on the page, or in a section. 
+* **Use primary for the most important action.** Use the primary button for the most important action that you want the user to take on the page, or in a section.
 * **Use secondary for non-primary actions.** Use secondary buttons for any actions that need to be _downplayed_ against other actions on the page, or in a section.
 
 ### Placement

src/_components/template.md

@@ -37,14 +37,14 @@ Add Storybook examples as necessary.
 
 ### When to use Component name
 
-* **In this context**: Explain the scenario or user context where this component is, or could be, used.
-* **In this task**: Explain the user task or tasks where this component is, or could be, used.
+* **In this context.** Explain the scenario or user context where this component is, or could be, used.
+* **In this task.** Explain the user task or tasks where this component is, or could be, used.
 
 ### When to consider something else
 
-* **Not in this context**: Explain which scenarios or user context where this component is not, or should not, be used.
-* **Not for these tasks**: Explain the user tasks where this component is not, or should not, be used.
-* **Use this instead**: Explain when another component should be used instead.
+* **Not in this context.** Explain which scenarios or user context where this component is not, or should not, be used.
+* **Not for these tasks.** Explain the user tasks where this component is not, or should not, be used.
+* **Use this instead.** Explain when another component should be used instead.
 
 ### How this component works
 
@@ -54,10 +54,10 @@ Details the design decisions inherent to the component.
 
 Describe the key interactions for this component.
 
-* **Trigger**: What does the user do to start the interaction with this component.
-* **Rules**: What rules govern how the component behaves. How does it work?
-* **Feedback**: What the user sees, hears, and feels that help them understand the rules.
-* **Loops and modes**: Meta rules that govern the interaction.
+* **Trigger.** What does the user do to start the interaction with this component.
+* **Rules.** What rules govern how the component behaves. How does it work?
+* **Feedback.** What the user sees, hears, and feels that help them understand the rules.
+* **Loops and modes.** Meta rules that govern the interaction.
 
 ### Choosing between variations
 

src/_includes/content/button-labels.md

@@ -1,13 +1,12 @@
 
 Buttons signal important calls to action (CTA) and help people quickly see what's the most important action they need to take on a page. Treat buttons like important or primary content, and prioritize their placement on pages as you would essential information.
 
-[Use links for secondary or less important actions](../content-style-guide/links) on a page. Likewise, for simple navigation to lead people between pages, use links instead of buttons.
-
-- Use sentence case for button labels.
-- Make button labels as short as possible.
-- Use “trigger words” that people recognize and clearly signal what will happen when they click the button.
-- Keep the character limit for button labels to 35 characters. Button labels should be as short as possible with “trigger words” that your users will recognize to clearly explain what will happen when the button is clicked (for example, "Back" or "Continue"). 
+For simple navigation to lead people between pages, use links instead of buttons.
 
+* Use sentence case for button labels (except for Button - Icon).
+* Make button labels as short as possible.
+* Use "action words" that people recognize and clearly signal what will happen when they click the button.
+* Keep the character limit for button labels to 35 characters. Button labels should be as short as possible with "trigger words" that your users will recognize to clearly explain what will happen when the button is clicked (for example, "Back" or "Continue").
 
 <div class="do-dont">
 <div class="do-dont__do">
@@ -24,8 +23,7 @@ Get started
 </div>
 </div>
 
-
-- Make it an action.
+* Make it an action.
 
 <div class="do-dont">
 <div class="do-dont__do">
@@ -42,8 +40,7 @@ Complaint filing
 </div>
 </div>
 
-- Always take users to the right level of access for the CTA.
-  -   **Like this:** “Explore VA health care” button should take you to a general health care benefits landing page like [VA health care](https://www.va.gov/health-care).
-  -   **Like this:** “Apply for VA health care” button should take you to an application page like [Apply for VA healthcare](https://www.va.gov/health-care/apply/application/introduction).
-  -   **Like this:** “Compare GI Bill benefits” button should take you right to the [GI Bill® Comparison Tool](https://www.va.gov/education/gi-bill-comparison-tool/).
-
+* Always take users to the right level of access for the CTA.
+  * **Like this:** “Explore VA health care” button should take you to a general health care benefits landing page like [VA health care](https://www.va.gov/health-care).
+  * **Like this:** “Apply for VA health care” button should take you to an application page like [Apply for VA healthcare](https://www.va.gov/health-care/apply/application/introduction).
+  * **Like this:** “Compare GI Bill benefits” button should take you right to the [GI Bill® Comparison Tool](https://www.va.gov/education/gi-bill-comparison-tool/).