Polymer · addyosmani · Aug 27, 2015 · Aug 24, 2015 · Aug 25, 2015
diff --git a/README.md b/README.md
@@ -102,12 +102,38 @@ gulp
 
 Build and optimize the current project, ready for deployment. This includes linting as well as vulcanization, image, script, stylesheet and HTML optimization and minification.
 
-## Application Theming
+## Application Theming & Styling
 
 Polymer 1.0 introduces a shim for CSS custom properties. We take advantage of this in `app/styles/app-theme.html` to provide theming for your application. You can also find our presets for Material Design breakpoints in this file.
 
 [Read more](https://www.polymer-project.org/1.0/docs/devguide/styling.html) about CSS custom properties.
 
+### Styling
+1. ***main.css*** - to define styles that can be applied outside of Polymer's custom CSS properties implementation. Some of the use-cases include defining styles that you want to be applied for a splash screen, styles for your application 'shell' before it gets upgraded using Polymer or critical style blocks that you want parsed before your elements are.
+2. ***app-theme.html*** - to provide theming for your application. You can also find our presets for Material Design breakpoints in this file.
+3. ***shared-styles.html*** - to shared styles between elements and index.html.
+4. ***element styles only*** - styles specific to element. These styles should be inside the `<style></style>` inside `template`.
+
+  ```HTML
+  <dom-module id="my-list">
+    <template>
+      <style>
+        :host {
+          display: block;
+          background-color: yellow;
+        }
+      </style>
+      <ul>
+        <template is="dom-repeat" items="{{items}}">
+          <li><span class="paper-font-body1">{{item}}</span></li>
+        </template>
+      </ul>
+    </template>
+  </dom-module>
+  ```
+
+These style files are located in the [styles folder](app/styles/).
+
 ## Unit Testing
 
 Web apps built with Polymer Starter Kit come configured with support for [Web Component Tester](https://github.com/Polymer/web-component-tester) - Polymer's preferred tool for authoring and running unit tests. This makes testing your element based applications a pleasant experience.

diff --git a/app/elements/elements.html b/app/elements/elements.html
@@ -36,5 +36,6 @@
 
 <!-- Add your elements here -->
 <link rel="import" href="../styles/app-theme.html">
+<link rel="import" href="../styles/shared-styles.html">
 <link rel="import" href="my-greeting/my-greeting.html">
 <link rel="import" href="my-list/my-list.html">
diff --git a/app/elements/my-greeting/my-greeting.html b/app/elements/my-greeting/my-greeting.html
@@ -10,20 +10,11 @@
 
 <dom-module id="my-greeting">
   <template>
+    <style include="shared-styles"></style>
     <style>
       :host {
         display: block;
       }
-
-      .page-title {
-        @apply(--paper-font-display2);
-      }
-
-      @media (max-width: 600px) {
-        .page-title {
-          font-size: 24px!important;
-        }
-      }
     </style>
     <h2 class="page-title"><span>{{greeting}}</span></h2>
     <span class="paper-font-body2">Update text to change the greeting.</span>
@@ -48,4 +39,3 @@ <h2 class="page-title"><span>{{greeting}}</span></h2>
   </script>
 
 </dom-module>
-greeting
diff --git a/app/index.html b/app/index.html
@@ -53,6 +53,10 @@
   <!-- will be replaced with elements/elements.vulcanized.html -->
   <link rel="import" href="elements/elements.html">
   <!-- endreplace-->
+
+  <!-- For shared styles, shared-styles.html import in elements.html -->
+  <style is="custom-style" include="shared-styles"></style>
+
 </head>
 
 <body unresolved class="fullbleed layout vertical">

diff --git a/app/styles/app-theme.html b/app/styles/app-theme.html
@@ -127,10 +127,6 @@
     height: 900px;
   }
 
-  .page-title {
-    @apply(--paper-font-display2);
-  }
-
   /* Breakpoints */
 
   /* Small */
@@ -160,10 +156,6 @@
       background: white;
     }
 
-    .page-title {
-      font-size: 24px;
-    }
-
   }
 
   /* Tablet+ */

diff --git a/app/styles/shared-styles.html b/app/styles/shared-styles.html
@@ -0,0 +1,16 @@
+<!-- shared styles for all elements and index.html -->
+<dom-module id="shared-styles">
+  <template>
+    <style>
+      .page-title {
+        @apply(--paper-font-display2);
+      }
+
+      @media (max-width: 600px) {
+        .page-title {
+          font-size: 24px!important;
+        }
+      }
+    </style>
+  </template>
+</dom-module>