mod-blocks preview: dark-mode block overrides mode-aware tokens with different families

[markdumay]

What

The preview panel sets its surface and its iframe border from mode-aware Bootstrap tokens, and then overrides both in a [data-bs-theme="dark"] block with tokens from different families. Because the light-mode tokens already carry dark values of their own, the overrides are not needed to obtain a dark appearance — what they do is change which token the component follows, depending on the color mode.

The two instances

// light
.preview-content {
    background-color: var(--bs-tertiary-bg);          // line 56
}
.preview-iframe {
    border: 1px solid var(--bs-border-color);         // line 74
}

// dark
&[data-bs-theme="dark"],
[data-bs-theme="dark"] & {                            // lines 243-244
    .preview-content {
        background-color: var(--bs-dark-bg-subtle);   // line 246
    }
    .preview-iframe {
        border-color: var(--bs-border-color-translucent);  // line 250
    }
}

Why the overrides look unintended

Both light-mode tokens are redefined by Bootstrap under the dark root, so they flip on their own. From Bootstrap's scss/_root.scss:

• --bs-tertiary-bg — defined at line 76 for the light root, redefined at line 152 for the dark root
• --bs-border-color — defined at line 100, redefined at line 178

So .preview-content would already have had a dark surface with no override at all.

The substitutes are not the dark counterparts of those tokens, they are members of other families:

• --bs-dark-bg-subtle is generated from $theme-colors-bg-subtle (_root.scss:29-30, and :159-160 for dark), i.e. the theme-color subtle family keyed on the dark theme color. It is not a body-surface token. In light mode it resolves to $dark-bg-subtle, which defaults to $gray-400.
• --bs-border-color-translucent is the alpha variant of the border token rather than its dark value.

The net effect is that the panel's surface identity is tertiary-bg in one mode and a theme-color subtle in the other. For a theme that customizes $body-tertiary-bg / $body-tertiary-bg-dark — which is the documented way to restyle surfaces — the light mode picks the customization up and the dark mode does not.

Reproducing

Set $body-tertiary-bg-dark to a distinctive value in a site's variable overrides and view a preview block in dark mode. The panel keeps --bs-dark-bg-subtle and ignores the surface value. The light mode responds as expected.

Suggested resolution

Either drop the two dark-mode declarations and let the mode-aware tokens flip — which appears to be what the light branch already assumes — or, if the different tokens are deliberate, a short comment saying so would prevent this being re-reported. I could not find an existing issue covering it.

Note

preview.scss line numbers are from the current default branch at the time of writing; the rules are easy to find by selector if they move.