CSS variable consistancy

[pixtur]

Prerequisites

• [X] I have searched for duplicate or closed feature requests
• [X] I have read the contributing guidelines

Proposal

I am currently working on a Figma design to incorporate variable-based theme support for a BS5-based site. During the process, I found the CSS Variable documentation to be particularly helpful.

I understand that the Bootstrap team invested significant time and effort in determining these names, likely with good reasons for maintaining the status quo. However, I firmly believe that constructive feedback is always beneficial, hence I would like to share my thoughts.

Expectations

To begin with, I have certain expectations from a variable collection:

• Conciseness should be prioritized, with elements omitted if uncertain.
• Clear and distinct intended purposes for each variable.
• Semantic naming should be followed, focusing on the function rather than appearance.
• Consistency across both light and dark themes.
• Completeness: There should be no other "magic" colors in the CSS to allow seamless switching between light and dark themes by only replacing the variable definitions.
• Bonus: Semantic grouping through the use of prefixes like status-, text-, bg- would be beneficial when sorting alphabetically, though I recognize this may be a personal preference.

While developing the variable specification, I found the current naming conventions rather challenging to work with. As a result, I created a mapping table to prevent any errors. I am sharing my findings with the hope that they might be considered for inclusion in a future version of Bootstrap.

Suggestions

• Align definitions for dark and light themes for completeness and consistency.
• Remove the --bs-gray-XXX variables, as their inversion for the dark theme could lead to misleading names. A potential alternative could be naming it --bs-foreground-???, where --bs-foreground-full represents the pure color for the light theme and --bs-foreground-000 represents the background color. (Although there might be better names for foreground).
• Remove all duplicate occurrences of -rgb. It's extremely unfortunate that CSS does not allow RGBA variables to be used in rules like...
  background-color: rgba(var(--bs-danger-rgb),var(--bs-bg-opacity))
  But I strongly believe that placing the burden on the theme-developer is confusing, adds unnecessary duplication, is error-prone, and bloats the size of the variable collections. I would prefer to enforce all variable definitions as rgb(23,23,23) as most of them don't use transparency anyways.
• Replace the -color suffix with -text to avoid confusion and maintain consistency with variables such as --bs-warning-text-emphasis or --bs-border-color.
• Replace -light and -dark with alternative wording. My suggestion is to use terms like -muted and -invert.
• I think the definition of emphasizing levels like subtle, (normal), emphasis, should be orthogonal to signals like warning, success, and usage text, bg, border. I can see how it can be nice for things like defining rules like .alert-danger{}. I just would have preferred separate variables for default -text and -bg colors to clarify that --bs-danger is never used for text and -emphasize is actually the default. If there is a --bs-secondary-bg, shouldn't there be --bs-danger-bg? I have the feeling that the naming for layout colors (e.g. --bs-secondary-rgb) collides with levels for signals like --bs-secondary-bg-subtle.

I propose the following mapping:

BS5	Proposal	Remark
--bs-primary	--bs-primary-fill	Colored button background used with white text
--bs-primary-text-emphasis	--bs-primary-text	Colored text in alert boxes, etc
--bs-primary-bg-subtle	--bs-primary-bg	Background for alert boxes with colored text
--bs-primary-border-subtle	--bs-primary-border	Outline for buttons and boxes
--bs-primary-bg	(removed)	Either remove or clarify usage with a suffix like -table-bg
--bs-body-bg	--bs-bg-body	Separate layout from signal.
--bs-secondary-rgb	--bs-bg-secondary	makes it more relatable to layout.

• I initially missed variables for input-components, like input-fill, input-border, input-placeholder and states like focused, required, disabled. But after checking the source-code of the Button-example, I noticed that there actually is a variable --bs-btn-disabled-color and the documentation was just incomplete. A link to the complete list would have helped me.
• If there is --bs-emphasis-color shouldn't there be a --bs-subtle-color? I would found that more intuitive than secondary.

Proposal (RFC).

For my project, I have created the following mapping. If things go well, I can release the figma-library with the correct mapping for dev export.

Figma	BS5	Default dark
text/body	--bs-body-color	#dee2e6
text/emphasis	--bs-emphasis-color	#fff
text/secondary	--bs-secondary-color	rgba(222, 226, 230, 0.75)
text/tertiary	--bs-tertiary-color	rgba(222, 226, 230, 0.5)
text/code	--bs-code-color	#e685b5
text/highlight	--bs-highlight-color	#dee2e6
bg/border-translucent	--bs-border-color-translucent	rgba(255, 255, 255, 0.15)
bg/body	--bs-body-bg	#212529
bg/border	--bs-border-color	#495057
bg/highlight	--bs-highlight-bg	#664d03
bg/secondary	--bs-secondary-bg	#343a40
bg/tertiary	--bs-tertiary-bg	#2b3035
form/invalid-border	--bs-form-invalid-border-color	#ea868f
form/invalid-bg	--bs-form-invalid-color	#ea868f
form/valid-border	--bs-form-valid-border-color	#75b798
form/valid-bg	--bs-form-valid-color	#75b798
text/heading	--bs-heading-color	inherit
text/link	--bs-link-color	#6ea8fe
text/link-hover	--bs-link-hover-color	#8bb9fe
signal/primary-fill	--bs-primary	#2c0b0e
signal/primary-bg	--bs-primary-bg-subtle	#2c0b0e
signal/primary-border	--bs-primary-border-subtle	#842029
signal/primary-text	--bs-primary-text-emphasis	#ea868f
signal/secondary-fill	--bs-secondary	#2c0b0e
signal/secondary-bg	--bs-secondary-bg-subtle	#2c0b0e
signal/secondary-border	--bs-secondary-border-subtle	#842029
signal/secondary-text	--bs-secondary-text-emphasis	#ea868f
signal/tertiary-fill	--bs-tertiary	#2c0b0e
signal/tertiary-bg	--bs-tertiary-bg-subtle	#2c0b0e
signal/tertiary-border	--bs-tertiary-border-subtle	#842029
signal/tertiary-text	--bs-tertiary-text-emphasis	#ea868f
signal/success-fill	--bs-success	#2c0b0e
signal/success-bg	--bs-success-bg-subtle	#2c0b0e
signal/success-border	--bs-success-border-subtle	#842029
signal/success-text	--bs-success-text-emphasis	#ea868f
signal/info-fill	--bs-info	#2c0b0e
signal/info-bg	--bs-info-bg-subtle	#2c0b0e
signal/info-border	--bs-info-border-subtle	#842029
signal/info-text	--bs-info-text-emphasis	#ea868f
signal/danger-fill	--bs-danger	#2c0b0e
signal/danger-bg	--bs-danger-bg-subtle	#2c0b0e
signal/danger-border	--bs-danger-border-subtle	#842029
signal/danger-text	--bs-danger-text-emphasis	#ea868f
signal/warning-fill	--bs-warning	#2c0b0e
signal/warning-bg	--bs-warning-bg-subtle	#2c0b0e
signal/warning-border	--bs-warning-border-subtle	#842029
signal/warning-text	--bs-warning-text-emphasis	#ea868f
signal/invert-fill	--bs-dark	#2c0b0e
signal/invert-bg	--bs-dark-bg-subtle	#2c0b0e
signal/invert-border	--bs-dark-border-subtle	#842029
signal/invert-text	--bs-dark-text-emphasis	#ea868f
-	--bs-body-color-rgb	222, 226, 230
-	--bs-emphasis-color-rgb	255, 255, 255
-	--bs-link-color-rgb	110, 168, 254
-	--bs-link-hover-color-rgb	139, 185, 254
-	--bs-tertiary-color-rgb	222, 226, 230
-	--bs-secondary-bg-rgb	52, 58, 64
-	--bs-tertiary-bg-rgb	43, 48, 53
-	--bs-light-border-subtle	#495057
-	--bs-light-text-emphasis	#f8f9fa

Motivation and context

see above.

[julien-deramond]

Thanks a lot @pixtur for such detailed feedback. I'm tagging it as v6 as it can be studied in depth when we start working on the new major version of Bootstrap where we plan some CSS refactoring, especially regarding the themes (and so the Sass/CSS vars linked to that). I'll read your feedback thoroughly as soon as possible.

[pixtur]

@julien-deramond Thank you. I hope I didn't come across too negative here. While writing the issue and reading the documentation more thoroughly, I had to remove and adjust many of my initial complaints. This is just my way of learning stuff. BS really has come a long way. So, if I can slightly contribute to upcoming releases, perfect!