CSS Codestyle proposal : name conventions for colors

Development
#1

Hi! I was working on the PR for XWIKI-21584: Mentions do not have enough contrast and figured out a codestyle rule would have made it easier to fix.

Proposal

All colors must be defined for either a foregound or a background. To name those, use color for foreground color, and background or bg for background colors.

Explanation

This codestyle contains 2 parts:
A. All colors must be background OR foreground.
B. Naming convention for background and foreground colors.

Keeping contrast correct on all elements is not easy without such a standard. Here is an example for part A. :

Dev1 defined color1 and bg1 to style UI1. Later on, Dev1 does not respect the codestyle proposal A., and uses color1 as a background color, with color2 as a foreground color for UI2. On the theme of Dev1, the contrast is okay. However, Admin1 uses its own corporate color theme. They saw how color1 and bg1 were used in UI1, and updated those colors to fit their color theme. However, when they update their instance and get to see UI2, it looks broken. Making sure the colors used have correct contrast will be difficult for Admin1: just changing color2 is not enough because color1 is too dark as a background… Here, in order to make sure it’s easy to migrate, Dev1 should have introduced a new variable bg2 to style UI2 (even if it has the exact same value as color1 in the default colortheme).

Part B. is just to make sure it’s easy to apply and respect part A. It makes sure we don’t have half the pairs named as color+background and the other half named as foreground+color.

Note that we already respect this codestyle in most places in xwiki-platform. In my opinion we should add it as a codestyle to make sure we have a better consistency.

Conclusion

Do you agree with adding this codestyle to our CSS Codestyle, right after don't hard code colors in properties?

Note that this rule should also be generalized to the content of color variables defined in other files. IMO it makes the most sense to have it in the CSS codestyle rules, but we might also want to put it in XWiki XML Files Code Style but I’d rather not duplicate the doc.

1 Like
#2

Hi,
I toadly agree on that.

It helps both for setting and customizing, and for updating.

Thanks.

#3

To be sure I understand, can you show some examples? (always better with some examples in rule definitions ;))

Globally seems good so ok for me.

Thanks

#4

Thank you for your feedback!

Updated proposal

All colors must be defined for either a foregound or a background. To name those, use color for foreground color, and background or bg for background colors. For example, we use @btn-default-color for the text color in the default button, and @btn-default-bg for its background color.

I’ll set this updated codestyle on Friday the 29th if noone disagrees by then :slight_smile:

Lucas C.

#5

oh ok, I thought you meant to use color for foreground color, and background or bg for background colors… :slight_smile: But you actually mean: suffix the variable with either color or bg (or background) ? Should we more precise about the use of dash -? Also why propose 2 suffixes for background and not just one?

Thanks

#6

I don’t think it’s necessary to enforce it being a suffix. It’ll probably happen most of the time but I think it’s also okay to let some leeway for naming those.
Note that some of the variables we have in the codebase would break this and are IMO easy enough to understand already e.g., @xwiki-background-secondary-color. Breaking backward compatibility or having a mapping for legacy use just to change word order here would be a bit overkill in my opinion.

We already have naming conventions for HTML classes and ids (use kebab-case), but not LESS variables. This codestyle is not a proposal for a full naming convention, just a standard for vocabulary used to define colors.
It could be interesting to get one, but to be honest, I think we’re very far from being consistent enough to adopt a naming convention just like that and someone would need to dig a bit further to see what we can do.

Because in practice there are both in our codebase and IMO it’s okay to use both as long as they both convey the same meaning. E.g., @xwiki-background-secondary-color

Note that my main pain point with the foreground+color wording is that color does convey a different meaning to color+background. The color meaning stays the same whether we use bg or background.

Does that make sense?

#7

Sure. But To name those, use color for foreground color, and background or bg for background colors is still not very precise. Proposal: To name those, use the "color" word in the variable name for foreground color, and the "background" or "bg" words in the variable name for background colors. + the example.

I was referring to bg and background.

What does foreground+color mean?

Is this a background color or a foreground color?

Thx

#8

:+1:

Updated proposal

To name those, use the “color” word in the variable name for foreground color, and the “background” or “bg” words in the variable name for background colors.For example, we use @btn-default-color for the text color in the default button, and @btn-default-bg for its background color.

Arg, I didn’t even notice but this variable name is a prime example of why it’s difficult to set a standard.
It uses both background and color in its name…
I’ll add a footnote to the codestyle rule to describe this weird case:
If a variable name must contain both "color" and "background", it will be considered a background variable.

The meaning of the pair is the same as color+background, but the meaning in isolation of color changes. In isolation, most -color variables are foreground variables. However this is the opposite for -color variables that are from a foreground+color pair.

I just checked and this should be used as a background color. This name ended up being quite terrible ^^’

Another example of use of background in a variable is @xwiki-accordion-title-bar-background.

Thanks!

#9

Closing this proposal and updating the documentation :slight_smile:

Thanks,
Lucas C.