First batch of Valo Sass API documentation, plus bug fixes

Also updates the test to always scroll the left panel to the top after
opening a section.

Change-Id: Icdb42795b8ec347b91694c162898f41aa8d80152

6 files changed, 812 insertions, 133 deletions

diff --git a/WebContent/VAADIN/themes/valo/shared/_contextmenu.scss b/WebContent/VAADIN/themes/valo/shared/_contextmenu.scss
index 4b737416c2..7fd182b6cd 100644
--- a/WebContent/VAADIN/themes/valo/shared/_contextmenu.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_contextmenu.scss
@@ -1,3 +1,9 @@
+/**
+ * Outputs the context menu selectors and styles, which is used by Table and Tree for instance.
+ * 
+ * @requires {mixin} valo-selection-item-style
+ * @requires {mixin} valo-selection-item-selected-style
+ */
 @mixin valo-contextmenu {
 
   .v-contextmenu {
diff --git a/WebContent/VAADIN/themes/valo/shared/_global.scss b/WebContent/VAADIN/themes/valo/shared/_global.scss
index 5c010c128d..049518af73 100644
--- a/WebContent/VAADIN/themes/valo/shared/_global.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_global.scss
@@ -4,9 +4,22 @@
 @import "tooltip";
 
 
-// Include global styles only once
+/*
+ * A flag which is set to true when the global styles have been included in the compilation.
+ * Used to only include them once, if Valo is imported multiple times during the compilation
+ * (multiple theme support).
+ *
+ * @access private
+ * @type bool
+ */
 $valo-global-included: false !default;
 
+/*
+ * Global Valo related styles, containing styles which are necessary for the application
+ * and widgets to work correctly.
+ *
+ * @access private
+ */
 @mixin valo-global {
   @if $valo-global-included == false {
 
@@ -173,14 +186,16 @@ $valo-global-included: false !default;
 }
 
 
-
 $valo-shared-pathPrefix: null;
 
 @if $v-relative-paths == false {
   $valo-shared-pathPrefix: "../valo/shared/";
 }
 
-
+/**
+ * Styles for the application root element. Outputs font, font color, background color and default
+ * cursor styles.
+ */
 @mixin valo-app-style {
   font: $v-font-weight #{$v-font-size}/#{$v-line-height} $v-font-family;
   color: $v-font-color;
@@ -195,7 +210,13 @@ $valo-shared-pathPrefix: null;
   }
 }
 
-
+/**
+ * Common application styles, such as loading indicators, tooltip and context menu styles,
+ * caption and icon defaults, basic HTML element resets.
+ * Should only be included once (done automatically when including the main valo mixin).
+ *
+ * @requires {mixin} valo-app-style
+ */
 @mixin valo-common {
 
   //@if & != null {
@@ -351,7 +372,9 @@ $valo-shared-pathPrefix: null;
 
 
 
-
+/**
+ * Generic component caption styles (captions which are generated by layouts).
+ */
 @mixin valo-caption-style {
   font-size: $v-caption-font-size;
   font-weight: $v-caption-font-weight;
@@ -362,7 +385,11 @@ $valo-shared-pathPrefix: null;
 }
 
 
-
+/**
+ * Error indicator styles. The error indicator is by default a font character which you can style freely.
+ *
+ * @requires {mixin} valo-error-indicator-icon-style by default
+ */
 @mixin valo-error-indicator-style {
   color: $v-error-indicator-color;
   font-weight: 600;
@@ -374,18 +401,23 @@ $valo-shared-pathPrefix: null;
   }
 }
 
+/**
+ * The error indicator icon style. Should be a font character or a font icon.
+ */
 @mixin valo-error-indicator-icon-style {
   content: "!";
 }
 
 
-
-// Make the BODY element scrollable instead of the .v-ui element. Scrolling the BODY works better on touch screens.
-// NOTE: breaks percentage sized overlay elements
-// @mixin valo-natural-page-scrolling
-// @usage
-// // Call without any parent selector somewhere in your theme
-// =valo-natural-page-scrolling;
+/**
+ * Make the BODY element scrollable instead of the .v-ui element. Scrolling the BODY usually
+ * works better on touch devices. You loose the ability to control the scroll position from
+ * the server side when using this.
+ *
+ * @example scss
+ *  // Include without any parent selector
+ *  @include valo-natural-page-scrolling;
+ */
 @mixin valo-natural-page-scrolling {
 
   html {
diff --git a/WebContent/VAADIN/themes/valo/shared/_loading-indicator.scss b/WebContent/VAADIN/themes/valo/shared/_loading-indicator.scss
index 56aab30d2b..645e188b09 100644
--- a/WebContent/VAADIN/themes/valo/shared/_loading-indicator.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_loading-indicator.scss
@@ -1,5 +1,3 @@
-// TODO make fallbacks for IE 8 & 9
-
 @-webkit-keyframes v-rotate-360 {
    to {-webkit-transform: rotate(360deg);}
 }
@@ -13,9 +11,16 @@
    to {transform: rotate(360deg);}
 }
 
-
-@mixin valo-spinner ($size: 24px, $thickness: 2px, $color: null, $speed: 500ms) {
-  $color: $color or $v-focus-color;
+/**
+ * Creates a spinner to be used as a loading indicator. On browsers which do not
+ * support CSS animations, an animated GIF image is used as a fallback.
+ *
+ * @param {size} $size (24px) - the diameter of the spinner, in pixels. Should be divisible by 2, increased by 1px if not
+ * @param {size} $thickness (2px) - the thickness or width of the border of the spinner
+ * @param {color} $color ($v-focus-color) - the color of the border of the spinner
+ * @param {time} $speed (500ms) - the speed of the spinning animation
+ */
+@mixin valo-spinner ($size: 24px, $thickness: 2px, $color: $v-focus-color, $speed: 500ms) {
   // Make size divisible by 2, so that the rotation won't jiggle
   $size: round($size) + round($size) % 2;
   height: $size !important;
@@ -59,9 +64,25 @@
 
 
 
-
+/**
+ * The color of the main loading indicator bar.
+ * @type color
+ */
 $v-loading-indicator-color: $v-focus-color !default;
+
+/**
+ * The height of the main loading indicator bar.
+ *
+ * @type size
+ */
 $v-loading-indicator-bar-height: ceil($v-unit-size/10) !default;
+
+/**
+ * The height of the main loading indicator bar when the request to the server
+ * is taking longer than usual and the user is notified that they should wait.
+ *
+ * @type size
+ */
 $v-loading-indicator-bar-height--wait: ceil($v-unit-size/6) !default;
 
 
@@ -89,7 +110,11 @@ $v-loading-indicator-bar-height--wait: ceil($v-unit-size/6) !default;
 }
 
 
-
+/*
+ * Outputs the necessary styles to create the main loading indicator bar.
+ *
+ * @access private
+ */
 @mixin valo-loading-bar {
 
   .v-loading-indicator {
diff --git a/WebContent/VAADIN/themes/valo/shared/_overlay.scss b/WebContent/VAADIN/themes/valo/shared/_overlay.scss
index dc54672cb6..926b00f529 100644
--- a/WebContent/VAADIN/themes/valo/shared/_overlay.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_overlay.scss
@@ -1,40 +1,160 @@
-@function valo-overlay-background-color ($context: $v-background-color) {
-  @if is-dark-color($context) {
-    @return darken($context, 3%);
-  }
-  @return lighten($context, 2%);
-}
-
-
-$v-overlay-background-color: valo-overlay-background-color() !default;
+/**
+ * The background color for overlay elements.
+ *
+ * @type color
+ * @group overlay
+ */
+$v-overlay-background-color: if(is-dark-color($v-background-color), darken($v-background-color, 3%), lighten($v-background-color, 2%)) !default;
+
+/**
+ * The corner radius for overlay elements.
+ *
+ * @type size (px)
+ * @group overlay
+ */
 $v-overlay-border-radius: $v-border-radius !default;
+
+/**
+ * The border width for overlay elements.
+ *
+ * @type size (px)
+ * @group overlay
+ */
 $v-overlay-border-width: first-number($v-border) !default;
 
+/**
+ * The animation which is used when overlay elements are made visible.
+ *
+ * @type list
+ * @group overlay
+ */
 $v-overlay-animate-in: valo-overlay-animate-in 120ms !default;
-$v-overlay-animate-out: valo-placeholder-animate-out 120ms, valo-anim-fade-out 120ms !default;
 
+/**
+ * The animation which is used when overlay elements are removed.
+ *
+ * @type list
+ * @group overlay
+ */
+$v-overlay-animate-out: valo-animate-out-fade 120ms !default;
+
+/**
+ * The padding on each size of overlay elements.
+ *
+ * @type size
+ * @group overlay
+ */
 $v-overlay-padding: round($v-unit-size/9) !default;
+
+/**
+ * The padding on the top and bottom edges of overlay elements.
+ *
+ * @type size
+ * @group overlay
+ */
 $v-overlay-padding-vertical: $v-overlay-padding !default;
+
+/**
+ * The padding on the left and right edges of overlay elements.
+ *
+ * @type size
+ * @group overlay
+ */
 $v-overlay-padding-horizontal: $v-overlay-padding !default;
 
+/**
+ * The shadow used for overlay elements.
+ *
+ * @type list
+ * @group overlay
+ */
 $v-overlay-shadow: 0 4px 10px 0 (v-shade 2), 0 3px 5px 0 v-shade, 0 0 0 $v-overlay-border-width (v-shade (2.5 - color-luminance($v-background-color)/255 + $v-bevel-depth/100%)) !default;
 
+/**
+ * The background color for selection overlays, i.e. overlays which present a
+ * list of options for the user to choose from, such as context menus and drop down
+ * menus.
+ *
+ * @type color
+ * @group overlay
+ */
 $v-selection-overlay-background-color: $v-overlay-background-color !default;
+
+/**
+ * The padding on each size of selection overlay elements.
+ *
+ * @type size
+ * @group overlay
+ */
 $v-selection-overlay-padding: $v-overlay-padding !default;
+
+/**
+ * The padding on the top and bottom edges of selection overlay elements.
+ *
+ * @type size
+ * @group overlay
+ */
 $v-selection-overlay-padding-vertical: $v-selection-overlay-padding !default;
+
+/**
+ * The padding on the left and right edges of selection overlay elements.
+ *
+ * @type size
+ * @group overlay
+ */
 $v-selection-overlay-padding-horizontal: $v-selection-overlay-padding !default;
 
+/**
+ * The corner radius for selection overlay elements.
+ *
+ * @type size (px)
+ * @group overlay
+ */
 $v-selection-item-border-radius: $v-border-radius - 1px !default;
+
+/**
+ * The height of individual selection overlay list items.
+ *
+ * @type size (px)
+ * @group overlay
+ */
 $v-selection-item-height: ceil($v-unit-size/1.4) !default;
+
+/**
+ * The horizontal padding for individual selection overlay list items.
+ *
+ * @type size
+ * @group overlay
+ */
 $v-selection-item-padding-horizontal: ceil($v-unit-size/4) !default;
+
+/**
+ * The font weight for individual selection overlay list items.
+ *
+ * @type number | identifier
+ * @group overlay
+ */
 $v-selection-item-font-weight: max(400, $v-font-weight);
-$v-selection-item-selection-color: $v-selection-color !default;
 
+/**
+ * The font color for individual selection overlay list items.
+ *
+ * @type color
+ * @group overlay
+ */
+$v-selection-item-selection-color: $v-selection-color !default;
 
 
 
 
 
+/*
+ * Simulates CSS box-shadow using the extraneous shadow elements in the DOM.
+ *
+ * @access private
+ * @deprecated The .v-shadow element is deprecated since 7.3.0
+ * @group overlay
+ */
 @mixin valo-ie8-shadow($shadow, $element: top) {
   .#{$element} {
     $shadow-offset-x: nth($shadow, 1);
@@ -97,7 +217,16 @@ $v-selection-item-selection-color: $v-selection-color !default;
 
 
 
-
+/**
+ * Outputs styles for overlay elements
+ *
+ * @group overlay
+ *
+ * @param {color} $background-color ($v-overlay-background-color) - the background color for the overlay
+ * @param {list} $shadow ($v-overlay-shadow) - the shadow for the overlay
+ * @param {list} $animate-in ($v-overlay-animate-in) - the animation used when the overlay is made visible
+ * @param {list} $animate-out ($v-overlay-animate-out) - the animation used when the overlay is removed
+ */
 @mixin valo-overlay-style (
     $background-color: $v-overlay-background-color,
     $shadow: $v-overlay-shadow,
@@ -135,7 +264,15 @@ $v-selection-item-selection-color: $v-selection-color !default;
 
 
 
-
+/**
+ * Outputs styles for selection overlay elements.
+ *
+ * @group overlay
+ *
+ * @param {color} $background-color ($v-selection-overlay-background-color) - the background color for the overlay
+ * @param {list} $animate-in ($v-overlay-animate-in) - the animation used when the selection overlay is made visible
+ * @param {list} $animate-out ($v-overlay-animate-out) - the animation used when the selection overlay is removed
+ */
 @mixin valo-selection-overlay-style ($background-color: $v-selection-overlay-background-color, $animate-in: $v-overlay-animate-in, $animate-out: $v-overlay-animate-out) {
   @include valo-overlay-style($background-color: $background-color, $animate-in: $animate-in, $animate-out: $animate-out);
   padding: $v-selection-overlay-padding-vertical $v-selection-overlay-padding-horizontal;
@@ -143,7 +280,11 @@ $v-selection-item-selection-color: $v-selection-color !default;
 
 
 
-
+/**
+ * Outputs the styles for selection item elements (i.e. individual items in context menus and drop down menus).
+ *
+ * @group overlay
+ */
 @mixin valo-selection-item-style {
   cursor: pointer;
   line-height: $v-selection-item-height;
@@ -178,7 +319,11 @@ $v-selection-item-selection-color: $v-selection-color !default;
 
 
 
-
+/**
+ * Outputs the styles for selected selection item elements.
+ *
+ * @group overlay
+ */
 @mixin valo-selection-item-selected-style {
   @include valo-gradient($v-selection-item-selection-color);
   $font-color: valo-font-color($v-selection-item-selection-color, 0.9);
@@ -192,13 +337,24 @@ $v-selection-item-selection-color: $v-selection-color !default;
 
 
 
-
+/**
+ * Outputs the selectors and styles for generic dragging ghost elements.
+ *
+ * @group drag-n-drop
+ */
 @mixin valo-drag-element {
   .v-drag-element {
     @include valo-drag-element-style;
   }
 }
 
+/**
+ * Outputs the styles for generic dragging ghost elements.
+ *
+ * @group drag-n-drop
+ *
+ * @param {color} $background-color ($v-app-background-color) - the background color for the ghost element
+ */
 @mixin valo-drag-element-style ($background-color: $v-app-background-color) {
   background: $background-color;
   color: valo-font-color($background-color);
diff --git a/WebContent/VAADIN/themes/valo/shared/_tooltip.scss b/WebContent/VAADIN/themes/valo/shared/_tooltip.scss
index 7b7b83ff33..3c9c914499 100644
--- a/WebContent/VAADIN/themes/valo/shared/_tooltip.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_tooltip.scss
@@ -1,16 +1,81 @@
-// @category Tooltip
-
+/**
+ * The backgound color for tooltips.
+ *
+ * @type color
+ * @group tooltip
+ */
 $v-tooltip-background-color: rgba(if(is-dark-color($v-background-color), scale-color($v-background-color, $lightness: 80%), scale-color($v-background-color, $lightness: -80%)), .9) !default;
+
+/**
+ * The font color for tooltips.
+ *
+ * @type color
+ * @group tooltip
+ */
 $v-tooltip-font-color: valo-font-color(opacify($v-tooltip-background-color, 1), 1) !default;
+
+/**
+ * The font size for tooltips.
+ *
+ * @type size
+ * @group tooltip
+ */
 $v-tooltip-font-size: max(12px, round($v-font-size * 0.86)) !default;
+
+/**
+ * The CSS box shadow for tooltips.
+ *
+ * @type list
+ * @group tooltip
+ */
 $v-tooltip-box-shadow: 0 2px 12px rgba(#000, .2) !default;
+
+/**
+ * The vertical padding for tooltips.
+ *
+ * @type size
+ * @group tooltip
+ */
 $v-tooltip-padding-vertical: round($v-unit-size/8) !default;
+
+/**
+ * The horizontal padding for tooltips.
+ *
+ * @type size
+ * @group tooltip
+ */
 $v-tooltip-padding-horizontal: round($v-unit-size/4) !default;
+
+/**
+ * The backgound color for error tooltips.
+ *
+ * @type color
+ * @group tooltip
+ */
 $v-tooltip-error-message-background-color: #fff !default;
+
+/**
+ * The font color for error tooltips.
+ *
+ * @type color
+ * @group tooltip
+ */
 $v-tooltip-error-message-font-color: $v-error-indicator-color !default;
+
+/**
+ * The corner radius for tooltips.
+ *
+ * @type size
+ * @group tooltip
+ */
 $v-tooltip-border-radius: $v-border-radius - 1px !default;
 
 
+/**
+ * Outputs the selectors and styles for tooltip elements.
+ *
+ * @group tooltip
+ */
 @mixin valo-tooltip {
   .v-tooltip {
     @include valo-tooltip-style;
@@ -54,7 +119,11 @@ $v-tooltip-border-radius: $v-border-radius - 1px !default;
   }
 }
 
-
+/**
+ * Outputs the main styles for tooltip elements.
+ *
+ * @group tooltip
+ */
 @mixin valo-tooltip-style {
   background-color: opacify($v-tooltip-background-color, 1);  // For IE8
   background-color: $v-tooltip-background-color;
diff --git a/WebContent/VAADIN/themes/valo/shared/_variables.scss b/WebContent/VAADIN/themes/valo/shared/_variables.scss
index 7dd3827298..4634a71fea 100644
--- a/WebContent/VAADIN/themes/valo/shared/_variables.scss
+++ b/WebContent/VAADIN/themes/valo/shared/_variables.scss
@@ -1,88 +1,459 @@
 // Color functions are used to calculate default font color
 @import "../util/color";
 
-
-
-// A static text that is shown while the application JavaScript is loaded and started
-$v-app-loading-text               : ""                                          !default;
-
-
-// Base line height used for all widgets
-$v-line-height                    : 1.55                                        !default;
-
-
-$v-background-color               : hsl(210, 0%, 98%)                           !default;
-$v-app-background-color           : $v-background-color                         !default;
-
-$v-font-size                      : 16px                                        !default; // Should be specified in pixels
-$v-font-weight                    : 300                                         !default; // Must be specified as a numeric value (i.e. not 'normal' or 'bold')
-$v-font-color                     : valo-font-color($v-app-background-color)    !default;
-$v-font-family                    : "Open Sans", sans-serif                     !default;
-
-$v-caption-font-size              : round($v-font-size * 0.9)                   !default; // Should be a pixel value
-$v-caption-font-weight            : max(400, $v-font-weight)                    !default;
-
-$v-unit-size                      : round(2.3 * $v-font-size)                   !default; // Must be specified in pixels (suitable range 18-50)
-
-$v-layout-margin-top              : round($v-unit-size)                         !default;
-$v-layout-margin-right            : round($v-unit-size)                         !default;
-$v-layout-margin-bottom           : round($v-unit-size)                         !default;
-$v-layout-margin-left             : round($v-unit-size)                         !default;
-
-$v-layout-spacing-vertical        : round($v-unit-size/3)                       !default;
-$v-layout-spacing-horizontal      : round($v-unit-size/3)                       !default;
-
-$v-border                         : 1px solid (v-shade 0.7)                     !default; // Size must be specified in pixels
-$v-border-radius                  : 4px                                         !default; // Must be specified in pixels
-
-$v-gradient                       : v-linear 8%                                 !default;
-
-$v-bevel                          : inset 0 1px 0 v-tint, inset 0 -1px 0 v-shade !default;
-$v-bevel-depth                    : 30%                                         !default;
-
-$v-shadow                         : 0 2px 3px v-shade                           !default;
-$v-shadow-opacity                 : 5%                                          !default;
-
-$v-focus-color                    : valo-focus-color()                          !default;
-$v-focus-style                    : 0 0 0 2px rgba($v-focus-color, .5)          !default;
-
-$v-animations-enabled             : true                                        !default;
-$v-hover-styles-enabled           : true                                        !default;
-
-$v-disabled-opacity               : 0.5                                         !default;
-
-$v-selection-color                : $v-focus-color                              !default;
-
-$v-default-field-width            : $v-unit-size * 5                            !default;
-
-$v-error-indicator-color          : #ed473b                                     !default;
-$v-required-field-indicator-color : $v-error-indicator-color                    !default;
-$v-friendly-color                 : #2c9720                                     !default;
-
-
-$v-scaling-factor--tiny           : 0.75                                        !default;
-$v-scaling-factor--small          : 0.85                                        !default;
-$v-scaling-factor--large          : 1.2                                         !default;
-$v-scaling-factor--huge           : 1.6                                         !default;
-
-$v-unit-size--tiny                : round($v-unit-size * $v-scaling-factor--tiny)  !default;
-$v-unit-size--small               : round($v-unit-size * $v-scaling-factor--small) !default;
-$v-unit-size--large               : round($v-unit-size * $v-scaling-factor--large) !default;
-$v-unit-size--huge                : round($v-unit-size * $v-scaling-factor--huge)  !default;
-
-$v-font-size--tiny                : ceil($v-font-size * $v-scaling-factor--tiny)  !default;
-$v-font-size--small               : ceil($v-font-size * $v-scaling-factor--small) !default;
-$v-font-size--large               : ceil($v-font-size * $v-scaling-factor--large) !default;
-$v-font-size--huge                : ceil($v-font-size * $v-scaling-factor--huge)  !default;
-
-
-
-// List of components to include in the theme compilation. The list can be modified to make
-// the compiled theme smaller by removing unused components from the list.
-//
-// @usage
-// // Remove the Calendar component styles from the output
-// $v-included-components: remove($v-included-components, calendar);
+/**
+ * A static text that is shown under the loading spinned while the client-side
+ * engine is being loaded and started. The text must be given in quotes. The
+ * text can not be localized currently.
+ *
+ * @type string, quoted
+ */
+$v-app-loading-text: "" !default;
+
+/**
+ * Base line height for all widgets. It must be given a unitless number.
+ *
+ * @group typography
+ * @type number
+ */
+$v-line-height: 1.55 !default;
+
+/**
+ * Base font size for the theme. The font size defines the overall sizing of
+ * UI components by default. Must be specified in pixels.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size: 16px !default;
+
+/**
+ * Base font weight for plain text.
+ * Must be specified as a numeric value: 100, 200, 300 (light), 400 (regular),
+ * 500, 600, 700 (bold), 800 or 900.
+ *
+ * @group typography
+ * @type number
+ */
+$v-font-weight: 300 !default;
+
+/**
+ * Base font family for the theme. Can be any valid CSS font stack.
+ *
+ * @group typography
+ * @type list
+ */
+$v-font-family: "Open Sans", sans-serif !default;
+
+/**
+ * Font size for generic component captions. Can be any valid CSS font-size. A
+ * round pixel value is recommended.
+ *
+ * @group typography
+ * @type number
+ */
+$v-caption-font-size: round($v-font-size * 0.9) !default;
+
+/**
+ * Font weight for generic component captions. Can be any valid CSS font-weight.
+ *
+ * @group typography
+ * @type number | identifier
+ */
+$v-caption-font-weight: max(400, $v-font-weight) !default;
+
+/**
+ * Border specification for the components that have a border. The border width
+ * must be specified in pixels. For the border color, you can specify any CSS color
+ * or one of the v-tint, v-shade, and v-tone keywords.
+ *
+ * @group style
+ * @type list
+ */
+$v-border: 1px solid (v-shade 0.7) !default;
+
+/**
+ * Corner radius for components that have a border. The measure must be specified as a
+ * single pixel value (i.e. not as a list of values for each corner).
+ *
+ * @group style
+ * @type size (px)
+ */
+$v-border-radius: 4px !default;
+
+/**
+ * Color gradient style for components that have a gradient. The gradient style may use
+ * the following keywords: v-linear and v-linear-reverse. The opacity must be given
+ * as percentage between 0% and 100%.
+ * 
+ * #### Gradient styles
+ * 
+ *  - __v-linear__ - The start of the gradient is a lighter shade of the base color and the end is a darker shade of the base color. A basic linear gradient.
+ *  - __v-linear-reverse__ - Same as v-linear, but the color stops are reversed (darker at the start and lighter at the end)
+ *
+ * @group style
+ * @type list
+ */
+$v-gradient: v-linear 8% !default;
+
+/**
+ * Inset shadow style to define how some components are "raised" from the background.
+ * The value follows the syntax of CSS box-shadow, and should be a list of insets.
+ * For the bevel color, you can specify any CSS color or one of the v-tint, v-shade,
+ * and v-tone keywords.
+ *
+ * @group style
+ * @type list
+ */
+$v-bevel: inset 0 1px 0 v-tint, inset 0 -1px 0 v-shade !default;
+
+/**
+ * Specifies the "depth" of the bevel shadow, as applied to one of the color keywords for
+ * the bevel style. The actual amount of tint, shade, or tone is computed from the depth.
+ *
+ * @group style
+ * @type number (pct)
+ */
+$v-bevel-depth: 30% !default;
+
+/**
+ * Default shadow style for all components. As with $v-bevel, the value follows the syntax
+ * of CSS box-shadow, but without the inset. For the shadow color, you can specify any CSS
+ * color or one of the v-tint or v-shade keywords.
+ *
+ * @group style
+ * @type list
+ */
+$v-shadow: 0 2px 3px v-shade !default;
+
+/**
+ * Specifies the opacity of the shadow, as applied to one of the color keywords for the
+ * shadow style. The actual amount of tint or shade is computed from the depth.
+ *
+ * @group style
+ * @type number (pct)
+ */
+$v-shadow-opacity: 5% !default;
+
+/**
+ * The background color is the main control parameter for the Valo theme and
+ * it is  used for computing all other colors in the theme. If the color is dark
+ * (has low luminance),  * light foreground colors that give high contrast
+ * with the background are automatically used.
+ *
+ * Can be any valid CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-background-color: hsl(210, 0%, 98%) !default;
+
+/**
+ * Background color of the UI's root element. You can specify the color in
+ * any way allowed in CSS. Used as the base for other default colors, such
+ * as panel and window content areas.
+ *
+ * Can be any valid CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-app-background-color: $v-background-color !default;
+
+/**
+ * Base font color for the theme. Can be any valid CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-font-color: valo-font-color($v-app-background-color) !default;
+
+/**
+ * Color for the field focus indicator. The valo-focus-color() function computes a
+ * high-contrast color from the context, which is usually the background color. The color
+ * can be any CSS color.
+ *
+ * @group color
+ * @type color
+ */
+$v-focus-color: valo-focus-color() !default;
+
+/**
+ * Box-shadow specification for the field focus indicator. The space-separated values
+ * are the horizontal shadow position in pixels, vertical shadow position in pixels,
+ * blur distance in pixels, spread distance in pixels, and the color. The color can be
+ * any CSS color. You can only specify the color, in which case defaults for the position
+ * are used. rgba() or hsla() can be used to enable transparency.
+ *
+ * @group style
+ * @type list | color
+ */
+$v-focus-style: 0 0 0 2px rgba($v-focus-color, .5) !default;
+
+/**
+ * Opacity of disabled components, from 0 to 1. Not all components have reduced opacity when disabled, such as Labels.
+ *
+ * @group style
+ * @type number
+ */
+$v-disabled-opacity: 0.5 !default;
+
+/**
+ * Color for indicating selection in selection components.
+ *
+ * @group color
+ * @type color
+ */
+$v-selection-color: $v-focus-color !default;
+
+/**
+ * Color of the component error indicator and other error indications, such as the
+ * error style notification.
+ *
+ * @group color
+ * @type color
+ */
+$v-error-indicator-color: #ed473b !default;
+
+/**
+ * Color of the required indicator in field components.
+ *
+ * @group color
+ * @type color
+ */
+$v-required-field-indicator-color: $v-error-indicator-color !default;
+
+/**
+ * Color used for success states and to indicate safe actions (i.e. actions that
+ * will not cause any data loss).
+ *
+ * @group color
+ * @type color
+ */
+$v-friendly-color: #2c9720 !default;
+
+/**
+ * Color specifications for $v-border, $v-bevel, and $v-shadow may use, in addition to CSS colors, the following keywords:
+ *
+ *  - __v-tint__ - Lighter than the background color
+ *  - __v-shade__ - Darker than the background color
+ *  - __v-tone__ - Adaptive color specification: darker on light background and lighter on dark background. Not usable in $v-shadow.
+ *
+ *
+ *  These keywords can be further adjusted by combining them with a strength multiplier, specified in parenthesis.
+ *
+ *  Examples:
+ *
+ *      (v-tint 2)
+ *      (v-shade 0.6)
+ *      (v-tone 1.1)
+ *
+ * @group color
+ */
+$v-color-keywords: v-tint, v-shade, v-tone;
+
+/**
+ * This is the base size for various layout measures. It is directly used in some
+ * measures, such as button height and layout margins, while other measures are
+ * derived from it. The value must be specified in pixels, with a suitable range
+ * of 18-50.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size: round(2.3 * $v-font-size) !default;
+
+/**
+ * Scaling factor for tiny sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--tiny: 0.75 !default;
+
+/**
+ * Scaling factor for small sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--small: 0.85 !default;
+
+/**
+ * Scaling factor for large sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--large: 1.2 !default;
+
+/**
+ * Scaling factor for huge sizes. Must be a unitless number.
+ *
+ * @group layout
+ * @type number
+ */
+$v-scaling-factor--huge: 1.6 !default;
+
+/**
+ * Unit size for tiny components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--tiny: round($v-unit-size * $v-scaling-factor--tiny) !default;
+
+/**
+ * Unit size for small components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--small: round($v-unit-size * $v-scaling-factor--small) !default;
+
+/**
+ * Unit size for large components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--large: round($v-unit-size * $v-scaling-factor--large) !default;
+
+/**
+ * Unit size for huge components. Must be a pixel value.
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-unit-size--huge: round($v-unit-size * $v-scaling-factor--huge) !default;
+
+/**
+ * The top margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-top: round($v-unit-size) !default;
+
+/**
+ * The right margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-right: round($v-unit-size) !default;
+
+/**
+ * The bottom margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-bottom: round($v-unit-size) !default;
+
+/**
+ * The left margin size for all built-in layout components, when the margin is
+ * enabled with setMargin(). Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-margin-left: round($v-unit-size) !default;
+
+/**
+ * Amount of vertical space when spacing is enabled for a layout with setSpacing().
+ * Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-spacing-vertical: round($v-unit-size/3) !default;
+
+/**
+ * Amount of horizontal space when spacing is enabled for a layout with setSpacing().
+ * Can be any valid CSS size.
+ *
+ * @group layout
+ * @type size
+ */
+$v-layout-spacing-horizontal: round($v-unit-size/3) !default;
+
+/**
+ * Tiny font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--tiny: ceil($v-font-size * $v-scaling-factor--tiny) !default;
+
+/**
+ * Small font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--small: ceil($v-font-size * $v-scaling-factor--small) !default;
+
+/**
+ * Large font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--large: ceil($v-font-size * $v-scaling-factor--large) !default;
+
+/**
+ * Huge font size.
+ *
+ * @group typography
+ * @type size (px)
+ */
+$v-font-size--huge: ceil($v-font-size * $v-scaling-factor--huge) !default;
+
+/**
+ * Default width of certain field components, unless overridden with setWidth().
+ *
+ * @group layout
+ * @type size (px)
+ */
+$v-default-field-width: $v-unit-size * 5 !default;
+
+/**
+ * Specifies whether various CSS animations are used. Not all animations are disabled when
+ * set to false, such as the default loading indicator animations.
+ *
+ * @group optimization
+ * @type bool
+ */
+$v-animations-enabled: true !default;
+
+/**
+ * Specifies whether various :hover styles are used for indicating that mouse pointer
+ * hovers over an element.
+ *
+ * @group optimization
+ * @type bool
+ */
+$v-hover-styles-enabled: true !default;
+
+/**
+ * List of components to include in the theme compilation. The list can be modified to make
+ * the compiled theme smaller by removing unused components from the list.
+ *
+ * @group optimization
+ * @type list
+ *
+ * @example scss
+ * // Remove the Calendar component styles from the output (must be declared after importing Valo)
+ * $v-included-components: remove($v-included-components, calendar);
+ *
+ * @example scss
+ * // Only include the Label, Button and Vertical and Horizontal layouts in the compilation
+ * $v-included-components: label, button, orderedlayout;
+ */
 $v-included-components:
     absolutelayout,
     accordion,
@@ -125,23 +496,43 @@ $v-included-components:
     window,
     valo-menu !default;
 
-
+/**
+ * List of components whose additional styles should be included in the compilation.
+ *
+ * @group optimization
+ * @type list
+ */
 $v-included-additional-styles: $v-included-components !default;
 
-
-// Checks if a given component is included in the compilation. Used by the collection mixins that
-// include all components, like valo-components and valo-components.
-// @param     $component-name {String} the name of the component to check
-// @param     $is-included {list} (Optional) the list of components which is checked
-// @return    {Boolean} true if the component is included in the compilation, false if not
+/**
+ * Checks if a given component is included in the compilation. Used by the collection mixins that
+ * include all components (i.e. valo-components).
+ *
+ * @requires $v-included-components
+ *
+ * @example scss
+ *  @if v-is-included(button) {
+ *    // The Button component is included in the compilation
+ *  }
+ *
+ * @param {string} $component-name - the name of the component to check
+ * @param {list} $is-included ($v-included-components) - the list of components which is checked
+ *
+ * @return {bool} true if the component is included in the compilation, false if not
+ *
+ * @group optimization
+ */
 @function v-is-included ($component-name, $is-included: $v-included-components) {
   @return contains($is-included, $component-name);
 }
 
 
-
-// A flag to note whether relative URL paths are relative to the currently parsed SCSS file or to the compilation root file.
-// The Vaadin compiler parses URL paths differently than the regular Sass compiler (i.e. Vaadin modifies relative url paths).
-// This boolean is used to flag which compiler is used, so that paths are correct for different resources.
-// false == Ruby, true == Vaadin
+/**
+ * A flag to note whether relative URL paths are relative to the currently parsed SCSS file or to the compilation root file.
+ * The Vaadin compiler parses URL paths differently than the regular Sass compiler (i.e. Vaadin modifies relative url paths).
+ * This boolean is used to flag which compiler is used, so that paths are correct for different resources.
+ * false == Ruby, true == Vaadin
+ *
+ * @type bool
+ */
 $v-relative-paths: true !default;