diff --git a/.changeset/quiet-melons-live.md b/.changeset/quiet-melons-live.md
new file mode 100644
index 000000000..024afc74e
--- /dev/null
+++ b/.changeset/quiet-melons-live.md
@@ -0,0 +1,5 @@
+---
+"@tabler/core": patch
+---
+
+Improve documentation for alerts
diff --git a/docs/ui/components/alerts.mdx b/docs/ui/components/alerts.mdx
index dd595c8b5..8629ed99c 100644
--- a/docs/ui/components/alerts.mdx
+++ b/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"
Wow! Everything worked!
Your account has been saved!
@@ -28,106 +32,48 @@ Depending on the information you need to convey, you can use one of the followin
```
-```html
-
-
Wow! Everything worked!
-
Your account has been saved!
-
-```
-
## 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
-
```
## 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
+
+```
+
+```html example vertical background="surface" columns={2} centered separated height="420px"
-
-
-
-
-
-
Wow! Everything worked!
-
Your account has been saved!
-
+
+
Wow! Everything worked!
+
Your account has been saved!
-
-
-
-
-
-
Did you know?
-
Here is something that you might like to know.
-
+
+
Did you know?
+
Here is something that you might like to know.
-
-
-
-
-
-
Uh oh, something went wrong
-
Sorry! There was a problem with your request.
-
+
+
Uh oh, something went wrong
+
Sorry! There was a problem with your request.
-
-
-
-
-
-
I'm so sorry…
-
Your account has been deleted and can't be restored.
-
-
-
-
-```
-
-```html
-
-
-
-
-
-
-
-
Wow! Everything worked!
-
Your account has been saved!
-
+
+
I'm so sorry…
+
Your account has been deleted and can't be restored.
@@ -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
+Use `alert-icon` class for `