Problem/Motivation

bs_base ships 19 custom mixins / functions in sass/mixins/. 8 of them already use a bs- prefix (bs-icon-*, bs-button-variant, bs-input-autofill-*); the other 11 are unprefixed (heading, content-box*,
link-*, clean-dropdown-menu, style-link, style-nav-link, media-responsive-breakpoint-up/down).

This is inconsistent and makes it harder to tell at a glance whether a callsite uses an upstream Bootstrap mixin or one of bs_base's own.

The bs- prefix that the 8 existing mixins use also overlaps with the --bs-* CSS-variable namespace BS5 already owns. BS5 has not shipped bs-* mixins to date, but the ambiguity is a latent collision risk.

Spun off from #3219565 where this was listed as a TODO but deferred during the BS5 upgrade.

Proposed resolution

Rename all 19 custom mixins / functions to use a bsb- prefix (unambiguously "bs_base custom"):

Current New
bs-icon-font bsb-icon-font
bs-create-icon bsb-create-icon
bs-icon bsb-icon
bs-icon-create-content bsb-icon-create-content
bs-icon-var bsb-icon-var
bs-button-variant bsb-button-variant
bs-input-autofill-box-shadow (function) bsb-input-autofill-box-shadow
bs-input-autofill-fix bsb-input-autofill-fix
content-box bsb-content-box
content-box-shadow bsb-content-box-shadow
content-box-shadow-hover bsb-content-box-shadow-hover
link-hover-focus-active bsb-link-hover-focus-active
link-hover-active-line-effect bsb-link-hover-active-line-effect
clean-dropdown-menu bsb-clean-dropdown-menu
style-link bsb-style-link
style-nav-link bsb-style-nav-link
heading bsb-heading
media-responsive-breakpoint-up bsb-media-responsive-breakpoint-up
media-responsive-breakpoint-down bsb-media-responsive-breakpoint-down

Add a migration update function bs_base_bs_update_NNNNNN($target_theme_name) that walks
.scss files in the target theme and rewrites old → new names. Regex must use lookaround boundaries (e.g. (?<![a-zA-Z0-9_-])bs-icon(?![a-zA-Z0-9_-])) since - is not a word-boundary character — a naive replace would also rewrite bs-icon-create-content if bs-icon is processed first. Process the longer names first to avoid substring collisions, or use
preg_replace_callback with the full name table.

Two distinct rewrite shapes to handle:

  • Mixin calls: @include old-name( → @include new-name(
  • Function calls: old-name( anywhere (e.g. inside a value), with careful boundary handling to avoid matching SASS variables or substrings.

Backwards compatibility

BC-breaking for any child theme that consumes these mixins directly. Mitigated by the update function — running drush updb after upgrading bs_base rewrites the child theme's SASS automatically. The child theme then needs a CSS rebuild (gulp sass or equivalent).

Remaining tasks

  • Rename in sass/mixins/_icons.scss, _util.scss, _mixins.scss,
    _typography.scss.
  • Find / replace internal callsites in bs_base (~50 occurrences across sass/).
  • Implement bs_base_bs_update_NNNNNN with boundary-safe regex.
  • Smoke-test the migration on a sample child theme.
  • Recompile CSS in bs_base and the Primer themes.
  • Update README.md with the rename for child theme maintainers.

Notes

No urgency: 5+ years since the original TODO and no concrete name collision has surfaced. Pick this up when a custom mixin you want to add gets blocked, or as part of an unrelated bs_base touch-up session — not as standalone priority work.

Comments

pivica created an issue.