Skip to main content

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:

GroupVariables
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:

CategoryTrigger
importBootstrap 5.3 and this theme use @import, not @use
global-builtinBootstrap calls map-merge(), map-get() without the map. namespace
color-functionsBootstrap's mix(), red(), lighten() helpers
if-functionBootstrap'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.