Establish CSS principles to avoid conflicts

[ggrossetie]

Since the HTML produced by Asciidoctor will be deployed to many different applications, it’s critical to ensure that the design system’s CSS doesn’t conflict with other libraries and systems.

For reference, using a unique name (for instance "asciidoc") on the root element to scope styles (e.g., ".asciidoc .block") is not enough because we can still create elements within this root element using JavaScript or Asciidoctor extensions.

For instance:

<main class="asciidoc">
<p>
Press <span class="button">Okay</span> or <span class="button">Cancel</span> to close the dialog.
</p>
</main>

In the above example, we don't really know if the buttons are AsciiDoc buttons or not.
This can be addressed by adding a global namespace:

<main class="asciidoc">
<p>
Press <span class="asciidoc-button">Okay</span> or <span class="button">Cancel</span> to close the dialog.
</p>
</main>

Here the "Okay" button is an AsciiDoc button whereas "Cancel" is just a button.

All classes associated with the design system are prefixed with a global namespace, which is the Company Name followed by a hyphen
If you’re working on a CSS architecture that is only meant to be served to a single site or if you have a lot of control over your environment, including a global namespace is likely unnecessary. But if your design system is intermingling with other technologies, it might make sense to create an identifier for system-specific code.

bradfrost.com/blog/post/css-architecture-for-design-systems

It's interesting to note that using an additional class name won't prevent conflicts with other CSS libraries. For instance, Bulma or Bootstrap could declare a specific style on ".button" and, as a result, it will also apply on ".asciidoc .button".

If we decide to add a namespace on every elements created by Asciidoctor we might want to control whether or not we want to add this namespace when creating an element from an Asciidoctor extension.

I also think that we should use this global namespace even if we produce a complete HTML document. The reason is that it's still possible to create elements within the root element (for instance using JavaScript from a Docinfo file).

Thoughts?