v6 migration: which tokens replace the v5 Sass variables a theme overrides?

Open
  • Is something wrong?
#43,227 1 comment 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
sass, scss
Domain
documentation

Research direction

Start with the v5.3.8 and v6 Sass sources and the migration guide to compare v5 variables with v6 token map entries, including fallback tokens used in var() declarations. Add a migration table that maps each overridden v5 !default variable to its v6 counterpart or marks it removed, plus an example expressing a v5 brand color as a v6 theme map. The issue asks whether the table belongs in the migration guide or Sass customization page, so confirm the location with maintainers.

Written by the indexing model from the issue text.

Description

docs v6
Prerequisites
Proposal

I'm trying 6.0.0-alpha.1 on two themes of a large Bootstrap 5.3 app. Between them they override 106 Sass variables before @import "bootstrap/scss/variables". In v6, 102 of those no longer exist: $primary, $font-size-base, $btn-font-weight, $input-btn-padding-y, $table-cell-padding-y, $dropdown-item-padding-y, $form-label-font-weight, $headings-font-weight, $badge-border-radius, $breadcrumb-divider, and so on.

The migration guide and the bootstrap-v5-v6-migration skill cover the renamed ones ($grid-breakpoints, $zindex-*, the radii, $font-size-base → --body-font-size). For most of the others I had to grep the token maps by hand. Many do have a counterpart, but under a name you can't guess from the v5 one: $input-btn-padding-y became --btn-input-padding-y, $form-label-font-weight became --label-font-weight, $dropdown-item-padding-y became --menu-item-padding-y. Some exist only as a fallback nobody declares, like --heading-font-weight in Reboot's var(--heading-font-weight, var(--font-weight-medium)), so grepping the token maps misses them. Colors are the biggest step: a v5 theme set $primary: #0057c2 and let Sass derive the rest, while a v6 theme color is a nine-key map (base, fg, fg-emphasis, bg, bg-subtle, bg-muted, border, focus-ring, contrast), and the docs only show it built from the existing palette tokens.

A table in the migration guide mapping each v5 !default variable to its v6 token map entry, or marking it "removed", would turn this into a mechanical step. A short example of a v5 brand color expressed as a v6 theme map would help with the rest. I'm happy to draft the table from a diff of the v5.3.8 and v6 sources if that would be welcome.

Motivation and context

Customized v5 themes override Sass scalars almost by definition, so every one of them hits this wall before the first successful build. Right now the only way through is reading scss/ file by file.

Would a generated v5 → v6 variable table fit in the migration guide, and if so, would you rather it live there or on the Sass customization page?

Dominant language
MDX
Stars
175k
Forks
78.7k
Avg merge
1d 7h
Merged PRs (30d)
103

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from twbs/bootstrap

All issues in twbs/bootstrap

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.