Here's some in-depth UI / UX feedback on the current Integrations section of Home Assistant 0.92.2.

This took a long time to put together so hopefully there's some solid feedback and suggestions in here. While I'm sure some of these issues are known already, I also offered potential suggestions and mockups on how to improve things. It always helps to have a second pair of eyes when it comes to UI things.

In order to make Home Assistant truly user friendly and accessible to the masses (as well as attracting official partners), I think it's very important to really nail the experience of adding and configuring integrations through the UI. Currently the foundation seems to be in place, but there's lots of areas for improvement and polish.

Initial View: Configured Integrations

1. The first problem is that integrations do not appear to be organized in any way. The user would expect them to be either listed alphabetically, sorted by popularity, or grouped together by type (Philips Hue and LIFX under a "Lights" category), but none of these are the case right now.

2. Almost all integrations have duplicate wording in their names, for example Google Cast: Google Cast. I suspect it's intended to be Integration Name: Device Name but in 99% of cases this seems to be the same exact thing, and it looks very weird and confusing. Proposal: hide the device name if it's identical to the integration name.

   1. Side note: if you happen to have MQTT: configuration.yaml Integration and then click on it, look at the subpage heading in the blue bar - it'll say just configuration.yaml which again looks very weird.

3. For integrations with no devices, such as IFTTT Webhook for example, you simply get an empty page that displays a This integration has no devices message when clicked on, and user then wonders why they were even allowed to click on a rather useless page. (Note: I know the delete integration button is located on this page, so it's not 100% useless, but this can still be improved somehow).

4. Displaying devices in this view serves little purpose.

   1. An icon-oriented view is not particularly helpful in distinguishing items, because the icons can be the same more often than not (especially for new users who haven't customized their entities yet). My Google Cast integration shows that I have 7 cast devices, but they all have identical icons. Which brings me to the next point.
   2. The only way to truly tell these devices apart is to hover over each tiny individual icon and wait for a tiny tooltip to appear. This takes considerably longer than simply going to the device overview page where you can quickly read everything in a second (thanks to larger font and better layout).
   3. The device overview page is laid out in a far superior way and has more features to boot (like being able to assign areas for instance). The interface should be directing users to this far more helpful area, rather than wasting their time hovering over tooltips (which when clicked on ultimately brings them to the same device overview page anyway, just with a more-info window on top of it). See this comparison of the two.
   4. Sometimes these tooltips appear inside of the table cell or something, see this image of my Z-Wave setup. All of my Z-Wave stuff has the generic eye icon, and I can read zero tooltips when hovering for some reason.
   5. Experience on mobile is even worse, because you don't even have hover/tooltips on a touch screen device obviously. Now depending on where the user taps, they get taken to the more-info view of a random device rather than the device overview page they almost were almost certainly expecting. Here is an annotated image demonstrating that there's up to 13 tap targets on one row, which is kind of insane. Mobile users are used to tapping anywhere on the row, but this turns it into a minefield where you have to be careful of where you tap.
   6. Lastly, this is a more minor thing, but it can look bad and visually inconsistent when some items have 20 icons (Hue) and another right next to it (IFTTT) has 0. Makes it look like one failed to be setup properly.

Proposal: Don't display devices here. It offers practically no value and just introduces problems. Getting rid of it makes the UI look cleaner, is more simple and consistent for users, and gets them to the page they want faster.

---

Adding Integrations

1. While the orange circular plus button in the bottom corner looks fine on mobile, it's not ideal on desktop browsers. Being anchored to the bottom right corner of the screen means it can be very easy to miss on desktop, especially with larger browser widths. See this annotated image demonstrating the issue.

2. I also discovered a potential issue where poorly designed themes can make this button even harder to find. Take a look at this screenshot on the solarized_dark theme (theme link) for example. Admittedly this was the only theme out of the dozens I tested that exhibited this behavior, but thought it was worth mentioning, because ideally a theme should not be able to make a crucial UI element like this nearly invisible.

3. Because the official iOS and upcoming Android mobile apps uses pull to refresh, and the bottom list doesn't have scroll bar, user could want to be scrolling up to the very top of the list and accidentally invoke a pull to refresh which takes them to the Lovelace default view. This is a little hard to explain but hopefully this screenshot demonstrates what I mean. You can see the pull to refresh spinner at the top of the page when I was just trying to scroll to the top of the list.

4. But the biggest issue with this design is that it hinders discoverability. You cannot see which integrations are available until clicking this button, which has no label or anything. People are going to think "I don't want to install or add anything, just browse."

Proposal: There's a very simple solution that solves all four of these problems: just make it a standard tab bar at the top of the screen, similar to the Hass.io panel. There would be two clearly defined sections - "Configured" and "Available". No confusion, right at the top of the screen and hard to miss, UI looks nice on both mobile and desktop, and as a bonus it's also consistent with an already familiar area.

---

Integrations Overview Page

This below screenshot I think demonstrates a couple issues with the current design of the overview / device management page.

1. Much like the + button for adding integrations, this trash can icon in the top right corner for deleting integrations might work okay on mobile devices with smaller widths, but it just doesn't feel right on desktop browsers. It's super easy to miss.

   1. The delete prompt could be improved - instead of the generic Are you sure you want to delete this integration? message, display the integration name inside of the delete prompt. "Are you sure you want to delete the Google Cast integration?" makes the users action a lot more clear.
   2. Also on the delete prompt, change the "OK" button to a "Delete" button to more clearly communicate to the user which action will be performed.

2. The first listing for Hassapp is an app that I tried briefly for like 30 minutes and decided it wasn't for me. But I cannot remove it from here since there's no way to get rid of individual devices. It appears that I can navigate to the Entity Registry page and delete the two sensors from there, but why not here?

3. Next issue is that there's no way to see when a device was added. You can see I have duplicates here, but there's no easy way to tell them apart because even the firmware version is identical. Displaying something like "Added Feb 12, 2018" would help. And this goes back to the above issue - even if I determined which one to get rid of, there's no way to do it on this page.

4. These are mobile devices, so there is no point in displaying the "Area" dropdown for them. Instead, you should be able to assign mobile devices to a Person. In this example, if I were to assign "Sean's iPhone XS" to myself, my person.sean entry would be updated with device_tracker.seans_iphone_xs.

5. This is more of a nice-to-have suggestion rather than an issue, but it would be great if the firmware info linked to a release notes page when available. For example the Hue firmware would have a clickable link like Firmware: 1.46.13_r26312 and the PS4 integration would be Firmware: 6.5.1. Making this info easily accessible to users would allow for better more detailed bug reports etc.

6. There appears to be a fixed card height, so on integrations with a single device yet lots of sensors (the new Home Assistant 2.0 mobile app for example), you see just the first four sensors, even though there's tons of vertical space. Here's a desktop screenshot and a mobile screenshot. iOS hides the scroll bars until actively scrolling, so there's no indication that can even be scrolled.

---

Config Flows

Once the user finds the integration they want, they arrive on the config flow... All of which are inconsistent from one another and usually lacking even the most basic of info (such as the integrations name). The inconsistency makes sense since these are all from different contributors, but it shouldn't feel that way to the user. See below for the problems and some suggested solutions.

Example #1 - Ambient PWS

Not trying to single out this integration or anything, it was simply the very first one on the list, so I'm using this as an example. The issues I'm about to point out here apply to almost every currently available integration.

• No way to back out - There's no back button, no cancel button, no close / X button. The user either needs to know how to hit the escape key or how to click off the screen. This might be obvious to nerds like us, but not to a lot of less tech savvy folks.
• No intro - what is this integration? What does it do and how would it benefit me? There's literally zero information presented to the user, beyond a generic title, two text fields, and a submit button.
• No title - "Fill in your information" is a very poor heading.
  • If I accidentally clicked on this when I meant to click on the integration above or beneath it, how do I tell I made a mistake if there's no heading? Example: Jack wants to set up his Arlo integration but unknowingly clicks Ambient PWS instead. Now he's entering his Arlo API key on this screen and wondering why it's not working.
  • Imagine a scenario where user is attempting to set up integration but gets a phone call, comes back to their computer later in the day. Would they remember what integration this was and what they were setting up?
• No helpful info - There's an API key field, but where do I obtain an API key? The Ambient Weather Station Sensor docs provide help, why not here? This is supposed to be the easy setup method!

Example #2 - Zones

Note: Pretty much everything from the above example also applies to this integration as well.

1. This UI asks for Latitude and Longitude coordinates but nobody would know this off the top of their head, and there's nothing here to help the user obtain that information. So already on just the second text field they have to start Googling for how to fill out this UI. The Zone documentation has helpful information, but not here.

2. User has now figured out the Latitude and Longitude coordinates with help from Google, but now they're stumped on the Radius field which is even harder to figure out. What do you type here? What's the unit of measurement - feet, yards, meters, miles? Who knows. You can see in this second image I typed in 100 yards and got an error (more on this shortly). Radius has a default value of 100 according to the documentation, but user would never know that because it's not pre-filled with placeholder text. Can easily solve this particular issue by making the field text "Radius in yards" and having "100" as placeholder text.

3. Same thing goes for the icon. What is the field expecting me to type? Does it want a true/false value? How on earth is the user supposed to know that it wants a value like mdi:home? We know this as existing HA users, but new users wouldn't have a clue and this has to be designed for them too.

4. Bad error handling. In this integration there's only one error type of User input malformed which is unhelpful. This error doesn't appear next to the form where I made the mistake, so I have to guess which of the five fields it was. It says that something is wrong but doesn't give any tips on how to correct it. And it only appears after I press submit, rather than checking for errors as I typed into the field. It should say something like "Error: Radius must be a numeric value only."

5. Passive checkbox, what does this do? It doesn't describe anything here. I am a pretty long time user of Home Assistant with over two dozen zones and even I have never used this option before. The UI doesn't need to match the YAML syntax 100%, don't be afraid to rename this checkbox to something more descriptive like "Don't Display in Frontend" or whatever.

The user interface is supposed to make things easier to set up than using YAML and text editors, but in this case it doesn't. Five of the six options here required the user to either perform Google searches or completely guess how to enter the data because there wasn't any descriptive text, placeholder text in the fields, no link to documentation, nothing at all that would assist the user. Most people would simply give up rather than jumping through those hoops.

Here are some other recurring issues.

"Only a single instance is necessary"

The majority of integrations seem to return this error. If the user sets up an integration that only supports a single instance, that integration should then not be shown under the "Set up a new integration" section until it's first removed. What is even the point of displaying something that only leads to a frustrating error when clicked?

Noticed this on: Google Cast, Geofency Webhook, IFTTT webhook, Home Assistant iOS, MQTT, OwnTracks. Basically every single one of my integrations besides PS4.

Lack of GPS location

The Portuguese weather service (IPMA) integration pre-fills the config flow with the latitude and longitude values of the users home zone, which is great and very convenient! This is the entire point of Integrations, to set users up easily with a few clicks.

But unfortunately no other integration that asks for latitude/longitude seems to support this user-friendly default. Not OpenUV, not Swedish weather service (SMHI), not Zone either. This is something that should be figured out. Ideally there should be one of those GPS locator buttons that can pre-fill your current coordinates.

Improving Config Flow

Now that I've identified a bunch of issues, let's recap some things that need to be addressed and make a sort of UI style guide for contributors in the process.

• Every integration must have a brief intro explaining what it does. This can be copied and pasted from the components/documentation page, but it needs to be here as the first screen before the user presses continue button. This could have a potential additional benefit - if there is background tasks happening (such as scanning network for devices) while the user is reading intro text, it can speed things up when the user is ready to move on to the next step.

• Every integration must display name in heading. Instead of "Fill in your information" the heading should be something like "SimpliSafe Setup" or "Integrate SimpliSafe with Home Assistant" for example. This information is found in manifest.json so it would be easy to force this, at least for the intro screen.

• Every integration must display a documentation link on this setup screen at all times. This information is found in manifest.json so it should be possible to force this and update every integration with this?

• Every integration must have a cancel button so the user is aware they can back out for whatever reason (not meeting the requirements, not feeling comfortable entering certain login information, whatever). Also if the user has proceeded past the intro screen, make the cancel button shows some kind of "Are you sure you wish to cancel?" prompt to prevent any accidental cancellations.

• Every location based integration should have a location button to easily pre-fill the fields with current coordinates.

• Enforce a style guide for commonly used words and phrases so that all integrations feel on the same page and consistent. A login form shouldn't be titled a dozen different ways. For example, right now there's Authenticate against (TelldusLive), Fill in your information (Ambient PWS, OpenUV, RainMachine, SimpliSafe), Set up device (Axis), Login (Google Hangouts) etc. Some integrations use E-Mail while others use Email.

• More descriptive buttons. Everything right now is just a "Submit" button regardless of context. More descriptive buttons should be used depending on what task the config flow is doing - Continue, Log in, Connect to Device, Finish Setup, etc.

• Much better error handling. Perform validation of each field as the user types, throw red error text underneath the specific text field that is invalid. There should be a couple re-usable classes that contributors can use. One that checks if the value is numeric, letters, a URL, etc.

• Have Steppers so that user knows exactly what step they're on and how much is left (thx to iantrich for floating that idea).

• All fields should be designated "Optional" or "Required" so the user never has to guess or become frustrated when they leave a field blank and then get an error.

• Allow password managers to work here. Most of these config flows ask for a username and password, but because password managers do not work at all in Home Assistant (part of a larger issue it seems) the user has to leave the config, find their password, copy and paste it in. It breaks up the flow.

Example

Here's a mockup of how the initial introduction screen might look, using the above Example #1 (Ambient PWS). This was done pretty quickly and isn't perfect, but I think it's a major improvement.

The heading has a clear action associated with it, there's a nice logo which makes it feel far more professional, and in just one sentence the introductory text gives a clear description of what the integration does and the benefit it provides (while also mentioning in a natural way that a hardware accessory is required for setup). The bottom area contains a link to the integrations documentation, a cancel button so the user can back out, and a Get Started button if they wish to continue.

It would be great if Home Assistant could do the framework of this UI (on this intro screen at least), and contributors would only have to worry about the intro text. This would ensure a level of consistency amongst all integrations that wouldn't be possible otherwise. The documentation link would always be in the same familiar place, everything would have a cancel button, the headings would be the same, etc. Name and Documentation link are both in the manifest.json file so the info is already there.

Integrations Reimagined

This mockup has the following improvements that were identified above.

• Icons allow the user to easily scan the page and identify an integration without reading.
  • If an integration does not specify path to an icon image, the card would use a default fallback icon for that particular category type. For example Lighting category would be mdi:lightbulb-outline, Weather category would be mdi:weather-snowy-rainy etc. Here is a mockup image showing an integration with an icon and one without. This ensures a consistent look and feel, rather than displaying a blank area or no image.
  • These icons would be hosted on home-assistant.io CDN only, no external image hosts allowed.
• Intro text is displayed describing exactly what the integration does and how it benefits the user.
  • This makes a huge difference in discoverability. In previous design when you could only read the integration name RainMachine you might assume it's one of those white noise machines that plays rain sounds to help you fall asleep. But now thanks to the intro text you know that it's actually a smart Wi-Fi sprinkler.
  • What I just mentioned above attracts official partners. I was not even aware of that product category before, now I know of a company that makes one and that has Home Assistant support.
  • Intro text can save time and frustration too. For example in the Geofency example text I wrote it mentions "iOS only" so Android users know not to waste their time trying to configure it, since the required app simply isn't available on their platform.
  • Would like this to have a strict character limit. No truncated / cut off text.
• Categories
  • This idea is aimed at bringing parity with the Home Assistant Components page inside Home Assistant itself.
  • User would be able to filter the view by category to only show Lighting integrations, or only show Weather integrations etc.
  • Integrations could appear in more than one category, for example Belkin WeMo would fall under both Hub and Switch categories, or the iOS app might fall under both a Presence Detection and Mobile App category.
    • To prevent the card from getting too cluttered it would only display one category at a time. For example when first browsing for Integrations, the SmartThings card would display Category: Hub (its primary category) but if you filter the view to the Switch category, the SmartThings card would display Category: Switch (one of that integrations secondary categories) instead to match the users active category/view. This is how it works on the Components page already.
  • As mentioned above each category would have a unique default icon, so if the integration doesn't specify an icon it would display a generic light bulb or weather icon.
• Appearance
  • Every card has a consistent size and appearance, because it eliminates unnecessary clutter like device icons and only focuses on the essentials.
  • Design takes advantage of the full width of users screen. Current design is mobile-optimized and shows a tiny in the middle of the screen. This would still work perfectly fine on mobile but also look way better on desktop.
  • Re-usable design. Could be used in Hass.io add-ons section so everything is a consistent style. Could be used in a potential future custom cards gallery or themes gallery. Could be used to make the Lovelace "Add New Card" popup screen a lot nicer looking. It scales well to where you could put it in scrollable sidebar for example.
• Not in Mockup (note: this mockup was made several months ago)
  • Any upcoming official partner integrations (as mentioned in the "Update from the Field" blog post) could have a verified checkmark similar to Twitter, or some kind of badge in one of the corners of the card.
    • Further in the future, perhaps official partners could get a customized device overview page too. Links to their official website and socials, support page, store, etc.
  • As mentioned in the "Adding Integrations" section above, instead of the orange plus button there'd be a tab bar at the top of this page with two clearly defined sections - Configured and Available. You could potentially do some neat things with that type of design. For example when new integrations are added, display a "NEW" text or some kind of numbered badge next to the Available tab to let user know 5 new integrations were added in this latest version / since user last clicked.
  • The "Available" / Integration Store area would be sorted by popularity or a curated "Featured" section would be shown first, similar to the Featured Components page. This makes it easy for users to find and set up the most popular integrations.
  • On the "Available" tab there would be a search bar and some dropdown menus or something to filter the results by category or whatever. As currently there's only 3 or 4 dozen integrations I don't think this is needed right away.

Updated Mockups

Mobile mockup:

Integrated Search and Category Filter:

This one was put together quickly so is kinda sloppy/rough, but it shows an example of the search field and category filter directly inside of the content area (rather than up in the top app bar / blue header area). Having it in the top app bar looks a lot cleaner, but it could also be easier to miss since it'd be two small right aligned icons.

I don't think it's necessary to stress over the filter/search UI too much in this first version anyway since there's "only" a couple dozen integrations at this stage.

Revised mockup (possibly final?):

Full Size Link

This one uses all "generic" mdi icons rather than real logos since it was a bit questionable whether they could be distributed. I'll do a chart below of which categories get assigned which icons.

The backdrop of the icons will match the users primary-color of their theme. So in the default theme it'd be blue, if the user had a red theme it would be red, etc. See this image for an idea.

It's also simplified a bit by removing the category and arrow icon, which now makes the entire card clickable. The reduced height of cards (see bottom row for example) would also have the benefit of allowing more cards on screen at once.

Categories

Every integration will have an icon, so here's a list of all categories on the Home Assistant Components page along with a default icon for that categorization. It seems like a good idea to keep the categories on the website and HA consistent.

Integrations will be able to override these defaults by specifying their own icon to use. For example the PS4 media player integration would by default be assigned mdi:play but it could use mdi:playstation instead. Google Hangouts by default would get the notification bell icon since it's in the Notifications category, but it could be mdi:google-hangouts instead.

Category	Default Icon
Alarm	mdi:security
Automation	mdi:robot
Binary Sensor	mdi:checkbox-marked-circle
Calendar	mdi:calendar-multiple-check
Camera	mdi:cctv
Car	mdi:car
Climate
Cover	mdi:garage
DIY	mdi:chip
Doorbell	mdi:doorbell-video
Downloading	mdi:download
Energy	mdi:solar-power
Environment	mdi:flower
Fan	mdi:fan
Finance	mdi:cash-usd or mdi:chart-areaspline
Front end	mdi:palette
Geolocation
Health	mdi:medical-bag
History	mdi:history
Hub
Image Processing	mdi:file-image
Intent
Irrigation	mdi:water-outline
Light	mdi:lightbulb-on-outline
Lock	mdi:lock
Mailbox	mdi:mailbox
Media Player	mdi:play
Multimedia
Network	mdi:access-point-network
Notifications	mdi:bell-ring
Organization
Postal Service	mdi:mailbox
Presence Detection	mdi:crosshairs-gps
Remote	mdi:remote
Scene
Sensor
Social	mdi:chat-processing
Switch
System Monitor	mdi:pulse
Text-to-speech	mdi:voice
Transport	mdi:bus
Utility
Vacuum	mdi:broom
Voice	mdi:microphone
Water heater
Weather	mdi:weather-hail
Other	mdi:dots-horizontal

Manifest

I do not have any programming experience so it might be more complicated than this, but from what I can tell, I think that all of this seems possible with just a few more items added to manifest.json - icon, description, category (or perhaps a comma separated list of category ID's or something)?