Migration Guide: v5 to v6

Bullframe CSS v6 is a major rewrite. The framework has been migrated from Sass/SCSS to native CSS with PostCSS. This guide covers everything you need to update.

Breaking Changes at a Glance

What changed	v5	v6
Source language	Sass/SCSS	Native CSS
Variables	$bf-* (Sass)	--bf-* (CSS custom properties)
Mixins	Sass @mixin / @include	Utility classes or direct CSS
Build tool	Vite + Sass	Vite + PostCSS
Source directory	src/scss/	src/css/
IE support	Dropped in v5	Not supported

1. Update Your Install

npm install bullframe.css@latest

The CDN link also changes:

<!-- v5 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css@5" />

<!-- v6: pin a version; add integrity + crossorigin for SRI (see Getting started) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bullframe.css@6.0.0/dist/css/bullframe.min.css" />

2. Replace Sass Variables with CSS Custom Properties

All Sass variables ($bf-*) are now CSS custom properties (--bf-*).

/* v5 (Sass) */
$bf-blue: #007bff;
$bf-font-family-sans-serif: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

/* v6 (CSS) */
:root {
  --bf-blue: rgb(0 102 204);
  --bf-font-family-sans-serif: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
}

Common Variable Renames

v5 Sass Variable	v6 CSS Custom Property
$bf-blue	--bf-blue
$bf-blue-light	--bf-blue-light
$bf-spacing-sm	--bf-spacing-sm
$bf-spacing-md	--bf-spacing-md
$bf-spacing-lg	--bf-spacing-lg
$bf-font-family-sans-serif	--bf-font-family-sans-serif
$bf-body-font-size	--bf-body-font-size
$bf-body-line-height	--bf-body-line-height
$bf-grid-gutter	--bf-grid-gutter

3. Remove Sass Mixins

Sass mixins no longer exist. Replace them with:

• Utility classes (e.g., .bf-clearfix, .bf-sr-only, .bf-reduced-motion)
• Direct CSS using the custom properties

4. Update Your Build

If you were importing Sass files directly:

/* v5: no longer works */
@import 'bullframe.css/src/scss/bullframe';

/* v6: use CSS imports or just link the built file */
@import 'bullframe.css/dist/css/bullframe.css';

If you had a custom Sass build, replace it with PostCSS. See Customization for details.

5. Color Contrast Changes

v6 darkened --bf-blue and --bf-blue-light to meet WCAG AA contrast requirements (4.5:1 ratio). Links and primary buttons are slightly darker blue.

To restore the brighter v5 colors:

:root {
  --bf-blue: rgb(0 123 255);
  --bf-blue-light: rgb(0 86 179);
}

6. New Dark Mode Variants

v6 ships dark and system themes for both markup modes:

File	Behavior
bullframe-dark.css	Always dark (class-based)
bullframe-system-default.css	Follows prefers-color-scheme
bullframe-classless-dark.css	Always dark (classless)
bullframe-classless-system-default.css	Classless + system preference

See Dark Mode for implementation details.

7. New Accessibility Features

v6 adds built-in support for:

• :focus-visible keyboard-only focus indicators
• prefers-reduced-motion via .bf-reduced-motion
• ARIA attribute styling (aria-busy, aria-disabled, aria-hidden)

These are included automatically; no migration needed.

Need Help?

If you run into issues migrating, open an issue on GitHub.