path: root/documentation/themes/themes-valo.asciidoc

---
title: Valo Theme
order: 7
layout: page
---

[[themes.valo]]
= Valo Theme

Valo is the word for light in Finnish. The Valo theme incorporates the use of
light in its logic, in how it handles shades and highlights. It creates lines,
borders, highlights, and shadows adaptively according to a background color,
always with contrasts pleasant to human visual perception. Auxiliary colors are
computed using an algorithmic color theory to blend gently with the background.
The static art is complemented with responsive animations.

The true power of Valo lies in its configurability with parameters, functions,
and Sass mixins. You can use the built-in definitions in your own themes or
override the defaults. Detailed documentation of the available mixins,
functions, and variables can be found in the Valo API documentation available at
http://vaadin.com/valo.

[[themes.valo.use]]
== Basic Use

Valo is used just like other themes. Its optional parameters must be given
before the [literal]#++@import++# statement.

Your project theme file, such as [filename]#mytheme.scss#, included from the
[filename]#styles.scss# file, could be as follows:


----
// Modify the base color of the theme
$v-background-color: hsl(200, 50%, 50%);

// Import valo after setting the parameters
@import "../valo/valo";

.mythemename {
  @include valo;

  // Your theme's rules go here
}
----

If you need to override mixins or function definitions in the valo theme, you
must do that after the import statement, but before including the valo mixin.
Also, with some configuration parameters, you can use variables defined in the
theme. In this case, they need to be overridden after the import statement.


[[themes.valo.variables]]
== Common Settings

In the following, we describe the optional parameters that control the visual
appearance of the Valo theme. In addition to the ones given here, component
styles have their own parameters, listed in the sections describing the
components in the other chapters.

[[themes.valo.variables.general]]
=== General Settings

$v-background-color(default:[literal]#++hsl(210, 0%, 98%)++#):: 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.

+
You can specify the color in any way allowed in CSS: hexadecimal RGB color code,
RGB/A value specified with [methodname]#rgb()# or [methodname]#rgba()#, HSL/A
value specified with [methodname]#hsl()# or [methodname]#hsla()#. You can also
use color names, but it should be avoided, as not all CSS color names are
currently supported.

$v-app-background-color(default:$v-background-color):: Background color of the UI's root element. You can specify the color in any way
allowed in CSS.

$v-app-loading-text(default:[literal]#++""++#):: 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.


+
----
$v-app-loading-text: "Loading Resources...";
----
$v-line-height(default:[literal]#++1.55++#):: Base line height for all widgets. It must be given a unitless number.


+
----
$v-line-height: 1.6;
----



[[themes.valo.variables.fonts]]
=== Font Settings

$v-font-size(default:[literal]#++16px++#):: Base font size. It should be specified in pixels.


+
----
$v-font-size: 18px;
----
$v-font-weight(default:[literal]#++300++#):: Font weight for normal fonts. The size should be given as a numeric value, not
symbolic.


+
----
$v-font-weight: 400;
----
$v-font-color(default: computed):: Foreground text color, specified as any CSS color value. The default is computed
from the background color so that it gives a high contrast with the background.

$v-font-family(default:[literal]#++"Open Sans", sans-serif++#):: Font family and fallback fonts as a comma-separated list. Font names containing
spaces must be quoted. The default font Open Sans is a web font included in the
Valo theme. Other used Valo fonts must be specified in the list to enable them.
See <<themes.valo.fonts>>.


+
----
$v-font-family: "Source Sans Pro", sans-serif;
----
$v-caption-font-size(default:[literal]#++round($v-font-size * 0.9)++#):: Font size for component captions. The value should be a pixel value.

$v-caption-font-weight(default:[literal]#++max(400, $v-font-weight)++#):: Font weight for captions. It should be defined with a numeric value instead of
symbolic.




[[themes.valo.variables.layout]]
=== Layout Settings


++++
<variablelist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xl="http://www.w3.org/1999/xlink"><varlistentry><term><varname>$v-unit-size</varname> (default: <literal>round(2.3 * $v-font-size)</literal>)</term><listitem><para>
                                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.
                            </para><programlisting>$v-unit-size: 40px;</programlisting></listitem></varlistentry><varlistentry><term><varname>$v-layout-margin-top</varname></term><term><varname>$v-layout-margin-right</varname></term><term><varname>$v-layout-margin-bottom</varname></term><term><varname>$v-layout-margin-left</varname> (default: <literal>$v-unit-size</literal>)</term><listitem><para>
                                Layout margin sizes for all built-in layout components,
                                when the margin is enabled with
                                <methodname>setMargin()</methodname>, as described in
                                <xref linkend="layout.settings.margins"/>.
                            </para></listitem></varlistentry><varlistentry><term><varname>$v-layout-spacing-vertical</varname> and
                            <varname>$v-layout-spacing-horizontal</varname> (default:
                            <literal>round($v-unit-size/3)</literal>)</term><listitem><para>
                                Amount of vertical or horizontal space when spacing is enabled
                                for a layout with <methodname>setSpacing()</methodname>, as
                                described in <xref linkend="layout.settings.spacing"/>.
                            </para></listitem></varlistentry></variablelist>
++++


[[themes.valo.variables.component]]
=== Component Features

The following settings apply to various graphical features of some components.

$v-border(default:[literal]#++1px solid (v-shade 0.7)++#):: Border specification for the components that have a border. The thickness
measure must be specified in pixels. For the border color, you can specify any
CSS color or one of the [literal]#++v-tint++#, [literal]#++v-shade++#, and
[literal]#++v-tone++# keywords described later in this section.

$v-border-radius(default:[literal]#++4px++#):: Corner radius for components that have a border. The measure must be specified
in pixels.


+
----
$v-border-radius: 8px;
----
$v-gradient(default:[literal]#++v-linear 8%++#):: Color gradient style for components that have a gradient. The gradient style may
use the following keywords: [literal]#++v-linear++# and
[literal]#++v-linear-reverse++#. The opacity must be given as percentage between
0% and 100%.


+
----
$v-gradient: v-linear 20%;
----
$v-bevel(default:[literal]#++inset 0 1px 0 v-tint, inset 0 -1px 0 v-shade++#):: 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
[literal]#++v-tint++#, [literal]#++v-shade++#, and [literal]#++v-tone++#
keywords described later in this section.

+
//TODO Check the meaning of v-tone
$v-bevel-depth(default:[literal]#++30%++#):: 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.

$v-shadow(default:[literal]#++0 2px 3px v-shade++#):: Default shadow style for all components. As with $v-bevel, the value follows the
syntax of CSS box-shadow, but without the [literal]#++inset++#. For the shadow
color, you can specify any CSS color or one of the [literal]#++v-tint++# or
[literal]#++v-shade++# keywords described later in this section.

$v-shadow-opacity(default:[literal]#++5%++#):: 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.

$v-focus-style(default:[literal]#++0 0 0 2px rgba($v-focus-color, .5)++#):: 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. [methodname]#rgba()# or [methodname]#hsla()#
can be used to enable transparency.

+
For example, the following creates a 2 pixels wide orange outline around the
field:


+
----
$v-focus-style: 0 0 0 2px orange;
----
$v-focus-color(default:[literal]#++valo-focus-color()++#):: Color for the field focus indicator. The [methodname]#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.

$v-animations-enabled(default:[literal]#++true++#):: Specifies whether various CSS animations are used.

$v-hover-styles-enabled(default:[literal]#++true++#):: Specifies whether various [literal]#++:hover++# styles are used for indicating
that mouse pointer hovers over an element.

$v-disabled-opacity(default:[literal]#++0.5++#):: Opacity of disabled components, as described in
<<dummy/../../../framework/components/components-features#components.features.enabled,"Enabled">>.

$v-selection-color(default:[literal]#++$v-focus-color++#):: Color for indicating selection in selection components.

$v-default-field-width(default:[literal]#++$v-unit-size * 5++#):: Default width of certain field components, unless overridden with
[methodname]#setWidth()#.

$v-error-indicator-color(default:[literal]#++#ed473b++#):: Color of the component error indicator, as described in
<<dummy/../../../framework/application/application-errors#application.errors.error-indicator,"Error
Indicator and Message">>.

$v-required-field-indicator-color(default:[literal]#++$v-error-indicator-color++#):: Color of the required indicator in field components.
ifdef::vaadin7[]
Field components are described in <<dummy/../../../framework/components/components-fields#components.fields.field,"Field Interface">>.
endif::vaadin7[]

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.



For example:


----
$v-border: 1px solid v-shade;
----

You can fine-tune the contrast by giving a weight parameter in parentheses:


----
$v-border: 1px solid (v-tint 2);
----


----
$v-border: 1px solid (v-tone 0.5);
----


[[themes.valo.variables.optimization]]
=== Theme Compilation and Optimization

$v-relative-paths(default:[literal]#++true++#):: This flags specifies whether relative URL paths are relative to the currently
parsed SCSS file or to the compilation root file, so that paths are correct for
different resources. Vaadin theme compiler parses URL paths differently from the
regular Sass compiler (Vaadin modifies relative URL paths). Use
[literal]#++false++# for Ruby compiler and [literal]#++true++# for Vaadin Sass
compiler.

$v-included-components(default: component list):: Theme optimization parameter to specify the included component themes, as
described in <<themes.valo.optimization>>.

$v-included-additional-styles(default:[literal]#++$v-included-components++#):: Theme optimization parameter that lists the components for which the additional
component stylenames should be included. See <<themes.valo.component>> for more
details.





[[themes.valo.mixins]]
== Valo Mixins and Functions

Valo uses Sass mixins and functions heavily to compute various theme features,
such as colors and shades. Also, all component styles are mixins. You can use
the built-in mixins or override them. For detailed documentation of the mixins
and functions, please refer to the Valo API documentation available at
http://vaadin.com/valo/api.


[[themes.valo.fonts]]
== Valo Fonts

Valo includes the following custom fonts:

* Open Sans
* Source Sans Pro
* Roboto
* Lato
* Lora

The used fonts must be specified with the $v-font-family parameter for Valo, in
a fallback order. A font family is used in decreasing order of preference, in
case a font with higher preference is not available in the browser. You can
specify any font families and generic families that browsers may support. In
addition to the primary font family, you can use also others in your
application. To enable using the fonts included in Valo, you need to list them
in the variable.


----
$v-font-family: 'Open Sans', sans-serif, 'Source Sans Pro';
----

Above, we specify Open Sans as the preferred primary font, with any sans-serif
font that the browser supports as a fallback. In addition, we include the Source
Sans Pro as an auxiliary font that we can use in custom rules as follows:


----
.v-label pre {
  font-family: 'Source Sans Pro', monospace;
}
----

This would specify using the font in any [classname]#Label# component with the
[literal]#++PREFORMATTED++# content mode.


[[themes.valo.component]]
== Component Styles

Many components have component-specific styles to make them smaller, bigger, and
so forth. You can specify the component styles with [methodname]#addStyleName()#
using the constants defined in the [classname]#ValoTheme# enum.


----
table.addStyleName(ValoTheme.TABLE_COMPACT);
----

For a complete up-to-date list of component-specific styles, please refer to
Vaadin API documentation on the [classname]#ValoTheme# enum. Some are also
described in the component-specific styling sections.

[[themes.valo.component.disabling]]
=== Disabling Component Styles

Component styles are optional, but all are enabled by default. They can be
enabled on per-component basis with the $v-included-additional-styles parameter.
It defaults to $v-included-components and can be customized in the same way, as
described in <<themes.valo.optimization>>.


[[themes.valo.component.parameters]]
=== Configuration Parameters

The following variables control some common component styles:

$v-scaling-factor--tiny(default:[literal]#++0.75++#):: A scaling multiplier for [literal]#++TINY++# component styles.

$v-scaling-factor--small(default:[literal]#++0.85++#):: A scaling multiplier for [literal]#++SMALL++# component styles.

$v-scaling-factor--large(default:[literal]#++1.2++#):: A scaling multiplier for [literal]#++LARGE++# component styles.

$v-scaling-factor--huge(default:[literal]#++1.6++#):: A scaling multiplier for [literal]#++HUGE++# component styles.





[[themes.valo.optimization]]
== Theme Optimization

Valo theme allows optimizing the size of the compiled theme CSS by including the
rules for only the components actually used in the application. The included
component styles can be specified in the [literal]#++$v-included-components++#
variable, which by default includes all components. The variable should include
a comma-separated list of component names in lower-case letters. Likewise, you
can specify which additional component styles, as described in
<<themes.valo.component>>, should be included using the
$v-included-additional-styles parameter and the same format. The list of
additional styles defaults to $v-included-components.

For example, if your UI contains just [classname]#VerticalLayout#,
[classname]#TextField#, and [classname]#Button# components, you could define the
variable as follows:


----
$v-included-components:
    verticallayout,
    textfield,
    button;
----

You can use the [methodname]#remove()# function reversely to remove just some
component themes from the standard selection.

For example, with the following you can remove the theme definitions for the
[classname]#Calendar# component:


----
$v-included-components: remove($v-included-components, calendar);
----

Note that in this case, you need to give the statement __after__ the
[literal]#++@import++# statement for the Valo theme, because it overrides a
variable by using its value that is defined in the theme.