Color palettes

[David-Mulder]

The material design spec often talks about stuff like:

Use 50-value of secondary app color for background fill

which as far as I know the best way to go about is using something like --paper-pink-50 for the default app-theme.html, however it sucks that the consumer of an element next has to go through all elements to manually set the the respective values up. Wouldn't it be better to have palettes like

--accent-color-50: var(--paper-red-50);
--accent-color-100: var(--paper-red-100);
--accent-color-200: var(--paper-red-200);
--accent-color-300: var(--paper-red-300);
--accent-color-400: var(--paper-red-400);
--accent-color-500: var(--paper-red-500);
--accent-color-600: var(--paper-red-600);
--accent-color-700: var(--paper-red-700);
--accent-color-800: var(--paper-red-800);
--accent-color-900: var(--paper-red-900);
--accent-color-a100: var(--paper-red-a100);
--accent-color-a200: var(--paper-red-a200);
--accent-color-a400: var(--paper-red-a400);
--accent-color-a700: var(--paper-red-a700);

and then use the correct respective colors wherever we need them. Sure, I get that it takes a bit longer to set it up when you start off, but a simple element could help out a lot there in that case (<paper-theme primary="indigo" accent="red">) and that way you would be 99% done in seconds.

[notwaldorf]

That would be neat! After talking to @cdata I think an easy way to do this that (might) work is to make a style is=custom-theme extension that would automagically do this on the fly.

I'll try to take a look at this week! Thanks for the suggestion!

[bendavis78]

I'm actually a bit confused by the recent changes to default-theme.html. I see that the existing names have been deprecated (and I agree, some of them were confusing). But, as an element author, I'm not sure what to use between the --light-* and --dark-* variables. Shouldn't it be up to the app developer whether to use light vs dark theme? It seems that we still need a set of variables that are "preference agnostic" (unless I'm misunderstanding something).

[notwaldorf]

In the past, default-theme was basically just using the light theme (i.e. dark text on a light background). All I did was just rename them in a way for this to make sense.

So, in your code, if you want the text to be dark, because your backgrounds are light, you should use the --light-* versions. I think that's pretty agnostic -- it's just trying to be helpful so you don't accidentally use black text on your dark blue background. :)

[David-Mulder]

@notwaldorf But as a component consumer I will be deciding whether I want my site to use a dark or light theme, so if I want it dark yet the component creator made it light then I would have to set the --light versions with dark colors which makes no sense.

[notwaldorf]

Is the question just about the "deprecated" comment? I can remove it (it's really just --text-primary-color: var(--dark-theme-text-color); that needs to be cut out, so that you still have primary-text-color available and configurable everywhere

[notwaldorf]

Alright, let me know if #89 makes more sense

[David-Mulder]

@notwaldorf The point @bendavis78 correctly raised is that right now there are specific css variables for the light and dark theme which makes no sense whatsoever:

So, I produce a component, let's say a <paper-datatable>, of course I am not going to pick the dark theme as the light theme is the normal one. So I set my background as background: var(--paper-datatable-background-color, --light-theme-background-color). Next a consumer of my element shows up and he wants the paper-datatable - and all other light themed elements - to look dark, so what does he have to do?

--light-theme-background-color:  #212121;

auch

Either way, it would be best to deprecate things like background-color entirely and migrate to things like just primary-color-500, because then it's a true theme rather than mixing intention ('background') and palette ('light' vs 'dark') through each other. The only thing a theme should care about is what 'type' the color is and considering this is supposed to be inspired by MD the setup with just primary-color and secondary-color makes most sense. My proposal would be as follows:

--primary-palette: #3F51B5;
--accent-palette: #FF4081;
--base-color: #000000;

or

<paper-theme primary-palette="#3F51B5" accent-palette="#FF4081" base-color="#000000"></paper-theme>

which will automatically generate the following

--primary-color: #3F51B5;   
--primary-color-light: #C5CAE9; //take by default --primary-color-100, but allow overwriting
--primary-color-dark: #303F9F; //take by default --primary-color-700, but allow overwriting
--accent-color: #FF4081; //take by default --accent-color-a200, but allow overwriting

--primary-color-50: #e8eaf6;
--primary-color-100: #c5cae9;
--primary-color-200: #9fa8da;
// etc.

--accent-color-50: #fce4ec;
--accent-color-100: #f8bbd0;
--accent-color-200: #f48fb1;
//etc.

//the below takes the `base-color` and applies the MD transparencies based on whether 
//the base color is less or more than #888;
--text-color: rgba(0,0,0, .87);
--secondory-text-color: rgba(0,0,0,.54);
--disabled-color: rgba(0,0,0,.38);
--divider-color: rgba(0,0,0,.12);

what do you think?

[notwaldorf]

First of all, I understand your comment about having an element that automatically generates themes. I already said that's a good idea, and I've started looking into it. That element is orthogonal to providing the default light and dark Material Design themes, and is completely unrelated to @bendavis78;s question.

I think you misunderstood what I originally tried to explain. If you look at paper-input, it is using --primary-text-color as its text colour, and will continue to do so. That colour is by default the "light theme" colour, because that's how our elements are set up.

In your demo page, where you are using paper-input and many other paper-elements that also use --primary-text-color as their default color, to change the theme for all the elements at once, all you have to do is:

: root {
  --primary-text-color: red;
}

If you want to change everything from light to dark, then you would change the 5 values in the first section (https://github.com/PolymerElements/paper-styles/pull/89/files#diff-fba59d2899b10cb0edb072669a58ffd1R24) to their dark equivalents, and this would update all the elements.

I have never disagreed with generating a color palette is a good idea, and it will eventually happen. However, in the meantime I don't see a problem with giving people the set of values for the two default Material Design palettes. You don't have to use these properties unless they're useful to you, and they change absolutely nothing from what paper-styles did before this change.

[David-Mulder]

Wait, are you suggesting that the dark and light variables should never be used by element authors? Because if so that would kind of make sense, but that should be very clearly communicated!

And as far as generating the palette, the reason I went out of my way to outline those things was because I wanted to make clear which variables as a component author I need access to based on the MD spec. Importantly noting that dark and light are not terms anywhere I should as a component author encounter. Either way, if my understanding is right now that the dark and light variables should only be used by people setting up app themes then you should probably move those variables from default-theme.html to color.html.

[notwaldorf]

I am not suggesting that. You can use any variables as you please. Maybe you don't want an element to be themable, in the same way you can literally hard code any colour in your element. But generally, not, you as an element author would probably not use the light-* variables except as defaults, if anything.

I think default-theme was meant to be one of the material design themes used in a demo. I can see them being split maybe in light-theme and dark-theme, but probably not color.html

/cc @cdata

[David-Mulder]

So, I worked out a bit of a proposal both on the variable side (which variables should be exposed and why the idea of --light-theme-* and --dark-theme-* is totally inadequate) and a quick implementation of an element generating such a set of variables:

https://github.com/David-Mulder/paper-theme

[JosefJezek]

Check out the PSK+ default-theme
https://github.com/StartPolymer/polymer-starter-kit-plus/blob/master/app/themes/default-theme/variables.css
https://github.com/StartPolymer/polymer-starter-kit-plus/blob/master/app/themes/default-theme/variables.js

[notwaldorf]

@David-Mulder That's super neat!

[mercmobily]

DISCLAIMER: I am fairly new to Polymer. I read this issue a million times, and it really really really confused me. Definitely not a seasoned element author like @bendavis78 and most definitely not a Polymer guru like @notwaldorf .

Having said this.

@notwaldorf I would like to submit a PR documenting exactly:

1. What a producer should do to make sure that widgets follow the paper theme
2. What a consumer should do to theme the elements

This issue is unfortunate because it mixes different things. However, I didn't have the heart to create yet another one -- especially since what I propose is a draft. So, I think I'd much rather pollute this one, and get the "OK" in terms of what I think the document should contain.

Now, let me try to answer the existing statements.

First things first: @danrschlosser

Next a consumer of my element shows up and he wants the paper-datatable - and all other light themed elements - to look dark, so what does he have to do?
--light-theme-background-color: #212121;
auch

I don't think so. default-theme.html defines the usual suspects:

/*
 * Material Design Light background theme
 */
--light-theme-background-color: #ffffff;
--light-theme-base-color: #000000;
--light-theme-text-color: #212121;
--light-theme-secondary-color: #737373;  /* for secondary text and icons */
--light-theme-disabled-color: #9b9b9b;  /* disabled/hint text */
--light-theme-divider-color: #dbdbdb;

/*
 * Material Design Dark background theme
 */
--dark-theme-background-color: #212121;
--dark-theme-base-color: #ffffff;
--dark-theme-text-color: #ffffff;
--dark-theme-secondary-color: #bcbcbc;  /* for secondary text and icons */
--dark-theme-disabled-color: #646464;  /* disabled/hint text */
--dark-theme-divider-color: #3c3c3c;

But --dark-theme-background is only ever referenced within default-theme.html. So, conceptually, it should be read-only, to be used by you if you want to use the values provided by the default themes for typography. They should probably be called --dark-default-theme-background-color, --dark-default-theme-text-color (although they would be obscenely long). So, your consumer would need to do:

--primary-background-color: var(--light-theme-background-color)

Or:

--primary-background-color: #212121;

And you, as a good producer, would use --primary-background-color as a fallback.

@David-Mulder

so if I want it dark yet the component creator made it light then I would have to set the --light version

I think component creators should simply use --primary-color, --primary-background-color, etc. Admittedly, some colours need to be set. For example paper-card.html has, for title-text, color: var(--paper-card-header-color, #000);. Or, paper-checkbox has:

  :host([disabled][checked]) #checkbox {
        background-color: var(--paper-checkbox-unchecked-color, --primary-text-color);
        opacity: 0.5;
      }

So I think here the rule is "element authors should try their very best to be colour-agnostic, and use the theme's default colours whenever possible.

3. @David-Mulder

So, I produce a component, let's say a , of course I am not going to pick the dark theme as the light theme is the normal one.

No, if you produce <paper-datatable>, you shouldn't pick either light nor dark. You should be colour-agnostic, and use the paper-style variables whenever possible (or default to them, like paper-checkbox does).

@notwaldorf

That colour is by default the "light theme" colour, because that's how our elements are set up.

As small correction -- very humbly -- if I may... this sentence should be:

That colour is by default the "light theme" colour, because that's how our default theme is set up by default

Also:

But generally, not, you as an element author would probably not use the light-* variables except as defaults, if anything.

I am not sure about this. I actually think that would be unideal as best, since I see the light- and dark- variables as ways to set defaults for a consumer, which uses them to set the "real" ones (-primary-text-color, -primary-background-color, etc.) which then IN TURN set defaults for widgers.

5. @notwaldorf

Lastly, I think most of the confusion here comes from the fact that default-theme.html defines two different colour sets (dark-theme and light-theme), but then 1) It only uses one of them 2) Element producers shouldn't really use those variables. 3) Element consumers should use those, but they are not told about them clearly enough.

(BTW the use of --light-theme-base-color is really obscure -- I couldn't find a single use-case, AND it's not referenced anywhere in any of polymer's components).

@notwaldorf Is there another use case, other than an element consumer who wants to redefine those variables to the default (dark or light) theme?

Hey @mercmobly, where is the proposal?!?

I hope I clarified some issues so that the next person finding this issue will be able to make heads of tails of this. I also hope I got things right and, if needed, straightened out. Please keep in mind that I am doing this very, very humbly.

In terms of my proposal, please allow me to put forward an outline. If I didn't write anything stupid (which would surprise me), I will flesh it out.

Theming guidelines

Overview of the default theming variables in paper elements

The default theme is defined in default-theme.html.

• The basic theme defines these basic properties:

  /* Typography */
  --primary-text-color
  --primary-background-color
  --secondary-text-color
  --disabled-text-color
  --divider-color

  /* Primary and accent colors */
  --primary-color
  --light-primary-color
  --dark-primary-color

  --accent-color
  --light-accent-color
  --dark-accent-color

• In terms of primary and accent color, in default-theme.html, these variables are set to sane defaults, using the paper-indigo palette (--paper-indigo-500 for the primary-color, --paper-indigo-100 for the light primary color, and so on)

• In terms of typography, default-theme.html defines two sets (one for --light-theme and one for --dark-theme) and uses by default the --light-theme set. For example:

  --primary-text-color: var(--light-theme-text-color);
  --primary-background-color: var(--light-theme-background-color);
  --secondary-text-color: var(--light-theme-secondary-color);
  --disabled-text-color: var(--light-theme-disabled-color);
  --divider-color: var(--light-theme-divider-color);

Remember that this is the default theme. These variables should be changed.

As an element consumer

As an element consumer, you are encouraged to redefine the basic properties (typography, primary color, accent color) by setting these variables in your own CSS, after including your elements:

<!-- Paper elements -->
<link rel="import" href="/bower_components/paper-drawer-panel/paper-drawer-panel.html">
<!-- ... more imports here ... -->
<link rel="import" href="/bower_components/paper-toolbar/paper-toolbar.html">
<link rel="import" href="/bower_components/paper-checkbox/paper-checkbox.html">

<!-- Your own theme -->
<link rel="import" href="/styles/app-theme.html">

In your app-theme.html, you redefine some of the variables:

<link rel="import" href="../polymer/polymer.html">
<style is="custom-style">
  :root {
    /*
     * You can use these generic variables in your elements for easy theming.
     * For example, if all your elements use `--primary-text-color` as its main
     * color, then switching from a light to a dark theme is just a matter of
     * changing the value of `--primary-text-color` in your application.
     */
:root {
    --primary-text-color: var(--light-theme-text-color);
    --primary-background-color: var(--light-theme-background-color);
    --secondary-text-color: var(--light-theme-secondary-color);
    --disabled-text-color: var(--light-theme-disabled-color);
    --divider-color: var(--light-theme-divider-color);

    --primary-color: #673ab7; /* --paper-deep-purple-500 */
    --light-primary-color: #d1c4e9; /* --paper-deep-purple-100 */
    --dark-primary-color: 303f9f; /* --paper-deep-purple-700 */
    --accent-color: #ff4081;
    --light-accent-color: #ff80ab;
    --dark-accent-color: #f50057;

Note that while for typography the same defaults are applied (in the light-theme set), you are free to use whichever color works for your application, or use the dark-theme presets. For primary and accent colors, in this case, the deep-purple colors were used as primary colors. Most (hopefully all) custom elements will pick up on your typography variables as defaults.

As an element producer

Elements should be as color-agnostic as possible, and use the default properties as much as possible. For example, a custom element my-element might have:

  <style>
      :host {
       background: var(--my-element-background-color, --primary-background-color);
       color: var(--my-element-text-color, --primary-text-color);

This will ensure that the element's colors are customizable, and -- if customization by the user didn't happen -- they have sane defaults based on the theme variables.

Conclusion

Phew! I hope my answers and my writeup make sense. @notwaldorf One thing I didn't quite understand is, this: why don't theme pages include color.html and use variables instead, so that the theming part becomes:

--primary-color: var(--paper-indigo-500)
--light-primary-color: var(--paper-indigo-100)
--dark-primary-color: var( --paper-indigo-700)

...? I didn't do this in the guide because well, it's not done anywhere in Polymer (not in default-theme.html nor in app-theme.html in the PSK). Also, there are a lot of elements that are still using the "old" --text-primary-color and --default-primary-color. I could create a PR for each one of them, but it's a little wasteful and time intensive. Do you guys talk to each other internally so that it can all happen in one go?

All this is a huge derail from the original issue. I decided to added it here because the original issue couldn't really get much worse (but maybe it did!).

@notwaldorf If you think the writeup is worthwhile expanding, please let me know. I will make a PR and we'll go from there.

About the original issue

I agree that having a way to automatically generate the palette would be grand. Something where you define the primary color and the accent color, and it generates color-agnostic primary and accent names. @notwaldorf Thanks for looking into it!

[rjcorwin]

Hi folks - I made a documentation PR to cover what I understand to be the most basic and common example of overriding colors, globally defining your primary and accent colors. Thanks so much for the discussion around this topic, this issue was key to figuring out how how to accomplish this.

#150