123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440 |
- ---
- 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, as described in
- <<dummy/../../../framework/components/components-fields#components.fields.field,"Field
- Interface">>.
-
-
-
- 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.
-
-
-
|