Merge pull request #3 from devnook/master

Adding icon guide

app.yaml

@@ -167,4 +167,4 @@ skip_files:
 - ^(.*/)?polymer-all/labs/dfreedm/core-icon-study/.*
 - ^(.*/)?polymer-all/labs/.* # don't upload all of labs
 - ^(.*/)?polymer-all/tools/doc/.*
-- ^(.*/)?components/tools/.* # tool is already in /polymer-all
+- ^(.*/)?components/tools/.* # tool is already in /polymer-all

docs/polymer/icons.md

@@ -9,29 +9,218 @@ subtitle: Guide
 
 {% include toc.html %}
 
-{{site.project_title}} provides a standard set of SVG icons (styleable using CSS), elements for working with individual icons, and elements for working with icon sets.
+{{site.project_title}}'s Core Elements provide utility components
+for working with individual icons and icon sets.
 
-TODO
+It includes a standard collection of SVG icons (styleable using CSS) as well as elements to
+create your own icon sets in SVG or bitmap, if needed.
 
-## Basic usage
+## Installation
 
-TODO
+This article describes the usage of four components: `core-icon`,
+`core-icons`, `core-iconset` and `core-iconset-svg`.
+You can install them using Bower:
 
-    <core-icon icon="search"></core-icon>
+    bower install Polymer/core-icon
+    bower install Polymer/core-icons
+    bower install Polymer/core-iconset
+    bower install Polymer/core-iconset-svg
 
-Produces: <core-icon icon="search"></core-icon>
+The rest of this article assumes the components are
+installed in the `bower_components` directory.
 
-## Using an icon set
 
-- loading
-- using
+## Basic usage: core-icon
+
+The simplest way of using Polymer icons is the `core-icon` element.
+To use it, import *core-icon.html* and declare an icon in your html:
+
+    <link rel="import" href="/bower_components/core-icon/core-icon.html">
+
+    <core-icon src="http://www.polymer-project.org/images/icons/android.svg"></core-icon>
+
+Produces: <core-icon src="/images/icons/android.svg"></core-icon>
+
+The source image is scaled to fit the icon size, which defaults to 24px square, and is used as the icon element’s background.
+
+You can control the size of the icon using the `size` attribute. Since icons are always square, the `size` specifies both the width and the height of the icon, in pixels.
+
+
+    <core-icon src="/images/icons/android.svg" size="24"></core-icon>
+    <core-icon src="/images/icons/android.svg" size="32"></core-icon>
+    <core-icon src="/images/icons/android.svg" size="48"></core-icon>
+
+<core-icon src="/images/icons/android.svg" size="24"></core-icon>
+<core-icon src="/images/icons/android.svg" size="32"></core-icon>
+<core-icon src="/images/icons/android.svg" size="48"></core-icon>
+
+The `src` attribute works well when you want to use a single icon. However, most of the time you need more than one, so Polymer makes it easy to work with *icon sets*.
+
+
+## Using Polymer's built-in icon sets
+
+If you import `core-icons`, you get access to
+a whole range of predefined icon sets. To use an icon from an icon set, use the `icon` attribute instead of `src`:
+
+    <link rel="import" href="/bower_components/core-icons/core-icons.html">
+
+    <core-icon icon="polymer"></core-icon>
+
+This loads the *polymer* icon from the default iconset: <core-icon icon="polymer"></core-icon>
+
+In the *iconset* directory
+of `core-icons` you can find more interesting icon sets.
+If the icon is not part of the default icon set, it's name needs to be prefixed with the name of the icon set (e.g. `set:iconname`). For example:
+
+    <core-icon icon="social:cake"></core-icon>
+
+This loads the *cake* icon from the *social* iconset: <core-icon icon="social:cake"></core-icon>
+
+You can browse available icon sets on the
+[core-icons demo page](http://polymer.github.io/core-icons/components/core-icons/demo.html).
+
+## Styling with CSS
+
+Because icons in Polymer iconsets are SVG-based, you can control their appearance
+with CSS. For example, you can set properties like `fill`, `stroke` and `stroke-width` for your icons.
+
+    <style>
+      core-icon[icon="android"] {
+        fill: #9aed00;
+      }
+    </style>
+    <core-icon icon="android" size="32"></core-icon>
+
+<style>
+  core-icon[icon="android"] {
+    fill: #9aed00;
+  }
+</style>
+Produces: <core-icon icon="android" size="32"></core-icon>
+
+## Roll your own
+
+The styling possibilities become even more exciting when you want to make
+your own icon sets. To create a custom icon set with SVG, import and declare
+`core-iconset-svg` in your html. Because SVG is just markup, you can put your
+SVG icons inside the `core-iconset-svg` element as its children.
+
+    <link rel="import" href="../bower_components/core-iconset-svg/core-iconset-svg.html">
+    <core-iconset-svg id="custom-icons" iconSize="50">
+      <svg>
+        <defs>
+          <g id="fancy-circles">
+            <circle cx="25" cy="25" r="18" />
+            <circle cx="12" cy="12" r="10" />
+            <circle cx="35" cy="40" r="6" />
+          </g>
+        </defs>
+      </svg>
+    </core-iconset-svg>
+
+Because the icons are defined as SVG, you can style them with CSS. Let's make
+our fancy circles even more fancy by adding some color:
+
+    <style type="text/css">
+      core-icon circle {
+        fill: #0b50bf;
+      }
+      core-icon circle:first-child {
+        fill: #66bbff;
+      }
+      core-icon circle:last-child {
+        fill: #0083ff;
+      }
+    </style>
+
+Now you can display the icon using `core-icon` by referring to the `id` of the iconset and
+the `id` of a particular icon, joined by a colon. For example, to display the icon
+defined above use `custom-icons:fancy-circles` as `icon` attribute.
+
+    <core-icon icon="custom-icons:fancy-circles" size="30"></core-icon>
+
+<style type="text/css">
+  core-icon circle {
+    fill: #0b50bf;
+  }
+  core-icon circle:first-child {
+    fill: #66bbff;
+  }
+  core-icon circle:last-child {
+    fill: #0083ff;
+  }
+</style>
+<core-iconset-svg id="custom-icons" iconSize="50">
+  <svg>
+    <defs>
+      <g id="fancy-circles">
+        <circle cx="25" cy="25" r="18" />
+        <circle cx="12" cy="12" r="10" />
+        <circle cx="35" cy="40" r="6" />
+      </g>
+    </defs>
+  </svg>
+</core-iconset-svg>
+Tadaa! Here's how your brand new icon looks: <core-icon icon="custom-icons:fancy-circles" size="30"></core-icon>
+
+If you prefer to work with more traditional bitmap graphics like *jpg* or *png*,
+there is also an element for that: `core-iconset`.
+
+Let's say you have a *png* file with your icons:
+
+<a href="/components/core-iconset/my-icons.png" target="_blank">
+  <img src="/components/core-iconset/my-icons.png">
+</a>
+
+You can set the `src` attribute of `core-iconset` to point to this file.
+Icons are expected to be square and of the size specified
+by the `iconSize` property. If the icons are arranged over multiple rows, use the `width`
+attribute to specify the width of the image file. List the name of each icon in the `icons` attribute, in the same order as they appear
+in the image file.
+
+    <core-iconset id="custom-icons-png" src="/components/core-iconset/my-icons.png" width="96" iconSize="24"
+      icons="location place starta stopb bus car train walk">
+    </core-iconset>
+
+Now you can refer to the icon using colon notation:
+
+    <core-icon icon="custom-icons-png:place"></core-icon>
+
+<core-iconset id="custom-icons-png" src="/components/core-iconset/my-icons.png" width="96" iconSize="24"
+  icons="location place starta stopb bus car train walk">
+</core-iconset>
+Produces: <core-icon icon="custom-icons-png:place"></core-icon>
+
+## Icons in other core components
+
+You can use icons on their own, but also use them with other elements, such as buttons. You can use the built-in and custom icon sets with any `core-` element that has an `icon` attribute. Remember to include the appropriate icon set
+before refering to an icon, otherwise the icon
+will not render.
+
+Here is an example of `core-icon-button`, `core-menu-button` and `core-item` using
+icons from the *default* and *av* icon sets:
+
+    <link rel="import" href="/bower_components/core-icons/iconsets/av-icons.html">
+
+    <core-icon-button icon="av:play-arrow"></core-icon-button>
+    <core-menu-button icon="menu">
+      <core-item icon="settings" label="Settings"></core-item>
+    </core-menu-button>
+
+Produces: <core-icon-button icon="av:play-arrow"></core-icon-button>
+<core-menu-button icon="menu">
+  <core-item icon="settings" label="Settings"></core-item>
+</core-menu-button>
+
+## Summary
+
+You just learned how to import Polymer's ready-made icon sets,
+display an icon using the `core-icon` element and style it with CSS. You also learned
+how to create your own icon set using SVG or bitmap images and how to use icons
+from other elements that support this feature.
+
 
-## Icon buttons
 
-- how they differ
-- what they do
 
-## Styling
 
-- how to use `fill` to style the inner SVG
 

elements/common_elements.html

@@ -27,8 +27,15 @@
 <link rel="import" href="../elements/page-scrim.html">
 <link rel="import" href="../elements/dropdown-panel.html">
 
+<link rel="import" href="../components/core-icon/core-icon.html">
+<link rel="import" href="../components/core-icon-button/core-icon-button.html">
 <link rel="import" href="../components/core-icons/core-icons.html">
+<link rel="import" href="../components/core-icons/iconsets/av-icons.html">
 <link rel="import" href="../components/core-icons/iconsets/social-icons.html">
+<link rel="import" href="../components/core-iconset/core-iconset.html">
+<link rel="import" href="../components/core-iconset-svg/core-iconset-svg.html">
+<link rel="import" href="../components/core-item/core-item.html">
+<link rel="import" href="../components/core-menu-button/core-menu-button.html">
 <link rel="import" href="../components/paper-button/paper-button.html">
 
 <!--<link rel="import" href="../components/core-tooltip/core-tooltip.html">-->