Getting started
Introduction
What rb-bootstrap is, what it changes, and how to install it.
What it is
rb-bootstrap is a Sass theme for Bootstrap 5.3 (the current long-term line; Bootstrap 6 is still alpha). It does three things:
-
Maps every Bootstrap variable to a RopeBreak.net design token. Palette, type, spacing, radius,
shadow, motion and z-index all come from
@ropebreak/design. See Tokens. - Removes Bootstrap's JavaScript. Every plugin — collapse, dropdown, modal, offcanvas, tabs, toast, tooltip, popover, carousel, scrollspy, alert dismiss, form validation — is re-implemented on native HTML elements and progressively enhanced CSS. See No JavaScript.
- Documents everything. Every component, helper and utility has a page here, written against the theme's own markup. The docs site itself ships no script.
Install
npm install @ropebreak/bootstrap
Then link the compiled CSS. Both files include the Big Shoulders Display web font import.
<link rel="stylesheet" href="node_modules/@ropebreak/bootstrap/dist/rb-bootstrap.min.css" />
Add <meta name="color-scheme" content="light dark"> so form controls and scrollbars follow
the page's color mode.
Use the Sass source
To customise, import the Sass entry instead of the CSS and override variables before it. All palette
variables are !default.
// your-theme.scss
$rb-gold-500: #e0b83c; // tweak the ramp
$rb-enable-google-fonts: false; // self-host the display font
@import "@ropebreak/bootstrap/scss/rb-bootstrap";
Or pick parts, exactly as with stock Bootstrap. The import order is documented in scss/rb-bootstrap.scss.
What is different from stock Bootstrap
| Area | Stock Bootstrap | rb-bootstrap |
|---|---|---|
| Spacing scale | 0–5 (1 rem at step 3) | 0–8, 4 px base (1 rem at step 4). Spacing |
| Primary | Blue | Title-belt gold (gold-700 light, gold-500 dark) |
| Extra theme colors | — | gold, navy, cream |
| Headings | Inherit body font | h1–h3 in Big Shoulders Display; h4–h6 stay system sans |
| Display classes | Sentence case | Uppercase, weight 800 |
| Buttons | 6 px radius | 2 px "bracket" radius |
| Color modes | data-bs-theme only | data-bs-theme and automatic prefers-color-scheme |
| Form validation | .was-validated via JS | :user-invalid / :user-valid, no class needed |
| Interactive components | JavaScript plugins | <details>, <dialog>, Popover API, scroll-snap, scroll-driven animations |
| CSS grid | Off | On (.grid and .g-col-*) |
| Negative margins | Off | On (.mt-n2 …) |
Browser support
The baseline is any engine that supports :has() and the Popover API — Chrome 114, Safari 17,
Firefox 125 and later. Each component page lists the enhancement features it uses (anchor positioning,
@starting-style, ::details-content, CSS scroll buttons, scroll-driven
animations) and what the fallback looks like without them.
Package layout
rb-bootstrap/
dist/rb-bootstrap.css compiled, expanded
dist/rb-bootstrap.min.css compiled, minified
scss/rb-bootstrap.scss entry — import order
scss/_palette.scss $rb-* raw palette + type + motion tokens
scss/_variables.scss Bootstrap overrides (light)
scss/_variables-dark.scss Bootstrap overrides (dark)
scss/_maps.scss extra theme colors
scss/_mixins.scss color-mode + validation mixin overrides
scss/_tokens.scss --rb-* / --color-* compat layer
scss/_brand.scss gold ramp, hard rule, bracket frame, marquee
scss/components/*.scss the no-JS component layer
docs/src/ these pages