Build your home while onboarding

[carlhye]

Problem statement

Home Assistant's onboarding wizard walks new users through 6 steps:

1. Welcome
2. Preparing Home Assistant
3. Create user
4. Home location
5. Accept/deny analytics
6. We found compatible devices

This flow does not align with the goal of making Home Assistant more approachable — particularly in light of the new auto-generated dashboards, which rely on a user-defined floor and area structure to place devices and entities meaningfully.

Two specific problems compound each other:

Integrations create areas autonomously, polluting the user's home structure. Integrations like Sonos and Hue create areas on setup, typically naming them after the devices they want to place. This means a user who installs HA fresh, or adds a new device, can end up with automatically created areas that have no relation to their actual home — named after whatever the device was called in a third-party app. Users who have carefully structured their home find these auto-generated areas disruptive and confusing.

The onboarding flow does not prompt users to define their home structure. Without a floor and area setup step in onboarding, users are dropped into a dashboard that either reflects auto-generated integration areas or is effectively empty. Neither outcome is a good first impression, and the "We found compatible devices" screen — which exists primarily to surface this auto-area creation — creates expectations the current UX cannot fulfil gracefully.

The result is that new users start with a home structure they didn't define, and existing users who add devices find their carefully maintained structure corrupted. This directly undermines the value of the auto-generated dashboard.

Scope & Boundaries

In scope

• Remove the ability for integrations to autonomously create areas during setup
• Remove the "We found compatible devices" onboarding step (made redundant by the above)
• Insert a "Build your home" step into the onboarding wizard, positioned after the "Home location" step
• Update the existing create floors and areas page to support a sidebar with pre-built floor and area suggestions that can be dragged and dropped into the home pane
• Pre-built suggestions cover common floor names (Ground floor, 1st floor, Basement, etc.) and common area names (Kitchen, Living room, Bedroom, Bathroom, Dining room, etc.)
• A "Custom floor" and "Custom area" option in the sidebar triggers the existing creation modal, unchanged
• All floors and areas created during onboarding are editable post-setup via the same controls available today
• The updated create floors and areas page applies both in onboarding and post-onboarding (Settings → Areas)

Not in scope

• Changes to how devices and entities are assigned to areas (only the creation flow)
• Area icons, images, or aliases
• Auto-discovery or device setup within the onboarding step
• Migration of existing auto-created areas for current HA installations
• Removing any integration's ability to use existing areas — only autonomous creation is blocked
• Mobile-specific onboarding UI (desktop-first for this cycle)

Foreseen solution

Step 1 — Stop integrations from creating areas autonomously

Integrations should be able to suggest areas for devices, but not create them. If a suggested area doesn't exist in the user's home structure, the device is placed in an uncategorised state until the user assigns it, rather than silently generating an area with a potentially nonsensical name.

This also removes the trigger condition for the "We found compatible devices" onboarding screen, which can be retired.

Step 2 — Add "Build your home" as an onboarding step

Insert the existing create floors and areas page as step 5 in the onboarding wizard, between "Home location" (step 4) and "Accept/deny analytics" (step 5, renumbered to 6):

1. Welcome
2. Preparing Home Assistant
3. Create user
4. Home location
5. Build your home ← new
6. Accept/deny analytics

The step is skippable — users who want to come back to it later can proceed without defining any structure.

Step 3 — Update create floors and areas with a drag-and-drop sidebar

The current page has an empty canvas (home pane) on the left and no scaffolding to help users get started. The update introduces a right-hand sidebar (as shown in the screenshot provided) with two sections:

Add floor — pre-built options: Ground floor, 1st floor, Basement, + Custom floor
Add area — pre-built options: Kitchen, Living room, Bedroom, Bathroom, Dining room, + Custom area

Clicking a pre-built floor or area adds it to the home pane immediately, without a modal. Clicking "Custom floor" or "Custom area" opens the existing creation modal.

Floors and areas added via the sidebar behave identically to those created manually today — they can be renamed, reordered, assigned icons, and deleted via the same controls.

Visuals:

Wireframe:

Drag and drop function sketch:

Community signals

User testing

Micro test:
The problem has been tested with 3 non-admin users of Home Assistant, and all participants found it considerably more logical to build you home at the on-boarding stage, than on-boarding and then going back to define floors and areas later.

After a short introduction the users where presented with the solution present today, and 3 versions of the sidebar area-picker - the one that combines floors and areas into one sidebar was found to be most intuitive to use.

Floors and areas in one picker sidebar (high-score):

Floors are always custom, areas have prebuilt versions and a custom:

Floors are a function at the top, areas can be picked below:

Further community signals

Researched with Claude AI

Integrations autonomously creating areas is a known, recurring pain point. A community forum thread from August 2023 — still receiving replies as recently as January 2025 — documents users with Hue, Tado, and LIFX reporting that integrations repeatedly recreate areas they have manually removed, reassigning their devices every time HA restarts or an integration reconfigures. One user described it as "strange default behavior"; another said it was "starting to piss me off." No platform-level resolution exists — users are currently expected to work around it manually. (Thread)

Floors as a concept were community-requested for years before shipping. Multiple feature requests — including "Add Floor for Area and single device" (May 2022) and "Add areas within areas (AKA Floors)" (June 2022) — show that the floor/area hierarchy was a long-standing user demand, with duplicates consolidating the vote. Floors eventually shipped in 2024.4. The community investment in this concept makes it all the more important that the setup experience lives up to expectations. (Thread)

The core team described floors and areas as foundational infrastructure for dashboards, voice, and AI — at launch. The 2024.4 release notes stated explicitly that "the better Home Assistant knows your home and how it is spatially structured, the better it can help you — especially when it comes to future features like generating dashboards, voice commands, and maybe even AI-related features." Two years on, those future features are present-tense, and the setup gap this bet addresses has become a blocker rather than a footnote.

The community has already raised the mismatch between the area-based dashboard and new users. During the 2025.4 beta, a community member explicitly questioned "whether pushing new users into an 'areas' model is the best approach," noting that users who haven't defined any areas get little value from the new dashboard direction. This concern was raised organically — not in response to a feature request, but as a reaction to the release notes describing the new dashboard as a future default. (Thread)

The 2025 roadmap survey quantifies the approachability gap this opportunity directly addresses. According to the HA community survey cited in the 2025 roadmap, only 46% of partners and 27% of children of long-time HA users directly interact with Home Assistant. The roadmap names improving the "Home Approval Factor" — making HA usable for all household members, not just the admin — as the central theme for 2025 and 2026.

Recent releases reveal the product team working around the same root problem. Home Assistant 2026.1 introduced a dedicated "Devices" page on the Home dashboard specifically to surface devices not assigned to any area, acknowledging that many users end up with "orphaned" devices after onboarding. Home Assistant 2026.2 went further, adding in-dashboard prompts to help users categorise those unassigned devices into rooms. Both are symptoms of the same upstream gap: users are not guided to define their home structure before their devices arrive in it.

Risks & open questions

• Integration compatibility: Some integrations may depend on their ability to create areas. What is the right deprecation path, and how do we communicate the change to integration developers? Does the core team have a view on a grace period or a capability flag?
• "Suggest area" API: Should integrations be able to propose an area name for their devices (surfaced during device setup), even if they can't create it autonomously? This would preserve some of the UX value without polluting the home structure.
• Skip behaviour in onboarding: If a user skips "Build your home", the auto-generated dashboard will be sparse or empty until they return to Settings → Areas. Is this acceptable, or should we show a contextual nudge the first time they open the dashboard?
• Pre-built suggestion list: Who owns the canonical list of floor and area names, and in how many languages does it need to be localised at launch? Is the current set in the screenshot (Ground floor, 1st floor, Basement / Kitchen, Living room, Bedroom, Bathroom, Dining room) the right starting set, or do we expand it?
• Drag and drop vs. click-to-add: The screenshot shows click-to-add buttons rather than true drag-and-drop into a canvas. Should this be a drag-and-drop interaction (higher implementation cost, more tactile) or click-to-add (simpler, faster to build)? Does the home pane need to be a spatial canvas, or is a structured list sufficient?
• Existing installations: Users who upgrade to a version with this change will already have auto-created areas from integrations. Do we prompt them to review their area structure, or leave it as-is?

Appetite

Medium — roughly 1–2 cycles across frontend and core.

The three parts have different surface areas: the integration change touches core and potentially many integration maintainers; the onboarding step is primarily frontend wiring; the sidebar UI is a new component. If the integration deprecation work proves larger than expected, it may be right to scope it as a separate bet and ship the onboarding + sidebar work independently.

Execution issues

No response

Decision log

Date	Decision	Outcome

[tobbexiv]

This is strongly related to #83 and should consider changes suggested there (everything is an area, areas can be nested, ...). Otherwise effort would be put into one (or the other) solution which in the end is "wasted".

[carlhye]

This is strongly related to #83 and should consider changes suggested there (everything is an area, areas can be nested, ...). Otherwise effort would be put into one (or the other) solution which in the end is "wasted".

Hi @tobbexiv

Yes, it is related - but two different changes.
#123 allows the user to set up the home during initial setup, while #83 expands the way the floors and areas relates to each other. If implemented, all the changes from #83 will be reflected in the initial setup of #123

[tobbexiv]

Yes, but if #123 lands first but does not consider potential changes done in #83 in its design/architecture, then the work might need to be redone after #83 lands.

[carlhye]

#123 is the focus for now, and expands on current feature set. #83 introduces new features. Sure, we'll need to adapt the front end to any changes that might comes from #83, but the foundation is already there.

[nielsrowinbik]

On the proposed floor/area assignment: be careful about mobile, because while dragging areas into floors from the sidebar is nice on desktop, it won't work on mobile.

I recently onboarded myself onto Homey, and I remember liking their setup. Basically, what they're doing is, creating areas/floors as you're assigning devices to them. So it's not forcing the user to create a full "model" of their home before assigning the devices, but doing it in one go. Here's some screenshots.

First, they detect some devices and I set them up:

Then, they ask me to assign them to "zones" (areas in our world):

[WS-Dave]

related to onboarding - consider reverting the docker image to gzip per
home-assistant/core#168340 (comment)

[carlhye]

@nielsrowinbik

This is a bit like Sonos does it. But how do the different zones interrelate?
Referring to the conversation in #83