Add documentation for supplemental CSS classes

[stpaultim]

We need to add documentation to support backdrop/backdrop-issues#4782

I'm not sure where to put this documentation, so I created a new documation page for Basis here:
https://docs.backdropcms.org/documentation/default-theme-basis

I welcome feedback on the location and content of this page.

This page is currently in draft mode and should not be published until the release of version 1.30.

[stpaultim]

It occurs to me (and @bugfolder) that we probably ought to provide some documentation for core contributors on how to use supplemental CSS classes in PR's that effect Basis.

I could try to write this documentation. But, may wait until I have a chance to discuss at a meeting.

[stpaultim]

One thing to clarify may be whether or not to use body.update-1-30 if it's not necessary or to stick with update-1-30.

Here are the first three PR's using the new class.

• https://github.com/backdrop/backdrop/pull/4967/files
• https://github.com/backdrop/backdrop/pull/4974/files
• https://github.com/backdrop/backdrop/pull/4959/files

[izmeez]

I'm not sure where to put this documentation, so I created a new documation page for Basis here: https://docs.backdropcms.org/documentation/default-theme-basis

I welcome feedback on the location and content of this page.

This page is currently in draft mode and should not be published until the release of version 1.30.

Unfortunately, I get Access Denied because it is a draft.

[bugfolder]

One thing to clarify may be whether or not to use body.update-1-30 if it's not necessary or to stick with update-1-30.

That's part of a more general question: should we we always strive for the minimum-sized selector necessary (versus giving a hint to CSS readers which DOM element is carrying the selector)?

An existing example would be html[dir="rtl"] versus [dir="rtl"]. I see in the example for "Styling for Right-To-Left Languages" on https://docs.backdropcms.org/css-standards that the latter is what's suggested. So that suggests that we should stick with update-1-30.

[bugfolder]

https://docs.backdropcms.org/documentation/default-theme-basis... is currently in draft mode and should not be published until the release of version 1.30.

Since it specifically states that it's applicable to 1.30 (and later), I'm taking the liberty of publishing it to make it visible to potential reviewers like @izmeez and others.

I like it. I'd suggest it belongs at User Guide > Using Backdrop > Themes > Default Theme: Basis—which is right where @stpaultim set it to appear (so agreement on placement).

[izmeez]

Thank you for publishing the draft doc.

At the point where it goes:

If you have an older site and wish to accept supplemental css updates to Basis you may want to try the Supplemental CSS UI module.

This can have a heading:

Supplemental CSS UI module (release pending).

The Supplemental CSS UI module provides options to:
...

Before this section it may help to have a section,

How existing sites can accept supplemental css updates to Basis

Existing sites with Basis subthemes will need to consider if the CSS changes to Basis conflict or make obsolete CSS in the subtheme. Also, must do ....

[izmeez]

On the docs page css-standards https://docs.backdropcms.org/css-standards before the heading Whitespace would it help to add:

While, selectors can include the DOM element, in Backdrop we always strive for the minimum-sized selector necessary.

For example: rather than body.update-1-30 it is kept minimal as .update-1-30.

Another existing example is html[dir="rtl"] versus [dir="rtl"].
where in "Styling for Right-To-Left Languages" it is suggested to use the latter.