Add documentation for the tabler-themes stylesheet (#2901)

Co-authored-by: codecalm <codecalm@gmail.com>

.changeset/theme-base-colors-docs.md

@@ -0,0 +1,5 @@
+---
+"@tabler/docs": minor
+---
+
+Added a Theme base colors page documenting the five `data-bs-theme-base` gray palettes in `tabler-themes.css`.

docs/content/ui/getting-started/color-modes.mdx

@@ -2,7 +2,7 @@
 title: Color modes
 summary: Tabler ships a small theming script that switches your site between light, dark, and auto color modes, plus base gray shade, font, primary color, and corner radius - all without a page reload or a flash of the wrong theme.
 description: Set up Tabler's light, dark, and auto color modes, and learn the five theme attributes for base color, font, primary color, and corner radius.
-related: [/ui/getting-started/customize]
+related: [/ui/getting-started/customize, /ui/plugins/theme-base-colors]
 ---
 
 import { site } from '@shared/lib/site.ts';
@@ -20,7 +20,7 @@ Tabler includes a small script, [`tabler-theme.js`](https://github.com/tabler/ta
 | Primary color | `data-bs-theme-primary` | `blue` | `blue`, `azure`, `indigo`, `purple`, `pink`, `red`, `orange`, `yellow`, `lime`, `green`, `teal`, `cyan`, `inverted` |
 | Corner radius | `data-bs-theme-radius` | `1` | `0`, `0.5`, `1`, `1.5`, `2` |
 
-The `data-bs-theme-base` colors are the gray palettes that back every other color mode. See [issue #2894](https://github.com/tabler/tabler/issues/2894) for the dedicated page documenting each palette; this page only covers the script that switches between them.
+The `data-bs-theme-base` colors are the gray palettes that back every other color mode. See [Theme base colors](/ui/plugins/theme-base-colors) for every shade of every palette; this page only covers the script that switches between them.
 
 Each setting only appears on `<html>` when it differs from its default. For example, `data-bs-theme-primary="blue"` is never written because `blue` is already the default - the browser falls back to Tabler's built-in styles instead.
 

docs/content/ui/plugins/index.mdx

@@ -1,8 +1,8 @@
 ---
 title: Plugins
 order: 7
-description: Optional Tabler plugins - charts, calendars, editors, file uploads, flags, payment logos and social icons. Each one needs a file you load on demand.
+description: Optional Tabler plugins - charts, calendars, editors, file uploads, flags, payment logos, social icons and extra theme base colors. Each one needs a file you load on demand.
 summary: Tabler plugins extend the functionality of the framework, providing additional tools and features to enhance your projects and streamline the development process.
 ---
 
-Plugins add features that not every project needs, so none of them are part of the core CSS and JavaScript. Some wrap a third-party library, such as charts, calendars, file uploads or the WYSIWYG editor - those need that library on the page as well. Others, like country flags, payment provider logos and social icons, only ship an extra stylesheet. Either way you load a plugin on demand, and pages that need it list the files at the top.
+Plugins add features that not every project needs, so none of them are part of the core CSS and JavaScript. Some wrap a third-party library, such as charts, calendars, file uploads or the WYSIWYG editor - those need that library on the page as well. Others, like country flags, payment provider logos, social icons and extra theme base colors, only ship an extra stylesheet. Either way you load a plugin on demand, and pages that need it list the files at the top.

docs/content/ui/plugins/theme-base-colors.mdx

@@ -0,0 +1,91 @@
+---
+title: Theme base colors
+summary: The tabler-themes stylesheet ships five gray palettes - slate, gray, zinc, neutral, and stone - that you switch between with the data-bs-theme-base attribute.
+description: Load the tabler-themes plugin and switch between five gray base palettes (slate, gray, zinc, neutral, stone) with data-bs-theme-base.
+css-plugins: [themes]
+related: [/ui/getting-started/customize, /ui/getting-started/color-modes]
+---
+
+import CdnImportPlugin from '@components/CdnImportPlugin.astro';
+
+Every gray you see in Tabler - card backgrounds, borders, muted text, table stripes - is built from a `--tblr-gray-50` … `--tblr-gray-950` scale. By default that scale is Tabler's own `gray` palette. The `tabler-themes` stylesheet adds four more takes on the same scale - `slate`, `zinc`, `neutral`, and `stone` - so you can pick a cooler or warmer neutral without touching a single component's CSS.
+
+## Installation
+
+This part of Tabler is distributed as a plugin, separate from the core `tabler.css` bundle. To enable it, include `tabler-themes.css` (or `tabler-themes.min.css`) in your page, alongside the core stylesheet:
+
+<CdnImportPlugin plugins={['themes']} />
+
+If you compile Tabler from source with Sass, add its own entry point:
+
+```scss
+@use '@tabler/core/scss/tabler-themes';
+```
+
+## Base color palettes
+
+Set `data-bs-theme-base` on `<html>` to one of five values. `gray` is the default - Tabler looks the same with or without the attribute set to `gray`.
+
+| Value | Description |
+| --- | --- |
+| `gray` | Tabler's default neutral gray (no attribute needed) |
+| `slate` | A cooler, slightly blue-tinted gray |
+| `zinc` | A neutral, low-saturation gray |
+| `neutral` | A pure, desaturated gray |
+| `stone` | A warmer, slightly brown-tinted gray |
+
+```html
+<html data-bs-theme-base="slate">
+```
+
+Here is every shade of every palette, from lightest (`50`) to darkest (`950`):
+
+export const bases = {
+  slate: ['#f8fafc', '#f1f5f9', '#e2e8f0', '#cbd5e1', '#94a3b8', '#64748b', '#475569', '#334155', '#1e293b', '#0f172a', '#020617'],
+  gray: ['#f9fafb', '#f3f4f6', '#e5e7eb', '#d1d5db', '#9ca3af', '#6b7280', '#4b5563', '#374151', '#1f2937', '#111827', '#030712'],
+  zinc: ['#fafafa', '#f4f4f5', '#e4e4e7', '#d4d4d8', '#a1a1aa', '#71717a', '#52525b', '#3f3f46', '#27272a', '#18181b', '#09090b'],
+  neutral: ['#fafafa', '#f5f5f5', '#e5e5e5', '#d4d4d4', '#a3a3a3', '#737373', '#525252', '#404040', '#262626', '#171717', '#0a0a0a'],
+  stone: ['#fafaf9', '#f5f5f4', '#e7e5e4', '#d6d3d1', '#a8a29e', '#78716c', '#57534e', '#44403c', '#292524', '#1c1917', '#0c0a09'],
+};
+
+<div class="table-responsive">
+<table class="table card-table">
+<thead><tr><th>Base</th><th>50</th><th>100</th><th>200</th><th>300</th><th>400</th><th>500</th><th>600</th><th>700</th><th>800</th><th>900</th><th>950</th></tr></thead>
+<tbody>
+{Object.entries(bases).map(([name, shades]) => (
+<tr>
+<td>{name}</td>
+{shades.map((hex) => (
+<td><span style={{ display: 'inline-block', width: '24px', height: '24px', borderRadius: '6px', background: hex, border: '1px solid var(--tblr-border-color)' }} /></td>
+))}
+</tr>
+))}
+</tbody>
+</table>
+</div>
+
+## How it connects to `data-bs-theme-base`
+
+For each palette, the stylesheet redefines the eleven gray variables under an attribute selector:
+
+```css
+[data-bs-theme-base='slate'],
+[data-theme-base='slate'] {
+  --gray-50: #f8fafc;
+  /* … through --gray-950 */
+}
+```
+
+Every selector matches two attributes: `data-bs-theme-base` (Bootstrap's namespaced convention, the one Tabler's own theme script writes) and the shorter `data-theme-base` (for setups that don't use the `bs-` prefix). Set either one - you don't need both. The compiled CSS variables are published with Tabler's `tblr-` prefix, so in your own CSS you read them as `--tblr-gray-50` … `--tblr-gray-950`.
+
+<Info title="The stylesheet alone changes nothing">
+  Because it only redefines CSS variables, you still need `data-bs-theme-base` on `<html>` (or an ancestor) to pick a palette. Set it in markup, or let Tabler's theme script pick it up from a `?theme-base=slate` query parameter or `localStorage`.
+</Info>
+
+## Customizing further
+
+`tabler-themes.css` only covers the five built-in palettes. To use your own gray scale instead, override the same eleven variables directly, as shown in [Customize Tabler: gray scale](/ui/getting-started/customize#gray-scale) - you don't need this plugin at all if you only ever use one custom scale.
+
+## Accessibility
+
+Every built-in palette keeps roughly the same lightness steps as the default `gray` scale, so switching `theme-base` doesn't break the contrast that Tabler's components already rely on between text, borders, and surfaces. If you build a custom palette instead (see above), check that your `50` and `950` shades still give enough contrast against white and black text - large lightness jumps between adjacent steps can make borders disappear or muted text unreadable.

shared/data/docs.json

@@ -458,6 +458,10 @@
 							"title": "Social icons",
 							"url": "/ui/plugins/social-icons"
 						},
+						{
+							"title": "Theme base colors",
+							"url": "/ui/plugins/theme-base-colors"
+						},
 						{
 							"title": "Vector map",
 							"url": "/ui/plugins/vector-map"