Skip to main content

Customize

Tokens

How every RopeBreak.net design token maps onto a Bootstrap variable, and why the old token names still work.

Three layers

The theme keeps the two-layer model from @ropebreak/design and puts Bootstrap in the middle.

  1. Raw palette — $rb-* in Sass, --rb-* in CSS. Private. Components never reference it.
  2. Bootstrap — $primary, $body-bg, $spacers and the rest are set from the palette in scss/_variables.scss, and compile to --bs-*.
  3. Semantic compat — --color-*, --font-*, --space-*, --radius-*, --shadow-*, --duration-*, --ease-*, --z-*. Emitted by scss/_tokens.scss as aliases of the Bootstrap variables, so the two layers can never disagree.
/* compiled: dist/rb-bootstrap.css */
:root, [data-bs-theme="light"] {
  --rb-gold-700: #b8941f;            /* 1. raw */
  --bs-primary: #b8941f;             /* 2. Bootstrap */
  --color-accent: var(--bs-primary); /* 3. compat alias */
}

Write new CSS against layer 2. Keep old CSS on layer 3. Leave layer 1 alone.

Palette

Fourteen raw colors. Each exists three ways: a Sass variable you can override, a private --rb-* property, and a public --bs-* property (the theme adds them to Bootstrap's $colors map). The chips below are painted with var(--rb-…).

--rb-navy-50
#e8edf6
--rb-navy-100
#c8d2e6
--rb-navy-300
#5a73a8
--rb-navy-400
#4a6398
--rb-navy-500
#1e3a6e
--rb-navy-700
#122553
--rb-navy-900
#0a1b3d
--rb-gold-300
#e6c769
--rb-gold-500
#d4af37
--rb-gold-700
#b8941f
--rb-gold-800
#7e620d
--rb-cream-50
#faf3df
--rb-cream-100
#f4ecd8
--rb-cream-300
#d9cdb0
--rb-red-600
#b3261e
--rb-green-600
#277432
SassPrivatePublicUsed for
$rb-navy-900--rb-navy-900--bs-navy-900$dark, body text (light), body bg (dark), text on gold
$rb-navy-700--rb-navy-700--bs-navy-700$navy, link color (light), tertiary bg (dark)
$rb-navy-500--rb-navy-500--bs-navy-500$info, border color (dark)
$rb-navy-300--rb-navy-300--bs-navy-300$cyan, switch knob, $dark-border-subtle
$rb-navy-400--rb-navy-400--bs-navy-400$secondary, secondary text (light) — the text-safe step
$rb-navy-100, -50--rb-navy-100, -50--bs-navy-100, -50Subtle backgrounds and borders
$rb-gold-700--rb-gold-700--bs-gold-700$primary (light), bottom of the gold ramp
$rb-gold-800--rb-gold-800--bs-gold-800link hover, .btn-outline-primary label — the text-safe gold
$rb-gold-500--rb-gold-500--bs-gold-500$gold, primary (dark), $yellow
$rb-gold-300--rb-gold-300--bs-gold-300$warning, link color (dark), mark bg
$rb-cream-100--rb-cream-100--bs-cream-100$cream, body bg (light), body text (dark)
$rb-cream-50--rb-cream-50--bs-cream-50$light, tertiary bg, input bg, text on navy
$rb-cream-300--rb-cream-300--bs-cream-300Border color (light), secondary bg (light)
$rb-red-600--rb-red-600--bs-red-600$danger, $red
$rb-green-600--rb-green-600--bs-green-600$success, $green

Bootstrap's own named colors are remapped too: $blue is navy-500, $indigo is navy-700, $yellow is gold-500, $cyan is navy-300. The gray ramp runs cream on the light end and navy on the dark end.

Semantic colors

Every --color-* token is an alias. It follows data-bs-theme and prefers-color-scheme automatically because the Bootstrap variable underneath does.

TokenAlias ofLightDark
--color-bg--bs-body-bgcream-100navy-900
--color-bg-elevated--bs-tertiary-bgcream-50navy-700
--color-fg--bs-body-colornavy-900cream-100
--color-fg-muted--bs-secondary-colornavy-400navy-100
--color-accent--bs-primarygold-700gold-500
--color-accent-fgliteralnavy-900navy-900
--color-link--bs-link-colornavy-700gold-300
--color-link-hover--bs-link-hover-colorgold-800gold-500
--color-border--bs-border-colorcream-300navy-500
--color-danger--bs-dangerred-600red-600
--color-success--bs-successgreen-600green-600

The full set of theme colors, with their emphasis and subtle variants, is on Color.

Typography

TokenBootstrapValue
--font-sans--bs-font-sans-serif / $font-family-sans-serifui-sans-serif, system-ui, …
--font-display--bs-font-display (theme addition)"Big Shoulders Display", then the sans stack
--font-mono--bs-font-monospace / $font-family-monospaceui-monospace, SFMono-Regular, Menlo, …
--font-weight-regular / -medium / -bold$font-weight-base / -medium / -bold400 / 500 / 700 ($font-weight-bolder is 800)
--font-size-xs … -3xl$font-size-sm, $font-size-base, $font-size-lg, $h3–$h1-font-size0.75 / 0.875 / 1 / 1.125 / 1.5 / 2 / 3 rem
--line-height-tight / -normal / -loose$line-height-sm / -base / -lg ($headings-line-height is 1.15)1.15 / 1.5 / 1.75

Heading sizes: h1 3 rem, h2 2 rem, h3 1.5 rem, h4 1.125 rem, h5 1 rem, h6 0.875 rem. h1–h3 are set in the display face by scss/_brand.scss; h4–h6 stay in the sans stack. Display classes are weight 800, line-height 1, uppercase. Typography.

H1 in Big Shoulders Display

H4 stays system sans

Display: caps, 800

HTML
<p class="h1 mb-1">H1 in Big Shoulders Display</p>
<p class="h4 mb-1">H4 stays system sans</p>
<p class="display-6 mb-0">Display: caps, 800</p>

Spacing

Nine steps on a 4 px base. $spacers and --space-* are the same map, so .p-4 and padding: var(--space-4) are both 1 rem.

StepTokenValueUtilities
0--space-00.m-0 .p-0 .gap-0 .g-0
1--space-10.25 rem (4 px).m-1 …
2--space-20.5 rem (8 px).m-2 …
3--space-30.75 rem (12 px).m-3 …
4--space-41 rem (16 px).m-4 …
5--space-51.5 rem (24 px).m-5 …
6--space-62 rem (32 px).m-6 …
7--space-73 rem (48 px).m-7 …
8--space-84 rem (64 px).m-8 …
p-1
p-2
p-3
p-4
p-5
p-6
HTML
<div class="bg-primary-subtle border border-primary-subtle p-1"><code>p-1</code></div>
<div class="bg-primary-subtle border border-primary-subtle p-2"><code>p-2</code></div>
<div class="bg-primary-subtle border border-primary-subtle p-3"><code>p-3</code></div>
<div class="bg-primary-subtle border border-primary-subtle p-4"><code>p-4</code></div>
<div class="bg-primary-subtle border border-primary-subtle p-5"><code>p-5</code></div>
<div class="bg-primary-subtle border border-primary-subtle p-6"><code>p-6</code></div>

Negative margins are on (.mt-n1 … .mt-n8). Spacing.

Radius

TokenBootstrapValueWhere
--radius-sm--bs-border-radius-sm2 pxButtons, inputs, badges, alerts, tabs, pagination, dropdowns, toasts, tooltips — the "bracket" corner
--radius-md--bs-border-radius6 pxCards, modals, popovers, .rounded
--radius-lg--bs-border-radius-lg (also -xl, -xxl)12 px.rounded-3 and up
--radius-pill--bs-border-radius-pill999 px.rounded-pill
2 px badge
6 px card
pill
HTML
<button type="button" class="btn btn-primary">2 px button</button>
<span class="badge text-bg-navy">2 px badge</span>
<div class="card d-inline-block p-2"><code>6 px card</code></div>
<span class="badge rounded-pill text-bg-gold">pill</span>

Shadow

TokenBootstrapLightDark
--shadow-sm--bs-box-shadow-sm0 1px 2px rgba(10, 27, 61, .08)0 1px 2px rgba(0, 0, 0, .4)
--shadow-md--bs-box-shadow (and -lg)0 4px 12px rgba(10, 27, 61, .16)0 4px 12px rgba(0, 0, 0, .5)

Light shadows are tinted navy so they sit on cream. $enable-shadows is off, so components ship flat; use .shadow-sm, .shadow or the variables when you want depth. Shadows.

.shadow-sm
.shadow
HTML
<div class="p-3 bg-body-tertiary rounded shadow-sm">.shadow-sm</div>
<div class="p-3 bg-body-tertiary rounded shadow">.shadow</div>

Motion

TokenValueBootstrap
--duration-fast120 ms$transition-fade: opacity 120ms linear
--duration-base200 ms$transition-base: all 200ms cubic-bezier(.2, 0, 0, 1)
--duration-slow320 ms$transition-collapse: height 320ms cubic-bezier(.2, 0, 0, 1)
--ease-standardcubic-bezier(0.2, 0, 0, 1)Used by base and collapse transitions
--ease-emphasizedcubic-bezier(0.3, 0, 0, 1)Not used by Bootstrap; available for your own

The three transitions are also published as --bs-transition-base, --bs-transition-fade and --bs-transition-collapse (a theme addition) and as the .transition-base / .transition-fade / .transition-none utilities. All three are set to none under prefers-reduced-motion: reduce.

Z-index

The token scale (100 / 200 / 300) with Bootstrap's intermediate layers slotted between.

LayerSassValueToken / utility
Base—0--z-base, .z-0
Dropdown$zindex-dropdown100--z-dropdown, .z-dropdown
Sticky$zindex-sticky110
Fixed$zindex-fixed120
Offcanvas backdrop / offcanvas$zindex-offcanvas-backdrop / $zindex-offcanvas190 / 195
Modal backdrop$zindex-modal-backdrop200.z-modal (200)
Modal$zindex-modal205--z-modal (205)
Popover$zindex-popover210
Tooltip$zindex-tooltip220
Toast$zindex-toast300--z-toast, .z-toast

Most overlays are popovers in the top layer, where z-index does not apply. The values matter for the :target fallbacks, static toasts and your own positioned elements. Z-index.

Old names still work

Markup written against tokens.css renders unchanged. This block uses only the old names, inline.

Pin it.

WrestleMania III · 1987 · Pontiac Silverdome · 93,173

HTML
<div style="padding: var(--space-4) var(--space-5); background: var(--color-accent); color: var(--color-accent-fg); font-family: var(--font-display); font-size: var(--font-size-xl); font-weight: var(--font-weight-bold); line-height: var(--line-height-tight); text-transform: uppercase; letter-spacing: 0.01em; border-radius: var(--radius-md); box-shadow: var(--shadow-md);">
  Pin it.
</div>
<p class="mt-3 mb-0" style="color: var(--color-fg-muted); font-family: var(--font-mono); font-size: var(--font-size-sm);">
  WrestleMania III · 1987 · Pontiac Silverdome · 93,173
</p>

Because --color-accent is var(--bs-primary), the block turns gold-500 in dark mode without any extra rule, and flips inside a data-bs-theme region. Color modes.

Sass

Override any raw value before importing the entry. Everything in scss/_palette.scss is !default.

$rb-gold-500: #e0b83c;
$rb-duration-base: 160ms;
$rb-shadow-md: 0 6px 16px rgba(10, 27, 61, 0.2);

@import "@ropebreak/bootstrap/scss/rb-bootstrap";

Changing a palette variable updates every layer: the Bootstrap variable derived from it, the --bs-* property, and the --color-* alias. See Sass.