feat(dashboard): improve onboarding and recovery flows

Author: awesomestvi

README.md

@@ -43,7 +43,7 @@ Navet (Swedish for "the hub") is a modern, responsive smart home dashboard built
 ### 🛠️ Functionality
 - **Edit Mode** - Drag-and-drop card reordering and resizing
 - **Custom Widgets** - Add Calendar, News, Weather, Photo Frame, and Quick Note widgets
-- **Entity Visibility Control** - Start with all entities or a blank board, then add/remove entities as needed
+- **Entity Visibility Control** - Start with all entities, a blank board, or import a saved config, then add/remove entities as needed
 - **Search & Filter** - Real-time search filters dashboard view
 - **All View** - See all devices grouped by room
 - **Notifications** - System notifications panel
@@ -166,12 +166,15 @@ Navet (Swedish for "the hub") is a modern, responsive smart home dashboard built
 
 #### Dashboard Content
 - On first launch, choose whether to start with all discovered entities or a blank dashboard
+- You can also import a previously exported dashboard config directly from onboarding
 - After onboarding, use **Add Entity** and **Remove Entity** to curate the board
 - This is useful for excluding helper, diagnostic, or duplicate Home Assistant entities without switching between dashboard modes
 - The empty dashboard state now exposes **Add Entity** directly so blank dashboards do not dead-end
+- Restarting onboarding from Settings sends you back to the Home dashboard and reopens the onboarding dialog
 
 #### Dashboard Config
 - In **Settings -> Dashboard Config**, export your local dashboard setup to a JSON file
+- The same config file can be imported later either from Settings or directly from first-run onboarding
 - Import that file later on the same machine or another device to restore:
   - theme and wallpaper
   - room order and card order

design-system/FEATURES.md

@@ -293,7 +293,7 @@ Beautiful placeholder screens for sections without data.
 
 ### First-Time User Flow
 1. **Login Page** → Enter Home Assistant URL and token
-2. **Onboarding Dialog** → Choose start with all entities or a blank dashboard
+2. **Onboarding Dialog** → Choose start with all entities, a blank dashboard, or import a config file
 3. **Dashboard** → See current entities and rooms
 4. **Explore Sections** → Navigate to different sections via sidebar/bottom nav
 5. **Customize** → Go to Settings → Change theme and color
@@ -366,6 +366,7 @@ Theme, navigation, search, and Home Assistant access use direct hook modules ins
 - `ha_dashboard_primary_color` - Primary color preference
 - `ha-dashboard-navigation` - Active section and current room
 - `navet-dashboard-entities` - Removed entity ids and onboarding state
+- Restarting onboarding should always return the user to Home / All before reopening the wizard
 
 ### CSS Variables
 
@@ -447,7 +448,7 @@ Theme system uses CSS custom properties defined in `/src/styles/theme.css`:
 2. Create section component in /components/sections.tsx
 3. Add icon and route to Sidebar component
 4. Include in mobile bottom navigation (if appropriate)
-5. Implement empty state if no data available
+5. Implement empty state if no data available, with the primary recovery action visible when possible
 6. Test at all breakpoints
 
 ### When Adding Theme-Dependent Styling

design-system/LAYOUT-STRUCTURE.md

@@ -16,7 +16,7 @@ App Container
     ├── Room Navigation Tabs
     │   └── Customize / Add Entity / Add Card / Done Editing
     └── Device Grid (Main Content)
-        └── Dynamic Card Grid
+        └── Dynamic Card Grid / empty-state recovery actions
 ```
 
 ---

docs/DOCKER_HOME_ASSISTANT_ADDON.md

@@ -151,7 +151,7 @@ The current dashboard build includes a few runtime-focused optimizations:
 - Zustand-backed search result state to reduce context fan-out
 - Stable device-map reuse to avoid rerendering unchanged cards
 - Onboarding-based dashboard visibility with add/remove entity curation
-- Local dashboard config export/import for layout and preference backup
+- Local dashboard config export/import for layout and preference backup, including first-run import from onboarding
 - Configurable entity card interaction styles with a live preview in Settings
 - Optional no-animation mode for slower devices such as Raspberry Pi deployments
 

src/app/App.tsx

@@ -30,6 +30,7 @@ import { LoadingProvider } from './contexts/loading-context';
 import { LoginPage } from './features/auth/login-page';
 import { AllViewGrid } from './features/dashboard/all-view-grid';
 import type { CardType } from './features/dashboard/components/AddCardDialogContainer';
+import { AddEntityDialog } from './features/dashboard/components/add-entity-dialog';
 import { DashboardLayout } from './features/dashboard/dashboard-layout';
 import { DeviceGrid } from './features/dashboard/device-grid';
 import {
@@ -46,17 +47,14 @@ import {
 import { useCustomCards } from './hooks/use-custom-cards';
 import { useDevices, useRooms } from './hooks/use-devices';
 import { useDashboardEntitiesStore, useSettingsStore } from './stores';
+import { importDashboardConfigFromFile } from './utils/dashboard-config';
 import { getDeviceRoom, getDeviceRoomLabel } from './utils/device-location';
 
 const AddCardDialog = lazy(async () => {
   const module = await import('./features/dashboard/components/AddCardDialogContainer');
   return { default: module.AddCardDialogContainer };
 });
 
-const AddEntityDialog = lazy(async () => {
-  const module = await import('./features/dashboard/components/add-entity-dialog');
-  return { default: module.AddEntityDialog };
-});
 const DashboardOnboardingDialog = lazy(async () => {
   const module = await import('./features/dashboard/components/dashboard-onboarding-dialog');
   return { default: module.DashboardOnboardingDialog };
@@ -72,7 +70,7 @@ const SettingsSection = lazy(async () => {
  * The main dashboard view after authentication
  */
 function Dashboard() {
-  const { activeSection } = useNavigation();
+  const { activeSection, setActiveSection } = useNavigation();
   const { connected, connecting, error } = useHomeAssistant();
   const [devicesLoaded, setDevicesLoaded] = useState(false);
   const [showAddCardDialog, setShowAddCardDialog] = useState(false);
@@ -106,6 +104,10 @@ function Dashboard() {
   const { deviceMap } = useDeviceMap(devices);
   const { deviceMap: availableDeviceMap } = useDeviceMap(allDevices);
   const allEntityIds = useMemo(() => Array.from(availableDeviceMap.keys()), [availableDeviceMap]);
+  const addableEntityIds = useMemo(
+    () => (hiddenEntityIds.length > 0 ? hiddenEntityIds : allEntityIds),
+    [allEntityIds, hiddenEntityIds]
+  );
   const lightDeviceMap = useMemo(
     () => new Map(Array.from(deviceMap.entries()).filter(([, device]) => device.type === 'lights')),
     [deviceMap]
@@ -215,6 +217,30 @@ function Dashboard() {
     [hideAutoEntity]
   );
 
+  const handleImportDashboardConfig = useCallback(async (file: File) => {
+    try {
+      await importDashboardConfigFromFile(file);
+      toast.success('Dashboard config imported. Reloading...');
+      window.setTimeout(() => {
+        window.location.reload();
+      }, 600);
+    } catch {
+      toast.error('Failed to import dashboard config');
+    }
+  }, []);
+
+  const handleChooseAllEntities = useCallback(() => {
+    setActiveSection('home');
+    changeRoom('All');
+    completeOnboarding(allEntityIds, false);
+  }, [allEntityIds, changeRoom, completeOnboarding, setActiveSection]);
+
+  const handleChooseBlankDashboard = useCallback(() => {
+    setActiveSection('home');
+    changeRoom('All');
+    completeOnboarding(allEntityIds, true);
+  }, [allEntityIds, changeRoom, completeOnboarding, setActiveSection]);
+
   // Handle updating a card
   const handleUpdateCard = useCallback(
     (cardId: string, data: Record<string, unknown>) => {
@@ -281,6 +307,7 @@ function Dashboard() {
                 ? 'All light entities have been removed from the dashboard.'
                 : 'No Home Assistant light entities are currently available.'
             }
+            actionIcon={Lightbulb}
             actionLabel={hiddenEntityIds.length > 0 ? 'Add Entity' : undefined}
             onAction={hiddenEntityIds.length > 0 ? () => setShowAddEntityDialog(true) : undefined}
           />
@@ -334,7 +361,7 @@ function Dashboard() {
           onToggleEditMode={toggleEditMode}
           onMoveRoom={moveRoom}
           onAddCard={() => setShowAddCardDialog(true)}
-          onAddEntity={hiddenEntityIds.length > 0 ? () => setShowAddEntityDialog(true) : undefined}
+          onAddEntity={addableEntityIds.length > 0 ? () => setShowAddEntityDialog(true) : undefined}
           addEntityLabel="Add Entity"
         />
 
@@ -378,8 +405,9 @@ function Dashboard() {
             icon={Lightbulb}
             title="No Visible Entities"
             description="Your dashboard is empty. Add entities from your hidden list or add custom cards to start building it."
-            actionLabel={hiddenEntityIds.length > 0 ? 'Add Entity' : undefined}
-            onAction={hiddenEntityIds.length > 0 ? () => setShowAddEntityDialog(true) : undefined}
+            actionIcon={Lightbulb}
+            actionLabel={addableEntityIds.length > 0 ? 'Add Entity' : undefined}
+            onAction={addableEntityIds.length > 0 ? () => setShowAddEntityDialog(true) : undefined}
           />
         )}
 
@@ -395,27 +423,30 @@ function Dashboard() {
         )}
 
         {showAddEntityDialog && (
-          <Suspense fallback={null}>
-            <AddEntityDialog
-              open={showAddEntityDialog}
-              onClose={() => setShowAddEntityDialog(false)}
-              onAddEntity={handleAddEntity}
-              currentRoom={activeRoom}
-              deviceMap={availableDeviceMap}
-              addedEntityIds={[]}
-              visibleEntityIds={hiddenEntityIds}
-              title="Add Entity"
-              description="Add Home Assistant entities back to the dashboard."
-              actionLabel="Add"
-            />
-          </Suspense>
+          <AddEntityDialog
+            open={showAddEntityDialog}
+            onClose={() => setShowAddEntityDialog(false)}
+            onAddEntity={handleAddEntity}
+            currentRoom={activeRoom}
+            deviceMap={availableDeviceMap}
+            addedEntityIds={[]}
+            visibleEntityIds={addableEntityIds}
+            title="Add Entity"
+            description={
+              hiddenEntityIds.length > 0
+                ? 'Add Home Assistant entities back to the dashboard.'
+                : 'Choose Home Assistant entities to add to the dashboard.'
+            }
+            actionLabel="Add"
+          />
         )}
         {!onboardingCompleted && allEntityIds.length > 0 && (
           <Suspense fallback={null}>
             <DashboardOnboardingDialog
               open
-              onChooseAll={() => completeOnboarding(allEntityIds, false)}
-              onChooseBlank={() => completeOnboarding(allEntityIds, true)}
+              onChooseAll={handleChooseAllEntities}
+              onChooseBlank={handleChooseBlankDashboard}
+              onImportConfig={handleImportDashboardConfig}
             />
           </Suspense>
         )}

src/app/components/layout/room-nav.tsx

@@ -1,7 +1,7 @@
 import { DndContext, type DragEndEvent, PointerSensor, useSensor, useSensors } from '@dnd-kit/core';
 import { horizontalListSortingStrategy, SortableContext, useSortable } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
-import { Check, Edit3, Plus } from 'lucide-react';
+import { Check, Edit3, LayoutGrid, Lightbulb } from 'lucide-react';
 import { memo } from 'react';
 import { useTheme } from '@/app/hooks';
 import { getThemeColorValue } from '@/app/utils/theme-colors';
@@ -102,7 +102,7 @@ export const RoomNav = memo(function RoomNav({
             onClick={onAddEntity}
             className={`p-2 rounded-lg transition-colors flex items-center gap-2 px-3 ${inactiveBg} ${hoverBg}`}
           >
-            <Plus className={`w-4 h-4 ${textSecondary}`} />
+            <Lightbulb className={`w-4 h-4 ${textSecondary}`} />
             <span className={`text-xs font-medium hidden md:inline ${textSecondary}`}>
               {addEntityLabel}
             </span>
@@ -115,7 +115,7 @@ export const RoomNav = memo(function RoomNav({
             onClick={onAddCard}
             className={`p-2 rounded-lg transition-colors flex items-center gap-2 px-3 ${inactiveBg} ${hoverBg}`}
           >
-            <Plus className={`w-4 h-4 ${textSecondary}`} />
+            <LayoutGrid className={`w-4 h-4 ${textSecondary}`} />
             <span className={`text-xs font-medium hidden md:inline ${textSecondary}`}>
               Add Card
             </span>

src/app/components/shared/empty-state.tsx

@@ -5,6 +5,7 @@ interface EmptyStateProps {
   icon: React.ComponentType<{ className?: string }>;
   title: string;
   description: string;
+  actionIcon?: React.ComponentType<{ className?: string }>;
   actionLabel?: string;
   onAction?: () => void;
 }
@@ -13,6 +14,7 @@ export const EmptyState = memo(function EmptyState({
   icon: Icon,
   title,
   description,
+  actionIcon: ActionIcon,
   actionLabel,
   onAction,
 }: EmptyStateProps) {
@@ -38,8 +40,9 @@ export const EmptyState = memo(function EmptyState({
           <button
             type="button"
             onClick={onAction}
-            className="mt-6 px-4 py-2 rounded-xl bg-gray-900 text-white text-sm font-medium"
+            className="mt-6 inline-flex items-center gap-2 px-4 py-2 rounded-xl bg-gray-900 text-white text-sm font-medium"
           >
+            {ActionIcon && <ActionIcon className="h-4 w-4" />}
             {actionLabel}
           </button>
         )}

src/app/components/ui/alert-dialog.tsx

@@ -2,7 +2,8 @@
 
 import * as AlertDialogPrimitive from '@radix-ui/react-alert-dialog';
 import type * as React from 'react';
-import { buttonVariants } from './button';
+import { useTheme } from '@/app/hooks';
+import { getThemeColorValue } from '@/app/utils/theme-colors';
 import { cn } from './utils';
 
 function AlertDialog({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Root>) {
@@ -27,7 +28,7 @@ function AlertDialogOverlay({
     <AlertDialogPrimitive.Overlay
       data-slot="alert-dialog-overlay"
       className={cn(
-        'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50',
+        'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/55 backdrop-blur-sm',
         className
       )}
       {...props}
@@ -39,15 +40,26 @@ function AlertDialogContent({
   className,
   ...props
 }: React.ComponentProps<typeof AlertDialogPrimitive.Content>) {
+  const { theme, primaryColor } = useTheme();
+  const accentColor = getThemeColorValue(primaryColor);
+  const surfaceClass =
+    theme === 'light' ? 'border-gray-200/80 text-gray-900' : 'border-white/10 text-white';
+  const background =
+    theme === 'light'
+      ? `linear-gradient(180deg, rgba(255,255,255,0.96) 0%, rgba(255,255,255,0.92) 72%, ${accentColor}10 100%)`
+      : `linear-gradient(180deg, rgba(18,18,20,0.96) 0%, rgba(12,12,14,0.94) 72%, ${accentColor}14 100%)`;
+
   return (
     <AlertDialogPortal>
       <AlertDialogOverlay />
       <AlertDialogPrimitive.Content
         data-slot="alert-dialog-content"
         className={cn(
-          'bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 sm:max-w-lg',
+          'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-5 rounded-[32px] border p-6 shadow-2xl backdrop-blur-xl duration-200 sm:max-w-lg sm:p-8',
+          surfaceClass,
           className
         )}
+        style={{ background }}
         {...props}
       />
     </AlertDialogPortal>
@@ -68,7 +80,7 @@ function AlertDialogFooter({ className, ...props }: React.ComponentProps<'div'>)
   return (
     <div
       data-slot="alert-dialog-footer"
-      className={cn('flex flex-col-reverse gap-2 sm:flex-row sm:justify-end', className)}
+      className={cn('flex flex-col-reverse gap-2 pt-1 sm:flex-row sm:justify-end', className)}
       {...props}
     />
   );
@@ -81,7 +93,7 @@ function AlertDialogTitle({
   return (
     <AlertDialogPrimitive.Title
       data-slot="alert-dialog-title"
-      className={cn('text-lg font-semibold', className)}
+      className={cn('text-xl font-semibold tracking-tight', className)}
       {...props}
     />
   );
@@ -91,10 +103,15 @@ function AlertDialogDescription({
   className,
   ...props
 }: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
+  const { theme } = useTheme();
   return (
     <AlertDialogPrimitive.Description
       data-slot="alert-dialog-description"
-      className={cn('text-muted-foreground text-sm', className)}
+      className={cn(
+        'text-sm leading-relaxed',
+        theme === 'light' ? 'text-gray-600' : 'text-gray-300',
+        className
+      )}
       {...props}
     />
   );
@@ -104,16 +121,37 @@ function AlertDialogAction({
   className,
   ...props
 }: React.ComponentProps<typeof AlertDialogPrimitive.Action>) {
-  return <AlertDialogPrimitive.Action className={cn(buttonVariants(), className)} {...props} />;
+  const { primaryColor } = useTheme();
+  const accentColor = getThemeColorValue(primaryColor);
+  return (
+    <AlertDialogPrimitive.Action
+      className={cn(
+        'inline-flex h-10 items-center justify-center gap-2 rounded-full border-0 px-5 text-sm font-medium text-white shadow-sm transition-all hover:brightness-110 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-transparent',
+        className
+      )}
+      style={{ backgroundColor: accentColor }}
+      {...props}
+    />
+  );
 }
 
 function AlertDialogCancel({
   className,
   ...props
 }: React.ComponentProps<typeof AlertDialogPrimitive.Cancel>) {
+  const { theme } = useTheme();
+  const cancelClass =
+    theme === 'light'
+      ? 'border-gray-200/80 bg-gray-100 text-gray-900 hover:bg-gray-200'
+      : 'border-white/10 bg-white/5 text-white hover:bg-white/10';
+
   return (
     <AlertDialogPrimitive.Cancel
-      className={cn(buttonVariants({ variant: 'outline' }), className)}
+      className={cn(
+        'inline-flex h-10 items-center justify-center gap-2 rounded-full border px-5 text-sm font-medium transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-transparent',
+        cancelClass,
+        className
+      )}
       {...props}
     />
   );