Add some comments to explain CSS customizations

Author: jtpio

packages/notebook-extension/style/base.css

@@ -6,34 +6,25 @@
 
 @import './variables.css';
 
-/* Document oriented look for the notebook (scrollbar to the right of the page) */
+/**
+  Document oriented look for the notebook.
+  This includes changes to the look and feel of the JupyterLab Notebook
+  component like:
+  - scrollbar to the right of the page
+  - drop shadow on the notebook
+  - smaller empty space at the bottom of the notebook
+  - compact view on mobile
+*/
+
+/* Keep the notebook centered on the page */
 
 body[data-notebook='notebooks'] .jp-NotebookPanel-toolbar {
   padding-left: calc(calc(100% - var(--jp-notebook-max-width)) * 0.5);
   padding-right: calc(calc(100% - var(--jp-notebook-max-width)) * 0.5);
 }
 
-body[data-notebook='notebooks'] .jp-Notebook > * {
-  background: var(--jp-layout-color0);
-}
-
-body[data-notebook='notebooks']
-  .jp-Notebook.jp-mod-commandMode
-  .jp-Cell.jp-mod-active.jp-mod-selected:not(.jp-mod-multiSelected) {
-  background: var(--jp-layout-color0) !important;
-}
-
-body[data-notebook='notebooks'] .jp-WindowedPanel-inner {
-  margin-top: var(--jp-notebook-toolbar-margin-bottom);
-}
-
-body[data-notebook='notebooks'] .jp-Notebook > *:first-child:not(:last-child) {
-  box-shadow: 0px 0px 12px 1px var(--jp-shadow-umbra-color);
-}
-
 body[data-notebook='notebooks'] .jp-Notebook {
   padding-top: unset;
-  padding-bottom: unset;
   padding-left: calc(calc(100% - var(--jp-notebook-max-width)) * 0.5);
   padding-right: calc(
     calc(
@@ -43,12 +34,37 @@ body[data-notebook='notebooks'] .jp-Notebook {
   background: var(--jp-layout-color2);
 }
 
+body[data-notebook='notebooks'] .jp-WindowedPanel-inner {
+  margin-top: var(--jp-notebook-toolbar-margin-bottom);
+}
+
+body[data-notebook='notebooks'] .jp-Notebook-cell {
+  background: var(--jp-layout-color0);
+  padding-left: calc(2 * var(--jp-cell-padding));
+  padding-right: calc(2 * var(--jp-cell-padding));
+}
+
+/* Empty space at the bottom of the notebook (similar to classic) */
 body[data-notebook='notebooks'] .jp-Notebook.jp-mod-scrollPastEnd::after {
   min-height: 100px;
 }
 
-/* body[data-notebook='notebooks'] .jp-WindowedPanel-window > *:first-child { */
-/* TODO: revisit when https://github.com/jupyterlab/jupyterlab/issues/13151 is fixed */
+/* Fix background colors */
+
+body[data-notebook='notebooks'] .jp-Notebook > * {
+  background: var(--jp-layout-color0);
+}
+
+body[data-notebook='notebooks']
+  .jp-Notebook.jp-mod-commandMode
+  .jp-Cell.jp-mod-active.jp-mod-selected:not(.jp-mod-multiSelected) {
+  background: var(--jp-layout-color0) !important;
+}
+
+/**
+  Extra padding to the first and and last cell of the notebook.
+  TODO: revisit when https://github.com/jupyterlab/jupyterlab/issues/13151 is fixed
+*/
 .jp-Notebook-cell[data-windowed-list-index='0'] {
   padding-top: calc(2 * var(--jp-notebook-padding));
 }
@@ -106,7 +122,65 @@ body[data-notebook='notebooks']
   }
 }
 
-/* ---- */
+/* Mobile View */
+
+body[data-format='mobile'] .jp-NotebookCheckpoint {
+  display: none;
+}
+
+body[data-format='mobile'] .jp-Notebook > *:first-child {
+  margin-top: 0;
+}
+
+/* Virtual Notebook fixes */
+
+body[data-notebook='notebooks'] .jp-WindowedPanel-window {
+  background: var(--jp-layout-color0);
+  /* TODO: remove when https://github.com/jupyterlab/jupyterlab/pull/13154 is released */
+  width: unset;
+}
+
+body[data-notebook='notebooks'] .jp-WindowedPanel-inner {
+  /* TODO: remove when https://github.com/jupyterlab/jupyterlab/pull/13157 is released */
+  width: unset;
+}
+
+/* Notebook box shadow */
+
+body[data-notebook='notebooks'] .jp-Notebook > *:first-child:not(:last-child) {
+  box-shadow: 0px 0px 12px 1px var(--jp-shadow-umbra-color);
+}
+
+body[data-notebook='notebooks'] .jp-Notebook > *:first-child:not(:last-child) {
+  box-shadow: 0px 0px 12px 1px var(--jp-shadow-umbra-color);
+}
+
+body[data-notebook='notebooks']
+  .jp-Notebook
+  > *:first-child:last-child::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  box-shadow: 0px 0px 12px 1px var(--jp-shadow-umbra-color);
+}
+
+body[data-notebook='notebooks']
+  .jp-Notebook
+  .jp-Notebook-cell:not(:first-child)::after,
+body[data-notebook='notebooks']
+  .jp-Notebook
+  .jp-Notebook-cell:not(:first-child)::before {
+  content: ' ';
+  height: 100%;
+  position: absolute;
+  top: 0;
+  width: 11px;
+}
+
+/* Additional customizations of the components on the notebook page */
 
 .jp-NotebookKernelLogo {
   flex: 0 0 auto;
@@ -187,63 +261,3 @@ body[data-notebook='notebooks']
   overflow: hidden;
   white-space: nowrap;
 }
-
-/* Mobile View */
-
-body[data-format='mobile'] .jp-NotebookCheckpoint {
-  display: none;
-}
-
-body[data-format='mobile'] .jp-Notebook > *:first-child {
-  margin-top: 0;
-}
-
-/* Virtual Notebook fixes */
-
-body[data-notebook='notebooks'] .jp-WindowedPanel-window {
-  background: var(--jp-layout-color0);
-  /* TODO: remove when https://github.com/jupyterlab/jupyterlab/pull/13154 is released */
-  width: unset;
-}
-
-body[data-notebook='notebooks'] .jp-WindowedPanel-inner {
-  /* TODO: remove when https://github.com/jupyterlab/jupyterlab/pull/13157 is released */
-  width: unset;
-}
-
-body[data-notebook='notebooks'] .jp-Notebook-cell {
-  background: var(--jp-layout-color0);
-  padding-left: calc(2 * var(--jp-cell-padding));
-  padding-right: calc(2 * var(--jp-cell-padding));
-}
-
-/* Notebook box shadow */
-
-body[data-notebook='notebooks'] .jp-Notebook > *:first-child:not(:last-child) {
-  box-shadow: 0px 0px 12px 1px var(--jp-shadow-umbra-color);
-}
-
-body[data-notebook='notebooks']
-  .jp-Notebook
-  > *:first-child:last-child::before {
-  content: '';
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  left: 0;
-  right: 0;
-  box-shadow: 0px 0px 12px 1px var(--jp-shadow-umbra-color);
-}
-
-body[data-notebook='notebooks']
-  .jp-Notebook
-  .jp-Notebook-cell:not(:first-child)::after,
-body[data-notebook='notebooks']
-  .jp-Notebook
-  .jp-Notebook-cell:not(:first-child)::before {
-  content: ' ';
-  height: 100%;
-  position: absolute;
-  top: 0;
-  width: 11px;
-}