Customize
Sass
Import the entry, override the palette, pick parts, and run the build.
Import the entry
The package exports its Sass under ./scss/*. Import the entry and you get everything: fonts,
Bootstrap, the no-JS component layer, the brand layer and the utilities API.
// your-theme.scss
@import "@ropebreak/bootstrap/scss/rb-bootstrap";
The theme uses @import, same as Bootstrap 5.3. Dart Sass prints deprecation warnings for that;
the build script silences them (see Build script). Set your load path to include
node_modules so the ../node_modules/bootstrap/… paths inside the entry resolve.
Override the palette
Every value in scss/_palette.scss is !default. Set yours before the import
and the whole chain follows: the Bootstrap variable, the compiled --bs-* property, the
--rb-* and --color-* aliases.
// Palette
$rb-gold-500: #e0b83c;
$rb-navy-900: #08162f;
// Type
$rb-font-display: ("Big Shoulders Display", "Impact", sans-serif);
// Motion
$rb-duration-base: 160ms;
$rb-ease-standard: cubic-bezier(0.25, 0, 0, 1);
// Shadow
$rb-shadow-md: 0 6px 16px rgba(10, 27, 61, 0.2);
$rb-shadow-md-dark: 0 6px 16px rgba(0, 0, 0, 0.6);
@import "@ropebreak/bootstrap/scss/rb-bootstrap";
The variables available:
| Group | Variables |
|---|---|
| Navy | $rb-navy-50 -100 -300 -500 -700 -900 |
| Gold | $rb-gold-300 -500 -700 |
| Cream | $rb-cream-50 -100 -300 |
| Signal | $rb-red-600 $rb-green-600 |
| Type | $rb-font-sans $rb-font-display $rb-font-mono |
| Motion | $rb-duration-fast -base -slow, $rb-ease-standard -emphasized |
| Shadow | $rb-shadow-sm -md -sm-dark -md-dark |
| Options | $rb-enable-google-fonts, $rb-tabs-max (12), $rb-scrollspy-max (12) |
You can still override any Bootstrap variable the usual way ($primary, $border-radius,
$spacers …). The theme's own overrides in scss/_variables.scss are not
!default, so they win over yours unless you set them after the theme's variables are loaded — which
means importing parts (below).
Google Fonts
scss/_fonts.scss emits a Google Fonts @import for Big Shoulders Display (700 and 800).
To self-host, switch it off and declare your own @font-face.
$rb-enable-google-fonts: false;
@font-face {
font-family: "Big Shoulders Display";
font-weight: 700 800;
font-display: swap;
src: url("/fonts/big-shoulders-display.woff2") format("woff2");
}
@import "@ropebreak/bootstrap/scss/rb-bootstrap";
Only h1–h3, the display classes and .text-marquee use the face. Body text is the system stack and loads nothing.
Import order
This is scss/rb-bootstrap.scss. The order is the point: theme variables load before Bootstrap's so its !default values yield; theme maps load between Bootstrap's variables and its maps; theme mixins after Bootstrap's so they win.
// Fonts first (a plain CSS @import must lead the file)
@import "palette";
@import "fonts";
// 1. Configuration — ours first so Bootstrap's `!default` values yield
@import "../node_modules/bootstrap/scss/functions";
@import "variables";
@import "variables-dark";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";
@import "maps";
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "mixins";
@import "../node_modules/bootstrap/scss/utilities";
@import "utilities";
// 2. Layout & components — Bootstrap's CSS, minus `_transitions.scss`
@import "../node_modules/bootstrap/scss/root";
@import "tokens";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// … images, containers, grid, tables, forms, buttons
@import "components/transitions";
// … dropdown, button-group, nav, navbar, card, accordion, breadcrumb,
// pagination, badge, alert, progress, list-group, close, toasts, modal,
// tooltip, popover, carousel, spinners, offcanvas, placeholders, helpers
// 3. JavaScript plugins, re-implemented on native HTML + CSS
@import "components/forms";
@import "components/accordion";
@import "components/dropdown";
@import "components/navbar";
@import "components/tabs";
@import "components/alert";
@import "components/modal";
@import "components/offcanvas";
@import "components/toast";
@import "components/tooltip";
@import "components/popover";
@import "components/carousel";
@import "components/scrollspy";
// 4. Brand
@import "brand";
// 5. Utilities API (last so utilities win)
@import "../node_modules/bootstrap/scss/utilities/api";
Two things to notice. Bootstrap's _transitions.scss is replaced by components/transitions, which is where .fade and details.collapse live. And tokens comes right after root, so the --color-* aliases are declared next to the variables they alias.
Import parts
Copy the order above and drop what you do not need. Keep section 1 intact; everything after it is optional. A trimmed build with only buttons, forms, cards and the modal:
@import "@ropebreak/bootstrap/scss/palette";
@import "@ropebreak/bootstrap/scss/fonts";
@import "bootstrap/scss/functions";
@import "@ropebreak/bootstrap/scss/variables";
@import "@ropebreak/bootstrap/scss/variables-dark";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "@ropebreak/bootstrap/scss/maps";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "@ropebreak/bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@import "@ropebreak/bootstrap/scss/utilities";
@import "bootstrap/scss/root";
@import "@ropebreak/bootstrap/scss/tokens";
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
@import "bootstrap/scss/containers";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/forms";
@import "bootstrap/scss/buttons";
@import "@ropebreak/bootstrap/scss/components/transitions";
@import "bootstrap/scss/card";
@import "bootstrap/scss/close";
@import "bootstrap/scss/modal";
@import "bootstrap/scss/helpers";
@import "@ropebreak/bootstrap/scss/components/forms";
@import "@ropebreak/bootstrap/scss/components/modal";
@import "@ropebreak/bootstrap/scss/brand";
@import "bootstrap/scss/utilities/api";
Each file under scss/components/ depends only on the matching Bootstrap partial. The
popover component @extends Bootstrap's .bs-popover-* classes, so keep
bootstrap/scss/popover when you keep components/popover.
This is also where you set a Bootstrap variable the theme has already set: place it between
@ropebreak/bootstrap/scss/variables and bootstrap/scss/variables.
Build script
The package compiles with scripts/build-css.mjs, a short Node script around the sass package (Dart Sass 1.105). It writes four files to dist/: expanded, minified, and a source map for each.
npm run build:css # once
npm run watch # recompile on change under scss/
npm run build # css + docs
Deprecation categories it silences, and why:
| Category | Trigger |
|---|---|
import | Bootstrap 5.3 and this theme use @import, not @use |
global-builtin | Bootstrap calls map-merge(), map-get() without the map. namespace |
color-functions | Bootstrap's mix(), red(), lighten() helpers |
if-function | Bootstrap's if() calls |
If you compile with your own toolchain, pass the same list, or expect a wall of warnings from node_modules/bootstrap. quietDeps: true hides the ones that originate inside dependencies.
// Equivalent sass CLI flags
// sass --load-path=node_modules --quiet-deps \
// --silence-deprecation=import,global-builtin,color-functions,if-function \
// your-theme.scss dist/your-theme.css
Lint and format
The repo ships a Stylelint config (stylelint-config-standard-scss, with the new CSS features allow-listed) and a Prettier config. Run them from package.json:
npm run lint # stylelint "scss/**/*.scss"
npm run format # prettier --write scss, scripts, docs/src
npm run format:check # prettier --check (CI)
npm test # smoke tests on dist/ and docs/site/
npm run check # format:check + lint + build + test
.stylelintrc.json allow-lists the properties and pseudo-elements the component layer relies on
(position-area, anchor-name, interpolate-size, timeline-scope,
::details-content, ::scroll-button, :popover-open, :user-invalid
…). Copy it if you extend the theme with the same features.