Improve documentation for alerts (#2055)

Co-authored-by: Paweł Kuna <[email protected]>

.changeset/quiet-melons-live.md

@@ -0,0 +1,5 @@
+---
+"@tabler/core": patch
+---
+
+Improve documentation for alerts

docs/ui/components/alerts.mdx

@@ -9,7 +9,11 @@ description: Alert messages for user notifications.
 
 Depending on the information you need to convey, you can use one of the following types of alert messages - **success**, **info**, **warning** or **danger**. Using the right type of alert modal will help draw users' attention to the message and prompt them to take action.
 
-```html example vertical columns={2} centered separated
+Combine `alert` class with one of the following: `alert-success`, `alert-info`, `alert-warning`, `alert-danger` to get the alert that you need.
+
+Alert classes affect the color of all the text inside an alert. Use another class, e.g. `text-secondary` to change the color of the alert's content.
+
+```html example vertical background="surface" columns={2} centered separated height="420px"
 <div class="alert alert-success" role="alert">
   <h4 class="alert-title">Wow! Everything worked!</h4>
   <div class="text-secondary">Your account has been saved!</div>
@@ -28,106 +32,48 @@ Depending on the information you need to convey, you can use one of the followin
 </div>
 ```
 
-```html
-<div class="alert alert-success" role="alert">
-  <h4 class="alert-title">Wow! Everything worked!</h4>
-  <div class="text-secondary">Your account has been saved!</div>
-</div>
-```
-
 ## Alert links
 
-Add a link to your alert message to redirect users to the details they need to complete or additional information they should read.
+Add a link to your alert message to redirect users to the details they need to complete or additional information they should read. Use `alert-link` class to style the link and match the text color.
 
-```html example vertical columns={2} centered
-<div class="alert alert-danger m-0">
-  This is a danger alert — <a href="#" class="alert-link">check it out</a>!
-</div>
+```html example vertical background="surface" columns={2} centered height="120px"
+<div class="alert alert-danger m-0">This is a danger alert — <a href="#" class="alert-link">check it out</a>!</div>
 ```
 
 ## Dismissible alerts
 
 Add the `x` close button to make an alert modal dismissible. Thanks to that, your alert modal will disappear only once the user closes it.
 
-```html example vertical columns={2} centered separated
+```html
+<a class="btn-close" data-bs-dismiss="alert" aria-label="close"></a>
+```
+
+```html example vertical background="surface" columns={2} centered separated height="420px"
 <div class="alert alert-success alert-dismissible" role="alert">
-  <div class="d-flex">
-    <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
-        <path stroke="none" d="M0 0h24v24H0z" fill="none" />
-        <path d="M5 12l5 5l10 -10" />
-      </svg>
-    </div>
-    <div>
-      <h4 class="alert-title">Wow! Everything worked!</h4>
-      <div class="text-secondary">Your account has been saved!</div>
-    </div>
+  <div>
+    <h4 class="alert-title">Wow! Everything worked!</h4>
+    <div class="text-secondary">Your account has been saved!</div>
   </div>
   <a class="btn-close" data-bs-dismiss="alert" aria-label="close"></a>
 </div>
 <div class="alert alert-info alert-dismissible" role="alert">
-  <div class="d-flex">
-    <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
-        <path stroke="none" d="M0 0h24v24H0z" fill="none" />
-        <circle cx="12" cy="12" r="9" />
-        <line x1="12" y1="8" x2="12.01" y2="8" />
-        <polyline points="11 12 12 12 12 16 13 16" />
-      </svg>
-    </div>
-    <div>
-      <h4 class="alert-title">Did you know?</h4>
-      <div class="text-secondary">Here is something that you might like to know.</div>
-    </div>
+  <div>
+    <h4 class="alert-title">Did you know?</h4>
+    <div class="text-secondary">Here is something that you might like to know.</div>
   </div>
   <a class="btn-close" data-bs-dismiss="alert" aria-label="close"></a>
 </div>
 <div class="alert alert-warning alert-dismissible" role="alert">
-  <div class="d-flex">
-    <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
-        <path stroke="none" d="M0 0h24v24H0z" fill="none" />
-        <path d="M12 9v2m0 4v.01" />
-        <path d="M5 19h14a2 2 0 0 0 1.84 -2.75l-7.1 -12.25a2 2 0 0 0 -3.5 0l-7.1 12.25a2 2 0 0 0 1.75 2.75" />
-      </svg>
-    </div>
-    <div>
-      <h4 class="alert-title">Uh oh, something went wrong</h4>
-      <div class="text-secondary">Sorry! There was a problem with your request.</div>
-    </div>
+  <div>
+    <h4 class="alert-title">Uh oh, something went wrong</h4>
+    <div class="text-secondary">Sorry! There was a problem with your request.</div>
   </div>
   <a class="btn-close" data-bs-dismiss="alert" aria-label="close"></a>
 </div>
 <div class="alert alert-danger alert-dismissible" role="alert">
-  <div class="d-flex">
-    <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
-        <path stroke="none" d="M0 0h24v24H0z" fill="none" />
-        <circle cx="12" cy="12" r="9" />
-        <line x1="12" y1="8" x2="12" y2="12" />
-        <line x1="12" y1="16" x2="12.01" y2="16" />
-      </svg>
-    </div>
-    <div>
-      <h4 class="alert-title">I'm so sorry&hellip;</h4>
-      <div class="text-secondary">Your account has been deleted and can't be restored.</div>
-    </div>
-  </div>
-  <a class="btn-close" data-bs-dismiss="alert" aria-label="close"></a>
-</div>
-```
-
-```html
-<div class="alert alert-success alert-dismissible" role="alert">
-  <div class="d-flex">
-    <div>
-      <!-- SVG icon from http://tabler.io/icons/icon/check -->
-      <svg>...</svg>
-    </div>
-    <div>
-      <h4 class="alert-title">Wow! Everything worked!</h4>
-      <div class="text-secondary">Your account has been saved!</div>
-    </div>
+  <div>
+    <h4 class="alert-title">I'm so sorry&hellip;</h4>
+    <div class="text-secondary">Your account has been deleted and can't be restored.</div>
   </div>
   <a class="btn-close" data-bs-dismiss="alert" aria-label="close"></a>
 </div>
@@ -137,28 +83,24 @@ Add the `x` close button to make an alert modal dismissible. Thanks to that, you
 
 Add an icon to your alert modal to make it more user-friendly and help users easily identify the message.
 
-```html
-<div class="alert alert-success" role="alert">
-  <div class="d-flex">
-    <div>
-      <!-- SVG icon from http://tabler.io/icons/icon/check -->
-      <svg>...</svg>
-    </div>
-    <div>
-      <h4 class="alert-title">Wow! Everything worked!</h4>
-      <div class="text-secondary">Your account has been saved!</div>
-    </div>
-  </div>
-</div>
-```
-
-To see how the icon affects the alert modal, look at the example below.
+Use `alert-icon` class for `<svg>` or `<i>`, when using webfont, to provide the proper styling.
 
-```html example vertical columns={2} centered separated
+```html example vertical background="surface" columns={2} centered separated height="420px"
 <div class="alert alert-success" role="alert">
   <div class="d-flex">
     <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="icon alert-icon"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        stroke-width="2"
+        stroke="currentColor"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
         <path stroke="none" d="M0 0h24v24H0z" fill="none" />
         <path d="M5 12l5 5l10 -10" />
       </svg>
@@ -172,7 +114,18 @@ To see how the icon affects the alert modal, look at the example below.
 <div class="alert alert-info" role="alert">
   <div class="d-flex">
     <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="icon alert-icon"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        stroke-width="2"
+        stroke="currentColor"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
         <path stroke="none" d="M0 0h24v24H0z" fill="none" />
         <circle cx="12" cy="12" r="9" />
         <line x1="12" y1="8" x2="12.01" y2="8" />
@@ -188,7 +141,18 @@ To see how the icon affects the alert modal, look at the example below.
 <div class="alert alert-warning" role="alert">
   <div class="d-flex">
     <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="icon alert-icon"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        stroke-width="2"
+        stroke="currentColor"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
         <path stroke="none" d="M0 0h24v24H0z" fill="none" />
         <path d="M12 9v2m0 4v.01" />
         <path d="M5 19h14a2 2 0 0 0 1.84 -2.75l-7.1 -12.25a2 2 0 0 0 -3.5 0l-7.1 12.25a2 2 0 0 0 1.75 2.75" />
@@ -203,7 +167,18 @@ To see how the icon affects the alert modal, look at the example below.
 <div class="alert alert-danger" role="alert">
   <div class="d-flex">
     <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="icon alert-icon"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        stroke-width="2"
+        stroke="currentColor"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
         <path stroke="none" d="M0 0h24v24H0z" fill="none" />
         <circle cx="12" cy="12" r="9" />
         <line x1="12" y1="8" x2="12" y2="12" />
@@ -218,13 +193,11 @@ To see how the icon affects the alert modal, look at the example below.
 </div>
 ```
 
-
-
 ## Alert with avatar
 
 Add an avatar to your alert modal to make it more personalized.
 
-```html example vertical columns={2} centered separated
+```html example vertical background="surface" columns={2} centered separated height="420px"
 <div class="alert alert-success" role="alert">
   <div class="d-flex">
     <div>
@@ -271,10 +244,14 @@ Add an avatar to your alert modal to make it more personalized.
 
 Add primary and secondary buttons to your alert modals if you want users to take a particular action based on the information included in the modal message.
 
-```html example vertical columns={2} centered separated
+Buttons don't inherit the alert's color, so you should set the proper class if you want it to be matched. For example, `btn-success` for `alert-success`.
+
+```html example vertical background="surface" columns={2} centered separated height="740px"
 <div class="alert alert-success alert-dismissible" role="alert">
   <h3 class="mb-1">Some Title</h3>
-  <p>Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.</p>
+  <p class="text-secondary">
+    Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.
+  </p>
   <div class="btn-list">
     <a href="#" class="btn btn-success">Okay</a>
     <a href="#" class="btn">Cancel</a>
@@ -283,7 +260,9 @@ Add primary and secondary buttons to your alert modals if you want users to take
 </div>
 <div class="alert alert-info alert-dismissible" role="alert">
   <h3 class="mb-1">Some Title</h3>
-  <p>Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.</p>
+  <p class="text-secondary">
+    Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.
+  </p>
   <div class="btn-list">
     <a href="#" class="btn btn-info">Okay</a>
     <a href="#" class="btn">Cancel</a>
@@ -292,7 +271,9 @@ Add primary and secondary buttons to your alert modals if you want users to take
 </div>
 <div class="alert alert-warning alert-dismissible" role="alert">
   <h3 class="mb-1">Some Title</h3>
-  <p>Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.</p>
+  <p class="text-secondary">
+    Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.
+  </p>
   <div class="btn-list">
     <a href="#" class="btn btn-warning">Okay</a>
     <a href="#" class="btn">Cancel</a>
@@ -301,7 +282,9 @@ Add primary and secondary buttons to your alert modals if you want users to take
 </div>
 <div class="alert alert-danger alert-dismissible" role="alert">
   <h3 class="mb-1">Some Title</h3>
-  <p>Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.</p>
+  <p class="text-secondary">
+    Lorem ipsum Minim ad pariatur eiusmod ea ut nulla aliqua est quis id dolore minim voluptate.
+  </p>
   <div class="btn-list">
     <a href="#" class="btn btn-danger">Okay</a>
     <a href="#" class="btn">Cancel</a>
@@ -312,35 +295,53 @@ Add primary and secondary buttons to your alert modals if you want users to take
 
 ## Important alerts
 
-If you want your alert to be really eye-catching, you can add a class `alert-important`.
+If you want your alert to be really eye-catching, you can add a `alert-important` class. It will use the selected color as a background for the alert.
 
 ```html
-<div class="alert alert-important alert-success alert-dismissible" role="alert">
-  ...
-</div>
+<div class="alert alert-important alert-success alert-dismissible" role="alert">...</div>
 ```
 
-Look at the example below to see how the important alert affects the alert modal.
+You can also use other elements, like icons and dismissible buttons, with this type of alert.
 
 ```html example vertical columns={2} centered separated
 <div class="alert alert-important alert-success alert-dismissible" role="alert">
   <div class="d-flex">
     <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="icon alert-icon"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        stroke-width="2"
+        stroke="currentColor"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
         <path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
         <path d="M5 12l5 5l10 -10"></path>
       </svg>
     </div>
-    <div>
-      Wow! Everything worked!
-    </div>
+    <div>Wow! Everything worked!</div>
   </div>
   <a class="btn-close btn-close-white" data-bs-dismiss="alert" aria-label="close"></a>
 </div>
 <div class="alert alert-important alert-danger alert-dismissible" role="alert">
   <div class="d-flex">
     <div>
-      <svg xmlns="http://www.w3.org/2000/svg" class="icon alert-icon" width="24" height="24" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        class="icon alert-icon"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        stroke-width="2"
+        stroke="currentColor"
+        fill="none"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
         <path stroke="none" d="M0 0h24v24H0z" fill="none" />
         <circle cx="12" cy="12" r="9" />
         <line x1="12" y1="8" x2="12" y2="12" />
@@ -353,3 +354,33 @@ Look at the example below to see how the important alert affects the alert modal
 </div>
 ```
 
+## Custom alert's color
+
+You're not limited to the 4 default alert's colors. You can use any [base or social color](../base/colors) you want.
+
+```html example vertical background="surface" columns={2} centered separated height="420px"
+<div class="alert alert-lime" role="alert">
+  <h4 class="alert-title">Wow! Everything worked!</h4>
+  <div class="text-secondary">Your account has been saved!</div>
+</div>
+<div class="alert alert-cyan" role="alert">
+  <h4 class="alert-title">Did you know?</h4>
+  <div class="text-secondary">Here is something that you might like to know.</div>
+</div>
+<div class="alert alert-facebook" role="alert">
+  <h4 class="alert-title">You have a new friend on Facebook</h4>
+  <div class="text-secondary">Say hello to your new friend!</div>
+</div>
+<div class="alert alert-instagram alert-dismissible alert-important" role="alert">
+  <div class="d-flex">
+    <div>
+      <span class="avatar me-3" style="background-image: url(/static/samples/avatars/035f.jpg)"></span>
+    </div>
+    <div>
+      <h4 class="alert-title">Sophia just added a new post on Instagram</h4>
+      <div>Be the first to see it!</div>
+    </div>
+  </div>
+  <a class="btn-close" data-bs-dismiss="alert" aria-label="close"></a>
+</div>
+```