Update to new CSS variable naming scheme and document it (#3403)

* Update to new CSS variable naming scheme. * Fix typos.
jupyterlab · Dec 18, 2017 · 66c9b95 · 66c9b95
1 parent 8289c28
commit 66c9b95
Show file tree

Hide file tree

Showing 9 changed files with 73 additions and 83 deletions.
diff --git a/docs/css.md b/docs/css.md
@@ -7,34 +7,38 @@ depend on CSS variables dfined in a main theme package.
 
 ## CSS checklist
 
-* CSS classnames are defined as all caps file-level `const`s and follow the CSS
-  class naming convention described below.
-* CSS files for packages are located within the `src/style` subdirecotory and
+* CSS classnames are defined inline in the code. We used to put them as all caps
+  file-level `const`s, but we are moving away from that.
+* CSS files for packages are located within the `src/style` subdirectory and
   imported into the plugin's `index.css`.
-* The JupyterLab default CSS variables in the `default-theme` package
-  are used to style packages where ever possible. Individual packages should not
-  depend on this package though, to allow the theme to be swaped out.
+* The JupyterLab default CSS variables in the `theme-light-extension` and
+  `theme-dark-extension` packages are used to style packages where ever possible.
+  Individual packages should not npm-depend on these packages though, to allow the
+  theme to be swapped out.
 * Additional public/private CSS variables are defined by plugins sparingly and in
   accordance with the conventions described below.
 
 ## CSS variables
 
 We are using native CSS variables in JupyterLab. This is to enable dynamic theming
-of built-in and third party plugins. As of Septmeber 2016, CSS variables are
-supported in the latest stable versions of all popular browsers, except for IE/Edge.
+of built-in and third party plugins. As of December 2017, CSS variables are
+supported in the latest stable versions of all popular browsers, except for IE.
 If a JupyterLab deployment needs to support these browsers, a server side CSS
 preprocessor such as Myth or cssnext may be used.
 
 ### Naming of CSS variables
 
 We use the following convention for naming CSS variables:
 
-* Start all CSS variables with `--jp-`
-* Words in the variable name should be lowercase and separated with `-`
+* Start all CSS variables with `--jp-`.
+* Words in the variable name should be lowercase and separated with `-`.
+* The next segment should refer to the component and subcomponent, such as
+  `--jp-notebook-cell-`.
+* The next segment should refer to any state modifiers such as `active`, `not-active` or
+  `focused`: `--jp-notebook-cell-focused`.
 * The final segment will typically be related to a CSS properties, such as
-  `color`, `font-size` or `background`.
-* Intermediate segments should have refer to the component and subcomponent, such
-  as `--jp-notebook-cell-`.
+  `color`, `font-size` or `background`: `--jp-notebook-cell-focused-background`.
+
 
 ### Public/private
 
@@ -48,13 +52,13 @@ The difference between public and private variables is simple:
   ensures that public CSS variables can be inspected under the top-level
   `<html>` tag in the browser's dev tools.
 * Where possible, private variables should be defined and scoped under an 
-  appropriate selector.
+  appropriate selector other than `:root`.
 
 ### CSS variable usage
 
 JupyterLab includes a default set of CSS variables in the file:
 
-`packages/default-theme/style/variables.css`
+`packages/theme-light-extension/style/variables.css`
 
 To ensure consistent design in JupyterLab, all built-in and third party
 extensions should use these variables in their styles if at all possible.
@@ -75,8 +79,6 @@ We are organizing our CSS files in the following manner:
   any CSS files in a `style` subdirectory that are needed to style itself.
 * Multiple CSS files may be used and organized as needed, but they should be
   imported into a single `index.css` at the top-level of the plugin.
-* The `index.css` of each plugin should be imported inside
-  `packages/default-theme/style/index.css`.
 
 ## CSS class names
 
@@ -86,17 +88,16 @@ First, CSS class names are associated with TypeScript classes that extend
 `phosphor.Widget`:
 
 The `.node` of each such widget should have a CSS class that matches
-the name of the TypeScript class, and those classnames should be defined
-as a file-level `const`:
+the name of the TypeScript class:
 
 ```TypeScript
-const MYWIDGET_CLASS = 'jp-MyWidget';
+
 
 class MyWidget extends Widget {
 
   constructor() {
     super();
-    this.addClass(MYWIDGET_CLASS);
+    this.addClass('jp-MyWidget');
   }
 
 }
@@ -105,13 +106,11 @@ class MyWidget extends Widget {
 Second, subclasses should have a CSS class for both the parent and child:
 
 ```TypeScript
-const MYWIDGET_SUBCLASS_CLASS = 'jp-MyWidgetSubclass';
-
 class MyWidgetSubclass extends MyWidget {
 
   constructor() {
     super(); // Adds `jp-MyWidget`
-    this.addClass(MYWIDGET_SUBCLASS_CLASS);
+    this.addClass('jp-MyWidgetSubclass');
   }
 
 }
@@ -143,8 +142,8 @@ Fourth, some CSS classes are used to modify the state of a widget:
 
 Fifth, some CSS classes are used to distinguish different types of a widget:
 
-* `--jp-type-separator`: applied to menu items that are separators
-* `--jp-type-directory`: applied to elements in the file browser that are directories
+* `jp-type-separator`: applied to menu items that are separators
+* `jp-type-directory`: applied to elements in the file browser that are directories
 
 ## Edge cases
 
@@ -170,7 +169,3 @@ the DOM stucture is highly recursive, the usual descendant selectors may
 not be specific to target only the desired children.
 
 When in doubt, there is little harm done in parents adding selectors to children.
-
-
-
-
diff --git a/packages/apputils/style/commandpalette.css b/packages/apputils/style/commandpalette.css
@@ -40,7 +40,7 @@
   overflow: overlay;
   padding: 0px 8px;
   border: 1px solid var(--jp-border-color0);
-  background-color: var(--jp-input-background-color-active);
+  background-color: var(--jp-input-active-background);
   height: 30px;
 }
 

diff --git a/packages/apputils/style/styling.css b/packages/apputils/style/styling.css
@@ -24,7 +24,7 @@ button.jp-mod-styled {
 
 
 input.jp-mod-styled {
-  background: var(--jp-input-background-color);
+  background: var(--jp-input-background);
   height: 28px;
   box-sizing: border-box;
   border: var(--jp-border-width) solid var(--jp-border-color1);
@@ -62,17 +62,17 @@ button.jp-mod-styled:focus {
 
 
 .jp-select-wrapper.jp-mod-focused select.jp-mod-styled {
-  border: var(--jp-border-width) solid var(--jp-input-border-color-active);
+  border: var(--jp-border-width) solid var(--jp-input-active-border-color);
   box-shadow: var(--jp-input-box-shadow);
-  background-color: var(--jp-input-background-color-active);
+  background-color: var(--jp-input-active-background);
 }
 
 
 select.jp-mod-styled:hover {
   background-color: var(--jp-layout-color1);
   cursor: pointer;
   color: var(--jp-ui-font-color0);
-  background-color: var(--jp-input-background-color-hover);
+  background-color: var(--jp-input-hover-background);
   box-shadow: inset 0 0px 1px rgba(0, 0, 0, 0.5);
 }
 
@@ -82,7 +82,7 @@ select.jp-mod-styled {
   height: 32px;
   width: 100%;
   font-size: var(--jp-ui-font-size2);
-  background: var(--jp-input-background-color);
+  background: var(--jp-input-background);
   color: var(--jp-ui-font-color0);
   padding-left: 8px;
   padding-right: 8px;

diff --git a/packages/codeeditor/style/index.css b/packages/codeeditor/style/index.css
@@ -82,7 +82,7 @@
 
 
 .jp-JSONEditor-host.jp-mod-focused {
-  background-color: var(--jp-input-background-color-active);
-  border: 1px solid var(--jp-input-border-color-active);
+  background-color: var(--jp-input-active-background);
+  border: 1px solid var(--jp-input-active-border-color);
   box-shadow: var(--jp-input-box-shadow);
 }
diff --git a/packages/console/style/index.css b/packages/console/style/index.css
@@ -71,9 +71,9 @@
 
 
 .jp-CodeConsole-content .jp-InputArea-editor.jp-InputArea-editor {
-  border: var(--jp-border-width) solid var(--jp-cell-editor-border-color-active);
+  border: var(--jp-border-width) solid var(--jp-cell-editor-active-border-color);
   box-shadow: var(--jp-input-box-shadow);
-  background-color: var(--jp-cell-editor-background-active);
+  background-color: var(--jp-cell-editor-active-background);
 }
 
 
@@ -89,7 +89,7 @@
 
 
 .jp-CodeConsole-promptCell .jp-InputArea-editor.jp-mod-focused {
-  border: var(--jp-border-width) solid var(--jp-cell-editor-border-color-active);
+  border: var(--jp-border-width) solid var(--jp-cell-editor-active-border-color);
   box-shadow: var(--jp-input-box-shadow);
-  background-color: var(--jp-cell-editor-background-active);
+  background-color: var(--jp-cell-editor-active-background);
 }
diff --git a/packages/notebook/style/index.css b/packages/notebook/style/index.css
@@ -93,13 +93,13 @@
 /* Command or edit modes */
 
 .jp-Notebook .jp-Cell:not(.jp-mod-active) .jp-InputPrompt {
-  opacity: var(--jp-cell-prompt-opacity-not-active);
-  color: var(--jp-cell-prompt-font-color-not-active);
+  opacity: var(--jp-cell-prompt-not-active-opacity);
+  color: var(--jp-cell-prompt-not-active-font-color);
 }
 
 .jp-Notebook .jp-Cell:not(.jp-mod-active) .jp-OutputPrompt {
-  opacity: var(--jp-cell-prompt-opacity-not-active);
-  color: var(--jp-cell-prompt-font-color-not-active);
+  opacity: var(--jp-cell-prompt-not-active-opacity);
+  color: var(--jp-cell-prompt-not-active-font-color);
 }
 
 .jp-Notebook .jp-Cell.jp-mod-active .jp-Cell-inputCollapser .jp-Collapser-child,
@@ -126,9 +126,9 @@
 /* Edit mode */
 
 .jp-Notebook.jp-mod-editMode .jp-Cell.jp-mod-active .jp-InputArea-editor {
-  border: var(--jp-border-width) solid var(--jp-cell-editor-border-color-active);
+  border: var(--jp-border-width) solid var(--jp-cell-editor-active-border-color);
   box-shadow: var(--jp-input-box-shadow);
-  background-color: var(--jp-cell-editor-background-active);
+  background-color: var(--jp-cell-editor-active-background);
 }
 
 
@@ -237,8 +237,8 @@
 
 .jp-ActiveCellTool .jp-InputArea-editor {
   flex: 1 1 auto;
-  background-color: var(--jp-cell-editor-background-active);
-  border-color: var(--jp-cell-editor-border-color-active);
+  background-color: var(--jp-cell-editor-active-background);
+  border-color: var(--jp-cell-editor-active-border-color);
   box-shadow: var(--jp-cell-editor-box-shadow);
 }
 

diff --git a/packages/notebook/style/toolbar.css b/packages/notebook/style/toolbar.css
@@ -30,7 +30,7 @@
 /* select wrapper */
 .jp-Toolbar-item.jp-Notebook-toolbarCellType > .jp-select-wrapper {
   height: 100%;
-  background-color: var(--jp-notebook-select-background-color);
+  background-color: var(--jp-notebook-select-background);
 }
 
 

diff --git a/packages/theme-dark-extension/style/variables.css b/packages/theme-dark-extension/style/variables.css
@@ -64,10 +64,10 @@ all of MD as it is not optimized for dense, information rich UIs.
      These will typically go from light to darker, in both a dark and light theme
    */
 
-  --jp-inverse-ui-font-color0: rgba(0,0,0,1.0);
-  --jp-inverse-ui-font-color1: rgba(0,0,0,0.8);
-  --jp-inverse-ui-font-color2: rgba(0,0,0,0.5);
-  --jp-inverse-ui-font-color3: rgba(0,0,0,0.3);
+  --jp-ui-inverse-font-color0: rgba(0,0,0,1.0);
+  --jp-ui-inverse-font-color1: rgba(0,0,0,0.8);
+  --jp-ui-inverse-font-color2: rgba(0,0,0,0.5);
+  --jp-ui-inverse-font-color3: rgba(0,0,0,0.3);
 
   /* Content Fonts
 
@@ -145,28 +145,28 @@ all of MD as it is not optimized for dense, information rich UIs.
   --jp-cell-editor-background: var(--jp-layout-color1);
   --jp-cell-editor-border-color: var(--md-grey-700);
   --jp-cell-editor-box-shadow: inset 0 0 2px var(--md-blue-300);
-  --jp-cell-editor-background-active: var(--jp-layout-color0);
-  --jp-cell-editor-border-color-active: var(--jp-brand-color1);
+  --jp-cell-editor-active-background: var(--jp-layout-color0);
+  --jp-cell-editor-active-border-color: var(--jp-brand-color1);
   --jp-cell-padding: 5px;
   --jp-cell-prompt-width: 100px;
   --jp-cell-prompt-font-family: 'Roboto Mono', monospace;
   --jp-cell-prompt-letter-spacing: 0px;
   --jp-cell-prompt-opacity: 1.0;
-  --jp-cell-prompt-opacity-not-active: 0.5;
-  --jp-cell-prompt-font-color-not-active: var(--md-grey-300);
+  --jp-cell-prompt-not-active-opacity: 0.5;
+  --jp-cell-prompt-not-active-font-color: var(--md-grey-300);
   --jp-cell-inprompt-font-color: var(--md-grey-50);
   --jp-cell-outprompt-font-color: var(--md-grey-50);
 
   /* Notebook specific styles */
 
   --jp-notebook-padding: 10px;
   --jp-notebook-scroll-padding: 100px;
-  --jp-notebook-select-background-color: var(--jp-layout-color1);
+  --jp-notebook-select-background: var(--jp-layout-color1);
   --jp-notebook-multiselected-color: rgba(33,150,243,.24);
-  --jp-rendermime-error-background: rgba(244,67,54,.28);
 
   /* Rendermime styles */
 
+  --jp-rendermime-error-background: rgba(244,67,54,.28);
   --jp-rendermime-row-background: var(--md-grey-900);
   --jp-rendermime-row-hover-background: rgba(3,169,244,.2);
 
@@ -189,11 +189,11 @@ all of MD as it is not optimized for dense, information rich UIs.
   /* Input field styles */
 
   --jp-input-box-shadow: inset 0 0 2px var(--md-blue-300);
-  --jp-input-background-color-active: var(--jp-layout-color0);
-  --jp-input-background-color-hover: var(--jp-layout-color2);
-  --jp-input-background-color: var(--md-grey-800);
+  --jp-input-active-background: var(--jp-layout-color0);
+  --jp-input-hover-background: var(--jp-layout-color2);
+  --jp-input-background: var(--md-grey-800);
   --jp-input-border-color: var(--jp-border-color1);
-  --jp-input-border-color-active: var(--jp-brand-color1);
+  --jp-input-active-border-color: var(--jp-brand-color1);
 
   /* General editor styles */
 

diff --git a/packages/theme-light-extension/style/variables.css b/packages/theme-light-extension/style/variables.css
@@ -64,10 +64,10 @@ all of MD as it is not optimized for dense, information rich UIs.
      These will typically go from light to darker, in both a dark and light theme
    */
 
-  --jp-inverse-ui-font-color0: rgba(255,255,255,1);
-  --jp-inverse-ui-font-color1: rgba(255,255,255,1.0);
-  --jp-inverse-ui-font-color2: rgba(255,255,255,0.7);
-  --jp-inverse-ui-font-color3: rgba(255,255,255,0.5);
+  --jp-ui-inverse-font-color0: rgba(255,255,255,1);
+  --jp-ui-inverse-font-color1: rgba(255,255,255,1.0);
+  --jp-ui-inverse-font-color2: rgba(255,255,255,0.7);
+  --jp-ui-inverse-font-color3: rgba(255,255,255,0.5);
 
   /* Content Fonts
 
@@ -140,26 +140,20 @@ all of MD as it is not optimized for dense, information rich UIs.
   --jp-info-color2: var(--md-cyan-300);
   --jp-info-color3: var(--md-cyan-100);
 
-  /* Window/plugin scroll bar styling */
-
-  --jp-scrollbar-thumb-color: var(--jp-layout-color2);
-  --jp-scrollbar-background-color: var(--jp-layout-color0);
-  --jp-scrollbar-border: 1px solid var(--jp-border-color2);
-
   /* Cell specific styles */
 
   --jp-cell-editor-background: var(--md-grey-100);	
   --jp-cell-editor-border-color: var(--md-grey-300);
   --jp-cell-editor-box-shadow: inset 0 0 2px var(--md-blue-300);
-  --jp-cell-editor-background-active: var(--jp-layout-color0);
-  --jp-cell-editor-border-color-active: var(--jp-brand-color1);
+  --jp-cell-editor-active-background: var(--jp-layout-color0);
+  --jp-cell-editor-active-border-color: var(--jp-brand-color1);
   --jp-cell-padding: 5px;
   --jp-cell-prompt-width: 100px;
   --jp-cell-prompt-font-family: 'Roboto Mono', monospace;
   --jp-cell-prompt-letter-spacing: 0px;
   --jp-cell-prompt-opacity: 1.0;
-  --jp-cell-prompt-opacity-not-active: 0.5;
-  --jp-cell-prompt-font-color-not-active: var(--md-grey-700);
+  --jp-cell-prompt-not-active-opacity: 0.5;
+  --jp-cell-prompt-not-active-font-color: var(--md-grey-700);
   /* A custom blend of MD grey and blue 600
    * See https://meyerweb.com/eric/tools/color-blend/#546E7A:1E88E5:5:hex */
   --jp-cell-inprompt-font-color: #307FC1;
@@ -171,6 +165,7 @@ all of MD as it is not optimized for dense, information rich UIs.
 
   --jp-notebook-padding: 10px;
   --jp-notebook-scroll-padding: 100px;
+  --jp-notebook-select-background: var(--jp-layout-color1);
   --jp-notebook-multiselected-color: var(--md-blue-50);
 
   /* Rendermime styles */
@@ -199,11 +194,11 @@ all of MD as it is not optimized for dense, information rich UIs.
   /* Input field styles */
 
   --jp-input-box-shadow: inset 0 0 2px var(--md-blue-300);
-  --jp-input-background-color-active: var(--jp-layout-color1);
-  --jp-input-background-color-hover: var(--jp-layout-color1);
-  --jp-input-background-color: var(--md-grey-100);
+  --jp-input-active-background: var(--jp-layout-color1);
+  --jp-input-hover-background: var(--jp-layout-color1);
+  --jp-input-background: var(--md-grey-100);
   --jp-input-border-color: var(--jp-border-color1);
-  --jp-input-border-color-active: var(--jp-brand-color1);
+  --jp-input-active-border-color: var(--jp-brand-color1);
 
   /* General editor styles */