From ac03c1ccb1e8a40beb42e360876ad9a505f63e71 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Thu, 14 May 2026 09:10:23 -0500
Subject: [PATCH 01/10] Move sass to devDeps, fix banner toggle, spacing

Move "sass" from dependencies to devDependencies in package.json to reflect it's a build-time tool. Update UsaBanner to use Lit's boolean attribute binding (?hidden) driven by isOpen and remove the manual DOM attribute toggle in toggle(). Correct spacing token "05" from .025rem to .25rem in tokens/dimension/spacing.json.
---
 package-lock.json                  | 41 ++++++++++++++++++++++--------
 package.json                       |  4 +--
 src/components/usa-banner/index.ts |  6 +----
 tokens/dimension/spacing.json      |  2 +-
 4 files changed, 35 insertions(+), 18 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index a303a260..e89c30bf 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,8 +9,7 @@
       "version": "1.0.0-alpha.6",
       "dependencies": {
         "@uswds/uswds": "^3.13.0",
-        "lit": "^3.3.2",
-        "sass": "^1.94.0"
+        "lit": "^3.3.2"
       },
       "devDependencies": {
         "@changesets/cli": "^2.29.7",
@@ -45,6 +44,7 @@
         "jsdom": "^27.2.0",
         "lightningcss": "^1.30.2",
         "prettier": "^3.6.2",
+        "sass": "^1.94.0",
         "serve-static": "^2.2.0",
         "shadow-dom-testing-library": "^1.13.1",
         "storybook": "^10.2.13",
@@ -3709,6 +3709,7 @@
       "version": "2.5.1",
       "resolved": "https://registry.npmjs.org/@parcel/watcher/-/watcher-2.5.1.tgz",
       "integrity": "sha512-dfUnCxiN9H4ap84DvD2ubjw+3vUNpstxa0TneY/Paat8a3R4uQZDLSvWjmznAY/DoahqTHl9V46HF/Zs3F29pg==",
+      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
@@ -3748,6 +3749,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3768,6 +3770,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3788,6 +3791,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3808,6 +3812,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3828,6 +3833,7 @@
       "cpu": [
         "arm"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3848,6 +3854,7 @@
       "cpu": [
         "arm"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3868,6 +3875,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3888,6 +3896,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3908,6 +3917,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3928,6 +3938,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3948,6 +3959,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3968,6 +3980,7 @@
       "cpu": [
         "ia32"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -3988,6 +4001,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
@@ -7243,7 +7257,7 @@
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
       "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "fill-range": "^7.1.1"
@@ -8350,6 +8364,7 @@
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-1.0.3.tgz",
       "integrity": "sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==",
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "bin": {
@@ -9329,7 +9344,7 @@
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
       "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "to-regex-range": "^5.0.1"
@@ -10239,6 +10254,7 @@
       "version": "5.1.5",
       "resolved": "https://registry.npmjs.org/immutable/-/immutable-5.1.5.tgz",
       "integrity": "sha512-t7xcm2siw+hlUM68I+UEOK+z84RzmN59as9DZ7P1l0994DKUWV7UXBMQZVxaoMSRQ+PBZbHCOoBt7a2wxOMt+A==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/import-fresh": {
@@ -10430,7 +10446,7 @@
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
       "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.10.0"
@@ -10479,7 +10495,7 @@
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
       "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "is-extglob": "^2.1.1"
@@ -10528,7 +10544,7 @@
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
       "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=0.12.0"
@@ -12808,7 +12824,7 @@
       "version": "4.0.8",
       "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
       "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "braces": "^3.0.3",
@@ -13042,6 +13058,7 @@
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
       "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "dev": true,
       "license": "MIT",
       "optional": true
     },
@@ -13949,7 +13966,7 @@
       "version": "2.3.2",
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
       "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=8.6"
@@ -14945,6 +14962,7 @@
       "version": "1.94.0",
       "resolved": "https://registry.npmjs.org/sass/-/sass-1.94.0.tgz",
       "integrity": "sha512-Dqh7SiYcaFtdv5Wvku6QgS5IGPm281L+ZtVD1U2FJa7Q0EFRlq8Z3sjYtz6gYObsYThUOz9ArwFqPZx+1azILQ==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "chokidar": "^4.0.0",
@@ -14981,6 +14999,7 @@
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
       "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "readdirp": "^4.0.1"
@@ -14996,6 +15015,7 @@
       "version": "4.1.2",
       "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
       "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">= 14.18.0"
@@ -15339,6 +15359,7 @@
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
       "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=0.10.0"
@@ -16436,7 +16457,7 @@
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
       "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
-      "devOptional": true,
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "is-number": "^7.0.0"
diff --git a/package.json b/package.json
index cb1cec4a..e3e1733e 100644
--- a/package.json
+++ b/package.json
@@ -59,8 +59,7 @@
   },
   "dependencies": {
     "@uswds/uswds": "^3.13.0",
-    "lit": "^3.3.2",
-    "sass": "^1.94.0"
+    "lit": "^3.3.2"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.7",
@@ -95,6 +94,7 @@
     "jsdom": "^27.2.0",
     "lightningcss": "^1.30.2",
     "prettier": "^3.6.2",
+    "sass": "^1.94.0",
     "serve-static": "^2.2.0",
     "shadow-dom-testing-library": "^1.13.1",
     "storybook": "^10.2.13",
diff --git a/src/components/usa-banner/index.ts b/src/components/usa-banner/index.ts
index b5178909..dec3bfdd 100644
--- a/src/components/usa-banner/index.ts
+++ b/src/components/usa-banner/index.ts
@@ -128,10 +128,6 @@ export class UsaBanner extends LitElement {
 
   toggle() {
     this.isOpen = !this.isOpen;
-    const contentElement = this.shadowRoot?.querySelector(".content");
-    if (contentElement) {
-      contentElement.toggleAttribute("hidden");
-    }
   }
 
   constructor() {
@@ -265,7 +261,7 @@ export class UsaBanner extends LitElement {
               </button>
             </div>
           </header>
-          <div class="content usa-accordion__content" hidden>
+          <div class="content usa-accordion__content" ?hidden="${!this.isOpen}">
             <div class="grid-row grid-gap-lg">
               <div class="guidance tablet:grid-col-6">
                 ${this.domainTemplate(tld)}
diff --git a/tokens/dimension/spacing.json b/tokens/dimension/spacing.json
index 97962b5e..ad6087b0 100644
--- a/tokens/dimension/spacing.json
+++ b/tokens/dimension/spacing.json
@@ -1,7 +1,7 @@
 {
   "spacing": {
     "05": {
-      "$value": { "value": ".025", "unit": "rem" }
+      "$value": { "value": ".25", "unit": "rem" }
     },
     "1": {
       "$value": { "value": ".5", "unit": "rem" }

From a2f2fa5324e28847dc805b1fedb735660b806080 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Mon, 18 May 2026 13:23:12 -0500
Subject: [PATCH 02/10] Add usa-alert component

Introduce a new UsaAlert web component (LitElement) with status variants (info, warning, error, success, emergency), slim, no-icon, and closeable options. Ship styles, Storybook stories, and unit tests; dispatches a close event and uses role=alert/status for accessibility. Also register/export the component, add a Vite build entry with size limit, and update custom-elements.json and a changeset.
---
 .changeset/add-usa-alert-component.md         |   5 +
 config/vite.config.ts                         |   5 +
 custom-elements.json                          | 230 +++++++++++++++++
 src/components/index.ts                       |   3 +-
 src/components/usa-alert/index.ts             | 136 +++++++++++
 src/components/usa-alert/usa-alert.css        | 231 ++++++++++++++++++
 src/components/usa-alert/usa-alert.spec.ts    | 198 +++++++++++++++
 src/components/usa-alert/usa-alert.stories.ts | 128 ++++++++++
 8 files changed, 935 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/add-usa-alert-component.md
 create mode 100644 src/components/usa-alert/index.ts
 create mode 100644 src/components/usa-alert/usa-alert.css
 create mode 100644 src/components/usa-alert/usa-alert.spec.ts
 create mode 100644 src/components/usa-alert/usa-alert.stories.ts

diff --git a/.changeset/add-usa-alert-component.md b/.changeset/add-usa-alert-component.md
new file mode 100644
index 00000000..74fe6e3a
--- /dev/null
+++ b/.changeset/add-usa-alert-component.md
@@ -0,0 +1,5 @@
+---
+"@uswds/elements": minor
+---
+
+Add usa-alert component with support for info, warning, error, success, and emergency statuses. Includes slim, no-icon, and closeable variants.
diff --git a/config/vite.config.ts b/config/vite.config.ts
index 8317686b..1719657a 100644
--- a/config/vite.config.ts
+++ b/config/vite.config.ts
@@ -22,6 +22,11 @@ const entries: Array<Entry> = [
     path: "src/components/usa-banner/index.ts",
     sizeLimit: "10 kB",
   },
+  {
+    name: "components/usa-alert",
+    path: "src/components/usa-alert/index.ts",
+    sizeLimit: "3 kB",
+  },
   {
     name: "components/usa-link",
     path: "src/components/usa-link/index.js",
diff --git a/custom-elements.json b/custom-elements.json
index c84f0585..22484474 100644
--- a/custom-elements.json
+++ b/custom-elements.json
@@ -7,6 +7,14 @@
       "path": "src/components/index.ts",
       "declarations": [],
       "exports": [
+        {
+          "kind": "js",
+          "name": "UsaAlert",
+          "declaration": {
+            "name": "UsaAlert",
+            "module": "src/components/index.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "UsaLink",
@@ -25,6 +33,228 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/usa-alert/index.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "UsaAlert",
+          "cssProperties": [
+            {
+              "description": "Override background color.",
+              "name": "--usa-alert-background-color"
+            },
+            {
+              "description": "Override left border color.",
+              "name": "--usa-alert-border-color"
+            },
+            {
+              "description": "Override icon color.",
+              "name": "--usa-alert-icon-color"
+            },
+            {
+              "description": "Override icon size.",
+              "name": "--usa-alert-icon-size"
+            },
+            {
+              "description": "Override horizontal padding.",
+              "name": "--usa-alert-padding-x"
+            },
+            {
+              "description": "Override vertical padding.",
+              "name": "--usa-alert-padding-y"
+            },
+            {
+              "description": "Override font family.",
+              "name": "--usa-alert-font-family"
+            },
+            {
+              "description": "Override text color.",
+              "name": "--usa-alert-text-color"
+            }
+          ],
+          "slots": [
+            {
+              "description": "The alert heading (use an h-element: h2, h3, etc.).",
+              "name": "headline"
+            },
+            {
+              "description": "Default slot for alert body content.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "status",
+              "privacy": "public",
+              "type": {
+                "text": "AlertStatus"
+              },
+              "default": "\"info\"",
+              "attribute": "status",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "slim",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "attribute": "slim",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "noIcon",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "attribute": "no-icon",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "closeable",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "attribute": "closeable",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "closeLabel",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"Close alert\"",
+              "attribute": "close-label"
+            },
+            {
+              "kind": "field",
+              "name": "_visible",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "attribute": "_visible"
+            },
+            {
+              "kind": "field",
+              "name": "_role",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "_handleClose",
+              "privacy": "private"
+            }
+          ],
+          "events": [
+            {
+              "name": "close",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Dispatched when the close button is clicked."
+            }
+          ],
+          "attributes": [
+            {
+              "type": {
+                "text": "AlertStatus"
+              },
+              "description": "Determines the icon and border/background color.",
+              "name": "status",
+              "default": "\"info\"",
+              "fieldName": "status",
+              "propName": "status"
+            },
+            {
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Displays the slim variation (smaller icon, no heading).",
+              "name": "slim",
+              "default": "false",
+              "fieldName": "slim",
+              "propName": "slim"
+            },
+            {
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Hides the status icon.",
+              "name": "no-icon",
+              "default": "false",
+              "fieldName": "noIcon",
+              "propName": "noIcon"
+            },
+            {
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Shows a close button.",
+              "name": "closeable",
+              "default": "false",
+              "fieldName": "closeable",
+              "propName": "closeable"
+            },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "Aria-label for the close button. Defaults to \"Close alert\".",
+              "name": "close-label",
+              "default": "\"Close alert\"",
+              "fieldName": "closeLabel",
+              "propName": "closeLabel"
+            },
+            {
+              "name": "_visible",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "fieldName": "_visible",
+              "propName": "_visible"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "usa-alert",
+          "customElement": true,
+          "summary": "Displays important messages to the user with contextual status styling."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UsaAlert",
+          "declaration": {
+            "name": "UsaAlert",
+            "module": "src/components/usa-alert/index.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/usa-banner/index.ts",
diff --git a/src/components/index.ts b/src/components/index.ts
index a42c8674..17a270e8 100644
--- a/src/components/index.ts
+++ b/src/components/index.ts
@@ -1,4 +1,5 @@
+import { UsaAlert } from "./usa-alert";
 import { UsaLink } from "./usa-link";
 import { UsaBanner } from "./usa-banner";
 
-export { UsaLink, UsaBanner };
+export { UsaAlert, UsaLink, UsaBanner };
diff --git a/src/components/usa-alert/index.ts b/src/components/usa-alert/index.ts
new file mode 100644
index 00000000..171022d7
--- /dev/null
+++ b/src/components/usa-alert/index.ts
@@ -0,0 +1,136 @@
+import { LitElement, html, css, unsafeCSS, nothing } from "lit";
+import { classMap } from "lit/directives/class-map.js";
+
+import styles from "./usa-alert.css";
+import iconClose from "../../shared/icons/close.svg";
+import { defineCustomElement } from "../../utils";
+
+const VALID_STATUSES = [
+  "info",
+  "warning",
+  "error",
+  "success",
+  "emergency",
+] as const;
+
+type AlertStatus = (typeof VALID_STATUSES)[number];
+
+/**
+ * @summary Displays important messages to the user with contextual status styling.
+ *
+ * @attribute {"info" | "warning" | "error" | "success" | "emergency"} status - Determines the icon and border/background color.
+ * @attribute {boolean} slim - Displays the slim variation (smaller icon, no heading).
+ * @attribute {boolean} no-icon - Hides the status icon.
+ * @attribute {boolean} closeable - Shows a close button.
+ * @attribute {string} close-label - Aria-label for the close button. Defaults to "Close alert".
+ *
+ * @cssprop --usa-alert-background-color - Override background color.
+ * @cssprop --usa-alert-border-color - Override left border color.
+ * @cssprop --usa-alert-icon-color - Override icon color.
+ * @cssprop --usa-alert-icon-size - Override icon size.
+ * @cssprop --usa-alert-padding-x - Override horizontal padding.
+ * @cssprop --usa-alert-padding-y - Override vertical padding.
+ * @cssprop --usa-alert-font-family - Override font family.
+ * @cssprop --usa-alert-text-color - Override text color.
+ *
+ * @slot headline - The alert heading (use an h-element: h2, h3, etc.).
+ * @slot - Default slot for alert body content.
+ *
+ * @fires close - Dispatched when the close button is clicked.
+ *
+ * @element usa-alert
+ */
+export class UsaAlert extends LitElement {
+  static properties = {
+    status: { type: String, reflect: true },
+    slim: { type: Boolean, reflect: true },
+    noIcon: { type: Boolean, attribute: "no-icon", reflect: true },
+    closeable: { type: Boolean, reflect: true },
+    closeLabel: { type: String, attribute: "close-label" },
+    _visible: { state: true },
+  };
+
+  status!: AlertStatus;
+  slim!: boolean;
+  noIcon!: boolean;
+  closeable!: boolean;
+  closeLabel!: string;
+  _visible!: boolean;
+
+  constructor() {
+    super();
+    this.status = "info";
+    this.slim = false;
+    this.noIcon = false;
+    this.closeable = false;
+    this.closeLabel = "Close alert";
+    this._visible = true;
+  }
+
+  private get _role(): string {
+    if (
+      this.status === "error" ||
+      this.status === "emergency" ||
+      this.status === "warning"
+    ) {
+      return "alert";
+    }
+    return "status";
+  }
+
+  private _handleClose() {
+    this.dispatchEvent(
+      new CustomEvent("close", { bubbles: true, composed: true }),
+    );
+    this._visible = false;
+  }
+
+  static styles = [
+    css`
+      :host {
+        --usa-icon-close: url("${unsafeCSS(iconClose)}");
+      }
+    `,
+    styles,
+  ];
+
+  render() {
+    if (!this._visible) {
+      return nothing;
+    }
+
+    const status = VALID_STATUSES.includes(this.status) ? this.status : "info";
+
+    const classes = {
+      "usa-alert": true,
+      [`usa-alert--${status}`]: true,
+      "usa-alert--slim": this.slim,
+      "usa-alert--no-icon": this.noIcon,
+    };
+
+    return html`
+      <div class="${classMap(classes)}" role="${this._role}">
+        <div class="usa-alert__body">
+          ${!this.slim ? html`<slot name="headline"></slot>` : null}
+          <div class="usa-alert__text">
+            <slot></slot>
+          </div>
+        </div>
+        ${this.closeable
+          ? html`
+              <button
+                class="usa-alert__close"
+                type="button"
+                aria-label="${this.closeLabel}"
+                @click="${this._handleClose}"
+              >
+                <span class="usa-alert__close-icon" aria-hidden="true"></span>
+              </button>
+            `
+          : null}
+      </div>
+    `;
+  }
+}
+
+defineCustomElement("usa-alert", UsaAlert);
diff --git a/src/components/usa-alert/usa-alert.css b/src/components/usa-alert/usa-alert.css
new file mode 100644
index 00000000..b56b91af
--- /dev/null
+++ b/src/components/usa-alert/usa-alert.css
@@ -0,0 +1,231 @@
+:host {
+  --usa-alert-font-family:
+    system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica,
+    Arial, sans-serif;
+  --usa-alert-text-color: var(--usa-color-base-darkest, #1b1b1b);
+  --usa-alert-padding-x: 1.25rem;
+  --usa-alert-padding-y: 1rem;
+  --usa-alert-icon-size: 2rem;
+  --usa-alert-border-width: 0.25rem;
+
+  /** Status colors — info */
+  --usa-alert-info-background: var(--usa-color-info-lighter, #e7f6f8);
+  --usa-alert-info-border: var(--usa-color-info, #00bde3);
+  --usa-alert-info-icon: var(--usa-color-info, #00bde3);
+
+  /** Status colors — warning */
+  --usa-alert-warning-background: var(--usa-color-warning-lighter, #faf3d1);
+  --usa-alert-warning-border: var(--usa-color-warning, #ffbe2e);
+  --usa-alert-warning-icon: var(--usa-color-warning, #ffbe2e);
+
+  /** Status colors — error */
+  --usa-alert-error-background: var(--usa-color-error-lighter, #f4e3db);
+  --usa-alert-error-border: var(--usa-color-error, #d54309);
+  --usa-alert-error-icon: var(--usa-color-error, #d54309);
+
+  /** Status colors — success */
+  --usa-alert-success-background: var(--usa-color-success-lighter, #ecf3ec);
+  --usa-alert-success-border: var(--usa-color-success, #00a91c);
+  --usa-alert-success-icon: var(--usa-color-success, #00a91c);
+
+  /** Status colors — emergency */
+  --usa-alert-emergency-background: var(--usa-color-emergency, #9c3d10);
+  --usa-alert-emergency-border: var(--usa-color-emergency-dark, #332d29);
+  --usa-alert-emergency-icon: #fff;
+
+  display: block;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+.usa-alert {
+  background-color: var(
+    --usa-alert-background-color,
+    var(--usa-alert-info-background)
+  );
+  border-left: var(--usa-alert-border-width) solid
+    var(--usa-alert-border-color, var(--usa-alert-info-border));
+  color: var(--usa-alert-text-color);
+  font-family: var(--usa-alert-font-family);
+  position: relative;
+}
+
+/** Status variants */
+.usa-alert--info {
+  --usa-alert-background-color: var(--usa-alert-info-background);
+  --usa-alert-border-color: var(--usa-alert-info-border);
+  --usa-alert-icon-color: var(--usa-alert-info-icon);
+}
+
+.usa-alert--warning {
+  --usa-alert-background-color: var(--usa-alert-warning-background);
+  --usa-alert-border-color: var(--usa-alert-warning-border);
+  --usa-alert-icon-color: var(--usa-alert-warning-icon);
+}
+
+.usa-alert--error {
+  --usa-alert-background-color: var(--usa-alert-error-background);
+  --usa-alert-border-color: var(--usa-alert-error-border);
+  --usa-alert-icon-color: var(--usa-alert-error-icon);
+}
+
+.usa-alert--success {
+  --usa-alert-background-color: var(--usa-alert-success-background);
+  --usa-alert-border-color: var(--usa-alert-success-border);
+  --usa-alert-icon-color: var(--usa-alert-success-icon);
+}
+
+.usa-alert--emergency {
+  --usa-alert-background-color: var(--usa-alert-emergency-background);
+  --usa-alert-border-color: var(--usa-alert-emergency-border);
+  --usa-alert-icon-color: var(--usa-alert-emergency-icon);
+
+  & .usa-alert__body {
+    color: #fff;
+  }
+}
+
+/** Alert body */
+.usa-alert__body {
+  padding: var(--usa-alert-padding-y) var(--usa-alert-padding-x);
+  padding-left: calc(
+    var(--usa-alert-padding-x) + var(--usa-alert-icon-size) + 0.75rem
+  );
+  position: relative;
+
+  &::before {
+    background-color: var(--usa-alert-icon-color);
+    content: "";
+    display: block;
+    height: var(--usa-alert-icon-size);
+    left: var(--usa-alert-padding-x);
+    mask-position: center;
+    mask-repeat: no-repeat;
+    mask-size: var(--usa-alert-icon-size);
+    position: absolute;
+    top: var(--usa-alert-padding-y);
+    width: var(--usa-alert-icon-size);
+  }
+}
+
+/** Status icons via CSS mask */
+.usa-alert--info .usa-alert__body::before {
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-6h2v6zm0-8h-2V7h2v2z'/%3E%3C/svg%3E");
+}
+
+.usa-alert--warning .usa-alert__body::before {
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z'/%3E%3C/svg%3E");
+}
+
+.usa-alert--error .usa-alert__body::before,
+.usa-alert--emergency .usa-alert__body::before {
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z'/%3E%3C/svg%3E");
+}
+
+.usa-alert--success .usa-alert__body::before {
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z'/%3E%3C/svg%3E");
+}
+
+/** No icon */
+.usa-alert--no-icon .usa-alert__body {
+  padding-left: var(--usa-alert-padding-x);
+
+  &::before {
+    display: none;
+  }
+}
+
+/** Slim */
+.usa-alert--slim .usa-alert__body {
+  padding: 0.5rem var(--usa-alert-padding-x);
+  padding-left: calc(var(--usa-alert-padding-x) + 1.5rem + 0.5rem);
+
+  &::before {
+    height: 1.5rem;
+    mask-size: 1.5rem;
+    top: 0.5rem;
+    width: 1.5rem;
+  }
+}
+
+.usa-alert--slim.usa-alert--no-icon .usa-alert__body {
+  padding-left: var(--usa-alert-padding-x);
+}
+
+/** Headline slot */
+::slotted([slot="headline"]) {
+  font-size: 1.33rem;
+  font-weight: 700;
+  line-height: 1.2;
+  margin: 0 0 0.5rem;
+}
+
+.usa-alert--emergency ::slotted([slot="headline"]) {
+  color: #fff;
+}
+
+/** Alert text */
+.usa-alert__text {
+  font-size: 1rem;
+  line-height: 1.5;
+  margin: 0;
+}
+
+.usa-alert__text ::slotted(*) {
+  margin: 0;
+}
+
+.usa-alert__text ::slotted(:not(:first-child)) {
+  margin-top: 0.5rem;
+}
+
+/** Close button */
+.usa-alert__close {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  cursor: pointer;
+  display: block;
+  padding: 0.5rem;
+  position: absolute;
+  right: 0.5rem;
+  top: 0.5rem;
+}
+
+.usa-alert__close:focus-visible {
+  outline: 2px solid var(--usa-color-blue-vivid-40, #2491ff);
+  outline-offset: 2px;
+}
+
+.usa-alert__close-icon {
+  background-color: var(--usa-alert-text-color);
+  display: block;
+  height: 1.5rem;
+  mask-image: var(--usa-icon-close);
+  mask-position: center;
+  mask-repeat: no-repeat;
+  mask-size: 1.5rem;
+  width: 1.5rem;
+}
+
+.usa-alert--emergency .usa-alert__close-icon {
+  background-color: #fff;
+}
+
+/** High contrast mode */
+@media (forced-colors: active) {
+  .usa-alert {
+    border: 1px solid ButtonText;
+    border-left-width: var(--usa-alert-border-width);
+  }
+
+  .usa-alert__body::before {
+    background-color: ButtonText;
+  }
+
+  .usa-alert__close-icon {
+    background-color: ButtonText;
+  }
+}
diff --git a/src/components/usa-alert/usa-alert.spec.ts b/src/components/usa-alert/usa-alert.spec.ts
new file mode 100644
index 00000000..83ae2d56
--- /dev/null
+++ b/src/components/usa-alert/usa-alert.spec.ts
@@ -0,0 +1,198 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { LitElement } from "lit";
+
+import "./index.js";
+
+function getAlert(): HTMLElement & LitElement {
+  const alert = document.body.querySelector("usa-alert");
+  if (!alert) throw new Error("usa-alert element not found");
+  return alert as HTMLElement & LitElement;
+}
+
+function getShadow(): ShadowRoot {
+  const shadow = getAlert().shadowRoot;
+  if (!shadow) throw new Error("usa-alert shadowRoot not found");
+  return shadow;
+}
+
+describe("usa-alert component", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <usa-alert>
+        <h3 slot="headline">Alert heading</h3>
+        <p>Alert body content.</p>
+      </usa-alert>
+    `;
+  });
+
+  it("renders with default info status", () => {
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.classList.contains("usa-alert--info")).toBe(true);
+  });
+
+  it("has role=status for info alerts", () => {
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.getAttribute("role")).toBe("status");
+  });
+
+  it("renders headline slot", () => {
+    const slot = getShadow().querySelector(
+      'slot[name="headline"]',
+    ) as HTMLSlotElement;
+    expect(slot).not.toBeNull();
+    const assigned = slot?.assignedElements();
+    expect(assigned?.[0]?.textContent).toBe("Alert heading");
+  });
+
+  it("renders default slot content", () => {
+    const slot = getShadow().querySelector(
+      "slot:not([name])",
+    ) as HTMLSlotElement;
+    expect(slot).not.toBeNull();
+    const assigned = slot?.assignedElements();
+    expect(assigned?.[0]?.textContent).toBe("Alert body content.");
+  });
+});
+
+describe("status variants", () => {
+  const statuses = ["info", "warning", "error", "success", "emergency"];
+
+  statuses.forEach((status) => {
+    it(`renders ${status} variant`, async () => {
+      document.body.innerHTML = `<usa-alert status="${status}"><p>Test</p></usa-alert>`;
+      await getAlert().updateComplete;
+      const alertDiv = getShadow().querySelector(".usa-alert");
+      expect(alertDiv?.classList.contains(`usa-alert--${status}`)).toBe(true);
+    });
+  });
+
+  it("falls back to info for invalid status", async () => {
+    document.body.innerHTML = `<usa-alert status="invalid"><p>Test</p></usa-alert>`;
+    await getAlert().updateComplete;
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.classList.contains("usa-alert--info")).toBe(true);
+  });
+});
+
+describe("ARIA roles", () => {
+  it("uses role=status for info", async () => {
+    document.body.innerHTML = `<usa-alert status="info"><p>Test</p></usa-alert>`;
+    await getAlert().updateComplete;
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.getAttribute("role")).toBe("status");
+  });
+
+  it("uses role=status for success", async () => {
+    document.body.innerHTML = `<usa-alert status="success"><p>Test</p></usa-alert>`;
+    await getAlert().updateComplete;
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.getAttribute("role")).toBe("status");
+  });
+
+  it("uses role=alert for error", async () => {
+    document.body.innerHTML = `<usa-alert status="error"><p>Test</p></usa-alert>`;
+    await getAlert().updateComplete;
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.getAttribute("role")).toBe("alert");
+  });
+
+  it("uses role=alert for warning", async () => {
+    document.body.innerHTML = `<usa-alert status="warning"><p>Test</p></usa-alert>`;
+    await getAlert().updateComplete;
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.getAttribute("role")).toBe("alert");
+  });
+
+  it("uses role=alert for emergency", async () => {
+    document.body.innerHTML = `<usa-alert status="emergency"><p>Test</p></usa-alert>`;
+    await getAlert().updateComplete;
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.getAttribute("role")).toBe("alert");
+  });
+});
+
+describe("slim variant", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<usa-alert slim><p>Slim alert</p></usa-alert>`;
+  });
+
+  it("applies slim class", () => {
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.classList.contains("usa-alert--slim")).toBe(true);
+  });
+
+  it("does not render headline slot when slim", () => {
+    const slot = getShadow().querySelector('slot[name="headline"]');
+    expect(slot).toBeNull();
+  });
+});
+
+describe("no-icon variant", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<usa-alert no-icon><p>No icon</p></usa-alert>`;
+  });
+
+  it("applies no-icon class", () => {
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv?.classList.contains("usa-alert--no-icon")).toBe(true);
+  });
+});
+
+describe("closeable", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<usa-alert closeable><p>Closeable alert</p></usa-alert>`;
+  });
+
+  it("renders close button", () => {
+    const btn = getShadow().querySelector(".usa-alert__close");
+    expect(btn).not.toBeNull();
+  });
+
+  it("has correct default aria-label", () => {
+    const btn = getShadow().querySelector(".usa-alert__close");
+    expect(btn?.getAttribute("aria-label")).toBe("Close alert");
+  });
+
+  it("dispatches close event on click", async () => {
+    const handler = vi.fn();
+    getAlert().addEventListener("close", handler);
+
+    const btn = getShadow().querySelector(
+      ".usa-alert__close",
+    ) as HTMLButtonElement;
+    btn.click();
+
+    expect(handler).toHaveBeenCalledOnce();
+  });
+
+  it("hides alert after close", async () => {
+    const btn = getShadow().querySelector(
+      ".usa-alert__close",
+    ) as HTMLButtonElement;
+    btn.click();
+
+    // Wait for Lit reactive update
+    await getAlert().updateComplete;
+
+    const alertDiv = getShadow().querySelector(".usa-alert");
+    expect(alertDiv).toBeNull();
+  });
+
+  it("supports custom close-label", async () => {
+    document.body.innerHTML = `<usa-alert closeable close-label="Dismiss warning"><p>Test</p></usa-alert>`;
+    await getAlert().updateComplete;
+    const btn = getShadow().querySelector(".usa-alert__close");
+    expect(btn?.getAttribute("aria-label")).toBe("Dismiss warning");
+  });
+});
+
+describe("does not render close button when not closeable", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<usa-alert><p>Not closeable</p></usa-alert>`;
+  });
+
+  it("has no close button", () => {
+    const btn = getShadow().querySelector(".usa-alert__close");
+    expect(btn).toBeNull();
+  });
+});
diff --git a/src/components/usa-alert/usa-alert.stories.ts b/src/components/usa-alert/usa-alert.stories.ts
new file mode 100644
index 00000000..79ded184
--- /dev/null
+++ b/src/components/usa-alert/usa-alert.stories.ts
@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from "@storybook/web-components-vite";
+import { html } from "lit";
+import "./index.js";
+
+const meta: Meta = {
+  title: "Components/Alert",
+  component: "usa-alert",
+  tags: ["autodocs", "alpha"],
+  argTypes: {
+    status: {
+      control: "select",
+      options: ["info", "warning", "error", "success", "emergency"],
+    },
+    slim: { control: "boolean" },
+    "no-icon": { control: "boolean" },
+    closeable: { control: "boolean" },
+    "close-label": { control: "text" },
+  },
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const Info: Story = {
+  render: () => html`
+    <usa-alert status="info">
+      <h3 slot="headline">Informative status</h3>
+      <p>An alert with contextual information for the user.</p>
+    </usa-alert>
+  `,
+};
+
+export const Warning: Story = {
+  render: () => html`
+    <usa-alert status="warning">
+      <h3 slot="headline">Warning status</h3>
+      <p>An alert that warns the user about something important.</p>
+    </usa-alert>
+  `,
+};
+
+export const Error: Story = {
+  render: () => html`
+    <usa-alert status="error">
+      <h3 slot="headline">Error status</h3>
+      <p>An alert indicating an error has occurred.</p>
+    </usa-alert>
+  `,
+};
+
+export const Success: Story = {
+  render: () => html`
+    <usa-alert status="success">
+      <h3 slot="headline">Success status</h3>
+      <p>An alert indicating a successful action.</p>
+    </usa-alert>
+  `,
+};
+
+export const Emergency: Story = {
+  render: () => html`
+    <usa-alert status="emergency">
+      <h3 slot="headline">Emergency status</h3>
+      <p>An alert for emergency communications.</p>
+    </usa-alert>
+  `,
+};
+
+export const Slim: Story = {
+  render: () => html`
+    <usa-alert status="info" slim>
+      <p>A slim alert without a heading.</p>
+    </usa-alert>
+  `,
+};
+
+export const SlimWarning: Story = {
+  render: () => html`
+    <usa-alert status="warning" slim>
+      <p>A slim warning alert.</p>
+    </usa-alert>
+  `,
+};
+
+export const NoIcon: Story = {
+  render: () => html`
+    <usa-alert status="info" no-icon>
+      <h3 slot="headline">No icon</h3>
+      <p>An alert without the status icon.</p>
+    </usa-alert>
+  `,
+};
+
+export const Closeable: Story = {
+  render: () => html`
+    <usa-alert status="info" closeable>
+      <h3 slot="headline">Closeable alert</h3>
+      <p>This alert can be dismissed by clicking the close button.</p>
+    </usa-alert>
+  `,
+};
+
+export const AllVariants: Story = {
+  render: () => html`
+    <div style="display: flex; flex-direction: column; gap: 1rem;">
+      <usa-alert status="info">
+        <h3 slot="headline">Informative status</h3>
+        <p>An informational alert.</p>
+      </usa-alert>
+      <usa-alert status="warning">
+        <h3 slot="headline">Warning status</h3>
+        <p>A warning alert.</p>
+      </usa-alert>
+      <usa-alert status="error">
+        <h3 slot="headline">Error status</h3>
+        <p>An error alert.</p>
+      </usa-alert>
+      <usa-alert status="success">
+        <h3 slot="headline">Success status</h3>
+        <p>A success alert.</p>
+      </usa-alert>
+      <usa-alert status="emergency">
+        <h3 slot="headline">Emergency status</h3>
+        <p>An emergency alert.</p>
+      </usa-alert>
+    </div>
+  `,
+};

From 5f50de258759e604042a7e295c18f84ab8ee3ca7 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Tue, 19 May 2026 08:54:51 -0500
Subject: [PATCH 03/10] Use updateComplete helper in usa-alert tests

Introduce an async updateComplete() helper that awaits getAlert().updateComplete in src/components/usa-alert/usa-alert.spec.ts, and replace repeated await getAlert().updateComplete calls with await updateComplete() to reduce duplication and improve test readability/maintainability.
---
 src/components/usa-alert/usa-alert.spec.ts | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/src/components/usa-alert/usa-alert.spec.ts b/src/components/usa-alert/usa-alert.spec.ts
index 83ae2d56..a55f1297 100644
--- a/src/components/usa-alert/usa-alert.spec.ts
+++ b/src/components/usa-alert/usa-alert.spec.ts
@@ -15,6 +15,10 @@ function getShadow(): ShadowRoot {
   return shadow;
 }
 
+async function updateComplete(): Promise<void> {
+  await getAlert().updateComplete;
+}
+
 describe("usa-alert component", () => {
   beforeEach(() => {
     document.body.innerHTML = `
@@ -60,7 +64,7 @@ describe("status variants", () => {
   statuses.forEach((status) => {
     it(`renders ${status} variant`, async () => {
       document.body.innerHTML = `<usa-alert status="${status}"><p>Test</p></usa-alert>`;
-      await getAlert().updateComplete;
+      await updateComplete();
       const alertDiv = getShadow().querySelector(".usa-alert");
       expect(alertDiv?.classList.contains(`usa-alert--${status}`)).toBe(true);
     });
@@ -68,7 +72,7 @@ describe("status variants", () => {
 
   it("falls back to info for invalid status", async () => {
     document.body.innerHTML = `<usa-alert status="invalid"><p>Test</p></usa-alert>`;
-    await getAlert().updateComplete;
+    await updateComplete();
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.classList.contains("usa-alert--info")).toBe(true);
   });
@@ -77,35 +81,35 @@ describe("status variants", () => {
 describe("ARIA roles", () => {
   it("uses role=status for info", async () => {
     document.body.innerHTML = `<usa-alert status="info"><p>Test</p></usa-alert>`;
-    await getAlert().updateComplete;
+    await updateComplete();
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.getAttribute("role")).toBe("status");
   });
 
   it("uses role=status for success", async () => {
     document.body.innerHTML = `<usa-alert status="success"><p>Test</p></usa-alert>`;
-    await getAlert().updateComplete;
+    await updateComplete();
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.getAttribute("role")).toBe("status");
   });
 
   it("uses role=alert for error", async () => {
     document.body.innerHTML = `<usa-alert status="error"><p>Test</p></usa-alert>`;
-    await getAlert().updateComplete;
+    await updateComplete();
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.getAttribute("role")).toBe("alert");
   });
 
   it("uses role=alert for warning", async () => {
     document.body.innerHTML = `<usa-alert status="warning"><p>Test</p></usa-alert>`;
-    await getAlert().updateComplete;
+    await updateComplete();
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.getAttribute("role")).toBe("alert");
   });
 
   it("uses role=alert for emergency", async () => {
     document.body.innerHTML = `<usa-alert status="emergency"><p>Test</p></usa-alert>`;
-    await getAlert().updateComplete;
+    await updateComplete();
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.getAttribute("role")).toBe("alert");
   });
@@ -172,7 +176,7 @@ describe("closeable", () => {
     btn.click();
 
     // Wait for Lit reactive update
-    await getAlert().updateComplete;
+    await updateComplete();
 
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv).toBeNull();
@@ -180,7 +184,7 @@ describe("closeable", () => {
 
   it("supports custom close-label", async () => {
     document.body.innerHTML = `<usa-alert closeable close-label="Dismiss warning"><p>Test</p></usa-alert>`;
-    await getAlert().updateComplete;
+    await updateComplete();
     const btn = getShadow().querySelector(".usa-alert__close");
     expect(btn?.getAttribute("aria-label")).toBe("Dismiss warning");
   });

From 98cdc2de520591c242963c610a13e750b005a562 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Tue, 19 May 2026 09:12:00 -0500
Subject: [PATCH 04/10] Simplify .usa-alert--slim left padding calc

Update usa-alert.css to replace calc(var(--usa-alert-padding-x) + 1.5rem + 0.5rem) with calc(var(--usa-alert-padding-x) + 2rem) for .usa-alert--slim .usa-alert__body. This simplifies the expression by combining the two fixed offsets into a single value, keeping the computed spacing unchanged and improving readability.
---
 src/components/usa-alert/usa-alert.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/usa-alert/usa-alert.css b/src/components/usa-alert/usa-alert.css
index b56b91af..8ed446a6 100644
--- a/src/components/usa-alert/usa-alert.css
+++ b/src/components/usa-alert/usa-alert.css
@@ -140,7 +140,7 @@
 /** Slim */
 .usa-alert--slim .usa-alert__body {
   padding: 0.5rem var(--usa-alert-padding-x);
-  padding-left: calc(var(--usa-alert-padding-x) + 1.5rem + 0.5rem);
+  padding-left: calc(var(--usa-alert-padding-x) + 2rem);
 
   &::before {
     height: 1.5rem;

From b30cbf9cc729234b7741eb9d7d8f84e7388449c2 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Tue, 19 May 2026 09:19:23 -0500
Subject: [PATCH 05/10] Use private #role getter and remove aria-hidden

Switch the private role getter from `_role` to the ECMAScript private accessor `#role` and update the template reference accordingly. Also remove the `aria-hidden="true"` attribute from the close-icon span so the icon is not explicitly hidden; the close button still uses an `aria-label` for its accessible name.
---
 src/components/usa-alert/index.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/components/usa-alert/index.ts b/src/components/usa-alert/index.ts
index 171022d7..e67d03af 100644
--- a/src/components/usa-alert/index.ts
+++ b/src/components/usa-alert/index.ts
@@ -67,7 +67,7 @@ export class UsaAlert extends LitElement {
     this._visible = true;
   }
 
-  private get _role(): string {
+  private get #role(): string {
     if (
       this.status === "error" ||
       this.status === "emergency" ||
@@ -109,7 +109,7 @@ export class UsaAlert extends LitElement {
     };
 
     return html`
-      <div class="${classMap(classes)}" role="${this._role}">
+      <div class="${classMap(classes)}" role="${this.#role}">
         <div class="usa-alert__body">
           ${!this.slim ? html`<slot name="headline"></slot>` : null}
           <div class="usa-alert__text">
@@ -124,7 +124,7 @@ export class UsaAlert extends LitElement {
                 aria-label="${this.closeLabel}"
                 @click="${this._handleClose}"
               >
-                <span class="usa-alert__close-icon" aria-hidden="true"></span>
+                <span class="usa-alert__close-icon"></span>
               </button>
             `
           : null}

From be7808fb712535d0a205ab9063c35c0d4b465215 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Thu, 21 May 2026 08:50:09 -0500
Subject: [PATCH 06/10] Delete add-usa-alert-component.md

---
 .changeset/add-usa-alert-component.md | 5 -----
 1 file changed, 5 deletions(-)
 delete mode 100644 .changeset/add-usa-alert-component.md

diff --git a/.changeset/add-usa-alert-component.md b/.changeset/add-usa-alert-component.md
deleted file mode 100644
index 74fe6e3a..00000000
--- a/.changeset/add-usa-alert-component.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@uswds/elements": minor
----
-
-Add usa-alert component with support for info, warning, error, success, and emergency statuses. Includes slim, no-icon, and closeable variants.

From 9613a3675ec53a345c5cba67600c4ffe525ea162 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Wed, 3 Jun 2026 12:38:00 -0500
Subject: [PATCH 07/10] Remove 'private' modifier from private getter

Drop the redundant 'private' modifier from the '#role' getter in the UsaAlert component. Combining the TS 'private' keyword with an ECMAScript private identifier ('#') is invalid and caused a syntax/compile error, so this change makes the accessor valid.
---
 src/components/usa-alert/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/usa-alert/index.ts b/src/components/usa-alert/index.ts
index e67d03af..f37cd948 100644
--- a/src/components/usa-alert/index.ts
+++ b/src/components/usa-alert/index.ts
@@ -67,7 +67,7 @@ export class UsaAlert extends LitElement {
     this._visible = true;
   }
 
-  private get #role(): string {
+  get #role(): string {
     if (
       this.status === "error" ||
       this.status === "emergency" ||

From 637abff7241764e448970c1086ce8d4542335469 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Wed, 3 Jun 2026 13:33:52 -0500
Subject: [PATCH 08/10] Use CSS var for emergency text and rename field

Rename the private field in custom-elements.json from `_role` to `#role` to match private field syntax. In usa-alert.css add a new `--usa-alert-emergency-text-color` variable (defaulting to #fff) and replace hardcoded `#fff` uses in emergency alert styles (body text, slotted headline, and close-icon background) so the emergency text color can be themed via CSS variables.
---
 custom-elements.json                   | 4 ++--
 src/components/usa-alert/usa-alert.css | 7 ++++---
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/custom-elements.json b/custom-elements.json
index 22484474..98356469 100644
--- a/custom-elements.json
+++ b/custom-elements.json
@@ -152,11 +152,11 @@
             },
             {
               "kind": "field",
-              "name": "_role",
+              "name": "#role",
+              "privacy": "private",
               "type": {
                 "text": "string"
               },
-              "privacy": "private",
               "readonly": true
             },
             {
diff --git a/src/components/usa-alert/usa-alert.css b/src/components/usa-alert/usa-alert.css
index 8ed446a6..95a2fea0 100644
--- a/src/components/usa-alert/usa-alert.css
+++ b/src/components/usa-alert/usa-alert.css
@@ -32,6 +32,7 @@
   --usa-alert-emergency-background: var(--usa-color-emergency, #9c3d10);
   --usa-alert-emergency-border: var(--usa-color-emergency-dark, #332d29);
   --usa-alert-emergency-icon: #fff;
+  --usa-alert-emergency-text-color: #fff;
 
   display: block;
 }
@@ -83,7 +84,7 @@
   --usa-alert-icon-color: var(--usa-alert-emergency-icon);
 
   & .usa-alert__body {
-    color: #fff;
+    color: var(--usa-alert-emergency-text-color);
   }
 }
 
@@ -163,7 +164,7 @@
 }
 
 .usa-alert--emergency ::slotted([slot="headline"]) {
-  color: #fff;
+  color: var(--usa-alert-emergency-text-color);
 }
 
 /** Alert text */
@@ -211,7 +212,7 @@
 }
 
 .usa-alert--emergency .usa-alert__close-icon {
-  background-color: #fff;
+  background-color: var(--usa-alert-emergency-text-color);
 }
 
 /** High contrast mode */

From 044899a8a1b9dd02d4b729ff3e980eb016527308 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Wed, 3 Jun 2026 13:55:05 -0500
Subject: [PATCH 09/10] Consolidate info status tests

Merge the default info status and role assertion into a single test and remove the duplicate ARIA role test for info in src/components/usa-alert/usa-alert.spec.ts. This reduces redundancy and simplifies the test suite by combining related assertions into one spec.
---
 src/components/usa-alert/usa-alert.spec.ts | 13 +------------
 1 file changed, 1 insertion(+), 12 deletions(-)

diff --git a/src/components/usa-alert/usa-alert.spec.ts b/src/components/usa-alert/usa-alert.spec.ts
index a55f1297..f7e22675 100644
--- a/src/components/usa-alert/usa-alert.spec.ts
+++ b/src/components/usa-alert/usa-alert.spec.ts
@@ -29,13 +29,9 @@ describe("usa-alert component", () => {
     `;
   });
 
-  it("renders with default info status", () => {
+  it("defaults to info status with role=status", () => {
     const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.classList.contains("usa-alert--info")).toBe(true);
-  });
-
-  it("has role=status for info alerts", () => {
-    const alertDiv = getShadow().querySelector(".usa-alert");
     expect(alertDiv?.getAttribute("role")).toBe("status");
   });
 
@@ -79,13 +75,6 @@ describe("status variants", () => {
 });
 
 describe("ARIA roles", () => {
-  it("uses role=status for info", async () => {
-    document.body.innerHTML = `<usa-alert status="info"><p>Test</p></usa-alert>`;
-    await updateComplete();
-    const alertDiv = getShadow().querySelector(".usa-alert");
-    expect(alertDiv?.getAttribute("role")).toBe("status");
-  });
-
   it("uses role=status for success", async () => {
     document.body.innerHTML = `<usa-alert status="success"><p>Test</p></usa-alert>`;
     await updateComplete();

From e1abe0681d853c5adc5b030353e6207e50f92085 Mon Sep 17 00:00:00 2001
From: Eric Sorenson <esorenson@flexion.us>
Date: Wed, 3 Jun 2026 15:23:55 -0500
Subject: [PATCH 10/10] Use usa-alert-close event for alerts

Rename the alert close event from "close" to "usa-alert-close" to avoid generic event name collisions. Update the @fires JSDoc, the dispatched CustomEvent in UsaAlert, and the unit test to listen for "usa-alert-close".
---
 src/components/usa-alert/index.ts          | 4 ++--
 src/components/usa-alert/usa-alert.spec.ts | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/components/usa-alert/index.ts b/src/components/usa-alert/index.ts
index f37cd948..8f6c3268 100644
--- a/src/components/usa-alert/index.ts
+++ b/src/components/usa-alert/index.ts
@@ -36,7 +36,7 @@ type AlertStatus = (typeof VALID_STATUSES)[number];
  * @slot headline - The alert heading (use an h-element: h2, h3, etc.).
  * @slot - Default slot for alert body content.
  *
- * @fires close - Dispatched when the close button is clicked.
+ * @fires usa-alert-close - Dispatched when the close button is clicked.
  *
  * @element usa-alert
  */
@@ -80,7 +80,7 @@ export class UsaAlert extends LitElement {
 
   private _handleClose() {
     this.dispatchEvent(
-      new CustomEvent("close", { bubbles: true, composed: true }),
+      new CustomEvent("usa-alert-close", { bubbles: true, composed: true }),
     );
     this._visible = false;
   }
diff --git a/src/components/usa-alert/usa-alert.spec.ts b/src/components/usa-alert/usa-alert.spec.ts
index f7e22675..1614e462 100644
--- a/src/components/usa-alert/usa-alert.spec.ts
+++ b/src/components/usa-alert/usa-alert.spec.ts
@@ -146,9 +146,9 @@ describe("closeable", () => {
     expect(btn?.getAttribute("aria-label")).toBe("Close alert");
   });
 
-  it("dispatches close event on click", async () => {
+  it("dispatches usa-alert-close event on click", async () => {
     const handler = vi.fn();
-    getAlert().addEventListener("close", handler);
+    getAlert().addEventListener("usa-alert-close", handler);
 
     const btn = getShadow().querySelector(
       ".usa-alert__close",