From b75f4fdac02502f9fe1e27318c64036e80da9269 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Sun, 13 Sep 2026 12:44:35 -0700 Subject: [PATCH 1/2] Add token playground to theme docs Show how theme and layout tokens flow to components. Readers change the radius, spacer, or primary color and see the button, input, alert, and card update together. The Remint control demonstrates how derived tokens (bg-subtle, fg, border) restate the theme today. --- .../shortcodes/TokenPlayground.astro | 358 ++++++++++++++++++ site/src/components/shortcodes/index.ts | 1 + site/src/content/docs/customize/theme.mdx | 8 + site/src/scss/_component-examples.scss | 48 +++ 4 files changed, 415 insertions(+) create mode 100644 site/src/components/shortcodes/TokenPlayground.astro diff --git a/site/src/components/shortcodes/TokenPlayground.astro b/site/src/components/shortcodes/TokenPlayground.astro new file mode 100644 index 0000000000..cc1ac5bce2 --- /dev/null +++ b/site/src/components/shortcodes/TokenPlayground.astro @@ -0,0 +1,358 @@ +--- +import Code from '@components/shortcodes/Code.astro' + +// Both menus move two steps of their scale rather than one, which is what +// changing the Sass base value does: `--radius-7` is `$radius * 1.5` and +// `--spacer-6` is `$spacer * 1.25` in scss/_config.scss. The components below +// read `--radius-5` and `--spacer` (button, input, alert) or `--radius-7` and +// `--spacer-6` (card), so driving both makes the whole group move together. +const defaultRadius = '0.5' +const defaultSpacer = '1' +const defaultColor = 'blue' + +const radiusOptions = ['0', '0.25', '0.5', '0.75', '1', '1.25', '1.5'] +const spacerOptions = ['0.75', '1', '1.25', '1.5'] + +const menus = [ + { control: 'radius', label: 'Radius', value: defaultRadius, options: radiusOptions }, + { control: 'spacer', label: 'Spacer', value: defaultSpacer, options: spacerOptions } +] + +const palette = [ + { name: 'blue', label: 'Blue' }, + { name: 'purple', label: 'Purple' }, + { name: 'pink', label: 'Pink' }, + { name: 'orange', label: 'Orange' }, + { name: 'green', label: 'Green' } +] + +// Today’s model: reminting `--bs-primary-base` alone recolors solid surfaces +// (button, badge) but leaves alerts, borders, and focus rings on the compiled +// blue pairing. To move the whole theme you must restate every derived token, +// which is what this snippet and the script below do. +const css = `.token-demo { + --bs-radius-5: ${defaultRadius}rem; + --bs-spacer: ${defaultSpacer}rem; + --bs-primary-base: var(--bs-${defaultColor}-500); + --bs-primary-bg: var(--bs-primary-base); + --bs-primary-bg-subtle: light-dark(var(--bs-${defaultColor}-100), var(--bs-${defaultColor}-900)); + --bs-primary-fg: light-dark(var(--bs-${defaultColor}-600), var(--bs-${defaultColor}-400)); + --bs-primary-border: light-dark(var(--bs-${defaultColor}-300), var(--bs-${defaultColor}-600)); +}` +--- + +
+
+
+ { + menus.map((menu) => ( +
+ + {menu.label} + + + +
+ )) + } + +
+ Primary +
+ { + palette.map((color) => ( + + )) + } +
+
+ +
+ Remint +
+ + +
+
+
+
+ +
+
+
+
+ + +
+ +
A token change reaches every component at once.
+ +
+
Card header
+
+

Card

+

Padding follows the spacer, corners follow the radius.

+
+
+
+
+ + +
+
+ + diff --git a/site/src/components/shortcodes/index.ts b/site/src/components/shortcodes/index.ts index 1bbf86b949..1165cd4a21 100644 --- a/site/src/components/shortcodes/index.ts +++ b/site/src/components/shortcodes/index.ts @@ -24,3 +24,4 @@ export { default as SpacingResponsive } from './SpacingResponsive.astro' export { default as Swatch } from './Swatch.astro' export { default as Table } from './Table.astro' export { default as TableContent } from './TableContent.md' +export { default as TokenPlayground } from './TokenPlayground.astro' diff --git a/site/src/content/docs/customize/theme.mdx b/site/src/content/docs/customize/theme.mdx index cd5a4e9303..c7ed926092 100644 --- a/site/src/content/docs/customize/theme.mdx +++ b/site/src/content/docs/customize/theme.mdx @@ -53,6 +53,14 @@ And within each semantic theme color, you’ll find the following keys, most of | `contrast` | Text color that needs to be readable on the `base` and `bg` colors | +## Token playground + +Every component reads the same theme and layout tokens, so one change reaches the whole group. Change the radius, the spacer, or the primary color below and watch the button, input, alert, and card update together. + + + +The **Remint** control shows how the theme works today. Set it to **All** and each color restates every derived token—`bg-subtle`, `fg`, `border`, and the rest—so the whole preview follows. Set it to **Base** and only `--bs-primary-base` and `--bs-primary-bg` change. The solid button recolors, but the alert keeps the compiled blue pairing, because its `bg-subtle`, `fg`, and `border` tokens still point at the blue palette on `:root`. + ## Theme colors Every token is available as a CSS variable, and most are then consumed by our utilities and components. So for the `primary` color, you have the following colors: diff --git a/site/src/scss/_component-examples.scss b/site/src/scss/_component-examples.scss index d2d1143024..0228a7ec7f 100644 --- a/site/src/scss/_component-examples.scss +++ b/site/src/scss/_component-examples.scss @@ -426,4 +426,52 @@ grid-template-columns: repeat(9, 1fr); } } + + // + // Token playground + // + + .bd-playground { + --bd-example-border-color: var(--bs-border-subtle); + + border: 1px solid var(--bd-example-border-color); + @include border-radius(var(--radius-5)); + + .bd-playground-controls { + border-bottom: 1px solid var(--bd-example-border-color); + @include border-top-radius(calc(var(--radius-5) - 1px)); + } + + .bd-code-snippet { + border: 0; + @include border-radius(0 0 calc(var(--radius-5) - 1px) calc(var(--radius-5) - 1px)); + } + + .menu-item.selected { + font-weight: var(--font-weight-semibold); + } + } + + .bd-token-swatch { + display: inline-flex; + align-items: center; + justify-content: center; + width: 1.75rem; + height: 1.75rem; + padding: 0; + color: var(--bs-white); + cursor: pointer; + border: 1px solid color-mix(in srgb, var(--bs-fg-body) 15%, transparent); + @include border-radius(var(--radius-4)); + + svg { + width: 1rem; + height: 1rem; + opacity: 0; + } + + &.selected svg { + opacity: 1; + } + } } From bab6fddd42c67aebd0f790f9a92d809af8e154ec Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Thu, 24 Sep 2026 20:42:32 -0700 Subject: [PATCH 2/2] Derive theme color pairings from --{name}-base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebuild $theme-colors through a new theme-color() helper so every pairing (fg, bg-subtle, border, focus-ring, …) derives from var(--{name}-base) with color-mix, instead of pointing at fixed palette stops. Add color-stop() and theme-blend() in _colors.scss and theme-pair() in _theme.scss to replay the palette recipe against the base. Default compiled colors are unchanged. One :root override of --bs-{name}-base now re-mints the whole set. Add a Root option to the token playground to demonstrate this, and document the mechanism, the cascade scope limits, and single-token overrides in theme.mdx. --- scss/_colors.scss | 28 +++++ scss/_theme.scss | 114 ++++++++---------- .../shortcodes/TokenPlayground.astro | 103 ++++++++++++---- site/src/content/docs/customize/theme.mdx | 69 ++++++++++- 4 files changed, 218 insertions(+), 96 deletions(-) diff --git a/scss/_colors.scss b/scss/_colors.scss index 20c4d05b66..31d232acbd 100644 --- a/scss/_colors.scss +++ b/scss/_colors.scss @@ -89,6 +89,34 @@ $color-shades: defaults( ); // scss-docs-end color-mix-options +// Replay a palette stop against any color, including a custom property. +// This lets theme pairings derive from `var(--{name}-base)` so a single +// base override re-mints the whole set. +// Ex: color-stop(var(--blue-500), 600) => color-mix(in oklch, var(--black) 16%, var(--blue-500)) +// scss-docs-start color-stop +@function color-stop($color, $stop) { + $stop: "#{$stop}"; + + @if $stop == "500" { + @return $color; + } @else if map.has-key($color-tints, $stop) { + @return color-mix(in #{$color-mix-space}, #{$tint-color} #{map.get($color-tints, $stop)}, #{$color}); + } @else if map.has-key($color-shades, $stop) { + @return color-mix(in #{$color-mix-space}, #{$shade-color} #{map.get($color-shades, $stop)}, #{$color}); + } + + @error "Unknown color stop `#{$stop}`. Use 500, a tint (#{map.keys($color-tints)}), or a shade (#{map.keys($color-shades)})."; +} +// scss-docs-end color-stop + +// Blend two stops of the same color. Keeps the value tied to `$color`, so it +// re-mints with the base. Ex: theme-blend(var(--indigo-500), 400, 300). +// scss-docs-start theme-blend +@function theme-blend($color, $stop-1, $stop-2, $weight: 50%) { + @return color-mix(in #{$color-mix-space}, #{color-stop($color, $stop-1)} #{$weight}, #{color-stop($color, $stop-2)}); +} +// scss-docs-end theme-blend + // scss-docs-start color-tokens $color-tokens: () !default; diff --git a/scss/_theme.scss b/scss/_theme.scss index d9404a9ec8..8f27670dec 100644 --- a/scss/_theme.scss +++ b/scss/_theme.scss @@ -1,4 +1,5 @@ @use "sass:map"; +@use "colors" as colors; @use "config" as *; @function theme-color-values($key) { @@ -46,6 +47,41 @@ @return $result; } +// Theme pairing helper +// +// Return one stop, or a `light-dark()` pairing of two stops, derived from +// `$color` (usually `var(--{name}-base)`). Ex: theme-pair($ref, 600, 400). +@function theme-pair($color, $light-stop, $dark-stop: null) { + @if $dark-stop == null { + @return colors.color-stop($color, $light-stop); + } + + @return light-dark(#{colors.color-stop($color, $light-stop)}, #{colors.color-stop($color, $dark-stop)}); +} + +// Build a theme color map +// +// Return the nine-key token map for a theme color. Every pairing derives from +// `var(--#{$name}-base)`, so one `:root` base override re-mints the whole set. +// `$overrides` merges on top for the few keys that break from the recipe. +@function theme-color($name, $base, $overrides: ()) { + $ref: var(--#{$name}-base); + + $defaults: ( + "base": $base, + "fg": theme-pair($ref, 600, 400), + "fg-emphasis": theme-pair($ref, 800, 300), + "bg": $ref, + "bg-subtle": theme-pair($ref, 100, 900), + "bg-muted": theme-pair($ref, 200, 800), + "border": theme-pair($ref, 300, 600), + "focus-ring": light-dark(#{color-mix(in oklch, #{$ref} 50%, var(--bg-body))}, #{color-mix(in oklch, #{$ref} 75%, var(--bg-body))}), + "contrast": var(--white), + ); + + @return map.merge($defaults, $overrides); +} + // Generate opacity values using color-mix() // $fallback lets the referenced $color-var fall back to another color (e.g. currentcolor) // when it hasn't been set by a companion color utility. @@ -110,72 +146,20 @@ $theme-colors: () !default; // stylelint-disable-next-line scss/dollar-variable-default $theme-colors: defaults( ( - "primary": ( - "base": var(--blue-500), - "fg": light-dark(var(--blue-600), var(--blue-400)), - "fg-emphasis": light-dark(var(--blue-800), var(--blue-200)), - "bg": var(--blue-500), - "bg-subtle": light-dark(var(--blue-100), var(--blue-900)), - "bg-muted": light-dark(var(--blue-200), var(--blue-800)), - "border": light-dark(var(--blue-300), var(--blue-600)), - "focus-ring": light-dark(color-mix(in oklch, var(--blue-500) 50%, var(--bg-body)), color-mix(in oklch, var(--blue-500) 75%, var(--bg-body))), - "contrast": var(--white) - ), - "accent": ( - "base": var(--indigo-500), - "fg": light-dark(var(--indigo-600), color-mix(in oklch, var(--indigo-400), var(--indigo-300))), - "fg-emphasis": light-dark(var(--indigo-800), var(--indigo-300)), - "bg": var(--indigo-500), - "bg-subtle": light-dark(var(--indigo-100), var(--indigo-900)), - "bg-muted": light-dark(var(--indigo-200), var(--indigo-800)), - "border": light-dark(var(--indigo-300), var(--indigo-600)), - "focus-ring": light-dark(color-mix(in oklch, var(--indigo-500) 50%, var(--bg-body)), color-mix(in oklch, var(--indigo-500) 75%, var(--bg-body))), - "contrast": var(--white) - ), - "success": ( - "base": var(--green-500), - "fg": light-dark(var(--green-600), var(--green-400)), - "fg-emphasis": light-dark(var(--green-800), var(--green-300)), - "bg": var(--green-500), - "bg-subtle": light-dark(var(--green-100), var(--green-900)), - "bg-muted": light-dark(var(--green-200), var(--green-800)), - "border": light-dark(var(--green-300), var(--green-600)), - "focus-ring": light-dark(color-mix(in oklch, var(--green-500) 50%, var(--bg-body)), color-mix(in oklch, var(--green-500) 75%, var(--bg-body))), - "contrast": var(--white) - ), - "danger": ( - "base": var(--red-500), - "fg": light-dark(var(--red-600), var(--red-400)), - "fg-emphasis": light-dark(var(--red-800), var(--red-300)), - "bg": var(--red-500), - "bg-subtle": light-dark(var(--red-100), var(--red-900)), - "bg-muted": light-dark(var(--red-200), var(--red-800)), - "border": light-dark(var(--red-300), var(--red-600)), - "focus-ring": light-dark(color-mix(in oklch, var(--red-500) 50%, var(--bg-body)), color-mix(in oklch, var(--red-500) 75%, var(--bg-body))), - "contrast": var(--white) - ), - "warning": ( - "base": var(--yellow-500), - "fg": light-dark(var(--yellow-700), var(--yellow-400)), - "fg-emphasis": light-dark(var(--yellow-800), var(--yellow-300)), - "bg": var(--yellow-500), - "bg-subtle": light-dark(var(--yellow-100), var(--yellow-900)), - "bg-muted": light-dark(var(--yellow-200), var(--yellow-800)), - "border": light-dark(var(--yellow-300), var(--yellow-600)), - "focus-ring": light-dark(color-mix(in oklch, var(--yellow-500) 50%, var(--bg-body)), color-mix(in oklch, var(--yellow-400) 85%, var(--bg-body))), - "contrast": var(--gray-900) - ), - "info": ( - "base": var(--cyan-500), - "fg": light-dark(var(--cyan-600), var(--cyan-400)), - "fg-emphasis": light-dark(var(--cyan-800), var(--cyan-300)), - "bg": var(--cyan-500), - "bg-subtle": light-dark(var(--cyan-100), var(--cyan-900)), - "bg-muted": light-dark(var(--cyan-200), var(--cyan-800)), - "border": light-dark(var(--cyan-300), var(--cyan-600)), - "focus-ring": light-dark(color-mix(in oklch, var(--cyan-500) 50%, var(--bg-body)), color-mix(in oklch, var(--cyan-500) 75%, var(--bg-body))), - "contrast": var(--gray-900) + "primary": theme-color("primary", var(--blue-500), ("fg-emphasis": theme-pair(var(--primary-base), 800, 200))), + "accent": theme-color("accent", var(--indigo-500), ("fg": light-dark(#{colors.color-stop(var(--accent-base), 600)}, #{colors.theme-blend(var(--accent-base), 400, 300)}))), + "success": theme-color("success", var(--green-500)), + "danger": theme-color("danger", var(--red-500)), + "warning": theme-color( + "warning", + var(--yellow-500), + ( + "fg": theme-pair(var(--warning-base), 700, 400), + "focus-ring": light-dark(#{color-mix(in oklch, var(--warning-base) 50%, var(--bg-body))}, #{color-mix(in oklch, #{colors.color-stop(var(--warning-base), 400)} 85%, var(--bg-body))}), + "contrast": var(--gray-900) + ) ), + "info": theme-color("info", var(--cyan-500), ("contrast": var(--gray-900))), "inverse": ( "base": var(--gray-900), "fg": light-dark(var(--gray-900), var(--gray-200)), diff --git a/site/src/components/shortcodes/TokenPlayground.astro b/site/src/components/shortcodes/TokenPlayground.astro index cc1ac5bce2..64a3962688 100644 --- a/site/src/components/shortcodes/TokenPlayground.astro +++ b/site/src/components/shortcodes/TokenPlayground.astro @@ -91,13 +91,13 @@ const css = `.token-demo {
Primary -
+
{ palette.map((color) => (
@@ -168,6 +172,7 @@ const css = `.token-demo { if (playground) { const target = playground.querySelector('[data-token-target]') + const root = document.documentElement const radiusControl = playground.querySelector('[data-control="radius"]') const spacerControl = playground.querySelector('[data-control="spacer"]') const colorControl = playground.querySelector('[data-control="color"]') @@ -188,6 +193,31 @@ const css = `.token-demo { return [...line.querySelectorAll('span')].filter((span) => span.childElementCount === 0) } + // Rewrite the selector on the snippet’s opening line (`.token-demo` ⇄ `:root`). + function setSelector(selector: string) { + const line = [...(code?.querySelectorAll('.line') ?? [])].find((candidate) => + (candidate.textContent ?? '').includes('{') + ) + + if (!line) { + return + } + + const leaves = leafSpans(line) + const brace = leaves.findIndex((span) => (span.textContent ?? '').includes('{')) + const selectorLeaves = brace === -1 ? leaves : leaves.slice(0, brace) + + if (selectorLeaves.length === 0) { + return + } + + selectorLeaves[0].textContent = `${selector} ` + + for (const extra of selectorLeaves.slice(1)) { + extra.textContent = '' + } + } + // Shiki splits values across spans, so collapse the value tokens on that // property’s line into a single rewrite. function setLineValue(property: string, value: string) { @@ -299,43 +329,64 @@ const css = `.token-demo { '--bs-primary-contrast': primary.contrast } + const isRoot = scope === 'root' + + // Radius and spacer always stay on the preview wrapper. target?.style.setProperty('--bs-radius-5', `${radius}rem`) target?.style.setProperty('--bs-radius-7', `${radius * 1.5}rem`) target?.style.setProperty('--bs-spacer', `${spacer}rem`) target?.style.setProperty('--bs-spacer-6', `${spacer * 1.25}rem`) - target?.style.setProperty('--bs-primary-base', primary.base) - target?.style.setProperty('--bs-primary-bg', primary.bg) - for (const [property, value] of Object.entries(derived)) { - if (scope === 'all') { - target?.style.setProperty(property, value) - } else { + if (isRoot) { + // One knob on `:root` re-mints every primary token, because the refactored + // `_theme.scss` derives each pairing from `--bs-primary-base`. Drop the + // wrapper overrides so the preview inherits the page-wide remint. + for (const property of ['--bs-primary-base', '--bs-primary-bg', ...Object.keys(derived)]) { target?.style.removeProperty(property) } + + root.style.setProperty('--bs-primary-base', primary.base) + } else { + // Leaving root scope: drop the page-wide override. + root.style.removeProperty('--bs-primary-base') + + target?.style.setProperty('--bs-primary-base', primary.base) + target?.style.setProperty('--bs-primary-bg', primary.bg) + + for (const [property, value] of Object.entries(derived)) { + if (scope === 'all') { + target?.style.setProperty(property, value) + } else { + target?.style.removeProperty(property) + } + } + } + + // Snippet: `:root { --bs-primary-base }` in root scope, else `.token-demo { … }`. + setSelector(isRoot ? ':root' : '.token-demo') + + const snippetLines: Record = { + '--bs-radius-5': !isRoot, + '--bs-spacer': !isRoot, + '--bs-primary-base': true, + '--bs-primary-bg': !isRoot, + '--bs-primary-bg-subtle': scope === 'all', + '--bs-primary-fg': scope === 'all', + '--bs-primary-border': scope === 'all' + } + + for (const [property, visible] of Object.entries(snippetLines)) { + lineFor(property)?.classList.toggle('d-none', !visible) } setLineValue('--bs-radius-5', `${radius}rem`) setLineValue('--bs-spacer', `${spacer}rem`) setLineValue('--bs-primary-base', primary.base) - // The derived lines in the snippet only appear in `all` scope. - const snippetDerived: Record = { - '--bs-primary-bg-subtle': primary.bgSubtle, - '--bs-primary-fg': primary.fg, - '--bs-primary-border': primary.border - } - - for (const [property, value] of Object.entries(snippetDerived)) { - const line = lineFor(property) - if (!line) { - continue - } - - line.classList.toggle('d-none', scope !== 'all') - - if (scope === 'all') { - setLineValue(property, value) - } + if (scope === 'all') { + setLineValue('--bs-primary-bg-subtle', primary.bgSubtle) + setLineValue('--bs-primary-fg', primary.fg) + setLineValue('--bs-primary-border', primary.border) } } diff --git a/site/src/content/docs/customize/theme.mdx b/site/src/content/docs/customize/theme.mdx index c7ed926092..5ebf6e6590 100644 --- a/site/src/content/docs/customize/theme.mdx +++ b/site/src/content/docs/customize/theme.mdx @@ -59,7 +59,55 @@ Every component reads the same theme and layout tokens, so one change reaches th -The **Remint** control shows how the theme works today. Set it to **All** and each color restates every derived token—`bg-subtle`, `fg`, `border`, and the rest—so the whole preview follows. Set it to **Base** and only `--bs-primary-base` and `--bs-primary-bg` change. The solid button recolors, but the alert keeps the compiled blue pairing, because its `bg-subtle`, `fg`, and `border` tokens still point at the blue palette on `:root`. +The **Remint** control shows the three ways to recolor. Set it to **All** and each color restates every derived token—`bg-subtle`, `fg`, `border`, and the rest—on the preview wrapper, so the whole group follows. Set it to **Base** and only `--bs-primary-base` and `--bs-primary-bg` change on the wrapper. The solid button recolors, but the alert keeps the compiled blue pairing, because a wrapper inherits the already-computed derived tokens from `:root`. Set it to **Root** and only `--bs-primary-base` changes, this time on `:root` itself. Each pairing derives from `--bs-primary-base`, so every derived token re-mints and every primary element on the page follows—one variable, not nine. + +## Reminting theme colors + +Each theme color builds its tokens from one base value. In `_theme.scss`, the `theme-color()` helper generates the nine tokens from `var(--{name}-base)` with the same tint and shade recipe as our [color palette]([[docsref:/customize/color/]]). So `--bs-primary-fg` is not a fixed palette stop—it is a `light-dark()` of two `color-mix()` values, each mixed against `var(--bs-primary-base)`. + +Because every derived token points back at the base, one override re-mints the whole set. Set the base on `:root` and the button, alert, border, and focus ring all follow: + +```css +:root { + --bs-primary-base: var(--bs-orange-500); +} +``` + +### Scope and the cascade + +CSS custom properties resolve where they are declared. Bootstrap declares the derived tokens on `:root`, so each `var(--bs-primary-base)` is substituted there. A descendant that resets `--bs-primary-base` inherits the already-resolved values, so the derived tokens do not re-mint: + +```css +.brand-region { + /* The solid button recolors, because it reads `--bs-primary-bg`. */ + /* The alert stays on the compiled pairing, because */ + /* `--bs-primary-bg-subtle` was already resolved on `:root`. */ + --bs-primary-base: var(--bs-orange-500); +} +``` + +To recolor a subtree, set the base on `:root`, or restate the tokens you need so they re-mint against the new base: + +```css +.brand-region { + --bs-primary-base: var(--bs-orange-500); + --bs-primary-bg-subtle: light-dark(var(--bs-orange-100), var(--bs-orange-900)); + --bs-primary-fg: light-dark(var(--bs-orange-600), var(--bs-orange-400)); + --bs-primary-border: light-dark(var(--bs-orange-300), var(--bs-orange-600)); +} +``` + +The **Remint** control in the playground shows this split. **Root** sets the base on `:root`, so every token follows. **Base** sets it on the wrapper, so only the solid surfaces move. + +### Override a single token + +You do not have to re-mint everything. Override any single token, on `:root` or a subtree, to step outside the recipe: + +```css +:root { + --bs-primary-focus-ring: var(--bs-primary-border); +} +``` ## Theme colors @@ -235,13 +283,22 @@ Here’s the same set of components rendered in both light and dark modes side b `} /> -Under the hood, token values like `--bs-primary-fg` resolve differently depending on the active color mode. For example, in our `_theme.scss`, the primary text color is defined as: +Under the hood, token values like `--bs-primary-fg` resolve differently depending on the active color mode. For example, in our `_theme.scss`, the primary text color derives from the base with `theme-pair()`: ```scss -"fg": light-dark(var(--blue-600), var(--blue-400)), +"fg": theme-pair(var(--primary-base), 600, 400), ``` -When `data-bs-theme="light"` is active (or the user’s system preference is light), this resolves to `var(--blue-600)`. In dark mode, it resolves to `var(--blue-400)`—a lighter shade that maintains readability against dark backgrounds. The same pattern applies to backgrounds, borders, and all other adaptive tokens. +That expands to a `light-dark()` of two `color-mix()` values, one per mode, each mixed against `var(--primary-base)`: + +```scss +"fg": light-dark( + color-mix(in oklch, var(--black) 16%, var(--primary-base)), // ≈ blue-600, light mode + color-mix(in oklch, var(--white) 20%, var(--primary-base)) // ≈ blue-400, dark mode +), +``` + +When `data-bs-theme="light"` is active (or the user’s system preference is light), the light value applies. In dark mode, the lighter value maintains readability against dark backgrounds. The same pattern applies to backgrounds, borders, and all other adaptive tokens. For more details on toggling color modes globally, building custom modes, and JavaScript toggler examples, see the [color modes documentation]([[docsref:/customize/color-modes/]]). @@ -319,7 +376,7 @@ The class sets each `--theme-*` custom property to `initial`. That makes the pro ## Theme Sass map -We use a large, nested Sass map to generate our theme color values. +We use a large, nested Sass map to generate our theme color values. Each built-in color runs through the `theme-color()` helper, which derives its pairing tokens from that color’s `base`. @@ -344,6 +401,8 @@ Configure `$theme-colors` through the main entrypoint with `@use ... with ()`. O Each theme color is a nested map, so the merge is one level deep. To change one sub-key of a built-in theme, pass the whole sub-map for that theme. For more detail, see the [Sass customization docs]([[docsref:/customize/sass#theme-color-map]]). +To recolor a built-in theme, you usually do not need Sass. Set `--bs-{name}-base` on `:root` and the pairings re-mint at runtime—see [Reminting theme colors](#reminting-theme-colors). Use the Sass map when you add or remove colors, or change the recipe. Colors you add through the map are used as authored, because the `theme-color()` derivation applies to the built-ins. Give a custom color the token keys its components need, or build the set yourself. + ## CSS variables CSS variables are generated from the `$theme-colors` Sass map at the `:root` level inside `_root.scss` using a Sass loop.