Refactor box-shadow variables in SCSS for improved customization and consistency

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.changeset/docs-css-variables-font-sizes.md

@@ -0,0 +1,5 @@
+---
+"@tabler/docs": patch
+---
+
+Updated documentation to explain font sizing and system color CSS variables (`--tblr-primary-rgb`, `--tblr-secondary`, `--tblr-tertiary`, `--tblr-link-color`, `--tblr-gray-*`).

.changeset/update-shadow-tokens.md

@@ -0,0 +1,5 @@
+---
+"@tabler/core": patch
+---
+
+Updated shadow tokens (`--tblr-shadow-*`) to use the new `xs`–`2xl` and `overlay` values.

.cursor/rules/branch-naming.mdc

@@ -0,0 +1,38 @@
+---
+description: Git Branch Naming Rules
+globs:
+alwaysApply: true
+---
+
+## Branch naming
+
+- Use lowercase branch names.
+- Use a type prefix and a short description in kebab-case.
+- Format: `<type>/<short-description>` or `<type>/<issue-id>-<short-description>`
+- Use `gh-123` as the issue id format (avoid `#` in branch names).
+
+### Allowed types
+
+- `feat` - new features
+- `fix` - bug fixes
+- `docs` - documentation changes
+- `chore` - maintenance / tooling
+- `refactor` - code refactoring (no behavior change)
+- `test` - tests only
+- `build` - build system changes
+- `ci` - CI changes
+- `perf` - performance improvements
+- `style` - formatting / lint-only changes
+- `revert` - reverting prior changes
+
+### Examples
+
+- `feat/gh-123-add-stepper-component`
+- `fix/markdown-table-overflow`
+- `docs/gh-45-update-contributing`
+- `chore/update-pnpm-lock`
+
+### Notes
+
+- Branch off `dev` by default (unless maintainers request otherwise).
+- Avoid spaces, uppercase letters, and special characters other than `/` and `-`.

.cursor/rules/pull-request.mdc

@@ -0,0 +1,39 @@
+---
+description: Pull Request Title & Description Rules
+globs:
+alwaysApply: true
+---
+
+## Pull request title
+
+- Write PR titles in **English**.
+- Start the title with a **capital letter**.
+- Use **present tense** and keep it concise (ideally <= 72 chars).
+- Avoid a trailing period.
+
+### Examples
+
+- `Improve markdown table overflow handling`
+- `Clarify contributing branch naming`
+- `Add onboarding stepper page`
+
+## Pull request description
+
+- Write PR descriptions in **English**.
+- Focus on **why** the change is needed and what user-visible effect it has.
+- Keep it skimmable: bullets, short paragraphs, clear headings.
+
+### Recommended template
+
+```md
+## Summary
+- <1–3 bullets describing the change and why>
+
+## Changes
+- <key implementation notes, non-obvious decisions>
+```
+
+### Notes
+
+- If you changed SCSS or any package behavior, add a **changeset** describing it (one sentence, with backticks for code elements).
+- If a PR is WIP, mark it as draft and prefix the title with `WIP:` only while it is not ready for review.

core/scss/_variables.scss

@@ -495,6 +495,11 @@ $line-heights: (
   h4: $h4-line-height,
   h5: $h5-line-height,
   h6: $h6-line-height,
+
+  base: $line-height-base,
+  sm: $line-height-sm,
+  lg: $line-height-lg,
+  xl: $line-height-xl,
 ) !default;
 
 $display-font-sizes: (
@@ -981,21 +986,36 @@ $aspect-ratios: (
 ) !default;
 
 // Shadows
-$box-shadow: color-transparent(var(--#{$prefix}body-color), 0.04) 0 2px 4px 0 !default;
-$box-shadow-sm: 0 0.125rem 0.25rem rgba($black, 0.075) !default;
-$box-shadow-lg: 0 1rem 3rem rgba($black, 0.175) !default;
+$box-shadow-xs: 0 1px 2px 0 rgba(18, 18, 23, 0.05) !default;
+$box-shadow-sm: 0 1px 3px 0 rgba(18, 18, 23, 0.1), 0 1px 2px 0 rgba(18, 18, 23, 0.06) !default;
+$box-shadow-md: 0px 2px 4px -1px rgba(18, 18, 23, 0.06), 0px 4px 6px -1px rgba(18, 18, 23, 0.08) !default;
+$box-shadow-lg: 0px 4px 6px -2px rgba(18, 18, 23, 0.05), 0px 10px 15px -3px rgba(18, 18, 23, 0.08) !default;
+$box-shadow-xl: 0px 10px 10px -5px rgba(18, 18, 23, 0.04), 0px 20px 25px -5px rgba(18, 18, 23, 0.10) !default;
+$box-shadow-2xl: 0px 25px 50px -12px rgba(18, 18, 23, 0.25) !default;
+$box-shadow-overlay:
+  0px 2px 4px 0px rgba(18, 18, 23, 0.04),
+  0px 5px 8px 0px rgba(18, 18, 23, 0.04),
+  0px 10px 18px 0px rgba(18, 18, 23, 0.03),
+  0px 24px 48px 0px rgba(18, 18, 23, 0.03),
+  0px 0px 0px 1px rgba(18, 18, 23, 0.10) !default;
+
+$box-shadow: $box-shadow-md !default;
 $box-shadow-transparent: 0 0 0 0 transparent !default;
-$box-shadow-border: inset 0 0 0 1px var(--#{$prefix}border-color-translucent) !default;
-$box-shadow-input: 0 1px 1px color-transparent(var(--#{$prefix}body-color), 0.06) !default;
-$box-shadow-card: 0px 1px 3px rgba(0, 0, 0, 0.08) !default;
-$box-shadow-card-hover: color-transparent(var(--#{$prefix}body-color), 0.16) 0 2px 16px 0 !default;
-$box-shadow-dropdown:
-  0 16px 24px 2px rgba(0, 0, 0, 0.07),
-  0 6px 30px 5px rgba(0, 0, 0, 0.06),
-  0 8px 10px -5px rgba(0, 0, 0, 0.1) !default;
+$box-shadow-border: 0px 0px 0px 1px rgba(18, 18, 23, 0.10) !default;
+$box-shadow-input: $box-shadow-xs !default;
+$box-shadow-card: $box-shadow-sm !default;
+$box-shadow-card-hover: $box-shadow-lg !default;
+$box-shadow-dropdown: $box-shadow-overlay !default;
 
 $box-shadows: (
   null: $box-shadow,
+  xs: $box-shadow-xs,
+  sm: $box-shadow-sm,
+  md: $box-shadow-md,
+  lg: $box-shadow-lg,
+  xl: $box-shadow-xl,
+  '2xl': $box-shadow-2xl,
+  overlay: $box-shadow-overlay,
   border: $box-shadow-border,
   transparent: $box-shadow-transparent,
   input: $box-shadow-input,

core/scss/ui/_markdown.scss

@@ -1,8 +1,12 @@
+$markdown-font-size: var(--#{$prefix}font-size-h3) !default;
+$markdown-line-height: var(--#{$prefix}line-height-lg) !default;
+
 /**
 Markdown
  */
 .markdown {
-  line-height: $line-height-xl;
+  line-height: $markdown-line-height;
+  font-size: $markdown-font-size;
 
   > :first-child {
     margin-top: 0;

docs/content/ui/getting-started/customize.md

@@ -27,6 +27,35 @@ Now you just need to tell Tabler to use your favorite font:
 </style>
 ```
 
+## Custom font sizes
+
+Tabler exposes typography settings as CSS variables. You can override them by setting variables on `:root` (global) or on any container (scoped).
+
+### Base font size
+
+To change the default font size used by body text and many components, override `--tblr-body-font-size`:
+
+```html
+<style>
+  :root {
+    --tblr-body-font-size: 1rem;
+  }
+</style>
+```
+
+### Headings
+
+Headings use `--tblr-font-size-h1` … `--tblr-font-size-h6` and `--tblr-line-height-h1` … `--tblr-line-height-h6`:
+
+```html
+<style>
+  :root {
+    --tblr-font-size-h1: 2rem;
+    --tblr-line-height-h1: 2.5rem;
+  }
+</style>
+```
+
 ## Custom primary color
 
 To change the primary color of Tabler you need to set the `--tblr-primary` variable in your CSS. You can use any color format you like (hex, rgb, hsl, etc). In this example we will use a custom red color:
@@ -34,7 +63,56 @@ To change the primary color of Tabler you need to set the `--tblr-primary` varia
 ```html
 <style>
   :root {
-	 --tblr-primary: #F11D46;
+    --tblr-primary: #f11d46;
   }
 </style>
-```
+```
+
+If you use `--tblr-primary` in `rgba()` contexts (or see inconsistent colors), also override `--tblr-primary-rgb` (as comma-separated RGB values) and optionally `--tblr-primary-fg` (text/icon color used on primary backgrounds):
+
+```html
+<style>
+  :root {
+    --tblr-primary: #f11d46;
+    --tblr-primary-rgb: 241, 29, 70;
+    --tblr-primary-fg: #fff;
+  }
+</style>
+```
+
+## Other system colors
+
+Tabler also exposes a few "system" colors you can customize globally:
+
+```html
+<style>
+  :root {
+    --tblr-secondary: #6b7280;
+    --tblr-tertiary: #9ca3af;
+    --tblr-link-color: #066fd1;
+    --tblr-link-hover-color: #045db0;
+  }
+</style>
+```
+
+### Gray scale
+
+You can override the full gray palette (`--tblr-gray-50` … `--tblr-gray-950`) to match your brand:
+
+```html
+<style>
+  :root {
+    --tblr-gray-50: #f9fafb;
+    --tblr-gray-100: #f3f4f6;
+    --tblr-gray-200: #e5e7eb;
+    --tblr-gray-300: #d1d5db;
+    --tblr-gray-400: #9ca3af;
+    --tblr-gray-500: #6b7280;
+    --tblr-gray-600: #4b5563;
+    --tblr-gray-700: #374151;
+    --tblr-gray-800: #1f2937;
+    --tblr-gray-900: #111827;
+    --tblr-gray-950: #030712;
+  }
+</style>
+```

docs/content/ui/getting-started/how-to-contribute.md

@@ -30,7 +30,8 @@ Follow these steps to set up Tabler for development:
 3. Create a new branch for your changes:
 
    ```bash
-   git checkout -b your-branch-name
+   # Use the project branch naming convention, e.g.:
+   git checkout -b fix/markdown-table-overflow
 	```
 
 ## Development

package.json

@@ -34,7 +34,7 @@
     "js-beautify": "^1.15.4",
     "markdownlint-cli": "^0.47.0",
     "nodemon": "^3.1.11",
-    "pnpm": "^10.6.5",
+    "pnpm": "^10.27.0",
     "postcss": "^8.5.6",
     "postcss-cli": "^11.0.1",
     "prettier": "^3.7.4",

pnpm-lock.yaml

@@ -52,8 +52,8 @@ importers:
         specifier: ^3.1.11
         version: 3.1.11
       pnpm:
-        specifier: ^10.6.5
-        version: 10.6.5
+        specifier: ^10.27.0
+        version: 10.27.0
       postcss:
         specifier: ^8.5.6
         version: 8.5.6
@@ -439,8 +439,8 @@ packages:
       search-insights:
         optional: true
 
-  '@emnapi/runtime@1.7.1':
-    resolution: {integrity: sha512-PVtJr5CmLwYAU9PZDMITZoR5iAOShYREoR45EyyLrbntV50mdePTgUn4AmOw90Ifcj+x2kRjdzr1HP3RrNiHGA==}
+  '@emnapi/runtime@1.8.1':
+    resolution: {integrity: sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==}
 
   '@epic-web/invariant@1.0.0':
     resolution: {integrity: sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA==}
@@ -1394,6 +1394,9 @@ packages:
   caniuse-lite@1.0.30001762:
     resolution: {integrity: sha512-PxZwGNvH7Ak8WX5iXzoK1KPZttBXNPuaOvI2ZYU7NrlM+d9Ov+TUvlLOBNGzVXAntMSMMlJPd+jY6ovrVjSmUw==}
 
+  caniuse-lite@1.0.30001763:
+    resolution: {integrity: sha512-mh/dGtq56uN98LlNX9qdbKnzINhX0QzhiWBFEkFfsFO4QyCvL8YegrJAazCwXIeqkIob8BlZPGM3xdnY+sgmvQ==}
+
   caseless@0.12.0:
     resolution: {integrity: sha512-4tYFyifaFfGacoiObjJegolkwSU4xQNGbVgUiNYVUxbQ2x2lUsFvY4hVgVzGiIe6WLOPqycWXA40l+PWsxthUw==}
 
@@ -2711,8 +2714,8 @@ packages:
   plyr@3.8.3:
     resolution: {integrity: sha512-0+iI5uw0WRvtKBpgPCkmQQv7ucHVQKTEo6UFJjgJ8cy/JZhy0dQqshHQVitHXV6l2O3MzhgnuvQ95VSkWcWeSw==}
 
-  pnpm@10.6.5:
-    resolution: {integrity: sha512-zfko/KIIMs1Z7FOCZJK33CXcUk1DcLa0rb9lgD0y76psHIgUfArk6NV5psnuxxV1e1DU+jXuoXnYaOraTtBDrw==}
+  pnpm@10.27.0:
+    resolution: {integrity: sha512-ctaZ2haxF5wUup5k3HHJpAmIy9xlwmTLDkidt96RfyDc9NZNhyNiXylpulLUt+KhFwaC2awqXcrqq3MrfhbwSg==}
     engines: {node: '>=18.12'}
     hasBin: true
 
@@ -3903,7 +3906,7 @@ snapshots:
     transitivePeerDependencies:
       - '@algolia/client-search'
 
-  '@emnapi/runtime@1.7.1':
+  '@emnapi/runtime@1.8.1':
     dependencies:
       tslib: 2.8.1
     optional: true
@@ -4101,7 +4104,7 @@ snapshots:
 
   '@img/sharp-wasm32@0.34.5':
     dependencies:
-      '@emnapi/runtime': 1.7.1
+      '@emnapi/runtime': 1.8.1
     optional: true
 
   '@img/sharp-win32-arm64@0.34.5':
@@ -4669,6 +4672,8 @@ snapshots:
 
   caniuse-lite@1.0.30001762: {}
 
+  caniuse-lite@1.0.30001763: {}
+
   caseless@0.12.0: {}
 
   ccount@2.0.1: {}
@@ -5851,7 +5856,7 @@ snapshots:
     dependencies:
       '@next/env': 16.0.4
       '@swc/helpers': 0.5.15
-      caniuse-lite: 1.0.30001762
+      caniuse-lite: 1.0.30001763
       postcss: 8.4.31
       react: 19.2.0
       react-dom: 19.2.0(react@19.2.0)
@@ -6060,7 +6065,7 @@ snapshots:
       rangetouch: 2.0.1
       url-polyfill: 1.1.13
 
-  pnpm@10.6.5: {}
+  pnpm@10.27.0: {}
 
   postcss-cli@11.0.1(postcss@8.5.6)(tsx@4.21.0):
     dependencies:

shared/layouts/docs/default.html

@@ -64,13 +64,12 @@
 		rel="stylesheet" />
 	{% endfor %}
 
-
 	{% if docs-libs -%}
-	{% for lib in libs.css -%}
+	{% for lib in libs -%}
 	{% if docs-libs contains lib[0] -%}
-	{% for file in lib[1] -%}
+	{% for file in lib[1].css -%}
 	<link
-		href="{% if file contains 'http://' or file contains 'https://' %}{{ file }}{% else %}{{ page | relative }}/libs/{% if environment != 'development' %}{{ file | replace: '@', '' }}{% else %}{{ file }}{% endif %}{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}{% endif %}"
+		href="{% if file contains 'http://' or file contains 'https://' %}{{ file }}{% else %}/dist/libs/{{ lib[1].npm }}/{% if environment != 'development' %}{{ file | replace: '@', '' }}{% else %}{{ file }}{% endif %}{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}{% endif %}"
 		rel="stylesheet" />
 	{% endfor -%}
 	{% endif -%}