uswds · thisisdano · Feb 26, 2024 · Jul 20, 2023 · Jul 21, 2023 · Sep 7, 2023
diff --git a/packages/usa-button/src/styles/_usa-button.scss b/packages/usa-button/src/styles/_usa-button.scss
@@ -11,11 +11,14 @@ $button-stroke: inset 0 0 0 units($theme-button-stroke-width);
   @include typeset($theme-button-font-family, null, 1);
   @include set-text-and-bg("primary", $context: $button-context);
   appearance: none;
+  align-items: center;
   border: 0;
   border-radius: radius($theme-button-border-radius);
   cursor: pointer;
-  display: inline-block;
+  column-gap: units($theme-button-icon-gap);
+  display: inline-flex;
   font-weight: font-weight("bold");
+  justify-content: center;
   margin-right: units(1);
   padding: units(1.5) units(2.5);
   text-align: center;
@@ -52,6 +55,10 @@ $button-stroke: inset 0 0 0 units($theme-button-stroke-width);
     @include button-disabled;
   }
 
+  .usa-icon {
+    flex-shrink: 0; // Avoid shrinking on small screens.
+  }
+
   @media (forced-colors: active) {
     &:not(.usa-button--unstyled) {
       border: $border-high-contrast;

diff --git a/packages/usa-button/src/usa-button.stories.js b/packages/usa-button/src/usa-button.stories.js
@@ -12,17 +12,22 @@ import {
   UnstyledContent,
 } from "./content";
 
+import { icons } from "../../usa-icon/src/usa-icon.json";
+
+const iconItems = icons.items;
+const iconNames = iconItems.map((item) => item.name);
+
 export default {
   title: "Components/Button",
   argTypes: {
     modifier: {
       name: "Variant",
     },
     text: {
-      name: "Text string",
+      name: "Text",
     },
     is_demo: {
-      name: "Show all button states",
+      name: "View all states",
       defaultValue: true,
       type: "boolean",
     },
@@ -32,6 +37,20 @@ export default {
       options: ["button", "reset", "submit"],
       control: { type: "radio" },
     },
+    add_icon: {
+      name: "Add icon",
+      defaultValue: false,
+      type: "boolean",
+    },
+    icon_name: {
+      name: "Icon name",
+      control: {
+        type: "select",
+        options: iconNames,
+        defaultValue: "add_circle_outline",
+      },
+      if: { arg: "add_icon" },
+    },
   },
 };
 
@@ -53,6 +72,14 @@ Base.args = BaseContent;
 export const Big = Template.bind({});
 Big.args = BigContent;
 
+export const Icon = Template.bind({});
+Icon.args = {
+  ...DefaultContent,
+  add_icon: true,
+  // Specifying name to preselect value in StorybookJS control.
+  icon_name: "add_circle_outline",
+};
+
 export const Outline = Template.bind({});
 Outline.args = OutlineContent;
 

diff --git a/packages/usa-button/src/usa-button.twig b/packages/usa-button/src/usa-button.twig
@@ -1,21 +1,45 @@
+{% macro usaButton(label, modifier, type, additional_class, additional_attributes) %}
+  <button
+    class="usa-button {{ modifier }} {{ additional_class | default("") }}"
+    type="{{ type ? type : "button" }}"
+    {{ additional_attributes }}
+  >
+    {{- label -}}
+    {% if add_icon %}{{- icon -}}{% endif %}
+  </button>
+{% endmacro %}
+
+{# Twig loader requirement for macro to work. #}
+{% import _self as button %}
+
 {% if 'usa-button--outline usa-button--inverse' in modifier %}
   <div class="bg-base-darkest padding-1" style="max-width: fit-content">
 {% endif %}
 
+{% set icon %}
+  <!-- @TODO: Allow size to be passed as a argument. -->
+  <!-- Example: usa-icon--size-{3-9} -->
+  <svg class="usa-icon" aria-hidden="true" focusable="false" role="img">
+    <use xlink:href="./img/sprite.svg#{{ icon_name | default("add_circle_outline") }}"></use>
+  </svg>
+{% endset %}
+
 {% if is_demo and 'usa-button--big' not in modifier %}
-  <button type="{{ type }}" class="usa-button {{ modifier }}">Default</button>
-  <button type="{{ type }}" class="usa-button {{ modifier }} usa-button--hover">Hover</button>
-  <button type="{{ type }}" class="usa-button {{ modifier }} usa-button--active">Active</button>
-  <button type="{{ type }}" class="usa-button {{ modifier }} usa-focus">Focus</button>
-  <button type="{{ type }}" class="usa-button {{ modifier }}" disabled>Disabled</button>
-  <button type="{{ type }}" class="usa-button {{ modifier }}" aria-disabled="true">aria-disabled</button>
-  <button type="{{ type }}" class="usa-button {{ modifier }} usa-button--unstyled">Unstyled button</button>
+  {{ button.usaButton('Default', modifier, type) }}
+  {{ button.usaButton('Hover', modifier, type, "usa-button--hover") }}
+  {{ button.usaButton('Active', modifier, type, "usa-button--active") }}
+  {{ button.usaButton('Focus', modifier, type, "usa-focus") }}
+  {{ button.usaButton('Disabled', modifier, type, null, 'disabled') }}
+  {{ button.usaButton('aria-disabled', modifier, type, null, 'aria-disabled="true"') }}
+  {{ button.usaButton('Unstyled button', modifier, type, 'usa-button--unstyled') }}
+
 {% else %}
-  <button type="{{ type }}" class="usa-button {{ modifier }}">{{ text }}</button>
+  {{ button.usaButton('Default', modifier, type) }}
+
   {% if is_demo and 'usa-button--big' in modifier %}
-    <button type="{{ type }}" class="usa-button {{ modifier }}" disabled>Disabled</button>
-    <button type="{{ type }}" class="usa-button {{ modifier }}" aria-disabled="true">aria-disabled</button>
-    <button type="{{ type }}" class="usa-button {{ modifier }} usa-button--unstyled">Unstyled button</button>
+    {{ button.usaButton('Disabled', modifier, type, null, 'disabled') }}
+    {{ button.usaButton('aria-disabled', modifier, type, null, 'aria-disabled="true"') }}
+    {{ button.usaButton('Unstyled button', modifier, type, 'usa-button--unstyled') }}
   {% endif %}
 {% endif %}
 

diff --git a/packages/uswds-core/src/styles/mixins/general/button-unstyled.scss b/packages/uswds-core/src/styles/mixins/general/button-unstyled.scss
@@ -10,9 +10,10 @@
   border-radius: 0;
   box-shadow: none;
   font-weight: font-weight("normal");
+  justify-content: normal;
+  text-align: left;
   margin: 0;
   padding: 0;
-  text-align: left;
 
   &:hover,
   &.usa-button--hover,

diff --git a/packages/uswds-core/src/styles/settings/_settings-components.scss b/packages/uswds-core/src/styles/settings/_settings-components.scss
@@ -53,8 +53,9 @@ $theme-breadcrumb-padding-x: 0 !default;
 $theme-breadcrumb-separator-color: "base" !default;
 
 // Button
-$theme-button-font-family: "ui" !default;
 $theme-button-border-radius: "md" !default;
+$theme-button-font-family: "ui" !default;
+$theme-button-icon-gap: 1 !default;
 $theme-button-small-width: 6 !default;
 $theme-button-stroke-width: 2px !default;