How should a tinted page canvas with raised cards be built with $theme-bgs?

[BVisagie]

v6 has one background role, --bg-body, for both the page and the default component surface. The numbered steps --bg-1 to --bg-4 get darker in light mode and lighter in dark mode. There is no role for a raised surface that differs from the page, so I'm not sure how the team intends a common layout to be built: a tinted canvas with raised cards on it, as in dashboards, settings pages or the Album example.

scss/_theme.scss (6.0.0-alpha.1, unchanged on main):

$theme-bgs: defaults(
  (
    'body': light-dark(var(--white), var(--gray-975)),
    '1': light-dark(var(--gray-025), var(--gray-950)),
    '2': light-dark(var(--gray-050), var(--gray-900)),
    '3': light-dark(var(--gray-100), var(--gray-800)),
    '4': light-dark(var(--gray-200), var(--gray-700)),
    // …
  ),
  $theme-bgs
);

How components use them:

• --bg-body paints the page (body { background-color: var(--bg-body); } in content/_reboot.scss). It is also the default fill for card (--card-bg), list group, table, dialog, drawer, menu, popover, toast, accordion, pagination, datepicker and form controls (--btn-input-bg).
• --bg-1 is the recessed fill inside those surfaces. It is used for:
  • card headers and footers (--card-cap-bg), alerts, the nav pills track, and toast and popover headers;
  • the hover state of nav links, list group actions, menu items and pagination.

There are two ways to build a tinted canvas, and each one breaks something. Measured with the snippet below; Chromium 156 and Firefox 157 give the same values:

Element	A, light	A, dark	B, light	B, dark
Canvas	#f1f2f3	#171a1d	#f1f2f3	#080a0c
Card	#ffffff	#080a0c	#ffffff	#0f1214
Card header	#f6f7f8	#0f1214	#ffffff	#0f1214
Nav pills track	#f6f7f8	#0f1214	#ffffff	#0f1214
Alert	#f6f7f8	#0f1214	#ffffff	#0f1214
List group item	#ffffff	#080a0c	#f1f2f3	#080a0c
Table cell	#ffffff	#080a0c	#f1f2f3	#080a0c

• A: canvas .bg-2, cards on --bg-body. The Album example does this with .bg-1. Light mode is right. In dark mode the card (#080a0c) is darker than the canvas (#171a1d), so raised cards look sunken, because body is the darkest step in dark mode.
• B: canvas on --bg-body, cards on --bg-1. Inside a card, list group items and table cells show the canvas colour, while the card header, alert and pills track lose their tint and match the card. Dialogs, menus, popovers and toasts also paint --bg-body, so they take the canvas colour too.

B can be repaired by re-pointing component token maps through the entrypoint. This compiles with alpha.1:

@use 'bootstrap/scss/bootstrap' with (
  $theme-bgs: (
    'body': light-dark(var(--gray-050), var(--gray-975)),
    '1': light-dark(var(--white), var(--gray-950)),
  ),
  $card-tokens: (
    --card-bg: var(--bg-1),
  ),
  $list-group-tokens: (
    --list-group-bg: var(--bg-1),
  ),
  $table-tokens: (
    --table-bg: var(--bg-1),
  ),
  $dialog-tokens: (
    --dialog-bg: var(--bg-1),
  ),
  $menu-tokens: (
    --menu-bg: var(--bg-1),
  ),
  $popover-tokens: (
    --popover-bg: var(--bg-1),
  ),
  $toast-tokens: (
    --toast-bg: var(--bg-1),
  )
);

That still leaves card caps, alerts, the pills track and hover states on --bg-1, the same colour as the card, so they have to move down a step as well. Every new component then needs the same check.

I ran into this while building Dayframe (#43152). It uses B, which meant re-pointing ten component token maps: card, list group, table, nav, nav pills, dialog, menu, popover, toast and datepicker (vite.config.ts).

Questions:

1. Is option A, the Album pattern, the intended way to build this layout, including how it looks in dark mode?
2. Would you consider a separate surface role, for example "surface" in $theme-bgs (--bg-surface), defaulting to var(--bg-body)? Card, list group, table, dialog, drawer, menu, popover and toast would read it instead of --bg-body. The default output would not change, and a tinted canvas would only need --bg-body changed, plus --bg-surface if the cards should differ from white.

Related: #42657 (keep $theme-bgs a linear scale) and #38733 (v5.3, where $body-bg also sets component backgrounds).

Snippet. Switch the OS or devtools colour scheme to see dark mode:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Tinted canvas with raised cards</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/bootstrap@6.0.0-alpha.1/dist/css/bootstrap.min.css"
      integrity="sha384-B/GM4XqrwHnWXNOWMbloTmrYXZg10cakYGmpfsR/bbzQ6JAJI4ihuyADKLnBgrCe"
      crossorigin="anonymous"
    />
    <style>
      /* A: keep --bs-bg-body as the card surface and paint the canvas with a numbered step
       (what the Album example does with .bg-1) */
      /* B: make the canvas the body token and raise cards onto the next step */
      .option-b {
        --bs-bg-body: light-dark(var(--bs-gray-050), var(--bs-gray-975));
        --bs-bg-1: light-dark(var(--bs-white), var(--bs-gray-950));
      }
      .option-b .card {
        --bs-card-bg: var(--bs-bg-1);
      }
    </style>
  </head>
  <body>
    <div class="container-fluid">
      <div class="row">
        <div class="md:col-6 p-4 bg-2 option-a">
          <h2 class="h6">
            A: canvas <code>.bg-2</code>, card <code>--bs-bg-body</code>
          </h2>
          <div class="card">
            <div class="card-header">Card header</div>
            <div class="card-body vstack gap-3">
              <ul class="nav nav-pills">
                <li class="nav-item">
                  <a class="nav-link active" aria-current="page" href="#"
                    >Active</a
                  >
                </li>
                <li class="nav-item"><a class="nav-link" href="#">Link</a></li>
              </ul>
              <div class="alert" role="alert">An alert inside the card</div>
              <ul class="list-group">
                <li class="list-group-item">List group item</li>
              </ul>
              <table class="table mb-0">
                <tbody>
                  <tr>
                    <td>Table cell</td>
                  </tr>
                </tbody>
              </table>
            </div>
          </div>
        </div>
        <div class="md:col-6 p-4 bg-body option-b">
          <h2 class="h6">
            B: canvas <code>--bs-bg-body</code>, card <code>--bs-bg-1</code>
          </h2>
          <div class="card">
            <div class="card-header">Card header</div>
            <div class="card-body vstack gap-3">
              <ul class="nav nav-pills">
                <li class="nav-item">
                  <a class="nav-link active" aria-current="page" href="#"
                    >Active</a
                  >
                </li>
                <li class="nav-item"><a class="nav-link" href="#">Link</a></li>
              </ul>
              <div class="alert" role="alert">An alert inside the card</div>
              <ul class="list-group">
                <li class="list-group-item">List group item</li>
              </ul>
              <table class="table mb-0">
                <tbody>
                  <tr>
                    <td>Table cell</td>
                  </tr>
                </tbody>
              </table>
            </div>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>

[i6moons]

You don't need to re-point the component token maps. In alpha.1 you get the same result by re-declaring the --bs-bg-* scale on the raised surfaces, because each component resolves its tokens on its own element. Whether the Album pattern's dark-mode result is intended is a question for the maintainers. What follows is just what works with the current code.

Each component emits its token map on its own selector. For example, .card { @include tokens($card-tokens) } sets --card-bg: var(--bg-body) and --card-cap-bg: var(--bg-1) (_card.scss#L24-L39). List group, table, menu, dialog, popover and toast all work the same way. The $theme-bgs values themselves are emitted only once, on :root (_root.scss#L148-L151, #L204-L206). So when .card declares its own scale, the card and everything inside it resolve against that scale. Caps, alerts, the pills track and hover states stay one step away from the card.

@layer custom {
  body {
    background-color: light-dark(var(--bs-gray-050), var(--bs-gray-975));
  }

  /* Raised surfaces: stock scale in light mode, one step lighter in dark mode */
  .card, .dialog, .menu, .popover, .toast {
    --bs-bg-body: light-dark(var(--bs-white), var(--bs-gray-950));
    --bs-bg-1: light-dark(var(--bs-gray-025), var(--bs-gray-900));
    --bs-bg-2: light-dark(var(--bs-gray-050), var(--bs-gray-800));
    --bs-bg-3: light-dark(var(--bs-gray-100), var(--bs-gray-700));
    --bs-bg-4: light-dark(var(--bs-gray-200), var(--bs-gray-600));

    /* These aliases are resolved on :root, so they don't follow the scale */
    --bs-btn-input-bg: var(--bs-bg-body);
    --bs-control-disabled-bg: var(--bs-bg-3);
    --bs-border-bg: var(--bs-bg-body);
    --bs-fg-bg: var(--bs-bg-body);
  }
}

I tested this in Chromium with the alpha.1 CDN CSS. Light mode matches your option A exactly. In dark mode:

• the canvas is #080a0c and the card is #0f1214;
• the card header, alert, pills track and hover states are #171a1d;
• list group items, table cells and inputs inside the card are #0f1214, the same as the card;
• menus, toasts, popovers and dialogs also take #0f1214, with #171a1d headers;
• list groups and inputs placed directly on the canvas keep their stock colours.

Add .drawer (and its responsive variants) or any other surface you treat as raised. custom is the layer Bootstrap reserves before helpers/utilities (_root.scss#L8), so .bg-* utilities still win. The bs- prefix is added by Bootstrap's PostCSS step (postcss.config.mjs#L29-L32). If you compile the Sass without that step, drop the prefix.

The catch is that this relies on where the tokens happen to be declared. That's my reading of the source, not a documented contract. Some tokens are resolved once on :root (#L78, #L85), along with the --bs-*-focus-ring colours, which are mixed against the root --bs-bg-body. Those don't move with the scope, and any future component that reads a root-level alias will escape it too. A surface role like the one you propose would make this explicit rather than incidental. That needs a framework change, so it's up to the maintainers.