Theming workflow

[HeroicEric]

While trying to develop the ui-tomato-theme I was pretty quickly faced with
some confusion around what type of stuff I should be editing. I thought it would
be useful to have the conversation here so we can maybe later use it as a
starting point for docs.

Theming by changing global variables

My initial thought was to start by customizing some of the SCSS configuration
variables to match the style of a tomato picnic.

The first step was to make sure that the variables that I wanted to customize
were marked as !default inside ui-base-theme:

$untitled-ui--page-background: #f5f8f9 !default;
$untitled-ui--content-background: #ffffff !default;
$untitled-ui--font-color: #303030 !default;
$untitled-ui--default-color: #6a6a6a !default;
$untitled-ui--primary-color: #1787e5 !default;
$untitled-ui--focus-color: #0090ff !default;
$untitled-ui--error-color: #ff0000 !default;

I figured this was a good set of variables to customize to quickly make the
theme visually distinguishable from the base theme. This allowed me to create a
config stylesheet in ui-tomato-theme to provide new values for these
variables:

$untitled-ui--page-background: #F9ECAB;
$untitled-ui--content-background: lighten(tomato, 90%);
$untitled-ui--font-color: darken(tomato, 85%);
$untitled-ui--default-color: tomato;
$untitled-ui--primary-color: #7CCF9B;
$untitled-ui--focus-color: lighten(tomato, 30%);
$untitled-ui--error-color: darken(tomato, 50%);

This works and we end up with components being styled differently but I'm not
sure if this is the intended workflow. These changes affect all of the
components from ui-base-theme.

Questions

If the eventual goal is to support multiple themes being active at the same
time, how does this work if the theme's styles are based on these variables?

If we instead created another set of variables in the subtheme with a different
prefix, how do automate those variables being passed to subtheme components?

Theming by creating new scss files in the subtheme

Another way to theme a component is to create a new SCSS file inside your
subtheme for the component.

For example, to create the tomato theme's ui-button--default, in your subtheme
you can create the following SCSS file:

// your-theme/addon/styles/components/ui-button--default.scss

@import "ui-base-theme/components/ui-button--default";

@component() {
  @include ui-button--default(
    $background: tomato,
    $color: white
  );
}

This will create a new themed version of ui-button--default component. You can
use this component by providing your theme's name as the value for the theme
property when invoking the component:

{{#ui-button theme="tomato"}}
  Tomato themed button
{{/ui-button}}

Customizing a component's styles this way does not change any of the global
variables and doesn't affect any other components.