From 87c45535d8b38bc4a5f14e13b421f64b8a391888 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 14:42:33 +0000
Subject: [PATCH 01/31] Draft an alert component

---
 resources/js/bootstrap/cms/ui.js     |  1 +
 resources/js/components/ui/Alert.vue | 64 ++++++++++++++++++++++++++++
 resources/js/components/ui/index.js  |  1 +
 3 files changed, 66 insertions(+)
 create mode 100644 resources/js/components/ui/Alert.vue

diff --git a/resources/js/bootstrap/cms/ui.js b/resources/js/bootstrap/cms/ui.js
index 684db0c5a5..adf68ff74c 100644
--- a/resources/js/bootstrap/cms/ui.js
+++ b/resources/js/bootstrap/cms/ui.js
@@ -1,4 +1,5 @@
 export {
+    Alert,
     AuthCard,
     Avatar,
     Badge,
diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
new file mode 100644
index 0000000000..7264bfbf11
--- /dev/null
+++ b/resources/js/components/ui/Alert.vue
@@ -0,0 +1,64 @@
+<script setup>
+import { computed, useSlots } from 'vue';
+import { cva } from 'cva';
+import Icon from './Icon/Icon.vue';
+
+const props = defineProps({
+    /** The alert message to display */
+    text: { type: [String, Number, Boolean, null], default: null },
+    /** Controls the appearance of the alert. <br><br> Options: `default`, `warning`, `error`, `success` */
+    variant: { type: String, default: 'default' },
+    /** Icon name to display. [Browse available icons](/?path=/story/components-icon--all-icons) */
+    icon: { type: String, default: null },
+});
+
+const slots = useSlots();
+const hasDefaultSlot = !!slots.default;
+
+const alertClasses = computed(() => {
+    return cva({
+        base: 'relative flex items-start gap-3 rounded-xl border p-4 text-sm',
+        variants: {
+            variant: {
+                default: [
+                    'bg-gray-50 dark:bg-gray-900/50 border-gray-200 dark:border-gray-700/80 text-gray-900 dark:text-gray-100',
+                ],
+                warning: [
+                    'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-300',
+                ],
+                error: [
+                    'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
+                ],
+                success: [
+                    'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
+                ],
+            },
+        },
+    })({ variant: props.variant });
+});
+
+const defaultIcon = computed(() => {
+    if (props.icon) return props.icon;
+    
+    switch (props.variant) {
+        case 'warning':
+            return 'alert-triangle';
+        case 'error':
+            return 'alert-circle';
+        case 'success':
+            return 'checkmark-circle';
+        default:
+            return 'information-circle';
+    }
+});
+</script>
+
+<template>
+    <div :class="alertClasses" data-ui-alert :data-variant="variant">
+        <Icon v-if="defaultIcon" :name="defaultIcon" class="size-5 shrink-0 mt-0.5 opacity-70" />
+        <div class="flex-1 min-w-0">
+            <slot v-if="hasDefaultSlot" />
+            <span v-else v-html="text" />
+        </div>
+    </div>
+</template>
diff --git a/resources/js/components/ui/index.js b/resources/js/components/ui/index.js
index 828345ae6b..aa0127f566 100644
--- a/resources/js/components/ui/index.js
+++ b/resources/js/components/ui/index.js
@@ -1,3 +1,4 @@
+export { default as Alert } from './Alert.vue';
 export { default as AuthCard } from './AuthCard.vue';
 export { default as Badge } from './Badge.vue';
 export { default as Button } from './Button/Button.vue';

From 3be6edd771a620ef73bc3f4a223acb307c914ce9 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 14:50:20 +0000
Subject: [PATCH 02/31] Fix icons

---
 resources/js/components/ui/Alert.vue | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 7264bfbf11..d54f41c6de 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -42,13 +42,13 @@ const defaultIcon = computed(() => {
     
     switch (props.variant) {
         case 'warning':
-            return 'alert-triangle';
+            return 'warning-diamond';
         case 'error':
-            return 'alert-circle';
+            return 'alert-alarm-bell';
         case 'success':
-            return 'checkmark-circle';
+            return 'checkmark';
         default:
-            return 'information-circle';
+            return 'info';
     }
 });
 </script>

From 0cfb8214616e552e54666dcc357904ac9ae28266 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 14:53:50 +0000
Subject: [PATCH 03/31] Alert - improve markup

---
 resources/js/components/ui/Alert.vue | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index d54f41c6de..d792cbb559 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -15,6 +15,17 @@ const props = defineProps({
 const slots = useSlots();
 const hasDefaultSlot = !!slots.default;
 
+const alertRole = computed(() => {
+    // Use 'alert' for urgent messages that need immediate attention
+    // Use 'status' for informational messages
+    return props.variant === 'error' || props.variant === 'warning' ? 'alert' : 'status';
+});
+
+const ariaLive = computed(() => {
+    // 'assertive' for urgent, 'polite' for informational
+    return props.variant === 'error' || props.variant === 'warning' ? 'assertive' : 'polite';
+});
+
 const alertClasses = computed(() => {
     return cva({
         base: 'relative flex items-start gap-3 rounded-xl border p-4 text-sm',
@@ -54,8 +65,19 @@ const defaultIcon = computed(() => {
 </script>
 
 <template>
-    <div :class="alertClasses" data-ui-alert :data-variant="variant">
-        <Icon v-if="defaultIcon" :name="defaultIcon" class="size-5 shrink-0 mt-0.5 opacity-70" />
+    <div
+        :class="alertClasses"
+        :role="alertRole"
+        :aria-live="ariaLive"
+        data-ui-alert
+        :data-variant="variant"
+    >
+        <Icon
+            v-if="defaultIcon"
+            :name="defaultIcon"
+            class="size-5 shrink-0 mt-0.5 opacity-70"
+            aria-hidden="true"
+        />
         <div class="flex-1 min-w-0">
             <slot v-if="hasDefaultSlot" />
             <span v-else v-html="text" />

From ef27349dd799dcc6858aa075e9f8ae8648c3be89 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 15:06:37 +0000
Subject: [PATCH 04/31] Alert - tweak alignment

---
 resources/js/components/ui/Alert.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index d792cbb559..601edaaf5b 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -75,7 +75,7 @@ const defaultIcon = computed(() => {
         <Icon
             v-if="defaultIcon"
             :name="defaultIcon"
-            class="size-5 shrink-0 mt-0.5 opacity-70"
+            class="size-5 shrink-0 opacity-70"
             aria-hidden="true"
         />
         <div class="flex-1 min-w-0">

From d9952d88b64f57c4524bac4a44c5e5653a4170c7 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 15:24:34 +0000
Subject: [PATCH 05/31] Alert - message styling

---
 resources/js/components/ui/Alert.vue | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 601edaaf5b..6c90dcf1e8 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -28,7 +28,16 @@ const ariaLive = computed(() => {
 
 const alertClasses = computed(() => {
     return cva({
-        base: 'relative flex items-start gap-3 rounded-xl border p-4 text-sm',
+        base: [
+            'relative flex items-start gap-3 rounded-xl border p-4 [&:has(p)]:py-5 [&:has(p)]:pb-6 text-sm',
+            '[&_h1]:mb-1 [&_h1]:font-bold',
+            '[&_h2]:mb-1 [&_h2]:font-bold',
+            '[&_h3]:mb-1 [&_h3]:font-bold',
+            '[&_h4]:mb-1 [&_h4]:font-bold',
+            '[&_h5]:mb-1 [&_h5]:font-bold',
+            '[&_h6]:mb-1 [&_h6]:font-bold',
+            '[&_p:not(:last-child)]:mb-3',
+        ].join(' '),
         variants: {
             variant: {
                 default: [

From 136176a6bc2e4bd65cd78b7abf6436203943c5e1 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 15:46:37 +0000
Subject: [PATCH 06/31] Alert - Style code snippets

---
 resources/js/components/ui/Alert.vue | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 6c90dcf1e8..ff31acbedb 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -42,15 +42,23 @@ const alertClasses = computed(() => {
             variant: {
                 default: [
                     'bg-gray-50 dark:bg-gray-900/50 border-gray-200 dark:border-gray-700/80 text-gray-900 dark:text-gray-100',
+                    '[&_code]:bg-gray-200! dark:[&_code]:bg-gray-800!',
+                    '[&_code]:border-gray-300 dark:[&_code]:border-gray-700',
                 ],
                 warning: [
                     'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-300',
+                    '[&_code]:bg-amber-200/60! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/25! dark:[&_code]:text-amber-200!',
+                    '[&_code]:border-amber-300/50 dark:[&_code]:border-amber-400/40',
                 ],
                 error: [
                     'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
+                    '[&_code]:bg-red-200/60! [&_code]:text-red-800! dark:[&_code]:bg-red-300/25! dark:[&_code]:text-red-200!',
+                    '[&_code]:border-red-300 dark:[&_code]:border-red-400/30',
                 ],
                 success: [
                     'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
+                    '[&_code]:bg-emerald-200/60! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/25! dark:[&_code]:text-emerald-200!',
+                    '[&_code]:border-emerald-300 dark:[&_code]:border-emerald-400/30',
                 ],
             },
         },

From e57144907badcb468ccaf0d646ffb824dd77c838 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 15:49:13 +0000
Subject: [PATCH 07/31] Alert / Style code snippets - remove unnecessary
 borders

---
 resources/js/components/ui/Alert.vue | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index ff31acbedb..f43949db7f 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -42,23 +42,19 @@ const alertClasses = computed(() => {
             variant: {
                 default: [
                     'bg-gray-50 dark:bg-gray-900/50 border-gray-200 dark:border-gray-700/80 text-gray-900 dark:text-gray-100',
-                    '[&_code]:bg-gray-200! dark:[&_code]:bg-gray-800!',
-                    '[&_code]:border-gray-300 dark:[&_code]:border-gray-700',
+                    '[&_code]:bg-gray-200! [&_code]:text-gray-800! dark:[&_code]:bg-gray-800! dark:[&_code]:text-gray-200!',
                 ],
                 warning: [
                     'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-300',
                     '[&_code]:bg-amber-200/60! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/25! dark:[&_code]:text-amber-200!',
-                    '[&_code]:border-amber-300/50 dark:[&_code]:border-amber-400/40',
                 ],
                 error: [
                     'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
                     '[&_code]:bg-red-200/60! [&_code]:text-red-800! dark:[&_code]:bg-red-300/25! dark:[&_code]:text-red-200!',
-                    '[&_code]:border-red-300 dark:[&_code]:border-red-400/30',
                 ],
                 success: [
                     'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
                     '[&_code]:bg-emerald-200/60! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/25! dark:[&_code]:text-emerald-200!',
-                    '[&_code]:border-emerald-300 dark:[&_code]:border-emerald-400/30',
                 ],
             },
         },

From 2fafc2419fbda92b82caa06f2431e5b458dbf6ce Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 15:52:15 +0000
Subject: [PATCH 08/31] Alert / Style code snippets - fix dark mode legibility

---
 resources/js/components/ui/Alert.vue | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index f43949db7f..da7cf0888e 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -46,15 +46,15 @@ const alertClasses = computed(() => {
                 ],
                 warning: [
                     'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-300',
-                    '[&_code]:bg-amber-200/60! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/25! dark:[&_code]:text-amber-200!',
+                    '[&_code]:bg-amber-200/60! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/10! dark:[&_code]:text-amber-200!',
                 ],
                 error: [
                     'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
-                    '[&_code]:bg-red-200/60! [&_code]:text-red-800! dark:[&_code]:bg-red-300/25! dark:[&_code]:text-red-200!',
+                    '[&_code]:bg-red-200/60! [&_code]:text-red-800! dark:[&_code]:bg-red-300/10! dark:[&_code]:text-red-200!',
                 ],
                 success: [
                     'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
-                    '[&_code]:bg-emerald-200/60! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/25! dark:[&_code]:text-emerald-200!',
+                    '[&_code]:bg-emerald-200/60! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/10! dark:[&_code]:text-emerald-200!',
                 ],
             },
         },

From 7b36101e0d01e6b6873a77af7cb436d14739d673 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 16:03:56 +0000
Subject: [PATCH 09/31] Alert / Style code snippets - improve

---
 resources/js/components/ui/Alert.vue | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index da7cf0888e..9751941603 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -37,6 +37,7 @@ const alertClasses = computed(() => {
             '[&_h5]:mb-1 [&_h5]:font-bold',
             '[&_h6]:mb-1 [&_h6]:font-bold',
             '[&_p:not(:last-child)]:mb-3',
+            '[&_code]:px-0.75 [&_code]:mx-0.5 [&_code]:py-0.5 [&_code]:rounded-sm',
         ].join(' '),
         variants: {
             variant: {
@@ -46,15 +47,15 @@ const alertClasses = computed(() => {
                 ],
                 warning: [
                     'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-300',
-                    '[&_code]:bg-amber-200/60! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/10! dark:[&_code]:text-amber-200!',
+                    '[&_code]:bg-amber-200/50! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/8! dark:[&_code]:text-amber-200!',
                 ],
                 error: [
                     'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
-                    '[&_code]:bg-red-200/60! [&_code]:text-red-800! dark:[&_code]:bg-red-300/10! dark:[&_code]:text-red-200!',
+                    '[&_code]:bg-red-200/50! [&_code]:text-red-800! dark:[&_code]:bg-red-300/8! dark:[&_code]:text-red-200!',
                 ],
                 success: [
                     'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
-                    '[&_code]:bg-emerald-200/60! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/10! dark:[&_code]:text-emerald-200!',
+                    '[&_code]:bg-emerald-200/50! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/8! dark:[&_code]:text-emerald-200!',
                 ],
             },
         },

From 698789098a2318b4799e280e31b034aaa8902eac Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 16:10:57 +0000
Subject: [PATCH 10/31] Dashboard demo

---
 resources/js/pages/Dashboard.vue | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/resources/js/pages/Dashboard.vue b/resources/js/pages/Dashboard.vue
index 20950ce77c..eda6e87ca3 100644
--- a/resources/js/pages/Dashboard.vue
+++ b/resources/js/pages/Dashboard.vue
@@ -1,7 +1,7 @@
 <script setup>
 import Head from '@/pages/layout/Head.vue';
 import DynamicHtmlRenderer from '@/components/DynamicHtmlRenderer.vue';
-import { Icon, EmptyStateMenu, EmptyStateItem, DocsCallout } from '@ui';
+import { Icon, EmptyStateMenu, EmptyStateItem, DocsCallout, Alert } from '@ui';
 import useArchitecturalBackground from '@/pages/layout/architectural-background.js';
 
 const props = defineProps({
@@ -48,6 +48,33 @@ function tailwindWidthClass(width) {
     <template v-if="widgets.length">
         <ui-header :title="__('Dashboard')" icon="dashboard" />
 
+        <div class="mb-6 space-y-3">
+            <Alert variant="default" text="This is a default alert message" />
+            <Alert variant="warning" text="This is a warning alert message" />
+            <Alert variant="error" text="This is an error alert message" />
+            <Alert variant="success" text="This is a success alert message" />
+            <Alert variant="warning" icon="git" text="This alert has a custom icon" />
+            <Alert variant="success">
+                <strong>Success!</strong> This alert uses a slot for custom content.
+            </Alert>
+            <Alert variant="warning">
+                <h3>Please run your migrations</h3>
+                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+            </Alert>
+            <Alert variant="default">
+                <h3>This is a default alert message</h3>
+                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+            </Alert>
+            <Alert variant="success">
+                <h3>This is a success alert message</h3>
+                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+            </Alert>
+            <Alert variant="error">
+                <h3>This is an error alert message</h3>
+                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+            </Alert>
+        </div>
+
         <div class="widgets @container/widgets flex flex-wrap gap-y-6 -mx-2 sm:-mx-3">
             <div
                 v-for="widget in widgets"

From 8f695999ec45cec105257449256a9d630c5d9b97 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 16:18:26 +0000
Subject: [PATCH 11/31] Move the demo to the playground

---
 resources/js/pages/Dashboard.vue  | 29 +----------------------------
 resources/js/pages/Playground.vue | 30 ++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 28 deletions(-)

diff --git a/resources/js/pages/Dashboard.vue b/resources/js/pages/Dashboard.vue
index eda6e87ca3..20950ce77c 100644
--- a/resources/js/pages/Dashboard.vue
+++ b/resources/js/pages/Dashboard.vue
@@ -1,7 +1,7 @@
 <script setup>
 import Head from '@/pages/layout/Head.vue';
 import DynamicHtmlRenderer from '@/components/DynamicHtmlRenderer.vue';
-import { Icon, EmptyStateMenu, EmptyStateItem, DocsCallout, Alert } from '@ui';
+import { Icon, EmptyStateMenu, EmptyStateItem, DocsCallout } from '@ui';
 import useArchitecturalBackground from '@/pages/layout/architectural-background.js';
 
 const props = defineProps({
@@ -48,33 +48,6 @@ function tailwindWidthClass(width) {
     <template v-if="widgets.length">
         <ui-header :title="__('Dashboard')" icon="dashboard" />
 
-        <div class="mb-6 space-y-3">
-            <Alert variant="default" text="This is a default alert message" />
-            <Alert variant="warning" text="This is a warning alert message" />
-            <Alert variant="error" text="This is an error alert message" />
-            <Alert variant="success" text="This is a success alert message" />
-            <Alert variant="warning" icon="git" text="This alert has a custom icon" />
-            <Alert variant="success">
-                <strong>Success!</strong> This alert uses a slot for custom content.
-            </Alert>
-            <Alert variant="warning">
-                <h3>Please run your migrations</h3>
-                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
-            </Alert>
-            <Alert variant="default">
-                <h3>This is a default alert message</h3>
-                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
-            </Alert>
-            <Alert variant="success">
-                <h3>This is a success alert message</h3>
-                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
-            </Alert>
-            <Alert variant="error">
-                <h3>This is an error alert message</h3>
-                <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
-            </Alert>
-        </div>
-
         <div class="widgets @container/widgets flex flex-wrap gap-y-6 -mx-2 sm:-mx-3">
             <div
                 v-for="widget in widgets"
diff --git a/resources/js/pages/Playground.vue b/resources/js/pages/Playground.vue
index 8b6521be7b..49645e70da 100644
--- a/resources/js/pages/Playground.vue
+++ b/resources/js/pages/Playground.vue
@@ -1,5 +1,6 @@
 <script setup>
 import Head from '@/pages/layout/Head.vue';
+import { Alert } from '@ui';
 
 defineProps(['icons']);
 </script>
@@ -297,6 +298,35 @@ defineProps(['icons']);
                 </div>
             </section>
 
+            <section class="mb-10 space-y-3">
+                <ui-heading size="lg">Alerts</ui-heading>
+
+                <Alert variant="default" text="This is a default alert message" />
+                <Alert variant="warning" text="This is a warning alert message" />
+                <Alert variant="error" text="This is an error alert message" />
+                <Alert variant="success" text="This is a success alert message" />
+                <Alert variant="warning" icon="git" text="This alert has a custom icon" />
+                <Alert variant="success">
+                    <strong>Success!</strong> This alert uses a slot for custom content.
+                </Alert>
+                <Alert variant="warning">
+                    <h1>Please run your migrations</h1>
+                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                </Alert>
+                <Alert variant="default">
+                    <h2>This is a default alert message</h2>
+                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                </Alert>
+                <Alert variant="success">
+                    <h3>This is a success alert message</h3>
+                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                </Alert>
+                <Alert variant="error">
+                    <h4>This is an error alert message</h4>
+                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                </Alert>
+            </section>
+
             <section class="space-y-4">
                 <ui-heading size="lg">Calendar</ui-heading>
                 <div class="flex gap-6">

From 46e755b7a363ef9ed2b6c1b3a3c0ec091b7ed3de Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 16:24:20 +0000
Subject: [PATCH 12/31] Improve realism of demo messages

---
 resources/js/pages/Playground.vue | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/resources/js/pages/Playground.vue b/resources/js/pages/Playground.vue
index 49645e70da..d2936aaf2e 100644
--- a/resources/js/pages/Playground.vue
+++ b/resources/js/pages/Playground.vue
@@ -314,16 +314,16 @@ defineProps(['icons']);
                     <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
                 </Alert>
                 <Alert variant="default">
-                    <h2>This is a default alert message</h2>
-                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                    <h2>New Feature Available</h2>
+                    <p>We've added support for custom field types. You can now create your own field types by extending the <code>Fieldtype</code> class. Check out the documentation for more details.</p>
                 </Alert>
                 <Alert variant="success">
-                    <h3>This is a success alert message</h3>
-                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                    <h3>Backup Completed Successfully</h3>
+                    <p>Your site backup has been created and saved to <code>/storage/backups/site-2032-01-15.tar.gz</code>. The backup includes all content, assets, and configuration files.</p>
                 </Alert>
                 <Alert variant="error">
-                    <h4>This is an error alert message</h4>
-                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                    <h4>Failed to Connect to Database</h4>
+                    <p>Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</p>
                 </Alert>
             </section>
 

From 0f8e853dcea23e1e8c6c1a98ae6c15610951b667 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 16:41:50 +0000
Subject: [PATCH 13/31] Add alert component to the test's expected exports list

---
 resources/js/tests/Package.test.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/resources/js/tests/Package.test.js b/resources/js/tests/Package.test.js
index 4090ebdae9..b7ead20e94 100644
--- a/resources/js/tests/Package.test.js
+++ b/resources/js/tests/Package.test.js
@@ -119,6 +119,7 @@ it('exports ui', async () => {
     // a component to one place that you don't forget to add it to the other places.
 
     const expectedCmsPackageExports = [
+        'Alert',
         'AuthCard',
         'Badge',
         'Button',

From 312826dd1dabd5104537c613cc4bc471842ed341 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 16:46:47 +0000
Subject: [PATCH 14/31] Add Alert to the package export file

---
 packages/cms/src/ui.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/cms/src/ui.js b/packages/cms/src/ui.js
index 6b801315d7..6b276d4313 100644
--- a/packages/cms/src/ui.js
+++ b/packages/cms/src/ui.js
@@ -1,4 +1,5 @@
 export const {
+    Alert,
     AuthCard,
     Avatar,
     Badge,

From fa29d92dbc4f252b95b933acef50d20944e4149e Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Mon, 19 Jan 2026 17:15:08 +0000
Subject: [PATCH 15/31] Alert - make code size smaller

---
 resources/js/components/ui/Alert.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 9751941603..e2dc982a63 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -37,7 +37,7 @@ const alertClasses = computed(() => {
             '[&_h5]:mb-1 [&_h5]:font-bold',
             '[&_h6]:mb-1 [&_h6]:font-bold',
             '[&_p:not(:last-child)]:mb-3',
-            '[&_code]:px-0.75 [&_code]:mx-0.5 [&_code]:py-0.5 [&_code]:rounded-sm',
+            '[&_code]:px-0.75 [&_code]:mx-0.5 [&_code]:py-0.5 [&_code]:rounded-sm [&_code]:text-xs',
         ].join(' '),
         variants: {
             variant: {

From f5e79e386b6e6ec5b93d8eb4f5cf25b9a526e3b8 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Tue, 20 Jan 2026 10:37:37 +0000
Subject: [PATCH 16/31] Alert - add storybook component

---
 resources/js/stories/Alert.stories.ts | 209 ++++++++++++++++++++++++++
 1 file changed, 209 insertions(+)
 create mode 100644 resources/js/stories/Alert.stories.ts

diff --git a/resources/js/stories/Alert.stories.ts b/resources/js/stories/Alert.stories.ts
new file mode 100644
index 0000000000..d838115f1e
--- /dev/null
+++ b/resources/js/stories/Alert.stories.ts
@@ -0,0 +1,209 @@
+import type {Meta, StoryObj} from '@storybook/vue3';
+import {Alert} from '@ui';
+import {icons} from './icons';
+
+const meta = {
+    title: 'Components/Alert',
+    component: Alert,
+    argTypes: {
+        variant: {
+            control: 'select',
+            options: ['default', 'warning', 'error', 'success'],
+        },
+        icon: {
+            control: 'select',
+            options: icons,
+        },
+    },
+} satisfies Meta<typeof Alert>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const defaultCode = `
+<Alert variant="default" text="This is a default alert message" />
+`;
+
+export const _DocsIntro: Story = {
+    tags: ['!dev'],
+    parameters: {
+        docs: {
+            source: { code: defaultCode }
+        }
+    },
+    render: () => ({
+        components: { Alert },
+        template: defaultCode,
+    }),
+};
+
+const variantsCode = `
+<Alert variant="default" text="This is a default alert message" />
+<Alert variant="warning" text="This is a warning alert message" />
+<Alert variant="error" text="This is an error alert message" />
+<Alert variant="success" text="This is a success alert message" />
+`;
+
+export const Variants: Story = {
+    argTypes: {
+        variant: { control: { disable: true } },
+        text: { control: { disable: true } },
+        icon: { control: { disable: true } },
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: variantsCode,
+            },
+        },
+    },
+    render: () => ({
+        components: { Alert },
+        template: `
+            <div class="space-y-3">
+                <Alert variant="default" text="This is a default alert message" />
+                <Alert variant="warning" text="This is a warning alert message" />
+                <Alert variant="error" text="This is an error alert message" />
+                <Alert variant="success" text="This is a success alert message" />
+            </div>
+        `,
+    }),
+};
+
+const customIconCode = `
+<Alert variant="warning" icon="git" text="This alert has a custom icon" />
+<Alert variant="default" icon="cog" text="This alert uses a custom icon" />
+`;
+
+export const CustomIcons: Story = {
+    argTypes: {
+        icon: { control: { disable: true } },
+        text: { control: { disable: true } },
+        variant: { control: { disable: true } },
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: customIconCode,
+            },
+        },
+    },
+    render: () => ({
+        components: { Alert },
+        template: `
+            <div class="space-y-3">
+                <Alert variant="warning" icon="git" text="This alert has a custom icon" />
+                <Alert variant="default" icon="cog" text="This alert uses a custom icon" />
+                <Alert variant="success" icon="sparkles" text="Custom success icon" />
+            </div>
+        `,
+    }),
+};
+
+const slotContentCode = `
+<Alert variant="success">
+    <strong>Success!</strong> This alert uses a slot for custom content.
+</Alert>
+`;
+
+export const SlotContent: Story = {
+    tags: ['!dev'],
+    argTypes: {
+        text: { control: { disable: true } },
+        variant: { control: { disable: true } },
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: slotContentCode,
+            },
+        },
+    },
+    render: () => ({
+        components: { Alert },
+        template: `
+            <div class="space-y-3">
+                <Alert variant="success">
+                    <strong>Success!</strong> This alert uses a slot for custom content.
+                </Alert>
+                <Alert variant="default">
+                    You can use <strong>bold text</strong>, <em>italic text</em>, and even <code>code</code> in slot content.
+                </Alert>
+            </div>
+        `,
+    }),
+};
+
+const richContentCode = `
+<Alert variant="warning">
+    <h1>Please run your migrations</h1>
+    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>.</p>
+</Alert>
+`;
+
+export const RichContent: Story = {
+    tags: ['!dev'],
+    argTypes: {
+        text: { control: { disable: true } },
+        variant: { control: { disable: true } },
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: richContentCode,
+            },
+        },
+    },
+    render: () => ({
+        components: { Alert },
+        template: `
+            <div class="space-y-3">
+                <Alert variant="warning">
+                    <h1>Please run your migrations</h1>
+                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+                </Alert>
+                <Alert variant="default">
+                    <h2>New Feature Available</h2>
+                    <p>We've added support for custom field types. You can now create your own field types by extending the <code>Fieldtype</code> class. Check out the documentation for more details.</p>
+                </Alert>
+                <Alert variant="error">
+                    <h3>Action Required</h3>
+                    <p>There was an issue processing your request. Please check the following:</p>
+                    <ul>
+                        <li>Verify your API credentials</li>
+                        <li>Check your network connection</li>
+                        <li>Review the error logs for more details</li>
+                    </ul>
+                </Alert>
+            </div>
+        `,
+    }),
+};
+
+export const Default: Story = {
+    args: {
+        text: 'This is a default alert message',
+        variant: 'default',
+    },
+};
+
+export const Warning: Story = {
+    args: {
+        text: 'This is a warning alert message',
+        variant: 'warning',
+    },
+};
+
+export const Error: Story = {
+    args: {
+        text: 'This is an error alert message',
+        variant: 'error',
+    },
+};
+
+export const Success: Story = {
+    args: {
+        text: 'This is a success alert message',
+        variant: 'success',
+    },
+};

From 02739de5e87ba1d430a2b9865c015112b94747ef Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Tue, 20 Jan 2026 11:01:37 +0000
Subject: [PATCH 17/31] Add some rich content examples

---
 resources/js/stories/Alert.stories.ts | 80 ++++++++++++++++-----------
 1 file changed, 47 insertions(+), 33 deletions(-)

diff --git a/resources/js/stories/Alert.stories.ts b/resources/js/stories/Alert.stories.ts
index d838115f1e..807b68ad90 100644
--- a/resources/js/stories/Alert.stories.ts
+++ b/resources/js/stories/Alert.stories.ts
@@ -20,6 +20,13 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+export const Default: Story = {
+    args: {
+        text: 'This is a default alert message',
+        variant: 'default',
+    },
+};
+
 const defaultCode = `
 <Alert variant="default" text="This is a default alert message" />
 `;
@@ -135,14 +142,48 @@ export const SlotContent: Story = {
 };
 
 const richContentCode = `
-<Alert variant="warning">
-    <h1>Please run your migrations</h1>
-    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>.</p>
-</Alert>
+<div class="space-y-3">
+    <Alert variant="warning">
+        <h1>Please run your migrations</h1>
+        <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+    </Alert>
+    <Alert variant="default">
+        <h2>New Feature Available</h2>
+        <p>We've added support for custom field types. You can now create your own field types by extending the <code>Fieldtype</code> class. Check out the documentation for more details.</p>
+    </Alert>
+    <Alert variant="success">
+        <h3>Backup Completed Successfully</h3>
+        <p>Your site backup has been created and saved to <code>/storage/backups/site-2032-01-15.tar.gz</code>. The backup includes all content, assets, and configuration files.</p>
+    </Alert>
+    <Alert variant="error">
+        <h4>Failed to Connect to Database</h4>
+        <p>Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</p>
+    </Alert>
+</div>
+`;
+
+const richContentTemplate = `
+<div class="space-y-3">
+    <Alert variant="warning">
+        <h1>Please run your migrations</h1>
+        <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
+    </Alert>
+    <Alert variant="default">
+        <h2>New Feature Available</h2>
+        <p>We've added support for custom field types. You can now create your own field types by extending the <code>Fieldtype</code> class. Check out the documentation for more details.</p>
+    </Alert>
+    <Alert variant="success">
+        <h3>Backup Completed Successfully</h3>
+        <p>Your site backup has been created and saved to <code>/storage/backups/site-2032-01-15.tar.gz</code>. The backup includes all content, assets, and configuration files.</p>
+    </Alert>
+    <Alert variant="error">
+        <h4>Failed to Connect to Database</h4>
+        <p>Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</p>
+    </Alert>
+</div>
 `;
 
 export const RichContent: Story = {
-    tags: ['!dev'],
     argTypes: {
         text: { control: { disable: true } },
         variant: { control: { disable: true } },
@@ -156,37 +197,10 @@ export const RichContent: Story = {
     },
     render: () => ({
         components: { Alert },
-        template: `
-            <div class="space-y-3">
-                <Alert variant="warning">
-                    <h1>Please run your migrations</h1>
-                    <p>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>. This alert uses a heading for the title and a paragraph for the message.</p>
-                </Alert>
-                <Alert variant="default">
-                    <h2>New Feature Available</h2>
-                    <p>We've added support for custom field types. You can now create your own field types by extending the <code>Fieldtype</code> class. Check out the documentation for more details.</p>
-                </Alert>
-                <Alert variant="error">
-                    <h3>Action Required</h3>
-                    <p>There was an issue processing your request. Please check the following:</p>
-                    <ul>
-                        <li>Verify your API credentials</li>
-                        <li>Check your network connection</li>
-                        <li>Review the error logs for more details</li>
-                    </ul>
-                </Alert>
-            </div>
-        `,
+        template: richContentTemplate,
     }),
 };
 
-export const Default: Story = {
-    args: {
-        text: 'This is a default alert message',
-        variant: 'default',
-    },
-};
-
 export const Warning: Story = {
     args: {
         text: 'This is a warning alert message',

From 97c436cc22882b53e483ee7daf4ae61dab42e264 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Tue, 20 Jan 2026 11:03:53 +0000
Subject: [PATCH 18/31] Fix icon

---
 resources/js/stories/Alert.stories.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/resources/js/stories/Alert.stories.ts b/resources/js/stories/Alert.stories.ts
index 807b68ad90..a4409e1c55 100644
--- a/resources/js/stories/Alert.stories.ts
+++ b/resources/js/stories/Alert.stories.ts
@@ -80,6 +80,7 @@ export const Variants: Story = {
 const customIconCode = `
 <Alert variant="warning" icon="git" text="This alert has a custom icon" />
 <Alert variant="default" icon="cog" text="This alert uses a custom icon" />
+<Alert variant="success" icon="clipboard-check" text="Custom success icon" />
 `;
 
 export const CustomIcons: Story = {
@@ -101,7 +102,7 @@ export const CustomIcons: Story = {
             <div class="space-y-3">
                 <Alert variant="warning" icon="git" text="This alert has a custom icon" />
                 <Alert variant="default" icon="cog" text="This alert uses a custom icon" />
-                <Alert variant="success" icon="sparkles" text="Custom success icon" />
+                <Alert variant="success" icon="clipboard-check" text="Custom success icon" />
             </div>
         `,
     }),

From 9d8b22ee6512919fd655da10e58212d784f39ce7 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Tue, 20 Jan 2026 11:11:22 +0000
Subject: [PATCH 19/31] Add docs

---
 resources/js/stories/docs/Alert.mdx | 32 +++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 resources/js/stories/docs/Alert.mdx

diff --git a/resources/js/stories/docs/Alert.mdx b/resources/js/stories/docs/Alert.mdx
new file mode 100644
index 0000000000..558797b0bb
--- /dev/null
+++ b/resources/js/stories/docs/Alert.mdx
@@ -0,0 +1,32 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/addon-docs/blocks';
+import * as AlertStories from '../Alert.stories';
+
+<Meta of={AlertStories} />
+
+# Alert
+Alerts are used to display important messages, notifications, and feedback to users. They come in multiple variants to convey different types of information.
+
+<Canvas of={AlertStories._DocsIntro} sourceState={'shown'} />
+
+## Variants
+Use the `variant` prop to change the appearance and semantic meaning of the alert. Available variants are `default`, `warning`, `error`, and `success`.
+
+<Canvas of={AlertStories.Variants} sourceState={'shown'} />
+
+## Custom Icons
+You can override the default icon by passing a custom `icon` prop with the name of any available icon.
+
+<Canvas of={AlertStories.CustomIcons} sourceState={'shown'} />
+
+## Slot Content
+Instead of using the `text` prop, you can use the default slot to provide custom content with HTML formatting.
+
+<Canvas of={AlertStories.SlotContent} sourceState={'shown'} />
+
+## Rich Content
+Alerts support rich content including headings, paragraphs, and code snippets. This makes them perfect for displaying detailed information and instructions.
+
+<Canvas of={AlertStories.RichContent} sourceState={'shown'} />
+
+## Arguments
+<ArgTypes of={AlertStories} />

From 62302918cf431f2f439fe29f29bc45f83bd0c125 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Tue, 20 Jan 2026 11:14:41 +0000
Subject: [PATCH 20/31] Add instruction

---
 resources/js/stories/docs/Alert.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/stories/docs/Alert.mdx b/resources/js/stories/docs/Alert.mdx
index 558797b0bb..fcb375e745 100644
--- a/resources/js/stories/docs/Alert.mdx
+++ b/resources/js/stories/docs/Alert.mdx
@@ -24,7 +24,7 @@ Instead of using the `text` prop, you can use the default slot to provide custom
 <Canvas of={AlertStories.SlotContent} sourceState={'shown'} />
 
 ## Rich Content
-Alerts support rich content including headings, paragraphs, and code snippets. This makes them perfect for displaying detailed information and instructions.
+Alerts support rich content including headings, paragraphs, and code snippets, making them ideal for detailed messages and instructions. All heading levels (h1–h6) are styled identically, so choose the heading level that's semantically appropriate for your content.
 
 <Canvas of={AlertStories.RichContent} sourceState={'shown'} />
 

From 84be7e9c4f0142f534ee91828b498018c886497f Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Tue, 20 Jan 2026 11:16:05 +0000
Subject: [PATCH 21/31] Simplify the Alert component to use Vue's slot fallback
 syntax

---
 resources/js/components/ui/Alert.vue | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index e2dc982a63..5b9c968254 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -1,5 +1,5 @@
 <script setup>
-import { computed, useSlots } from 'vue';
+import { computed } from 'vue';
 import { cva } from 'cva';
 import Icon from './Icon/Icon.vue';
 
@@ -12,9 +12,6 @@ const props = defineProps({
     icon: { type: String, default: null },
 });
 
-const slots = useSlots();
-const hasDefaultSlot = !!slots.default;
-
 const alertRole = computed(() => {
     // Use 'alert' for urgent messages that need immediate attention
     // Use 'status' for informational messages
@@ -93,8 +90,9 @@ const defaultIcon = computed(() => {
             aria-hidden="true"
         />
         <div class="flex-1 min-w-0">
-            <slot v-if="hasDefaultSlot" />
-            <span v-else v-html="text" />
+            <slot>
+                <span v-html="text" />
+            </slot>
         </div>
     </div>
 </template>

From 9c8b80b28f5f7bb205ba301e178c71e09e18aa7f Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Wed, 21 Jan 2026 15:52:46 +0000
Subject: [PATCH 22/31] Alerts should work with the Heading and Description
 components

---
 resources/js/components/ui/Alert.vue | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 5b9c968254..8ac6a4ec85 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -26,14 +26,16 @@ const ariaLive = computed(() => {
 const alertClasses = computed(() => {
     return cva({
         base: [
-            'relative flex items-start gap-3 rounded-xl border p-4 [&:has(p)]:py-5 [&:has(p)]:pb-6 text-sm',
+            'relative flex items-start gap-3 rounded-xl border p-4 [&:has(p)]:py-5 [&:has(p)]:pb-6 [&:has([data-ui-description])]:py-5 [&:has([data-ui-description])]:pb-6 text-sm',
             '[&_h1]:mb-1 [&_h1]:font-bold',
             '[&_h2]:mb-1 [&_h2]:font-bold',
             '[&_h3]:mb-1 [&_h3]:font-bold',
             '[&_h4]:mb-1 [&_h4]:font-bold',
             '[&_h5]:mb-1 [&_h5]:font-bold',
             '[&_h6]:mb-1 [&_h6]:font-bold',
+            '[&_[data-ui-heading]]:mb-1 [&_[data-ui-heading]]:font-bold',
             '[&_p:not(:last-child)]:mb-3',
+            '[&_[data-ui-description]:not(:last-child)]:mb-3',
             '[&_code]:px-0.75 [&_code]:mx-0.5 [&_code]:py-0.5 [&_code]:rounded-sm [&_code]:text-xs',
         ].join(' '),
         variants: {
@@ -41,18 +43,26 @@ const alertClasses = computed(() => {
                 default: [
                     'bg-gray-50 dark:bg-gray-900/50 border-gray-200 dark:border-gray-700/80 text-gray-900 dark:text-gray-100',
                     '[&_code]:bg-gray-200! [&_code]:text-gray-800! dark:[&_code]:bg-gray-800! dark:[&_code]:text-gray-200!',
+                    '[&_[data-ui-heading]]:text-gray-900! dark:[&_[data-ui-heading]]:text-gray-100!',
+                    '[&_[data-ui-description]]:text-gray-700! dark:[&_[data-ui-description]]:text-gray-300!',
                 ],
                 warning: [
                     'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-300',
                     '[&_code]:bg-amber-200/50! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/8! dark:[&_code]:text-amber-200!',
+                    '[&_[data-ui-heading]]:text-amber-800! dark:[&_[data-ui-heading]]:text-amber-300!',
+                    '[&_[data-ui-description]]:text-amber-700! dark:[&_[data-ui-description]]:text-amber-200!',
                 ],
                 error: [
                     'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
                     '[&_code]:bg-red-200/50! [&_code]:text-red-800! dark:[&_code]:bg-red-300/8! dark:[&_code]:text-red-200!',
+                    '[&_[data-ui-heading]]:text-red-800! dark:[&_[data-ui-heading]]:text-red-300!',
+                    '[&_[data-ui-description]]:text-red-700! dark:[&_[data-ui-description]]:text-red-200!',
                 ],
                 success: [
                     'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
                     '[&_code]:bg-emerald-200/50! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/8! dark:[&_code]:text-emerald-200!',
+                    '[&_[data-ui-heading]]:text-emerald-800! dark:[&_[data-ui-heading]]:text-emerald-300!',
+                    '[&_[data-ui-description]]:text-emerald-700! dark:[&_[data-ui-description]]:text-emerald-200!',
                 ],
             },
         },

From dd46b21dcda2dd455e56ffb5f6ac0ad1e0d05752 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Wed, 21 Jan 2026 16:28:35 +0000
Subject: [PATCH 23/31] Add some demos

---
 resources/js/pages/Playground.vue | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/resources/js/pages/Playground.vue b/resources/js/pages/Playground.vue
index d2936aaf2e..35efa4b68b 100644
--- a/resources/js/pages/Playground.vue
+++ b/resources/js/pages/Playground.vue
@@ -1,6 +1,6 @@
 <script setup>
 import Head from '@/pages/layout/Head.vue';
-import { Alert } from '@ui';
+import { Alert, Heading, Description } from '@ui';
 
 defineProps(['icons']);
 </script>
@@ -325,6 +325,31 @@ defineProps(['icons']);
                     <h4>Failed to Connect to Database</h4>
                     <p>Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</p>
                 </Alert>
+                <hr class="my-10">
+                <Alert variant="default">
+                    <Heading>Using Heading Component</Heading>
+                    <Description>This alert uses the Heading and Description components instead of native HTML elements. The styles should match the variant colors.</Description>
+                </Alert>
+                <Alert variant="warning">
+                    <Heading size="lg">Warning: Action Required</Heading>
+                    <Description>This is a heading size <code>lg</code> example, a warning alert with a larger heading. The Heading component supports different sizes and should inherit the alert's color scheme.</Description>
+                </Alert>
+                <Alert variant="success">
+                    <Heading size="xl">Backup Completed Successfully</Heading>
+                    <Description>Your site backup has been created and saved to <a href="https://statamic.dev"><code>/storage/backups/site-2032-01-15.tar.gz</code></a>. The backup includes all content, assets, and configuration files.</Description>
+                </Alert>
+                <Alert variant="success">
+                    <Heading size="2xl">Backup Completed Very Successfully</Heading>
+                    <Description>I wouldn't recommend such a massive heading, but it's here for testing purposes. Your site backup has been created and saved to <a href="https://statamic.dev"><code>/storage/backups/site-2032-01-15.tar.gz</code></a>. The backup includes all content, assets, and configuration files.</Description>
+                </Alert>
+                <Alert variant="error">
+                    <Heading level="2">Database Connection Failed</Heading>
+                    <Description>This is a heading level <code>2</code> example, with no heading size difference. Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</Description>
+                </Alert>
+                <Alert variant="warning">
+                    <Heading>Migration Required</Heading>
+                    <Description>The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>.</Description>
+                </Alert>
             </section>
 
             <section class="space-y-4">

From 37f11433361d9b17bba298a45bb7b2fda2cf6c3c Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Wed, 21 Jan 2026 16:46:46 +0000
Subject: [PATCH 24/31] Tweak variations

---
 resources/js/components/ui/Alert.vue | 2 ++
 resources/js/pages/Playground.vue    | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 8ac6a4ec85..5bfe2b70e8 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -34,6 +34,8 @@ const alertClasses = computed(() => {
             '[&_h5]:mb-1 [&_h5]:font-bold',
             '[&_h6]:mb-1 [&_h6]:font-bold',
             '[&_[data-ui-heading]]:mb-1 [&_[data-ui-heading]]:font-bold',
+            '[&_[data-ui-heading].text-lg]:-mt-1',
+            '[&_[data-ui-heading].text-2xl]:mt-[-0.45rem] [&_[data-ui-heading].text-2xl]:mb-2',
             '[&_p:not(:last-child)]:mb-3',
             '[&_[data-ui-description]:not(:last-child)]:mb-3',
             '[&_code]:px-0.75 [&_code]:mx-0.5 [&_code]:py-0.5 [&_code]:rounded-sm [&_code]:text-xs',
diff --git a/resources/js/pages/Playground.vue b/resources/js/pages/Playground.vue
index 35efa4b68b..369202de3c 100644
--- a/resources/js/pages/Playground.vue
+++ b/resources/js/pages/Playground.vue
@@ -340,7 +340,7 @@ defineProps(['icons']);
                 </Alert>
                 <Alert variant="success">
                     <Heading size="2xl">Backup Completed Very Successfully</Heading>
-                    <Description>I wouldn't recommend such a massive heading, but it's here for testing purposes. Your site backup has been created and saved to <a href="https://statamic.dev"><code>/storage/backups/site-2032-01-15.tar.gz</code></a>. The backup includes all content, assets, and configuration files.</Description>
+                    <Description>Such a massive heading isn't recommended, but here it is for testing purposes. Your site backup has been created and saved to <a href="https://statamic.dev"><code>/storage/backups/site-2032-01-15.tar.gz</code></a>. The backup includes all content, assets, and configuration files.</Description>
                 </Alert>
                 <Alert variant="error">
                     <Heading level="2">Database Connection Failed</Heading>

From 5f2ddb300dca2127a1fff2af3037be62a5ee23c6 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Wed, 21 Jan 2026 17:17:37 +0000
Subject: [PATCH 25/31] Finish documenting using Alerts with
 Heading/Description components

---
 resources/js/components/ui/Alert.vue  |  3 +-
 resources/js/stories/Alert.stories.ts | 89 ++++++++++++++++++++++++++-
 resources/js/stories/docs/Alert.mdx   |  4 +-
 3 files changed, 92 insertions(+), 4 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 5bfe2b70e8..3845502e51 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -26,7 +26,7 @@ const ariaLive = computed(() => {
 const alertClasses = computed(() => {
     return cva({
         base: [
-            'relative flex items-start gap-3 rounded-xl border p-4 [&:has(p)]:py-5 [&:has(p)]:pb-6 [&:has([data-ui-description])]:py-5 [&:has([data-ui-description])]:pb-6 text-sm',
+            'relative flex items-start gap-3 rounded-xl border p-4 [&:has(p)]:py-5 [&:has(p)]:pb-6 [&:has([data-ui-description])]:py-5 text-sm',
             '[&_h1]:mb-1 [&_h1]:font-bold',
             '[&_h2]:mb-1 [&_h2]:font-bold',
             '[&_h3]:mb-1 [&_h3]:font-bold',
@@ -34,6 +34,7 @@ const alertClasses = computed(() => {
             '[&_h5]:mb-1 [&_h5]:font-bold',
             '[&_h6]:mb-1 [&_h6]:font-bold',
             '[&_[data-ui-heading]]:mb-1 [&_[data-ui-heading]]:font-bold',
+            '[&_[data-ui-heading]]:-mt-0.5',
             '[&_[data-ui-heading].text-lg]:-mt-1',
             '[&_[data-ui-heading].text-2xl]:mt-[-0.45rem] [&_[data-ui-heading].text-2xl]:mb-2',
             '[&_p:not(:last-child)]:mb-3',
diff --git a/resources/js/stories/Alert.stories.ts b/resources/js/stories/Alert.stories.ts
index a4409e1c55..7bd4368929 100644
--- a/resources/js/stories/Alert.stories.ts
+++ b/resources/js/stories/Alert.stories.ts
@@ -1,5 +1,5 @@
 import type {Meta, StoryObj} from '@storybook/vue3';
-import {Alert} from '@ui';
+import {Alert, Heading, Description} from '@ui';
 import {icons} from './icons';
 
 const meta = {
@@ -160,6 +160,22 @@ const richContentCode = `
         <h4>Failed to Connect to Database</h4>
         <p>Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</p>
     </Alert>
+    <Alert variant="default">
+        <Heading>Base Size (default)</Heading>
+        <Description>This heading uses the default base size with Heading and Description components.</Description>
+    </Alert>
+    <Alert variant="warning">
+        <Heading size="lg">Large Size</Heading>
+        <Description>Here's an example of a larger heading with Heading and Description components. The Alert component automatically adjusts spacing for larger headings.</Description>
+    </Alert>
+    <Alert variant="success">
+        <Heading size="xl">Extra Large Size</Heading>
+        <Description>Here's an example of an extra large heading with Heading and Description components.</Description>
+    </Alert>
+    <Alert variant="success">
+        <Heading size="2xl">2XL Size</Heading>
+        <Description>Here's an example of the largest heading size with Heading and Description components. Note the adjusted spacing for larger headings.</Description>
+    </Alert>
 </div>
 `;
 
@@ -181,6 +197,22 @@ const richContentTemplate = `
         <h4>Failed to Connect to Database</h4>
         <p>Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</p>
     </Alert>
+    <Alert variant="default">
+        <Heading>Base Size (default)</Heading>
+        <Description>This heading uses the default base size with Heading and Description components.</Description>
+    </Alert>
+    <Alert variant="warning">
+        <Heading size="lg">Large Size</Heading>
+        <Description>Here's an example of a larger heading with Heading and Description components. The Alert component automatically adjusts spacing for larger headings.</Description>
+    </Alert>
+    <Alert variant="success">
+        <Heading size="xl">Extra Large Size</Heading>
+        <Description>Here's an example of an extra large heading with Heading and Description components.</Description>
+    </Alert>
+    <Alert variant="success">
+        <Heading size="2xl">2XL Size</Heading>
+        <Description>Here's an example of the largest heading size with Heading and Description components. Note the adjusted spacing for larger headings.</Description>
+    </Alert>
 </div>
 `;
 
@@ -188,16 +220,20 @@ export const RichContent: Story = {
     argTypes: {
         text: { control: { disable: true } },
         variant: { control: { disable: true } },
+        icon: { control: { disable: true } },
     },
     parameters: {
         docs: {
+            description: {
+                story: 'The Alert component supports both native HTML elements (h1-h6, p) and the Heading/Description components. Heading components support different sizes: `base`, `lg`, `xl`, and `2xl`. The Alert component automatically adjusts spacing for larger headings and both approaches receive consistent styling and color inheritance.',
+            },
             source: {
                 code: richContentCode,
             },
         },
     },
     render: () => ({
-        components: { Alert },
+        components: { Alert, Heading, Description },
         template: richContentTemplate,
     }),
 };
@@ -222,3 +258,52 @@ export const Success: Story = {
         variant: 'success',
     },
 };
+
+const headingAndDescriptionCode = `
+<div class="space-y-3">
+    <Alert variant="default">
+        <Heading>Using Heading Component</Heading>
+        <Description>This alert uses the Heading and Description components instead of native HTML elements.</Description>
+    </Alert>
+    <Alert variant="warning">
+        <Heading size="lg">Warning: Action Required</Heading>
+        <Description>This is a warning alert with a larger heading with Heading and Description components. The Heading component supports different sizes and inherits the alert's color scheme.</Description>
+    </Alert>
+    <Alert variant="success">
+        <Heading size="xl">Backup Completed Successfully</Heading>
+        <Description>This is an extra large heading with Heading and Description components. Your site backup has been created and saved to <code>/storage/backups/site-2032-01-15.tar.gz</code>. The backup includes all content, assets, and configuration files.</Description>
+    </Alert>
+    <Alert variant="error">
+        <Heading level="2">Database Connection Failed</Heading>
+        <Description>This is a heading level <code>2</code> example, with no heading size difference. Unable to establish a connection to the database server. Please check your database configuration in <code>.env</code> and ensure the database server is running.</Description>
+    </Alert>
+    <Alert variant="warning">
+        <Heading icon="warning-diamond">Migration Required</Heading>
+        <Description>This is a heading with an icon with Heading and Description components. The importer uses Laravel's job batching feature to keep track of the import progress, however, it requires a <code>job_batches</code> table in your database. Before you can run the importer, you will need to run <code>php artisan migrate</code>.</Description>
+    </Alert>
+</div>
+`;
+
+export const WithHeadingAndDescription: Story = {
+    tags: ['!dev'],
+    argTypes: {
+        text: { control: { disable: true } },
+        variant: { control: { disable: true } },
+        icon: { control: { disable: true } },
+    },
+    parameters: {
+        docs: {
+            description: {
+                story: 'The Alert component fully supports the Heading and Description components. When used together, they automatically inherit the Alert\'s variant colors and receive proper spacing and typography styles. This provides a consistent API whether you use native HTML elements (h1-h6, p) or the Heading/Description components.',
+            },
+            source: {
+                code: headingAndDescriptionCode,
+            },
+        },
+    },
+    render: () => ({
+        components: { Alert, Heading, Description },
+        template: headingAndDescriptionCode,
+    }),
+};
+
diff --git a/resources/js/stories/docs/Alert.mdx b/resources/js/stories/docs/Alert.mdx
index fcb375e745..ff35fb76e0 100644
--- a/resources/js/stories/docs/Alert.mdx
+++ b/resources/js/stories/docs/Alert.mdx
@@ -24,7 +24,9 @@ Instead of using the `text` prop, you can use the default slot to provide custom
 <Canvas of={AlertStories.SlotContent} sourceState={'shown'} />
 
 ## Rich Content
-Alerts support rich content including headings, paragraphs, and code snippets, making them ideal for detailed messages and instructions. All heading levels (h1–h6) are styled identically, so choose the heading level that's semantically appropriate for your content.
+Alerts support rich content including headings, paragraphs, and code snippets, making them ideal for detailed messages and instructions. You can use either native HTML elements (h1–h6, p) or the Heading/Description components—both approaches receive consistent styling and color inheritance.
+
+All heading levels (h1–h6) are styled identically, so choose the heading level that's semantically appropriate for your content. If you want to adjust the size of the headings, you can use the Heading component and specify a size (`base`, `lg`, `xl`, or `2xl`). The Alert component automatically adjusts spacing for larger headings.
 
 <Canvas of={AlertStories.RichContent} sourceState={'shown'} />
 

From 127ffdcbfb77d34e2c62126cbaa76b0dbe9ba0c2 Mon Sep 17 00:00:00 2001
From: Jason Varga <jason@pixelfear.com>
Date: Wed, 21 Jan 2026 14:40:19 -0500
Subject: [PATCH 26/31] heading prop and use heading/description components

---
 resources/js/components/ui/Alert.vue  |  9 +++++---
 resources/js/pages/Playground.vue     |  7 ++++++
 resources/js/stories/Alert.stories.ts | 31 +++++++++++++++++++++++++--
 resources/js/stories/docs/Alert.mdx   |  7 +++++-
 4 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 3845502e51..ede61af1fa 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -1,11 +1,13 @@
 <script setup>
 import { computed } from 'vue';
 import { cva } from 'cva';
-import Icon from './Icon/Icon.vue';
+import { Icon, Heading, Description } from '@ui';
 
 const props = defineProps({
     /** The alert message to display */
     text: { type: [String, Number, Boolean, null], default: null },
+    /** The alert heading to display */
+    heading: { type: [String, null], default: null },
     /** Controls the appearance of the alert. <br><br> Options: `default`, `warning`, `error`, `success` */
     variant: { type: String, default: 'default' },
     /** Icon name to display. [Browse available icons](/?path=/story/components-icon--all-icons) */
@@ -74,7 +76,7 @@ const alertClasses = computed(() => {
 
 const defaultIcon = computed(() => {
     if (props.icon) return props.icon;
-    
+
     switch (props.variant) {
         case 'warning':
             return 'warning-diamond';
@@ -104,7 +106,8 @@ const defaultIcon = computed(() => {
         />
         <div class="flex-1 min-w-0">
             <slot>
-                <span v-html="text" />
+                <Heading v-if="heading" :text="heading" />
+                <Description :text="text" />
             </slot>
         </div>
     </div>
diff --git a/resources/js/pages/Playground.vue b/resources/js/pages/Playground.vue
index ee3263c0aa..a422f38555 100644
--- a/resources/js/pages/Playground.vue
+++ b/resources/js/pages/Playground.vue
@@ -307,6 +307,13 @@ defineProps(['icons']);
                 <Alert variant="error" text="This is an error alert message" />
                 <Alert variant="success" text="This is a success alert message" />
                 <Alert variant="warning" icon="git" text="This alert has a custom icon" />
+
+                <Alert variant="default" heading="Alert Heading" text="This is a default alert message" />
+                <Alert variant="warning" heading="Alert Heading" text="This is a warning alert message" />
+                <Alert variant="error" heading="Alert Heading" text="This is an error alert message" />
+                <Alert variant="success" heading="Alert Heading" text="This is a success alert message" />
+                <Alert variant="warning" heading="Alert Heading" icon="git" text="This alert has a custom icon" />
+
                 <Alert variant="success">
                     <strong>Success!</strong> This alert uses a slot for custom content.
                 </Alert>
diff --git a/resources/js/stories/Alert.stories.ts b/resources/js/stories/Alert.stories.ts
index 7bd4368929..940606067b 100644
--- a/resources/js/stories/Alert.stories.ts
+++ b/resources/js/stories/Alert.stories.ts
@@ -28,7 +28,7 @@ export const Default: Story = {
 };
 
 const defaultCode = `
-<Alert variant="default" text="This is a default alert message" />
+<Alert text="This is a default alert message" />
 `;
 
 export const _DocsIntro: Story = {
@@ -40,7 +40,7 @@ export const _DocsIntro: Story = {
     },
     render: () => ({
         components: { Alert },
-        template: defaultCode,
+        template: `<div class="flex flex-col gap-2">${defaultCode}</div>`,
     }),
 };
 
@@ -108,6 +108,33 @@ export const CustomIcons: Story = {
     }),
 };
 
+
+
+const headingsCode = `
+<Alert heading="New Feature Available" text="We've added support for..." />
+`;
+
+export const Headings: Story = {
+    argTypes: {
+        icon: { control: { disable: true } },
+        text: { control: { disable: true } },
+        variant: { control: { disable: true } },
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: headingsCode,
+            },
+        },
+    },
+    render: () => ({
+        components: { Alert },
+        template: `
+            <Alert heading="New Feature Available" text="We've added support for custom field types. You can now create your own field types by extending the <code>Fieldtype</code> class. Check out the documentation for more details." />
+        `,
+    }),
+};
+
 const slotContentCode = `
 <Alert variant="success">
     <strong>Success!</strong> This alert uses a slot for custom content.
diff --git a/resources/js/stories/docs/Alert.mdx b/resources/js/stories/docs/Alert.mdx
index ff35fb76e0..062c702f88 100644
--- a/resources/js/stories/docs/Alert.mdx
+++ b/resources/js/stories/docs/Alert.mdx
@@ -18,8 +18,13 @@ You can override the default icon by passing a custom `icon` prop with the name
 
 <Canvas of={AlertStories.CustomIcons} sourceState={'shown'} />
 
+## Headings
+You can use the `heading` prop to prepend a heading.
+
+<Canvas of={AlertStories.Headings} sourceState={'shown'} />
+
 ## Slot Content
-Instead of using the `text` prop, you can use the default slot to provide custom content with HTML formatting.
+Instead of using the `text` and `heading` props, you can use the default slot to provide custom content with HTML formatting.
 
 <Canvas of={AlertStories.SlotContent} sourceState={'shown'} />
 

From 15544e706fa33ae58ee402002770e1eeef482348 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Thu, 22 Jan 2026 09:59:30 +0000
Subject: [PATCH 27/31] Fix color inconsistencies

---
 resources/js/components/ui/Alert.vue | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index ede61af1fa..e18ffe1792 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -52,22 +52,22 @@ const alertClasses = computed(() => {
                     '[&_[data-ui-description]]:text-gray-700! dark:[&_[data-ui-description]]:text-gray-300!',
                 ],
                 warning: [
-                    'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-300',
+                    'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800! dark:text-amber-300',
                     '[&_code]:bg-amber-200/50! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/8! dark:[&_code]:text-amber-200!',
                     '[&_[data-ui-heading]]:text-amber-800! dark:[&_[data-ui-heading]]:text-amber-300!',
-                    '[&_[data-ui-description]]:text-amber-700! dark:[&_[data-ui-description]]:text-amber-200!',
+                    '[&_[data-ui-description]]:text-amber-800! dark:[&_[data-ui-description]]:text-amber-200!',
                 ],
                 error: [
                     'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
                     '[&_code]:bg-red-200/50! [&_code]:text-red-800! dark:[&_code]:bg-red-300/8! dark:[&_code]:text-red-200!',
                     '[&_[data-ui-heading]]:text-red-800! dark:[&_[data-ui-heading]]:text-red-300!',
-                    '[&_[data-ui-description]]:text-red-700! dark:[&_[data-ui-description]]:text-red-200!',
+                    '[&_[data-ui-description]]:text-red-800! dark:[&_[data-ui-description]]:text-red-200!',
                 ],
                 success: [
                     'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
                     '[&_code]:bg-emerald-200/50! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/8! dark:[&_code]:text-emerald-200!',
                     '[&_[data-ui-heading]]:text-emerald-800! dark:[&_[data-ui-heading]]:text-emerald-300!',
-                    '[&_[data-ui-description]]:text-emerald-700! dark:[&_[data-ui-description]]:text-emerald-200!',
+                    '[&_[data-ui-description]]:text-emerald-800! dark:[&_[data-ui-description]]:text-emerald-200!',
                 ],
             },
         },

From 52a474b416f833217ae367ac5c3dd387e51fd101 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Thu, 22 Jan 2026 10:09:24 +0000
Subject: [PATCH 28/31] Fix color inconsistencies

---
 resources/js/components/ui/Alert.vue | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index e18ffe1792..af5f74f0cf 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -46,10 +46,10 @@ const alertClasses = computed(() => {
         variants: {
             variant: {
                 default: [
-                    'bg-gray-50 dark:bg-gray-900/50 border-gray-200 dark:border-gray-700/80 text-gray-900 dark:text-gray-100',
+                    'bg-gray-50 dark:bg-gray-900/50 border-gray-200 dark:border-gray-700/80 text-gray-800 dark:text-gray-100',
                     '[&_code]:bg-gray-200! [&_code]:text-gray-800! dark:[&_code]:bg-gray-800! dark:[&_code]:text-gray-200!',
-                    '[&_[data-ui-heading]]:text-gray-900! dark:[&_[data-ui-heading]]:text-gray-100!',
-                    '[&_[data-ui-description]]:text-gray-700! dark:[&_[data-ui-description]]:text-gray-300!',
+                    '[&_[data-ui-heading]]:text-gray-800! dark:[&_[data-ui-heading]]:text-gray-100!',
+                    '[&_[data-ui-description]]:text-gray-800! dark:[&_[data-ui-description]]:text-gray-300!',
                 ],
                 warning: [
                     'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800! dark:text-amber-300',

From c4dc1aefdc2559923cd5a5296f982cc224bb3960 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Thu, 22 Jan 2026 10:13:43 +0000
Subject: [PATCH 29/31] Fix dark icon colors

---
 resources/js/components/ui/Alert.vue | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index af5f74f0cf..62e9196efb 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -50,24 +50,28 @@ const alertClasses = computed(() => {
                     '[&_code]:bg-gray-200! [&_code]:text-gray-800! dark:[&_code]:bg-gray-800! dark:[&_code]:text-gray-200!',
                     '[&_[data-ui-heading]]:text-gray-800! dark:[&_[data-ui-heading]]:text-gray-100!',
                     '[&_[data-ui-description]]:text-gray-800! dark:[&_[data-ui-description]]:text-gray-300!',
+                    'dark:[&_svg]:text-gray-400',
                 ],
                 warning: [
                     'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800! dark:text-amber-300',
                     '[&_code]:bg-amber-200/50! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/8! dark:[&_code]:text-amber-200!',
                     '[&_[data-ui-heading]]:text-amber-800! dark:[&_[data-ui-heading]]:text-amber-300!',
                     '[&_[data-ui-description]]:text-amber-800! dark:[&_[data-ui-description]]:text-amber-200!',
+                    'dark:[&_svg]:text-amber-300',
                 ],
                 error: [
                     'bg-red-50 dark:bg-red-300/6 border-red-200 dark:border-red-400/25 text-red-800 dark:text-red-300',
                     '[&_code]:bg-red-200/50! [&_code]:text-red-800! dark:[&_code]:bg-red-300/8! dark:[&_code]:text-red-200!',
                     '[&_[data-ui-heading]]:text-red-800! dark:[&_[data-ui-heading]]:text-red-300!',
                     '[&_[data-ui-description]]:text-red-800! dark:[&_[data-ui-description]]:text-red-200!',
+                    'dark:[&_svg]:text-red-300',
                 ],
                 success: [
                     'bg-emerald-50 dark:bg-emerald-300/6 border-emerald-200 dark:border-emerald-400/25 text-emerald-800 dark:text-emerald-300',
                     '[&_code]:bg-emerald-200/50! [&_code]:text-emerald-800! dark:[&_code]:bg-emerald-300/8! dark:[&_code]:text-emerald-200!',
                     '[&_[data-ui-heading]]:text-emerald-800! dark:[&_[data-ui-heading]]:text-emerald-300!',
                     '[&_[data-ui-description]]:text-emerald-800! dark:[&_[data-ui-description]]:text-emerald-200!',
+                    'dark:[&_svg]:text-emerald-300',
                 ],
             },
         },

From f4cb913c4e06c3c9b6d7492741eeacccb2d96757 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Thu, 22 Jan 2026 10:21:23 +0000
Subject: [PATCH 30/31] Dark mode fix

---
 resources/js/components/ui/Alert.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 62e9196efb..987cafa104 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -53,7 +53,7 @@ const alertClasses = computed(() => {
                     'dark:[&_svg]:text-gray-400',
                 ],
                 warning: [
-                    'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800! dark:text-amber-300',
+                    'bg-amber-50 dark:bg-amber-300/6 border-amber-200 dark:border-amber-400/25 text-amber-800 dark:text-amber-200',
                     '[&_code]:bg-amber-200/50! [&_code]:text-amber-800! dark:[&_code]:bg-amber-300/8! dark:[&_code]:text-amber-200!',
                     '[&_[data-ui-heading]]:text-amber-800! dark:[&_[data-ui-heading]]:text-amber-300!',
                     '[&_[data-ui-description]]:text-amber-800! dark:[&_[data-ui-description]]:text-amber-200!',

From cc09401ca3f61ea3cf2f6099d8884eb208385ed6 Mon Sep 17 00:00:00 2001
From: Jay George <contact@jaygeorge.co.uk>
Date: Thu, 22 Jan 2026 10:26:22 +0000
Subject: [PATCH 31/31] Fix inconsistency

---
 resources/js/components/ui/Alert.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resources/js/components/ui/Alert.vue b/resources/js/components/ui/Alert.vue
index 987cafa104..4ccc13cb42 100644
--- a/resources/js/components/ui/Alert.vue
+++ b/resources/js/components/ui/Alert.vue
@@ -28,7 +28,7 @@ const ariaLive = computed(() => {
 const alertClasses = computed(() => {
     return cva({
         base: [
-            'relative flex items-start gap-3 rounded-xl border p-4 [&:has(p)]:py-5 [&:has(p)]:pb-6 [&:has([data-ui-description])]:py-5 text-sm',
+            'relative flex items-start gap-3 rounded-xl border p-4 [&:has(p)]:py-5 [&:has([data-ui-description])]:py-5 text-sm',
             '[&_h1]:mb-1 [&_h1]:font-bold',
             '[&_h2]:mb-1 [&_h2]:font-bold',
             '[&_h3]:mb-1 [&_h3]:font-bold',