1 files changed, 85 insertions, 0 deletions
diff --git a/documentation/themes/themes-fonts.asciidoc b/documentation/themes/themes-fonts.asciidoc
new file mode 100644
index 0000000000..741fb00a72
--- /dev/null
+++ b/documentation/themes/themes-fonts.asciidoc
@@ -0,0 +1,85 @@
+---
+title: Custom Fonts
+order: 9
+layout: page
+---
+
+[[themes.fonts]]
+= Custom Fonts
+
+In addition to using the built-in fonts of the browser and the web fonts
+included in the Vaadin themes, you can use custom web fonts.
+
+[[themes.fonts.loading]]
+== Loading Local Fonts
+
+You can load locally served web fonts with the [literal]#++font++# mixin as
+follows:
+
+
+----
+@include font(MyFontFamily,
+              '../../mytheme/fonts/myfontfamily');
+----
+
+The statement must be given in the [filename]#styles.scss# file __outside__ the
+[literal]#++.mytheme {}++# block.
+
+The first parameter is the name of the font family, which is used to identify
+the font. If the font family name contains spaces, you need to use single or
+double quotes around the name.
+
+The second parameter is the base name of the font files without an extension,
+including a relative path. Notice that the path is relative to the base theme,
+where the mixin is defined, not the used theme. We recommend placing custom font
+files under a [filename]#fonts# folder in a theme.
+
+Not all browsers support any single font file format, so the base name is
+appended with [filename]#.ttf#, [filename]#.eot#, [filename]#.woff#, or
+[filename]#.svg# suffix for the font file suitable for a user's browser.
+
+
+[[themes.fonts.webfonts]]
+== Loading Web Fonts
+
+You can load externally served web fonts such as Google Fonts simply by
+specifying the loading stylesheet for the UI with the [classname]#@StyleSheet#
+annotation.
+
+For example, to load the "Cabin Sketch" font from Google Fonts:
+
+[subs="normal"]
+----
+@StyleSheet({"[replaceable]#http://fonts.googleapis.com/css?family=Cabin+Sketch#"})
+public class MyUI extends UI {
+    ...
+----
+ifdef::web[]
+Note that such web fonts served from a domain different from the Vaadin
+application currently link:https://dev.vaadin.com/ticket/16249[do not work
+together with] responsive themes, as described in
+<<dummy/../../../framework/themes/themes-responsive#themes.responsive,"Responsive
+Themes">>. The problem occurs only in Firefox. A SecurityError is shown in the
+debug window.
+endif::web[]
+
+
+[[themes.fonts.using]]
+== Using Custom Fonts
+
+After loaded, you can use a custom font, or actually font family, by its name in
+CSS and otherwise.
+
+
+----
+.mystyle {
+    font-family: MyFontFamily;
+}
+----
+
+Again, if the font family name contains spaces, you need to use single or double
+quotes around the name.
+
+
+
+