diff --git a/source/_docs/frontend.markdown b/source/_docs/frontend.markdown index e9c6173a870..b6e4d76865c 100644 --- a/source/_docs/frontend.markdown +++ b/source/_docs/frontend.markdown @@ -3,12 +3,23 @@ title: "Frontend of Home Assistant" description: "Frontend of Home Assistant." --- -The frontend of Home Assistant is built with [Polymer](https://www.polymer-project.org/). +The Home Assistant frontend allows users to browse and control the state of their house, manage their automations and configure integrations. +The frontend is built with [Polymer](https://www.polymer-project.org/).

- +

-The [User Interface section](/examples/#user-interface) can give you some starting points to expand the frontend. +
-If you want to work on the frontend, please refer to the [Frontend Development documentation](/developers/frontend/). + If you're looking to contribute to the frontend, please refer to the [Frontend Development documentation](/developers/frontend/). + +
+ +## Icons + +Home Assistant utilizes the community-driven [Material Design Icons](https://www.materialdesignicons.com/) project for icons in the frontend. The [Icons section](/docs/frontend/icons/) has more information on how to use icons and suggest new ones. + +## Examples + +The [User Interface section](/examples/#user-interface) can give you some starting points to expand the frontend. diff --git a/source/_docs/frontend/icons.markdown b/source/_docs/frontend/icons.markdown new file mode 100644 index 00000000000..303813381a1 --- /dev/null +++ b/source/_docs/frontend/icons.markdown @@ -0,0 +1,84 @@ +--- +title: "Icons" +description: "Material Design Icons in the Home Assistant frontend" +--- + +

+ Material Design Icons +

+ +Home Assistant utilizes the community-driven [Material Design Icons](https://www.materialdesignicons.com/) (MDI) project for icons in the frontend. The icon library is a superset of the base icon library provided by Google and contains thousands of community-made icons for very specific applications, industries, and use-cases. + +## Default Icons + +Every entity in Home Assistant has a default icon assigned to it. There are way too many to list out here, but you'll see them in your dashboard. You can [customize any of your entities](/docs/configuration/customizing-devices/#icon) to change the icons displayed to you. + +## Finding Icons + +### Icon Picker + +The most common way you can find icons is by using the icon picker built right into Home Assistant. Click into the "Icon" field when customizing an entity and start typing. The list will filter to icons that match your search criteria. You can also scroll through all available icons when the field is empty. + +

+ Icon Picker in Home Assistant +

+ +
+ + The icon picker will filter by icon name and by aliases applied to the icon by the MDI project. For example, typing "user" will show you most "account"-named icons. + +
+ +### Material Design Icons Picker Browser Extension + +The easiest way to browse and find icons outside of Home Assistant is with the official [Material Design Icons Picker](https://github.com/Pictogrammers/MaterialDesignIcons-Picker) browser extension. The extension is available for Chrome, Firefox, and Edge and is maintained by the MDI team. + +

+ Material Design Icons Picker +

+ +
+ + Not all icons that appear in the MDI Picker Browser Extension may be available in Home Assistant (yet!). While the browser extension is updated as MDI releases new packages, Home Assistant may lag behind until its next release. + +
+ +### MaterialDesignIcons.com + +The last way to browse through available icons is on the official website, [MaterialDesignIcons.com](https://materialdesignicons.com). + +
+ + The official MDI website is updated in real-time as new icons are added. This means an icon you find there may not yet be released or available in Home Assistant (yet!) for several releases. You can check when an icon was added by viewing the [MDI history](https://materialdesignicons.com/history). + +
+ +## Suggesting or Contributing New Icons + +Being open-source like Home Assistant, the Material Design Icons project is always accepting suggestions and contributions to expand the library. + +
+ + Before suggesting or creating a new icon, it is very important that you [search the current library](https://materialdesignicons.com) and [search all issues](https://github.com/Templarian/MaterialDesign/issues?q=is%3Aissue), open and closed, on their GitHub. Try searching with different terms that might mean the same thing. (e.g. "user", "person", "account") + +
+ +### Suggesting a New Icon + +If you have an idea for an icon that isn't currently in the library, but are not interested in creating it yourself, [open a new icon suggestion](https://github.com/Templarian/MaterialDesign/issues/new?assignees=&labels=Icon+Request&template=1_icon_request.yml). + +### Contributing a New Icon + +If you want to contribute a new icon to the library, familiarize yourself with the [System icons guidelines](https://material.io/design/iconography/system-icons.html#design-principles) in the Material Design system. Then create your icon and [submit it to the MDI team for review](https://github.com/Templarian/MaterialDesign/issues/new?assignees=&labels=Icon+Request%2CContribution&template=2_contribution.yml). + +#### Tips for Creating New Icons + +- Really pay attention to [Material Design guidelines](https://material.io/design/iconography/system-icons.html#design-principles). +- Keep in mind that icons are meant to be contextual, not literal. +- When it comes to little details, less is more. +- If you're unsure, open an issue with MDI. They're more than happy to help you! +- Not all icons make it into the library and that is okay! + +### Suggesting an Icon Alias + +Sometimes an icon exists, but you aren't able to find it with the terms you were searching for. If this has ever happened to you, please [open an issue with the MDI team to suggest new aliases](https://github.com/Templarian/MaterialDesign/issues/new?assignees=&labels=Alias&template=4_alias.yml) that can be added to existing icons. diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index 8006ed7863f..7fa5b627746 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -123,6 +123,7 @@ %}
  • {% active_link /dashboards Dashboards %}
    • +
  • {% active_link /docs/frontend/icons/ Icons%}
  • diff --git a/source/images/frontend/mdi.png b/source/images/frontend/mdi.png new file mode 100644 index 00000000000..a837a223584 Binary files /dev/null and b/source/images/frontend/mdi.png differ diff --git a/source/images/frontend/ui2022.png b/source/images/frontend/ui2022.png new file mode 100644 index 00000000000..3fb01797c6a Binary files /dev/null and b/source/images/frontend/ui2022.png differ diff --git a/source/images/screenshots/icon-picker.png b/source/images/screenshots/icon-picker.png new file mode 100644 index 00000000000..4540207875f Binary files /dev/null and b/source/images/screenshots/icon-picker.png differ diff --git a/source/images/screenshots/mdi-picker.png b/source/images/screenshots/mdi-picker.png new file mode 100644 index 00000000000..c27d6fdd6e1 Binary files /dev/null and b/source/images/screenshots/mdi-picker.png differ