diff --git a/core/src/components/icon/readme.md b/core/src/components/icon/readme.md
new file mode 100644
index 0000000000..8bbef3fd45
--- /dev/null
+++ b/core/src/components/icon/readme.md
@@ -0,0 +1,113 @@
+<!-- This file is not generated by Stencil, it is taken from https://github.com/ionic-team/ionicons -->
+
+# ion-icon
+
+Icons can be used on their own as a standalone component, or inside of another component.
+
+Ionicons provide platform continuity out of the box in Ionic by rendering a different icon based on the device the app is running on. For example, by setting the icon `name` to `alarm` the icon will automatically use the `ios-alarm` on an iOS device, and the `md-alarm` for any device running Material Design. This allows the developer to write the markup once while Ionic handles displaying the appropriate icon based on the mode.
+
+For a full list of available icons and more usage explanations, check out the [Ionicons documentation](https://ionicons.com/).
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+#### ariaLabel
+
+string
+
+Specifies the label to use for accessibility. Defaults to the icon name.
+
+
+#### color
+
+string
+
+The color to use from your Sass `$colors` map.
+Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+For more information, see [Theming your App](/docs/theming/theming-your-app).
+
+
+#### ios
+
+string
+
+Specifies which icon to use on `ios` mode.
+
+
+#### md
+
+string
+
+Specifies which icon to use on `md` mode.
+
+
+#### name
+
+string
+
+Specifies which icon to use. The appropriate icon will be used based on the mode.
+For more information, see [Ionicons](/docs/ionicons/).
+
+
+#### size
+
+string
+
+The size of the icon.
+Available options are: `"small"` and `"large"`.
+
+
+## Attributes
+
+#### aria-label
+
+string
+
+Specifies the label to use for accessibility. Defaults to the icon name.
+
+
+#### color
+
+string
+
+The color to use from your Sass `$colors` map.
+Default options are: `"primary"`, `"secondary"`, `"danger"`, `"light"`, and `"dark"`.
+For more information, see [Theming your App](/docs/theming/theming-your-app).
+
+
+#### ios
+
+string
+
+Specifies which icon to use on `ios` mode.
+
+
+#### md
+
+string
+
+Specifies which icon to use on `md` mode.
+
+
+#### name
+
+string
+
+Specifies which icon to use. The appropriate icon will be used based on the mode.
+For more information, see [Ionicons](/docs/ionicons/).
+
+
+#### size
+
+string
+
+The size of the icon.
+Available options are: `"small"` and `"large"`.
+
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*
diff --git a/core/src/components/icon/usage/javascript.md b/core/src/components/icon/usage/javascript.md
new file mode 100644
index 0000000000..8737eafdfe
--- /dev/null
+++ b/core/src/components/icon/usage/javascript.md
@@ -0,0 +1,18 @@
+```html
+<!-- automatically uses the correct "star" icon depending on the mode -->
+<ion-icon name="star"></ion-icon>
+
+<!-- explicity set the icon for each mode -->
+<ion-icon ios="ios-home" md="md-home"></ion-icon>
+
+<!-- always use the same icon, no matter what the mode is -->
+<ion-icon name="ios-clock"></ion-icon>
+<ion-icon name="logo-twitter"></ion-icon>
+
+<!-- use a custom svg icon -->
+<ion-icon src="/path/to/external/file.svg"></ion-icon>
+
+<!-- set the icon size -->
+<ion-icon size="small" name="heart"></ion-icon>
+<ion-icon size="large" name="heart"></ion-icon>
+```