UX Audit: First-Time User Experience — Make Dashview Truly Zero-Config

[mholzi]

🎯 Perspective

I'm a user who just installed Dashview via HACS. I haven't read the README. I don't know how Dashview works. I just want a nice dashboard.

---

🚨 Critical: The "Zero Config" Promise vs Reality

The README promises: "Install it. Open it. Done." and "Zero configuration."

Reality: A new user hits a 7-step wizard that immediately tells them to leave Dashview and go configure Home Assistant first.

The Label Problem (Biggest Barrier)

Dashview requires 15 label categories to be manually mapped:
Lights, Covers, Roof Windows, Windows, Garages, Motion Sensors, Smoke Detectors, Water Leak Sensors, Vibration Sensors, Temperature, Humidity, Climate, Media Players, TVs, Locks.

The irony: Home Assistant already knows what these entities are. A light.living_room is a light. A climate.thermostat is a climate device. A cover.blinds is a cover. The entity domain tells you everything.

Recommendation: Auto-detect entity types from HA domains as the default. Labels should be an optional override, not a requirement. This alone would eliminate 80% of the setup friction.

Proposed auto-detection mapping:

HA Domain	Dashview Category
light.*	Lights
cover.*	Covers (+ check device_class for window/garage/blind)
climate.*	Climate
media_player.*	Media Players (+ check attributes for TV vs speaker)
lock.*	Locks
sensor.*	Check device_class: temperature, humidity, etc.
binary_sensor.*	Check device_class: motion, window, door, smoke, moisture, vibration

Labels would still be useful for edge cases and overrides, but the dashboard should work out of the box without them.

---

🧭 Onboarding Flow Issues

1. "Go Away and Come Back" Anti-Pattern

The welcome step's yellow notice box says:

"Please ensure you have configured: Areas, Floors, Labels"
"Set these up in Home Assistant under Settings → Areas & Zones"

This tells the user to leave the app they just installed to go do homework in another part of HA. Many users will:

• Not come back
• Not understand what Labels are
• Set up Areas but skip Floors/Labels
• Get frustrated

Fix: If Areas exist but Labels don't, auto-detect (see above). If no Areas exist at all, show a friendlier message: "Dashview works best when your devices are assigned to rooms. Want me to show you how?" with an inline guide or even an in-app area assignment tool.

2. Wizard Steps Are Overwhelming

7 steps for a "zero config" dashboard:

1. Welcome → 2. Floors → 3. Rooms → 4. Labels → 5. Room Config → 6. Floor Cards → 7. Review

A new user doesn't understand what "Floor Cards" means or why they need to configure them. They just want to see their house.

Fix: Reduce to 3 steps max:

1. Welcome — "Here's what we found in your home" (show auto-discovered floors/rooms)
2. Quick Customize — Drag to reorder floors/rooms, toggle visibility (optional, can skip)
3. Done — Show the dashboard with a "You can customize more in Settings" hint

3. No "Just Show Me Something" Option

There's no way to skip the wizard and just see a dashboard with sensible defaults. The wizard has no skip button (SKIPPABLE_STEPS = [] is empty).

Fix: Add a prominent "Skip Setup — Use Defaults" button on the welcome screen. Auto-detect everything and show the dashboard immediately. Let users fine-tune later via admin.

---

🖥️ Main Dashboard UX Issues

4. Floor Tabs Use Icons Only

Floor navigation shows only icons (from getFloorIcon()). A new user sees cryptic icons and doesn't know which floor is which.

Fix: Show floor names (or at least short labels) alongside icons. On mobile, abbreviate if needed. Consider: 🏠 Ground ⬆️ Upper instead of just icons.

5. No Visual Onboarding After Setup

After completing the wizard, the user lands on the dashboard with zero guidance. They don't know:

• What the weather widget does (tap to expand)
• That room cards are tappable (opens room popup)
• What the info text badges mean
• That the hamburger menu leads to admin
• That activity chips show real-time motion/smoke
• That scene buttons exist

Fix: Add a one-time coach marks overlay (3-4 tooltips pointing at key UI elements):

• "Tap a room for full controls"
• "Your home status at a glance" (info text)
• "Customize in settings" (menu button)
• "Weather details" (weather widget)

Note: There's a components/onboarding/ folder but it's empty (// No exports - coach mark removed). This was apparently planned and then removed.

6. Info Text Row is Cryptic

The status bar shows badges like "3 Lichter an" or "Fenster offen" — but a new user doesn't know:

• These are clickable (opens relevant popup)
• The ✕ button dismisses alerts
• The eye-off icon shows hidden alerts
• What "critical" vs "warning" means

Fix: Add subtle interactivity hints. A first-time tooltip: "Tap any status badge for quick controls." Use consistent, obvious iconography for dismiss/expand.

7. Empty State When Nothing Is Configured

If a floor has no cards configured and floor overview is disabled, the user sees:

"No cards configured for this floor"

This is a dead end. There's no link to admin, no suggestion of what to do next.

Fix: Show a friendly empty state with a CTA: "This floor is empty. [Add cards in Settings] or [Run Setup Wizard]"

---

⚙️ Admin Panel Issues

8. Admin Panel is Hidden and Complex

The admin is behind a hamburger menu (☰). Once opened, there are 7 tabs: Entities, Layout, Weather, Status, Setup, Scenes, Users.

For a user who just wants to tweak room order or hide an entity, this is overwhelming.

Fix:

• Rename tabs to be more intuitive: "Rooms & Devices" instead of "Entities", "Appearance" instead of "Layout"
• Add a "Quick Settings" surface accessible without the full admin (long-press on a room card → edit room, long-press on a floor tab → reorder floors)
• Consider grouping: Basic (Rooms, Appearance) vs Advanced (Weather, Status, Scenes, Users)

9. Entities Tab: 15 Label Dropdowns

Opening the Entities tab shows 15 dropdown selectors, each with a red or green border indicating configuration status. This looks like a failing checklist.

Fix: If auto-detection is implemented, this becomes an "Override" section that most users never need to touch. Show it collapsed by default with a note: "Dashview auto-detected your devices. Only change these if something was misidentified."

---

🌐 i18n Issues (Hardcoded Strings)

10. German Strings Hardcoded in Main Panel

Found in dashview-panel.js:

• "Sicherheit" (Security popup title — line ~4657)
• "Erneut versuchen" (Retry button — line ~4486)

These should use t() translations.

---

📱 Mobile UX

11. No Touch Gesture Discovery

Dashview has rich touch interactions:

• Swipe on floor overview cards
• Long-press on lights (opens more-info)
• Drag on light sliders
• Tap vs long-press on floor card lights

None of these are discoverable. A new user will only ever tap.

Fix: Either add a gesture tutorial on first use, or reduce reliance on hidden gestures. Every action should also be achievable with a simple tap (e.g., a visible "⋮" menu instead of relying on long-press).

---

📊 Summary: Priority Ranking

#	Issue	Impact	Effort
1	Auto-detect entities from HA domains	🔴 Critical	Medium
2	Skip wizard / show defaults immediately	🔴 Critical	Low
3	Remove "go configure HA first" blocker	🔴 Critical	Low
4	Reduce wizard to 3 steps	🟡 High	Medium
5	Coach marks / first-use tooltips	🟡 High	Medium
6	Floor tabs show names	🟢 Medium	Low
7	Fix hardcoded German strings	🟢 Medium	Low
8	Better empty states with CTAs	🟢 Medium	Low
9	Admin tab renaming / grouping	🟢 Medium	Low
10	Gesture discoverability	🟡 High	Medium
11	Info text row onboarding	🟢 Medium	Low

---

💡 The North Star

A user installs Dashview, opens it, and immediately sees their home organized by floor and room — with lights, sensors, and controls working — without touching a single setting.

Everything else is optional customization.

[mholzi]

🔬 Deep Research: First-Time User Experience Audit

Part 1: Current First-Run Experience — Step by Step

I traced every file in the onboarding flow. Here's exactly what happens:

Installation → First Dashboard Load:

1. User installs via HACS → Restart HA → Add Integration → Sidebar icon appears
2. User clicks sidebar → dashview-panel.js loads → OnboardingStore.shouldShowWizard() checks if enabledRooms, floorOrder, or roomOrder exist in settings
3. If nothing configured → 7-step wizard launches (no skip option)

The 7 Wizard Steps (current):

Step	File	What It Does	User Action Required
1. Welcome	welcome-step.js	Shows feature cards + yellow warning box	Read warning, understand prerequisites
2. Floors	floors-step.js	Drag-to-reorder floors	Drag/click arrows (if floors exist)
3. Rooms	rooms-step.js	Drag-to-reorder rooms per floor	Drag/click arrows
4. Labels	labels-step.js	Map 15 HA labels to Dashview categories	Select from 15 dropdowns (!)
5. Room Config	entities-step.js	Enable/disable rooms + entities	Toggle rooms, expand to configure entities
6. Floor Cards	floor-cards-step.js	Configure 6-slot grid per floor	Click slots, select entities from dropdowns
7. Review	review-step.js	Summary with edit buttons	Review and finish

Key code facts:

• SKIPPABLE_STEPS = [] — no steps are skippable (line in onboarding-store.js)
• No "Skip Wizard" button anywhere in the code
• LABEL_CATEGORIES has 15 entries — all requiring manual label mapping
• Empty state for no-areas: "No areas found in Home Assistant. Create areas in Settings → Areas & Zones." — dead end, no link
• Empty state for no-labels: "No labels configured in Home Assistant" — dead end
• Empty state for no-floors: "No floors found in Home Assistant." — dead end
• The components/onboarding/ folder exports nothing: // No exports - coach mark removed — coach marks were planned and removed

The Welcome Step Warning (the biggest barrier):

⚠ Before You Start
Dashview uses your Home Assistant setup to organize your dashboard. Please ensure you have configured:
• Areas - Create rooms/areas and assign your devices to them
• Floors - Group your areas by floor for better organization  
• Labels - Tag entities (e.g., "Lights", "Climate") for automatic categorization
Set these up in Home Assistant under Settings → Areas & Zones

This tells the user to leave and go configure HA. Classic "go away and come back" anti-pattern.

---

Part 2: Competitor Onboarding Comparison

Platform	First-Run Flow	Auto-Detection	Config Steps	Time to "Working"
Apple Home	Add home → Name rooms → Devices auto-appear in rooms	Full (via HomeKit)	2 (name home, add room)	~2 min
Google Home	Create home → Devices discovered → Assign to rooms	Full (via Matter/partnerships)	2-3 (create home, assign rooms)	~3 min
SmartThings	Hub discovery → Devices auto-found → Favorites dashboard	Full (via hub)	1-2 (pick favorites)	~2 min
Dwains Dashboard	Install via HACS → Add integration → Dashboard auto-generates from HA areas	Full (uses HA areas/entities)	0 steps	~30 sec
HA Sections View	Auto-generates from areas/floors → Drag-and-drop to customize	Full (native)	0 steps	Instant
Dashview (current)	Install → 7-step wizard → Must configure labels first	None (requires 15 labels)	7 steps	10-15 min

Key takeaway: Every competitor auto-detects. Dashview is the only one that requires manual label mapping before showing anything.

Dwains Dashboard is the closest competitor and the most relevant comparison:

• Also HACS-based, also uses HA areas
• Zero config — installs, adds sidebar, auto-generates dashboard from areas
• v4 (2025) simplified even further: left panel = areas, right panel = entities for selected area
• No wizard, no labels, no manual mapping

---

Part 3: Progressive Disclosure Patterns

Best practices from top products:

Pattern	Used By	Pros	Cons	Fit for Dashview
Wizard/Stepper	Slack, Notion, current Dashview	Structured, clear progress	Blocks access to app, high drop-off	⚠️ Only if 2-3 steps max
Inline Guidance	Figma, Linear	Non-blocking, contextual	Can be ignored	✅ Great for admin panel
Coach Marks	Slack mobile, Spotify	Visual, targeted	Annoying if too many	✅ 3-4 marks on first dashboard load
Getting Started Checklist	Notion, Linear, Vercel	Self-paced, tracks progress, non-blocking	Needs dismissal	✅ Perfect for optional setup
Video Tutorial	Complex SaaS	Rich, explanatory	Requires production effort	❌ Overkill for Dashview
Empty State CTAs	Every good app	Contextual, appears when needed	Only visible in empty states	✅ Must-have for dead ends

Recommended combination for Dashview:

1. Auto-detect + instant dashboard (replace wizard)
2. Coach marks (3-4 tooltips on first dashboard load)
3. Getting Started checklist (accessible from admin, tracks optional setup)
4. Empty state CTAs (every empty state gets actionable buttons)

---

Part 4: Empty States & Error Recovery

Current empty states (all dead ends):

State	Current Message	Fix
No areas	"No areas found in Home Assistant. Create areas in Settings → Areas & Zones."	Add deep-link button: "Open HA Area Settings"
No floors	"No floors found in Home Assistant."	Show rooms flat (no floor tabs). Add hint: "Add floors for better organization"
No labels	"No labels configured in Home Assistant"	Remove this dependency entirely via auto-detection
Empty floor	"No cards configured for this floor"	"This floor is empty. [Add cards in Settings] or [Run Setup]"
No weather entity	(hidden)	Show placeholder: "Configure weather in Dashview settings"
Module not loaded	"Security module not loaded"	Better error: "Security features need window/motion sensors. [Configure →]"

Graceful degradation strategy:

• Missing weather? → Hide weather widget (don't show error), show setup prompt in admin
• Missing security entities? → Hide security tab, add to Getting Started checklist
• No labels? → Auto-detect from domains (this is the whole point)
• No areas at all? → Show friendly "Welcome! Set up rooms in HA to get started" with link
• One floor only? → Hide floor tabs entirely, show rooms directly

---

Part 5: Top 5 Recommendations (Prioritized)

🏆 Recommendation 1: Auto-Detect Entities from HA Domains (Critical — Eliminates 80% of Setup)

Impact: 🔴 Critical | Effort: Medium (2-3 days) | Priority: P0

Create a domain-detector.js utility that maps HA entity domains + device_class to Dashview categories:

const DOMAIN_MAP = {
  'light': { category: 'light' },
  'cover': { 
    category: 'cover',
    deviceClassMap: {
      'window': 'window', 'garage': 'garage', 'blind': 'cover',
      'shutter': 'cover', 'awning': 'cover', 'curtain': 'cover'
    }
  },
  'climate': { category: 'climate' },
  'media_player': { category: 'mediaPlayer', tvCheck: (attrs) => attrs.device_class === 'tv' },
  'lock': { category: 'lock' },
  'sensor': {
    deviceClassMap: { 'temperature': 'temperature', 'humidity': 'humidity' }
  },
  'binary_sensor': {
    deviceClassMap: {
      'motion': 'motion', 'window': 'window', 'door': 'window',
      'smoke': 'smoke', 'moisture': 'waterLeak', 'vibration': 'vibration',
      'garage_door': 'garage'
    }
  }
};

Behavior: If a label is configured → use label. If not → fall back to domain detection. This makes labels optional overrides instead of required configuration.

---

🏆 Recommendation 2: "Skip to Dashboard" Button + Auto-Defaults (Critical — Low Effort)

Impact: 🔴 Critical | Effort: Low (1 day) | Priority: P0

On the Welcome step, add a prominent "Show My Dashboard" button that:

1. Runs domain auto-detection
2. Enables all rooms by default
3. Sets floor order from HA
4. Shows the dashboard immediately

Also add 'welcome' to SKIPPABLE_STEPS at minimum.

---

🏆 Recommendation 3: Reduce Wizard to 2 Optional Steps (High Impact)

Impact: 🟡 High | Effort: Medium (2 days) | Priority: P1

Replace the 7-step wizard with:

• Step 1: Welcome — "We detected X floors, Y rooms, Z devices" + "Show Dashboard" / "Customize First"
• Step 2: Quick Customize (optional) — Floor order + room visibility (toggles, not dropdowns)
• Done → Dashboard loads with coach marks

Remove: Labels step (auto-detected), Floor Cards step (use sensible defaults), Review step (unnecessary if only 2 steps).

---

🏆 Recommendation 4: Coach Marks on First Dashboard Load (High Impact)

Impact: 🟡 High | Effort: Medium (2 days) | Priority: P1

Re-implement the coach marks that were previously removed (components/onboarding/ is empty). Show 3-4 tooltips on first dashboard view:

1. "Tap a room for full controls" → points to first room card
2. "Status at a glance" → points to info bar
3. "Switch floors" → points to floor tabs
4. "Customize in Settings" → points to menu/gear icon

Use a simple overlay with a "Next" / "Got it" dismiss flow. Store dismissal in localStorage.

---

🏆 Recommendation 5: Better Empty States with CTAs (Medium Impact — Quick Win)

Impact: 🟢 Medium | Effort: Low (0.5 days) | Priority: P1

Replace every dead-end empty state with:

• A friendly illustration/icon
• Clear explanation of what's missing
• Actionable button that links to the fix (HA settings, admin panel, etc.)

Target files: room-cards-grid.js (renderNoCardsMessage), entities-step.js, floors-step.js, labels-step.js, floor-cards-step.js.

---

📐 Proposed Onboarding Flow Mockup

Interactive HTML mockup: mockups/140-first-time-ux.html

The mockup shows 5 screens:

1. Welcome — Auto-detection summary with "Show Dashboard" and "Customize First" CTAs
2. Quick Customize — Floor reorder + room visibility toggles (replaces 5 wizard steps)
3. Dashboard + Coach Marks — The actual dashboard with 4 overlay tooltips
4. Getting Started Checklist — Optional progressive setup tracker
5. Better Empty States — No-areas, empty-floor, and no-weather states with CTAs

---

📊 Implementation Effort Summary

#	Recommendation	Effort	Impact	Dependencies
1	Auto-detect entities from domains	2-3 days	🔴 Critical	None
2	"Skip to Dashboard" button	1 day	🔴 Critical	#1 (auto-detect)
3	Reduce wizard to 2 steps	2 days	🟡 High	#1, #2
4	Coach marks on first load	2 days	🟡 High	None
5	Better empty states with CTAs	0.5 days	🟢 Medium	None
—	Floor tabs show names	0.5 days	🟢 Medium	None
—	Getting Started checklist	1.5 days	🟢 Medium	None
—	Admin tab renaming	0.5 days	🟢 Low	None

Total: ~10 days for full implementation, ~4 days for P0 items (auto-detect + skip button)

🏁 The North Star

A user installs Dashview, opens it, and immediately sees their home organized by floor and room — with lights, sensors, and controls working — without touching a single setting. Everything else is optional customization.