1 files changed, 77 insertions, 0 deletions
diff --git a/documentation/themes/themes-overview.asciidoc b/documentation/themes/themes-overview.asciidoc
new file mode 100644
index 0000000000..05005ab83b
--- /dev/null
+++ b/documentation/themes/themes-overview.asciidoc
@@ -0,0 +1,77 @@
+---
+title: Overview
+order: 1
+layout: page
+---
+
+[[themes.overview]]
+= Overview
+
+Vaadin separates the appearance of the user interface from its logic using
+__themes__. Themes can include Sass or CSS style sheets, custom HTML layouts,
+and any necessary graphics. Theme resources can also be accessed from
+application code as [classname]#ThemeResource# objects.
+
+Custom themes are placed under the [filename]#VAADIN/themes/# folder of the web
+application (under [filename]#WebContent# in Eclipse or
+[filename]#src/main/webapp# in Maven projects). This location is fixed -- the
+[filename]#VAADIN# folder contains static resources that are served by the
+Vaadin servlet. The servlet augments the files stored in the folder by resources
+found from corresponding [filename]#VAADIN# folders contained in JARs in the
+class path. For example, the built-in themes are stored in the
+[filename]#vaadin-themes.jar#.
+
+<<figure.themes.theme-contents>> illustrates the contents of a theme.
+
+[[figure.themes.theme-contents]]
+.Contents of a Theme
+image::img/theme-contents-hi.png[]
+
+The name of a theme folder defines the name of the theme. The name is used in
+the [literal]#++@Theme++# annotation that sets the theme. A theme must contain
+either a [filename]#styles.scss# for Sass themes, or [filename]#styles.css#
+stylesheet for plain CSS themes, but other contents have free naming. We
+recommend that you have the actual theme content in a SCSS file named after the
+theme, such as [filename]#mytheme.scss#, to make the names more unique.
+
+We also suggest a convention for naming the folders as [filename]#img# for
+images, [filename]#layouts# for custom layouts, and [filename]#css# for
+additional stylesheets.
+
+Custom themes need to extend a base theme, as described in
+<<dummy/../../../framework/themes/themes-creating#themes.creating,"Creating and
+Using Themes">>. Copying and modifying an existing theme is also possible, but
+it is not recommended, as it may need more work to maintain if the modifications
+are small.
+
+You use a theme by specifying it with the [literal]#++@Theme++# annotation for
+the UI class of the application as follows:
+
+
+[source, java]
+----
+@Theme("mytheme")
+public class MyUI extends UI {
+    @Override
+    protected void init(VaadinRequest request) {
+        ...
+    }
+}
+----
+
+A theme can contain alternate styles for user interface components, which can be
+changed as needed.
+
+In addition to style sheets, a theme can contain HTML templates for custom
+layouts used with [classname]#CustomLayout#. See
+<<dummy/../../../framework/layout/layout-customlayout#layout.customlayout,"Custom
+Layouts">> for details.
+
+Resources provided in a theme can also be accessed using the
+[classname]#ThemeResource# class, as described in
+<<dummy/../../../framework/application/application-resources#application.resources.theme,"Theme
+Resources">>. This allows displaying theme resources in component icons, in the
+[classname]#Image# component, and other such uses.
+
+
+