Proposal: LESS and CSS variable naming convention

Development
1

Hi!

Context

When refactoring LESS variables at XWIKI-22893: Improve consistency of global LESS variable declaration in Flamingo by Sereza7 · Pull Request #3663 · xwiki/xwiki-platform · GitHub , i realized that we had pretty much already a LESS naming convention that was undocumented.

Proposal 1

Use kebab-case for LESS and CSS variables.

Explanation

  • Except for one LESS variable @loginFormMaxWidth, this convention is already respected in XWiki Standard. This was the LESS variable naming convention used in bootstrap.
  • This convention goes well with the CSS variable syntax: var(--login-form-max-width). It would be good to have a naming convention as soon as we start using CSS variables.
  • This is the same convention we use for naming HTML ids and classes. Adopting camel-case for variables in CSS/LESS too would keep some kind of consistency when writing stylesheets.

Proposal 2

Break backwards compatibility with @loginFormMaxWidth.

Explanation

  • This is the only LESS variable in XWiki Standard that does not follow the naming convention we were using off the books.
  • This variable has only been used in one specific place in XWiki Standard
  • It was never exposed in documentation.
  • Its name designates a very specific concept. I doubt it’d have been used in any customization. Could not find any usage in public extensions available on the XWiki org on github : Code search results · GitHub Even if it was used in a customization, its name is so specific that it shouldn’t break much (only some of the layout of the login form?).

All of the above makes me think that this variable should not be considered API and can be safely replaced by a new variable respecting the naming convention.

Conclusion

Here’s my personal +1 for proposal 1 and 2

Do you agree with those proposals?
If proposal 1 is validated, I’ll update our codestyle doc on https://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle/XhtmlCssCodeStyle/#HCSS . If proposal 2 is validated, we’ll go through with the replacement on XWIKI-22893: Improve consistency of global LESS variable declaration in Flamingo by Sereza7 · Pull Request #3663 · xwiki/xwiki-platform · GitHub .

Thank you for your time!
Lucas C.

2

+1 for kebab-case, I don’t have any strong opinions regarding proposal 2, +0 from my side.

3

Same here.

4

+1 for proposal 1

A few points regarding proposal 2:

  • this example shows that it is sometime useful to define internal stylesheet variables. Shouldn’t we agree on a naming convention (e.g., @xwiki-internal-...?) and, if we agree on the breakage, rename to @xwiki-internal-login-form-max-width)
  • I’m -0 to break, did you check if we have a way to define the variable on a “legacy” module? Otherwise, we’ll need to document this on the RN with a clear explanation of how to add back the variable if needed
5

Thanks for the idea!
Looks good to me. Makes it a bit clearer what we consider API while giving an option to leave things as internal :+1:

Summary of vote results

  1. Use kebab-case for naming LESS/CSS variables: +1 * 4
  2. Rename the @loginFormMaxWidth variable: +0 * 2 -0 * 1 (+1 * 1)

I’ll update our doc to add proposal 1. .
I’ll implement 2. but be especially careful in release notes (and provide a legacy variable if it’s something we already do).

Thanks for your feedback!
Lucas