Styling System

Boilerplate styling is organized around SASS variables, Bootstrap 5 compile-time overrides, CSS custom properties, rhythm-based spacing, and runtime light/dark theme tokens.

Theme SASS Variables

Use Boilerplate theme variables for project-level visual defaults: typography, layout widths, transitions, borders, buttons, forms, links, widgets, comments, breadcrumbs, media, print styles, and light/dark color tokens.

File: assets/sass/parent_theme/variables.scss

Use this for: Boilerplate-owned design tokens and child-theme visual customization.

Override behavior: parent variables use SASS !default, allowing child theme variables to override defaults before the parent theme SASS stack is compiled.

Bootstrap 5 Variable Overrides

Use Bootstrap variable overrides for framework-level values that must exist before Bootstrap compiles: font sizes, line heights, spacers, colors, link defaults, dropdown defaults, navbar defaults, pagination defaults, and Bootstrap component defaults.

File: assets/sass/parent_theme/bootstrap/variables.scss

Use this for: changing Bootstrap-generated CSS at compile time.

Bootstrap Runtime Overrides

Use Bootstrap runtime overrides to align compiled Bootstrap output with Boilerplate’s runtime theme system. This includes border tokens, input colors, button behavior, dropdown cleanup, card/list spacing, table colors, and right-aligned navbar dropdown fixes.

File: assets/sass/parent_theme/bootstrap/overrides.scss

Use this for: making Bootstrap components obey Boilerplate’s CSS custom properties and light/dark runtime colors.

CSS Custom Properties

Boilerplate emits runtime CSS custom properties for colors, borders, inputs, buttons, links, navbars, widgets, comments, media, and print behavior. Components should use these tokens instead of hardcoded colors whenever possible.

Primary files: assets/sass/parent_theme/color_mode.scss, assets/sass/parent_theme/variables.scss

Use this for: light/dark-aware styling and consistent runtime theming.

Rhythm Unit System

Boilerplate spacing is based on a responsive rhythm unit. The root --baseline value controls the rhythm, and SASS uses ru() to generate spacing that follows that baseline.

Function file: assets/sass/parent_theme/functions.scss

Typography file: assets/sass/parent_theme/layout/typography.scss

margin: 0 0 ru( 1 );
padding: ru( 0.5 );

Use this for: margins, padding, gutters, component spacing, and vertical rhythm.

Global Styles

Global styles define baseline body colors, link behavior, text decoration rules, blockquote styling, screen-reader support, lazy image behavior, breadcrumbs, search spacing, and other site-wide defaults.

File: assets/sass/parent_theme/global.scss

Use this for: site-wide defaults that should apply across templates, blocks, widgets, and post content.

Link States

Default links use runtime link tokens and remove Bootstrap’s default underline treatment. Theme-owned links should always provide visible hover/focus feedback.

Primary file: assets/sass/parent_theme/global.scss

Related tokens: --bp-link-color, --bp-link-hover-color, --bp-link-hover-bg-color

Use this for: default links, post links, breadcrumbs, widgets, comments, pagination, and theme-owned link exceptions.

Border Tokens

Boilerplate routes theme and Bootstrap borders through shared runtime border tokens so borders stay consistent across light and dark modes.

Primary files: assets/sass/parent_theme/variables.scss, assets/sass/parent_theme/color_mode.scss, assets/sass/parent_theme/bootstrap/overrides.scss

Related tokens: --bp-theme-border-color, --bp-theme-border, --bp-hr-border-color

Use this for: cards, forms, pagination, widgets, comments, media players, navbars, horizontal rules, and Bootstrap component borders.

Button Tokens

Theme buttons use runtime button tokens for default and hover states. Bootstrap button behavior is normalized where needed so search, password forms, calendar controls, and theme controls stay visually consistent.

Primary files: assets/sass/parent_theme/variables.scss, assets/sass/parent_theme/color_mode.scss, assets/sass/parent_theme/bootstrap/overrides.scss

Related tokens: --bp-button-bg-color, --bp-button-border-color, --bp-button-color, --bp-button-hover-bg-color, --bp-button-hover-border-color, --bp-button-hover-color

Input Tokens

Forms and inputs use runtime input tokens for background, border, text, disabled, and placeholder states. Bootstrap form controls are routed through the same token system.

Primary files: assets/sass/parent_theme/variables.scss, assets/sass/parent_theme/color_mode.scss, assets/sass/parent_theme/bootstrap/overrides.scss

Related tokens: --bp-input-bg-color, --bp-input-border-color, --bp-input-color, --bp-input-disabled-bg-color, --bp-input-placeholder-color

Recommended Styling Flow

1. Set Bootstrap compile-time defaults in bootstrap/variables.scss.
2. Set Boilerplate theme tokens in variables.scss.
3. Use color_mode.scss for runtime light/dark CSS custom properties.
4. Use bootstrap/overrides.scss to normalize compiled Bootstrap output.
5. Use global.scss for site-wide default behavior.

Rule of Thumb

If the value must affect Bootstrap before it compiles, use bootstrap/variables.scss. If the value belongs to Boilerplate’s theme system, use variables.scss. If the value must change at runtime for light/dark mode, route it through CSS custom properties. If the spacing should follow vertical rhythm, use ru().