Docs: extension styling and theming (#1267)

Signed-off-by: Alex Andreev <alex.andreev.email@gmail.com>

docs/extensions/capabilities/color-reference.md

@@ -0,0 +1,130 @@
+# Theme color reference
+You can use CSS variables generated from theme `.json` files to style an extension with respect of active theme.
+
+## Base colors
+- `blue`: blue color.
+- `magenta`: magenta color.
+- `golden`: gold/yellow color.
+- `halfGray`: gray with some apacity applied.
+- `primary`: Lens brand (blue) color.
+- `colorSuccess`: successfull operations color.
+- `colorOk`: successfull operations (bright version) color.
+- `colorInfo`: informational, in-progress color.
+- `colorError`: critical error color.
+- `colorSoftError`: error color.
+- `colorWarning`: warning color.
+- `colorVague`: soft gray color for notices, hints etc.
+- `colorTerminated`: terminated, closed, stale color.
+- `boxShadow`: semi-transparent box-shadow color.
+
+## Text colors
+- `textColorPrimary`: foreground text color.
+- `textColorSecondary`: foreground text color for different paragraps, parts of text.
+- `textColorAccent`: foreground text color to highlight its parts.
+
+## Border colors
+- `borderColor`: border color.
+- `borderFaintColor`: fainted (lighter or darker, which depends on the theme) border color.
+
+## Layout colors
+- `mainBackground`: main background color for the app.
+- `contentColor`: background color for panels contains some data.
+- `layoutBackground`: background color for layout parts.
+- `layoutTabsBackground`: background color for general tabs.
+- `layoutTabsActiveColor`: foreground color for general tabs.
+- `layoutTabsLineColor`: background color for lines under general tabs.
+
+## Sidebar colors
+- `sidebarLogoBackground`: background color behind logo in sidebar.
+- `sidebarActiveColor`: foreground color for active menu items in sidebar.
+- `sidebarSubmenuActiveColor`: foreground color for active submenu items in sidebar.
+- `sidebarBackground`: background color for sidebar.
+
+## Button colors
+- `buttonPrimaryBackground`: button background color for primary actions.
+- `buttonDefaultBackground`: default button background color.
+- `buttonAccentBackground`: accent button background color.
+- `buttonDisabledBackground`: disabled button background color.
+
+## Table colors
+- `tableBgcStripe`: background color for odd rows in table.
+- `tableBgcSelected`: background color for selected row in table.
+- `tableHeaderBackground`: background color for table header.
+- `tableHeaderBorderWidth`: border width under table header.
+- `tableHeaderBorderColor`: border color for line under table header.
+- `tableHeaderColor`: foreground color for table header.
+- `tableSelectedRowColor`: foreground color for selected row in table.
+
+## Dock colors
+- `dockHeadBackground`: background color for dock's header.
+- `dockInfoBackground`: background color for dock's info panel.
+- `dockInfoBorderColor`: border color for dock's info panel.
+
+## Helm chart colors
+- `helmLogoBackground`: background color for chart logo.
+- `helmImgBackground`: background color for chart image.
+- `helmStableRepo`: background color for stable repo.
+- `helmIncubatorRepo`: background color for incubator repo.
+- `helmDescriptionHr`: Helm chart description separator line color.
+- `helmDescriptionBlockqouteColor`: Helm chart description blockquote color.
+- `helmDescriptionBlockqouteBorder`: Helm chart description blockquote border color.
+- `helmDescriptionBlockquoteBackground`: Helm chart description blockquote background color.
+- `helmDescriptionHeaders`: Helm chart description headers color.
+- `helmDescriptionH6`: Helm chart description header foreground color.
+- `helmDescriptionTdBorder`: Helm chart description table cell border color.
+- `helmDescriptionTrBackground`: Helm chart description table row background color.
+- `helmDescriptionCodeBackground`: Helm chart description code background color.
+- `helmDescriptionPreBackground`: Helm chart description pre background color.
+- `helmDescriptionPreColor`: Helm chart description pre foreground color.
+
+## Terminal colors
+- `terminalBackground`: Terminal background color.
+- `terminalForeground`: Terminal foreground color.
+- `terminalCursor`: Terminal cursor color.
+- `terminalCursorAccent`: Terminal cursor accent color.
+- `terminalSelection`: Terminal selection background color.
+- `terminalBlack`: Terminal black color.
+- `terminalRed`: Terminal red color.
+- `terminalGreen`: Terminal green color.
+- `terminalYellow`: Terminal yellow color.
+- `terminalBlue`: Terminal blue color.
+- `terminalMagenta`: Terminal magenta color.
+- `terminalCyan`: Terminal cyan color.
+- `terminalWhite`: Terminal white color.
+- `terminalBrightBlack`: Terminal bright black color.
+- `terminalBrightRed`: Terminal bright red color.
+- `terminalBrightGreen`: Terminal bright green color.
+- `terminalBrightYellow`: Terminal bright yellow color.
+- `terminalBrightBlue`: Terminal bright blue color.
+- `terminalBrightMagenta`: Terminal bright magenta color.
+- `terminalBrightCyan`: Terminal bright cyan color.
+- `terminalBrightWhite`: Terminal bright white color.
+
+## Dialog colors
+- `dialogHeaderBackground`: background color for dialog header.
+- `dialogFooterBackground`: background color for dialog footer.
+
+## Detail panel (Drawer) colors
+- `drawerTitleText`: drawer title foreground color.
+- `drawerSubtitleBackground`: drawer subtitle foreground color.
+- `drawerItemNameColor`: foreground color for item name in drawer.
+- `drawerItemValueColor`: foreground color for item value in drawer.
+
+## Misc colors
+- `logsBackground`: background color for pod logs.
+- `clusterMenuBackground`: background color for cluster menu.
+- `clusterMenuBorderColor`: border color for cluster menu.
+- `clusterSettingsBackground`: background color for cluster settings.
+- `addClusterIconColor`: add cluster button background color.
+- `iconActiveColor`: active cluster icon foreground color.
+- `iconActiveBackground`: active cluster icon background color.
+- `filterAreaBackground`: page filter area (where selected namespaces are lister) background color.
+- `chartStripesColor`: bar chart zebra stripes background color.
+- `chartCapacityColor`: background color for capacity values in bar charts.
+- `pieChartDefaultColor`: default background color for pie chart values.
+- `selectOptionHoveredColor`: foregrond color for selected element in dropdown list.
+- `lineProgressBackground`: background color for progress line.
+- `radioActiveBackground`: background color for active radio buttons.
+- `menuActiveBackground`: background color for active menu items.
+
+In most cases you would only need base, text and some of the layout colors.

docs/extensions/capabilities/styling.md

@@ -0,0 +1,99 @@
+# Styling an extension
+Lens provides a set of global styles and UI components that can be used by any extension to preserve look and feel of the application.
+
+## Styling approach
+Lens heavily uses SCSS preprocessor with a set of predefined variables and mixins.
+
+For layout tasks Lens is using [flex.box](https://www.npmjs.com/package/flex.box) library which provides helpful class names to specify some of the [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox) properties. For example, `div` with class names:
+```
+<div className="flex column align-center"></div>
+```
+at the end will have following css properties:
+```
+div {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+```
+
+However, feel free to use any styling technique or framework like [Emotion](https://github.com/emotion-js/emotion) or just plain CSS if you prefer.
+
+## Themes
+Lens using 2 built-in themes located in `src/renderer/themes` folder each for light and dark color schemes. Active theme can be changed in the `Preferences` page.
+![Color Theme](images/theme-selector.png)
+
+When Lens gets loaded it transforms selected theme `json` file into list of [CSS Custom Properties (CSS Variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) which then gets injected into `:root` element so any of the down-level components can use them.
+![CSS vars listed in devtools](images/css-vars-in-devtools.png)
+
+When user changes a theme, the process is repeated, new css variables appear instead of previous ones.
+
+If you want to follow a selected theme to keep the 'native' Lens look and feel, respecting the light/dark appearance of your extension, you can use provided variables and build-in lens components such as buttons, dropdowns, checkboxes etc.
+
+## Injected styles
+Every extention is affected by list of default global styles defined in `src/renderer/components/app.scss`. These are basic browser resets like setting `box-sizing` property for every element, default text and background colors, default font size, basic headings visualisation etc.
+
+Extension may overwrite them if needed.
+
+## Variables to use
+### Basic styling
+There is a list of CSS Variables available for extension to use. Basic variables located inside `:root` selected in `src/renderer/components/app.scss`:
+```
+  --unit: 8px;
+  --padding: var(--unit);
+  --margin: var(--unit);
+  --border-radius: 3px;
+  --font-main: 'Roboto', 'Helvetica', 'Arial', sans-serif;
+  --font-monospace: Lucida Console, Monaco, Consolas, monospace;
+  --font-size-small: calc(1.5 * var(--unit));
+  --font-size: calc(1.75 * var(--unit));
+  --font-size-big: calc(2 * var(--unit));
+  --font-weight-thin: 300;
+  --font-weight-normal: 400;
+  --font-weight-bold: 500;
+```
+
+They're intended to set consistent paddings and font-sizes across components, e.g.
+```
+.status {
+  padding-left: calc(var(--padding) * 2);
+  font-size: var(--font-size-small);
+}
+```
+
+### Themable colors
+After theme file gets parsed it provides list of theme-defined colors. Most of their values are different for light and dark themes. You can use them to preserve consitent view of extension with respect of selected theme.
+```
+  "blue": "#3d90ce",
+  "magenta": "#c93dce",
+  "golden": "#ffc63d",
+  "halfGray": "#87909c80",
+  "primary": "#3d90ce",
+  "textColorPrimary": "#555555",
+  "textColorSecondary": "#51575d",
+  "textColorAccent": "#333333",
+  "borderColor": "#c9cfd3",
+  "borderFaintColor": "#dfdfdf",
+  "mainBackground": "#f1f1f1",
+  "contentColor": "#ffffff",
+  "layoutBackground": "#e8e8e8",
+  "layoutTabsBackground": "#f8f8f8",
+  "layoutTabsActiveColor": "#333333",
+  "layoutTabsLineColor": "#87909c80"
+  ...
+...
+```
+
+They can be used in form of `var(--magenta)`.
+
+A complete list of all themable colors can be found in the [color reference](../color-reference).
+
+Colors values are located inside `src/renderer/themes/lens-dark.json` and `src/renderer/themes/lens-light.json` files.
+
+## Using CSS Variables inside CSS-in-JS components
+If a developer uses an `Emotion` (or similar) framework to work with styles inside an extension, they can use variables in the following form:
+```
+const Container = styled.div(() => ({
+  backgroundColor: 'var(--mainBackground)'
+}));
+```

mkdocs.yml

@@ -26,7 +26,8 @@ nav:
     - Extension Capabilities:
       - Overview: extensions/capabilities/README.md
       - Common Capabilities: extensions/capabilities/common-capabilities.md
-      - Theming: extensions/capabilities/theming.md
+      - Styling: extensions/capabilities/styling.md
+      - Color reference: extensions/capabilities/color-reference.md
     - Extension Guides:
       - Overview: extensions/guides/README.md
       - Renderer Extension: extensions/guides/renderer-extension.md

src/renderer/components/app.scss

@@ -11,6 +11,18 @@
 }
 
 :root {
+  --unit: 8px;
+  --padding: var(--unit);
+  --margin: var(--unit);
+  --border-radius: 3px;
+  --font-main: 'Roboto', 'Helvetica', 'Arial', sans-serif;
+  --font-monospace: Lucida Console, Monaco, Consolas, monospace;
+  --font-size-small: calc(1.5 * var(--unit));
+  --font-size: calc(1.75 * var(--unit));
+  --font-size-big: calc(2 * var(--unit));
+  --font-weight-thin: 300;
+  --font-weight-normal: 400;
+  --font-weight-bold: 500;
   --mainBackground: #1e2124;
   --main-layout-header: 40px;
   --drag-region-height: 22px
@@ -122,7 +134,7 @@ code {
   vertical-align: middle;
   border-radius: $radius;
   font-family: $font-monospace;
-  font-size: $font-size * .9;
+  font-size: calc($font-size * .9);
   color: #b4b5b4;
 
   &.block {

src/renderer/components/radio/radio.scss

@@ -97,7 +97,7 @@
 
   .tick {
     color: $tickColor;
-    font: $font-size * 1.3 "Material Icons";
+    font: calc($font-size * 1.3) "Material Icons";
 
     &:after {
       content: "radio_button_unchecked";

src/renderer/components/vars.scss

@@ -5,17 +5,17 @@
 $unit: 8px;
 $padding: $unit;
 $margin: $unit;
-$radius: ceil($unit * .3);
+$radius: var(--border-radius);
 
 // Fonts
-$font-main: 'Roboto', 'Helvetica', 'Arial', sans-serif !default;
+$font-main: var(--font-main);
-$font-monospace: Lucida Console, Monaco, Consolas, monospace;
+$font-monospace: var(--font-monospace);
-$font-size-small: floor(1.5 * $unit);
+$font-size-small: var(--font-size-small);
-$font-size: floor(1.75 * $unit);
+$font-size: var(--font-size);
-$font-size-big: floor(2 * $unit);
+$font-size-big: var(--font-size-big);
-$font-weight-thin: 300;
+$font-weight-thin: var(--font-weight-thin);
-$font-weight-normal: 400;
+$font-weight-normal: var(--font-weight-normal);
-$font-weight-bold: 500;
+$font-weight-bold: var(--font-weight-bold);
 
 // Z-index correlations
 $zIndex-sidebar-hover: 500;