Spruce CSS v3 is a major release because it adds a lot, not because it breaks a lot. The Sass API is compatible with v2: no variable, map key, mixin or function was removed or renamed.
npm install sprucecss@^3Recompile, and check the changes in the default output below. For most projects, that's it.
With the default configuration, every v2 declaration is still generated. These are the visual differences you may notice:
| Change | How to revert |
|---|---|
Headings use text-wrap: balance. | $typography: ('text-wrap-heading': null) |
code, kbd, samp, pre use the font-family-mono stack. | Set font-family-mono in $typography. |
kbd has a border; pre has a background, padding and radius; pre code loses the inline code background. | Overwrite the kbd-border, pre-background colors or the pre-* typography keys. |
details, dialog, progress and meter are styled (with zero specificity, :where()). | $generators: ('content': ('details': false, 'dialog': false, 'progress': false)) |
The native controls get accent-color from the primary color. | $settings: ('accent-color': false) |
video is responsive (max-inline-size: 100%). | — |
.sr-only also uses clip-path: inset(50%). | — |
.form-control--sm/--lgand.form-check--lgnow get their intended font sizes (the old config referenced non-existing keys, so the value wasnull)..form-check--sm/--lgwork in custom property mode and no longer inherit the small/large form control radius and padding.
If you use 'css-custom-properties': true, the component custom properties now reference their style hooks:
/* v2 */
.btn { --spruce-padding: 0.75em 1em; }
/* v3 */
.btn { --spruce-padding: var(--spruce-btn-padding, 0.75em 1em); }The computed values are the same, and your overrides of --spruce-padding on .btn still work. Turn the hooks off with $settings: ('style-hooks': false) to get the v2 output.
- Dark mode: replace your manual dark mode with the
dark-modegenerator. Your$dark-colorsmap works as it is. - Styles: turn on the
stylesgenerator and let users pick a look, or set a default style. - Tokens: use
shadow(),radius(),z-index(),color-alpha()andcolor-tint()in your components (functions). - Elements: details and dialog, progress and meter, new button variants, table modifiers and form options.
- Layout: the new
layout-cluster,layout-switcher,layout-reelmixins and the opt-in layout utilities. - AI: add the AI skills to your project so your coding assistant writes idiomatic Spruce CSS.
- The npm package now has
sassandstyleentry points, so@use 'pkg:sprucecss';works with Sass's Node package importer, and CSS bundlers can resolvesprucecssto the compiled CSS. - A new
css/spruce.complete.cssbundle has every opt-in feature turned on.
The full list is in the changelog.
