Theme authoring best practices

[alex-ketch]

Starting a conversation here @nokome about reevaluating our approach to building themes, and how to best make them upstanding CSS citizens where they don't cause conflicts and clashes with existing styles or nested custom elements.

---

Right now it's hard for the Thema generated styles to be used

• in shared contexts where conflicts might occur to the theme, or unrelated elements on the host page
• Some of the selectors can cause unintended thrashing of child content (currently observed in the non-shadow DOM Designa components like the current CodeChunk)

To address some of these issues I want to explore generating themes targeting only top level block selectors, an adapted list based on Bulma's .content class selectors. We can go a step further and use child combinator (>) selectors to only style direct children of <article> or a some sort of #themeNameTarget id for higher selector precedence.

As mentioned here, something to solve for are nested block selectors such as ol > li > figure.

We can also generate two variants of the stylesheets, one that can be placed on a page to style every matching element, or another that can be scoped to the children of a certain element for use alongside other stylesheets. Adds more decision-making around usage, but give more control. (Tools ref: PostCSS Scopify, postcss-selector-scope)

Re. developer experience:
once we have a structure in place, we can add custom linter rules warning against using naked generic selectors such as div, span, etc.

I'm still not convinced that shared styles are a good idea in the context of multiple authors writing themes, where they are not familiar with the intricacies of other themes.
If we do have them, one of the top priorities for me would be to add screenshot regression testing for comparisons.
My concerns are that there are very few safe assumptions that can be made, and any "improvements" we make to the shared elements has potential to break the author's theme.

Instead I think we should provide a list of custom selectors and mixins to ease development, an a skeleton starter theme they can duplicate and work on.

---

Some ideas for dismissal/exploration:

• Having a init script to wrap content in a Shadow DOM context, and encapsulate the styles. Drawbacks being that themes now become dependent on JS, and we'll probably need to add some polyfills such as ShadyCSS for broader browser support.
• Not terribly sure how useful this would be, as it requires integration with the consumer build process, but we can generate CSS Modules with hashed selectors and JSON file with the mappings between the hashed selector, and the stylesheet.

[nokome]

use child combinator (>) selectors to only style direct children of

or a some sort of #themeNameTarget id for higher selector precedence.

Agree that we need something like this. Requiring theme authors to use direct child selector seems like a good approach. I'd like to keep an emphasis on "semantic selectors" and instead of using article or a id selector like #themeTarget, use :--Article. Although at present there is a one-to-one relation between <article> and :--Article, in the future we may find we have markup like `

.

something to solve for are nested block selectors such as ol > li > figure.

Shouldn't this be solvable using something like,

:--Article > figure,
:--Article > ol > li > figure

We can also generate two variants of the stylesheets

Using PostCSS Scopify would essentially be an automated way of doing the above. My initial sense is that we should not do that and ask authors to use the above approach to manual scoping.

once we have a structure in place, we can add custom linter rules warning against using naked generic selectors such as div, span, etc

I'm still not convinced that shared styles are a good idea in the context of multiple authors writing themes, where they are not familiar with the intricacies of other themes.
Instead I think we should provide a list of custom selectors and mixins to ease development, an a skeleton starter theme they can duplicate and work on.

Yep, those are valid concerns. I suggest we:

• rename common/ to shared/ to emphasize that any changes there will affect multiple themes and note that in guidelines for authors and PR reviewers.
• limit any CSS in there to custom selectors, variables (?) and mixins
• set up themes/skeleton as a minimal theme but with comprehensive use of those selectors and mixins including usage comments e.g. illustrating how to use the Person mixin, but

/* Authors of cited works */
:--Article > :--references > :--citation > :--Person {
  @mixin Person {
    /* Use `order` to change the order that names appear */
    :--givenName {
      order: 2;
    }
    :--familyName {
      order: 1;
    }
    /* Don't display email, or affiliations */
    :--affiliations, 
    :--email {
      display: none;
    }
  }
}

• refactor what is in designa/ into shared/

add screenshot regression testing for comparisons.

I think this should be a prority anyway, although not sure how much work is involved.

[stencila-ci]

🎉 This issue has been resolved in version 1.6.0 🎉

The release is available on:

• npm package (@next dist-tag)
• GitHub release
• v1.6.0

Your semantic-release bot 📦🚀