[K7] More robust theming (elastic#13129)

add tintOrShade() function. Adjust color vars. Document system and goals

style_guides/scss_style_guide.md

@@ -15,8 +15,9 @@ Our style guide is an extension of [Sass Guidelines by Hugo Giraudel](https://sa
 
 Kibana aims to provide at least a read-only (meaning, editing and controls can be hidden) on layouts when on a small device. We place any responsive Sass at the bottom of our SCSS documents, rather than intermingled within the components themselves.
 
-```
-// Good
+
+Good
+```sass
 @include component('kuiHeader') {
   display: block;
 }
@@ -26,8 +27,10 @@ Kibana aims to provide at least a read-only (meaning, editing and controls can b
     display: none;
   }
 }
+```
 
-// Bad
+Bad
+```sass
 @include component('kuiHeader') {
   display: block;
 
@@ -48,7 +51,7 @@ We use a mixin system for namespacing the sass into a BEM-like format. We use `c
 
 Component example with lots of nesting.
 
-```
+```sass
 // Generates .kuiButton
 @include component('kuiButton') {
   color: white;
@@ -87,8 +90,7 @@ Component example with lots of nesting.
 
 KUI includes utility classes in `global_styles/utility` which are used to cut down on the amount of duplicate CSS we write and make designing in code faster. Utilities include the `kui--` prefix, since we consider them modifiers to KUI as a whole.
 
-```
-```
+```sass
 // Generates .kui--textAlignRight
 @include utility('textAlignRight') {
   text-align: right !important;
@@ -112,5 +114,40 @@ Don't extend classes. The only time use should use an extend is when you are ext
 KUI is fully themeable. We do this with strict variable naming. Please use the following rules.
 
 * Global vars that can be used across all of KUI should be placed in the `global_styles/variables` directory.
-* Component vars that are local to the component should be places in the `component/component_name/index.scss` file at the top of the document.
+* Component vars that are local to the component should be places in the `component/component_name/_index.scss` file at the top of the document.
 * Component vars that deal with coloring should *always* be mathematically calculated from the global coloring variables. This allows us to cascade theming down into the components.
+* Make use of the `tintOrShade()` sass function for any coloring that needs variance based upon the lightness of the design.
+* In general, there should be few global variables, but we should strive to have many local variables that inherit them.
+
+### Example ###
+
+Good
+
+```sass
+// A global color variable that lives at /src/global_styling/variables/_colors.scss
+
+$kuiPrimaryColor: #0079a5; // Blue
+
+// A local color variable that lives at /src/components/some_component/_index.scss
+// tintOrShade() will alter the color one way or the other based upon the brightness of the theme.
+// This makes our colors work out of the box for dark and light themes.
+
+$kuiSomeComponentItemBackground: tintOrShade($kuiColorPrimary, 90%, 50%);
+
+// A local style that lives in /src/components/some_component/_some_component_item.scss
+
+$kuiSomeComponent__item {
+  background: $kuiSomeComponentItemBackground;
+}
+```
+
+Bad
+```sass
+// A global color variable that lives at /src/global_styling/variables/_colors.scss
+
+$kuiPrimaryColor: #0079a5; // Blue
+
+// A local variable that doesn't scope against our global theming.
+
+$kuiSomeComponentItemBackground: #990000;
+```

ui_framework/src/components/typography/_index.scss

@@ -1 +1,3 @@
+$kuiTitleColor: $kuiColorFullShade;
+
 @import 'typography';

ui_framework/src/global_styling/variables/_colors.scss

@@ -8,6 +8,16 @@
   @return mix(#000, $color, $percent);
 }
 
+// For theming. Checks the text color and tells us whether it's light or dark.
+// Based on that we either tint or shade.
+@function tintOrShade($color, $tint, $shade) {
+  @if (lightness($kuiTextColor) > 50) {
+    @return shade($color, $shade);
+  } @else {
+    @return tint($color, $tint);
+  }
+}
+
 // Core
 
 $kuiColorPrimary: #0079a5;
@@ -27,19 +37,22 @@ $kuiColorDarkShade: #666;
 $kuiColorDarkestShade: #3F3F3F;
 $kuiColorFullShade: #000;
 
-// Every color below must be based mathmatically on the set above.
-
-$kuiTextColor: $kuiColorDarkestShade;
-$kuiTitleColor: $kuiColorFullShade;
-$kuiLinkColor: $kuiColorPrimary;
-$kuiFocusBackgroundColor: tint($kuiColorPrimary, 90%);
 
 // Dark theme overides
 // $kuiColorEmptyShade: #222;
-// $kuiColorLightestShade: #3F3F3F;
-// $kuiColorLightShade: #666;
-// $kuiColorMediumShade: #999;
+// $kuiColorLightestShade: #333;
+// $kuiColorLightShade: #444;
+// $kuiColorMediumShade: #555;
 // $kuiColorDarkShade: #D9D9D9;
 // $kuiColorDarkestShade: #F5F5F5;
 // $kuiColorFullShade: #FFF;
-// $kuiFocusBackgroundColor: #3F3F3F;
+// $kuiColorPrimary: tint($kuiColorPrimary, 30%);
+
+
+// Every color below must be based mathmatically on the set above.
+
+$kuiTextColor: $kuiColorDarkestShade;
+$kuiTitleColor: $kuiColorFullShade;
+$kuiLinkColor: $kuiColorPrimary;
+$kuiFocusBackgroundColor: tintOrShade($kuiColorPrimary, 90%, 50%);
+