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 new file mode 100644 index 0000000000..64a3962688 --- /dev/null +++ b/site/src/components/shortcodes/TokenPlayground.astro @@ -0,0 +1,409 @@ +--- +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..5ebf6e6590 100644 --- a/site/src/content/docs/customize/theme.mdx +++ b/site/src/content/docs/customize/theme.mdx @@ -53,6 +53,62 @@ 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 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 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: @@ -227,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/]]). @@ -311,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`. @@ -336,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. 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; + } + } }