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.
- Raw palette —
$rb-*in Sass,--rb-*in CSS. Private. Components never reference it. - Bootstrap —
$primary,$body-bg,$spacersand the rest are set from the palette inscss/_variables.scss, and compile to--bs-*. - Semantic compat —
--color-*,--font-*,--space-*,--radius-*,--shadow-*,--duration-*,--ease-*,--z-*. Emitted byscss/_tokens.scssas 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| Sass | Private | Public | Used 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, -50 | Subtle 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-800 | link 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-300 | Border 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.
| Token | Alias of | Light | Dark |
|---|---|---|---|
--color-bg | --bs-body-bg | cream-100 | navy-900 |
--color-bg-elevated | --bs-tertiary-bg | cream-50 | navy-700 |
--color-fg | --bs-body-color | navy-900 | cream-100 |
--color-fg-muted | --bs-secondary-color | navy-400 | navy-100 |
--color-accent | --bs-primary | gold-700 | gold-500 |
--color-accent-fg | literal | navy-900 | navy-900 |
--color-link | --bs-link-color | navy-700 | gold-300 |
--color-link-hover | --bs-link-hover-color | gold-800 | gold-500 |
--color-border | --bs-border-color | cream-300 | navy-500 |
--color-danger | --bs-danger | red-600 | red-600 |
--color-success | --bs-success | green-600 | green-600 |
The full set of theme colors, with their emphasis and subtle variants, is on Color.
Typography
| Token | Bootstrap | Value |
|---|---|---|
--font-sans | --bs-font-sans-serif / $font-family-sans-serif | ui-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-monospace | ui-monospace, SFMono-Regular, Menlo, … |
--font-weight-regular / -medium / -bold | $font-weight-base / -medium / -bold | 400 / 500 / 700 ($font-weight-bolder is 800) |
--font-size-xs … -3xl | $font-size-sm, $font-size-base, $font-size-lg, $h3–$h1-font-size | 0.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.
| Step | Token | Value | Utilities |
|---|---|---|---|
| 0 | --space-0 | 0 | .m-0 .p-0 .gap-0 .g-0 |
| 1 | --space-1 | 0.25 rem (4 px) | .m-1 … |
| 2 | --space-2 | 0.5 rem (8 px) | .m-2 … |
| 3 | --space-3 | 0.75 rem (12 px) | .m-3 … |
| 4 | --space-4 | 1 rem (16 px) | .m-4 … |
| 5 | --space-5 | 1.5 rem (24 px) | .m-5 … |
| 6 | --space-6 | 2 rem (32 px) | .m-6 … |
| 7 | --space-7 | 3 rem (48 px) | .m-7 … |
| 8 | --space-8 | 4 rem (64 px) | .m-8 … |
p-1p-2p-3p-4p-5p-6HTML
<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
| Token | Bootstrap | Value | Where |
|---|---|---|---|
--radius-sm | --bs-border-radius-sm | 2 px | Buttons, inputs, badges, alerts, tabs, pagination, dropdowns, toasts, tooltips — the "bracket" corner |
--radius-md | --bs-border-radius | 6 px | Cards, modals, popovers, .rounded |
--radius-lg | --bs-border-radius-lg (also -xl, -xxl) | 12 px | .rounded-3 and up |
--radius-pill | --bs-border-radius-pill | 999 px | .rounded-pill |
6 px cardHTML
<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
| Token | Bootstrap | Light | Dark |
|---|---|---|---|
--shadow-sm | --bs-box-shadow-sm | 0 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.
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
| Token | Value | Bootstrap |
|---|---|---|
--duration-fast | 120 ms | $transition-fade: opacity 120ms linear |
--duration-base | 200 ms | $transition-base: all 200ms cubic-bezier(.2, 0, 0, 1) |
--duration-slow | 320 ms | $transition-collapse: height 320ms cubic-bezier(.2, 0, 0, 1) |
--ease-standard | cubic-bezier(0.2, 0, 0, 1) | Used by base and collapse transitions |
--ease-emphasized | cubic-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.
| Layer | Sass | Value | Token / utility |
|---|---|---|---|
| Base | — | 0 | --z-base, .z-0 |
| Dropdown | $zindex-dropdown | 100 | --z-dropdown, .z-dropdown |
| Sticky | $zindex-sticky | 110 | |
| Fixed | $zindex-fixed | 120 | |
| Offcanvas backdrop / offcanvas | $zindex-offcanvas-backdrop / $zindex-offcanvas | 190 / 195 | |
| Modal backdrop | $zindex-modal-backdrop | 200 | .z-modal (200) |
| Modal | $zindex-modal | 205 | --z-modal (205) |
| Popover | $zindex-popover | 210 | |
| Tooltip | $zindex-tooltip | 220 | |
| Toast | $zindex-toast | 300 | --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.
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.