From a65771caa793dea883bbc1306f964fc6f324f040 Mon Sep 17 00:00:00 2001
From: codecalm <codecalm@gmail.com>
Date: Wed, 16 Sep 2026 17:45:54 +0200
Subject: [PATCH] Document how to compile Tom Select's Sass against Tabler 1.5

---
 docs/content/ui/getting-started/upgrade.mdx | 10 ++++++++++
 docs/content/ui/plugins/advanced-select.mdx | 13 +++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/content/ui/getting-started/upgrade.mdx b/docs/content/ui/getting-started/upgrade.mdx
index ff052fee2..bbeaa28ea 100644
--- a/docs/content/ui/getting-started/upgrade.mdx
+++ b/docs/content/ui/getting-started/upgrade.mdx
@@ -292,6 +292,16 @@ The `*.rtl.css` files are still published, so nothing breaks if you keep them. S
 
 - **ApexCharts** moved from 3.54 to 7.0. If you install ApexCharts yourself, update it too and read the [ApexCharts changelog](https://github.com/apexcharts/apexcharts.js/releases) - the major versions renamed several options. Charts also read `--chart-{id}-color-{index}` variables now.
 - **Tabler Icons** moved to 3.46, and **Tabler Illustrations** to 1.16.
+- **Tom Select** cannot be compiled from its Sass sources against Tabler anymore. Its `tom-select.bootstrap5.scss` reads Bootstrap variables such as `$border-color` and passes them to `color.adjust()`, but in Tabler these are now CSS variables like `var(--gray-200)`, which is not a color to Sass. Use the compiled `tom-select.bootstrap5.css` instead, or set the two variables Tom Select adjusts to plain colors before importing it:
+
+  ```scss
+  // `as *` keeps Tabler's variables visible to the @import below
+  @use '@tabler/core/scss/tabler' as *;
+
+  $select-color-text: #182433;
+  $select-color-item-border: #e6e7e9;
+  @import 'tom-select/dist/scss/tom-select.bootstrap5';
+  ```
 
 ## Browser support
 
diff --git a/docs/content/ui/plugins/advanced-select.mdx b/docs/content/ui/plugins/advanced-select.mdx
index 6685af8ec..2615de98e 100644
--- a/docs/content/ui/plugins/advanced-select.mdx
+++ b/docs/content/ui/plugins/advanced-select.mdx
@@ -41,6 +41,19 @@ Or include it from a CDN. You need both the script and its stylesheet:
 <script src="${site.cdnUrl}/dist/libs/tom-select/dist/js/tom-select.base.min.js"></script>`}
 />
 
+### Compiling the Sass sources
+
+Use the compiled `tom-select.bootstrap5.css`. Tom Select's Sass sources read Bootstrap variables such as `$border-color` and pass them to `color.adjust()`, and in Tabler those variables hold CSS custom properties like `var(--gray-200)`, so Sass stops with `$color: var(--gray-200) is not a color`. If you still want to compile it, set the variables Tom Select adjusts to plain colors first:
+
+```scss
+// `as *` keeps Tabler's variables visible to the @import below
+@use '@tabler/core/scss/tabler' as *;
+
+$select-color-text: #182433;
+$select-color-item-border: #e6e7e9;
+@import 'tom-select/dist/scss/tom-select.bootstrap5';
+```
+
 ## Usage
 
 ### Basic select