RFC: Theming support

We get questions and requests for this a lot. Some of which can be seen in #802 #775 #366 #851 and #472. This is not an exhaustive list by any means and excludes Gitter conversations and conversations @TechnologyAdvice. I’m opening this RFC to get feedback and consolidate the brain cycles being spent on this.

The goal here is to support the full theming capabilities of Semantic-UI core (SUI) directly in Semantic-UI-React (SUIR). This is extremely powerful as can be seen in this GitHub remake example, be sure to click the little paint bucket icon next to the notifications icon to open the theming sidebar.

Problem Statement

Apps need themes. Theming should be stupid simple and immediately accessible. Currently, it is anything but. Theming requires cloning a separate repo, with a separate build system, building a theme, hosting it somewhere, then adding it to your project. This is not acceptable.

Ideal Scenario

You should be able to choose a theme right in the project that is implementing SUIR. You should also be able to change theme variables and add component style overrides directly in your project.

You should be able to add not only inline styles to individual components but theme-aware-inline-styles. Example, when the background color is set on a Button, it should know how to handle the variations for basic and inverted and also states like :hover and :active.

Possible Solutions

I’ve been experimenting with a few approaches to making this happen. Just today, I was shown Styletron, a highly performant “universal CSS-in-JS engine.” This is almost identical to the approach I wanted to take. I suggest reading the blog post and checking out the related projects linked in the README. Something very similar to this, or Styletron itself, might be the tool we need to bring theme support to SUIR.

I don’t think adding theme support is worth it if we were to consider doing so with a traditional CSS solution. These include preprocessor builds (SCSS/LESS/etc), intelligently importing individual component stylesheets, modifying preprocessor variables, and the like. All traditional approaches to CSS come with several issues such as globals, infinitely growing CSS sheets, no static analysis, no dead code elimination, etc. If we do this, I think it is only worth it if we do so with a novel modern approach that solves these issues as well.

How do we get there?

I don’t know. Here is a brain dump.

It’s a rewrite

Tools like Styletron bring us closer to be able to pull this off. The daunting bit here is that no matter the tool, we’re talking about implementing the SUI CSS spec in another language. This is an undertaking comparable to SUIR itself, which re-implemented SUI HTML in React.

This leads to an obvious point that if this work were produced, it certainly should not be dependent on React. It should be a framework agnostic tool that React components can implement easily. It also should not be dependent on a CSS preprocessor or CSS tool. Again, Styletron has this covered with styletron-react.

The good news here is that we would no longer be limited by the sometimes awkward CSS and HTML required by SUI. We could make changes to the styles along with the components as necessary.

It should be in JS

This should be done with plain JS objects and a smart engine that can generate stylesheets. JS gives you portability and static analysis. Portability means you can easily share and use style objects anywhere, client side, server side, React, Elm, etc. You can even request them as JSON from a server. Static analysis means you can generate selectors, perform dead code elimination, optimize stylesheets, and do just about anything else you desire.

This is where I think Styletron really got it right. It appears they are implementing many of these features based on plain objects.

Bye, bye, className buildup

Yep, no component would ever use an HTML className. Instead, they would compose style objects. The style engine would be responsible for applying that style to the component. Ideally, it would generate an optimized stylesheet, inject it into the page, and assign the required classNames to the component. In fact, this is precisely what Styletron does.

If we’re not using SUI CSS nor SUI markup, is this even a SUI project anymore?!

Absolutely. SUI is a language for web components, it is not an HTML, CSS, nor JS framework. Qutoing @jlukic from a recent email, he is actually working toward

…a “W3C for UI”, an organization which can create simple written specifications for UI components (what methods, options, behaviors) that developers can freely implement “to spec” in their chosen framework or methodology.

The SUI language would be expressed in our component props still just as it is today. We just would not implement any HTML classes. All our current utils for props-to-className buildup would become props-to-composed-style-object utils. I can imagine this tech aligning far better with the Semantic UI language itself.

Possible Implementation & API

Heads up! These are completely fragile and undeveloped ideas.

Composing Style Objects

SUI provides a common language across all components. Consider “variations” such as color, inverted, basic and fluid. Most components implement most variations. Each variation would then have an associated style object. Changing styles from basic to inverted just means merging the inverted style object into the style after the basic variation object. This is also true with theme information.

This sounds identical to CSS until you consider what can be done in JS compared to CSS in terms of libraries, logic, and functional composition. Color manipulation, context-aware CSS transitions, data-driven styles come to mind.

Child Components

Forgive the extremely unruly code here, but in experiments in this codepen, I’ve shown some rough ideas on how you could generating themes from plain objects. The important bit in that POC is the use of React context to pass cascading theme information to child components.

Example, there is a default Button style and at the bottom of the pen there is a Panel with a Button child. When placed in the Panel, the Button merges a new style it obtained from the Panel. A mechanism like this is needed to handle composing style objects in replacement of traditional cascading styles. This way, when a Button is placed in an inverted Segment, the Button applies its own inverted style “variation”.

A mechanism like this would need to be designed and generalized so that it works with all components. It should be based on the SUI language. If so, then most (hopefully all) nested styles could be rendered unnecessary. Instead of a stylesheet including all possible permutations of component hierarchies, parent components would set the theme context for their domain and child components would apply their appropriate style objects. This way, the theming is more or less “flat”.

Config and Provider

We would also need some ability to set configuration at the app level. This would contain the theme settings. I believe for this to work we may also need to include a root Provider component that would be in control the app’s theme.

---

I’ll leave this open-ended for comments, doubts, and other ideas.

[levithomason]

Thanks for the heads up @Un3qual. So everyone knows, we are currently reviewing:

• aphrodite
• cssobj
• cxs
• fela
• free-style
• glamor
• j2c
• jss
• styletron
• styled-components
• stylis

We’re also taking any insights and cues from https://github.com/airbnb/react-with-styles.

We’re considering these factors:

• package size
• ops/sec for various rendering tasks
• generated CSS size
• globals support (e.g. html and body styling)
• avoidance of name collisions with existing CSS
• SSR
• rehydration of styles on the first render
• …and some others

Our end goals will include:

• styles auto-imported with components
• only styles for used components are imported
• global theme settings
• component-level theme settings
• runtime element-level theme overrides
• live edit theming in the docs
• ease of creating, applying, and sharing themes (perhaps a theme builder app)

[Un3qual]

I came here from #1526 just to add that I think styled-components should be considered.

EDIT: Fela’s atomic thing looks cool too