@burdenoff/microfe-movethewheels 2026.625.1 → 2026.626.1

package/src/movethewheels/pages/ReportsPage.tsx

@@ -17,6 +17,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '../components/ui';
+import { EmphasisPanel, PagePurpose } from '@burdenoff/fe-libs/ui';
 
 export default function ReportsPage() {
   const reports = [
@@ -87,6 +88,12 @@ export default function ReportsPage() {
         </div>
       }
     >
+      <PagePurpose icon={<FileBarChart size={18} />}>
+        Turn your operational data into shareable summaries. Generate one-off reports on orders,
+        finance, fleet, customers or inventory, or schedule them to land in inboxes automatically —
+        so stakeholders always have the latest numbers without logging in.
+      </PagePurpose>
+
       <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
         <div className="lg:col-span-2 space-y-4">
           <h3 className="font-semibold">Available Reports</h3>
@@ -121,25 +128,22 @@ export default function ReportsPage() {
         </div>
 
         <div className="space-y-6">
-          <Card>
-            <CardHeader>
-              <CardTitle className="flex items-center gap-2">
-                <Clock size={18} /> Scheduled Reports
-              </CardTitle>
-            </CardHeader>
-            <CardContent className="space-y-3">
-              {scheduledReports.map((report) => (
-                <div key={report.name} className="p-3 border rounded-lg">
-                  <p className="font-medium">{report.name}</p>
-                  <p className="text-sm text-text-secondary">Next: {report.nextRun}</p>
-                  <p className="text-xs text-text-secondary">{report.recipients} recipients</p>
-                </div>
-              ))}
-              <Button variant="outline" className="w-full">
-                Schedule New Report
-              </Button>
-            </CardContent>
-          </Card>
+          {/* Scheduled Reports — the page's single emphasis zone */}
+          <EmphasisPanel className="space-y-3">
+            <h2 className="flex items-center gap-2 text-base font-semibold text-text-primary">
+              <Clock size={18} /> Scheduled Reports
+            </h2>
+            {scheduledReports.map((report) => (
+              <div key={report.name} className="p-3 border border-border-seam rounded-lg">
+                <p className="font-medium">{report.name}</p>
+                <p className="text-sm text-text-secondary">Next: {report.nextRun}</p>
+                <p className="text-xs text-text-secondary">{report.recipients} recipients</p>
+              </div>
+            ))}
+            <Button variant="outline" className="w-full">
+              Schedule New Report
+            </Button>
+          </EmphasisPanel>
 
           <Card>
             <CardHeader>

package/src/movethewheels/pages/RouteDetailsPage.tsx

@@ -4,9 +4,10 @@
 
 import { useParams } from 'react-router-dom';
 import { Navigation, ArrowLeft, Edit, MapPin, Clock, Zap, CheckCircle } from 'lucide-react';
-import { PageLayout, LoadingState, ErrorState } from '../components/PageLayout';
+import { PageLayout, LoadingState, ErrorState, EmptyState } from '../components/PageLayout';
 import { StatusBadge } from '../components/StatusBadge';
 import { Card, CardContent, CardHeader, CardTitle, Button, Badge } from '../components/ui';
+import { EmphasisPanel, NextSteps, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { useRoute, useRoutes } from '../hooks/useRoutes';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate, formatAddress } from '../utils/formatters';
@@ -19,6 +20,7 @@ export default function RouteDetailsPage() {
   const { optimizeRoute } = useRoutes();
 
   const goBack = () => navigate?.(joinPath(basePath, 'routes'));
+  const goTo = (path: string) => navigate?.(joinPath(basePath, path));
 
   // Handle new route form
   if (!routeId) {
@@ -33,11 +35,15 @@ export default function RouteDetailsPage() {
           </Button>
         }
       >
-        <Card>
-          <CardContent className="p-8 text-center">
-            <p className="text-text-secondary">Route creation form would go here</p>
-          </CardContent>
-        </Card>
+        <PagePurpose icon={<Navigation size={18} />}>
+          Plan a new delivery route — pick the stops to visit, and the optimizer will sequence them
+          into the shortest driving plan so one driver can cover them in a single run.
+        </PagePurpose>
+        <EmptyState
+          illustration="onboarding"
+          title="Build your route"
+          description="The route planner lets you add stops, set the running order, and optimize for distance and time."
+        />
       </PageLayout>
     );
   }
@@ -90,6 +96,43 @@ export default function RouteDetailsPage() {
         </div>
       }
     >
+      <PagePurpose icon={<Navigation size={18} />}>
+        A single optimized driving plan that chains together this route&apos;s stops. Review the
+        sequence, distance and timing here, re-optimize if traffic or stops change, then hand the
+        itinerary to a driver.
+      </PagePurpose>
+
+      <NextSteps
+        storageKey="movethewheels-route-details"
+        steps={[
+          ...(!route.optimized
+            ? [
+                {
+                  id: 'optimize',
+                  label: 'Optimize this route',
+                  description: 'Reorder stops to cut distance and driving time.',
+                  icon: <Zap size={16} />,
+                  onClick: handleOptimize,
+                },
+              ]
+            : []),
+          {
+            id: 'edit',
+            label: 'Adjust stops',
+            description: 'Add, remove or reorder the delivery stops.',
+            icon: <Edit size={16} />,
+            onClick: () => {},
+          },
+          {
+            id: 'orders',
+            label: 'Review the orders on this route',
+            description: 'Check the deliveries bundled into this run.',
+            icon: <MapPin size={16} />,
+            onClick: () => goTo('orders'),
+          },
+        ]}
+      />
+
       <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
         <div className="lg:col-span-2 space-y-6">
           <Card>
@@ -161,36 +204,33 @@ export default function RouteDetailsPage() {
         </div>
 
         <div className="space-y-6">
-          <Card>
-            <CardHeader>
-              <CardTitle>Route Info</CardTitle>
-            </CardHeader>
-            <CardContent className="space-y-4">
-              <div>
-                <p className="text-sm text-text-secondary">Total Distance</p>
-                <p className="text-2xl font-bold">
-                  {route.distance.toFixed(1)}
-                  <span className="text-sm font-normal"> km</span>
-                </p>
-              </div>
+          {/* Route Info — the page's single emphasis zone */}
+          <EmphasisPanel className="space-y-4">
+            <h2 className="text-base font-semibold text-text-primary">Route Info</h2>
+            <div>
+              <p className="text-sm text-text-secondary">Total Distance</p>
+              <p className="text-2xl font-bold">
+                {route.distance.toFixed(1)}
+                <span className="text-sm font-normal"> km</span>
+              </p>
+            </div>
+            <div>
+              <p className="text-sm text-text-secondary">Est. Duration</p>
+              <p className="text-2xl font-bold">
+                {route.estimatedDuration}
+                <span className="text-sm font-normal"> min</span>
+              </p>
+            </div>
+            {route.actualDuration && (
               <div>
-                <p className="text-sm text-text-secondary">Est. Duration</p>
+                <p className="text-sm text-text-secondary">Actual Duration</p>
                 <p className="text-2xl font-bold">
-                  {route.estimatedDuration}
+                  {route.actualDuration}
                   <span className="text-sm font-normal"> min</span>
                 </p>
               </div>
-              {route.actualDuration && (
-                <div>
-                  <p className="text-sm text-text-secondary">Actual Duration</p>
-                  <p className="text-2xl font-bold">
-                    {route.actualDuration}
-                    <span className="text-sm font-normal"> min</span>
-                  </p>
-                </div>
-              )}
-            </CardContent>
-          </Card>
+            )}
+          </EmphasisPanel>
 
           <Card>
             <CardHeader>

package/src/movethewheels/pages/RoutesPage.tsx

@@ -6,8 +6,8 @@ import { Plus, RefreshCw, Navigation } from 'lucide-react';
 import { PageLayout } from '../components/PageLayout';
 import { DataTable, type Column } from '../components/DataTable';
 import { StatusBadge } from '../components/StatusBadge';
-import { Badge } from '../components/ui';
-import { CTAOverflowMenu } from '@burdenoff/fe-libs/ui';
+import { Badge, Button } from '../components/ui';
+import { CTAOverflowMenu, EmphasisPanel, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { useRoutes } from '../hooks/useRoutes';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate } from '../utils/formatters';
@@ -86,12 +86,39 @@ export default function RoutesPage() {
             icon: <Plus size={16} />,
             onSelect: () => goTo('routes/new'),
           }}
-          actions={[
-            { label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() },
-          ]}
+          actions={[{ label: 'Refresh', icon: <RefreshCw size={16} />, onSelect: () => refetch() }]}
         />
       }
     >
+      <PagePurpose icon={<Navigation size={18} />}>
+        Routes group multiple delivery stops into an optimized driving plan. Build a route to batch
+        nearby drop-offs, cut distance and fuel, and give drivers a single ordered itinerary — then
+        open one to review stops, distance and optimization status.
+      </PagePurpose>
+
+      {/* Routes at a glance — the page's single emphasis zone */}
+      <EmphasisPanel>
+        <p className="text-sm font-medium text-text-secondary">Routes at a glance</p>
+        <div className="mt-3 grid grid-cols-3 gap-4">
+          <div>
+            <p className="text-2xl font-bold text-text-primary tabular-nums">{totalRoutes}</p>
+            <p className="text-xs text-text-secondary">Total routes</p>
+          </div>
+          <div>
+            <p className="text-2xl font-bold text-text-primary tabular-nums">
+              {routes.filter((r) => r.status === 'in_progress').length}
+            </p>
+            <p className="text-xs text-text-secondary">In progress</p>
+          </div>
+          <div>
+            <p className="text-2xl font-bold text-text-primary tabular-nums">
+              {routes.filter((r) => r.optimized).length}
+            </p>
+            <p className="text-xs text-text-secondary">Optimized</p>
+          </div>
+        </div>
+      </EmphasisPanel>
+
       <DataTable
         columns={columns}
         data={routes}
@@ -101,6 +128,15 @@ export default function RoutesPage() {
         searchFields={['name'] as (keyof Route)[]}
         onRowClick={(row) => goTo(`routes/${row.id}`)}
         getRowId={(row) => row.id}
+        emptyIllustration="empty-data"
+        emptyTitle="No routes yet"
+        emptyDescription="Create a route to batch deliveries into an optimized driving plan."
+        emptyAction={
+          <Button onClick={() => goTo('routes/new')}>
+            <Plus size={16} className="mr-1.5" />
+            Create Route
+          </Button>
+        }
       />
     </PageLayout>
   );

package/src/movethewheels/pages/SettingsPage.tsx

@@ -2,6 +2,7 @@
  * Settings Page
  */
 
+import { useState } from 'react';
 import { Settings, User, Bell, Shield, Globe, Webhook, Save } from 'lucide-react';
 import { PageLayout } from '../components/PageLayout';
 import {
@@ -24,15 +25,59 @@ import {
   TabsTrigger,
   TabsContent,
 } from '../components/ui';
+import { EmphasisPanel, PagePurpose, NextSteps } from '@burdenoff/fe-libs/ui';
 
 export default function SettingsPage() {
+  const [tab, setTab] = useState('general');
+
   return (
     <PageLayout
       title="Settings"
       subtitle="Manage your account and preferences"
       icon={<Settings size={24} />}
     >
-      <Tabs defaultValue="general">
+      <PagePurpose icon={<Settings size={18} />}>
+        Configure how MoveTheWheels works for your business — company details and localization,
+        which notifications you receive, account security, and the integrations (maps, payments,
+        messaging) that power deliveries. Set these once so the rest of the app behaves the way you
+        expect.
+      </PagePurpose>
+
+      <NextSteps
+        storageKey="movethewheels-settings"
+        steps={[
+          {
+            id: 'company',
+            label: 'Confirm company details & localization',
+            description: 'Set your name, contact info, timezone, currency and language.',
+            icon: <User size={16} />,
+            onClick: () => setTab('general'),
+          },
+          {
+            id: 'notifications',
+            label: 'Choose your notifications',
+            description: 'Decide which order, delivery and report emails you receive.',
+            icon: <Bell size={16} />,
+            onClick: () => setTab('notifications'),
+          },
+          {
+            id: 'security',
+            label: 'Secure your account',
+            description: 'Update your password and enable two-factor authentication.',
+            icon: <Shield size={16} />,
+            onClick: () => setTab('security'),
+          },
+          {
+            id: 'integrations',
+            label: 'Connect your tools',
+            description: 'Link maps, payments and messaging providers.',
+            icon: <Webhook size={16} />,
+            onClick: () => setTab('integrations'),
+          },
+        ]}
+      />
+
+      <Tabs value={tab} onValueChange={setTab}>
         <TabsList className="mb-6">
           <TabsTrigger value="general">
             <User size={16} /> General
@@ -49,32 +94,29 @@ export default function SettingsPage() {
         </TabsList>
 
         <TabsContent value="general" className="space-y-6">
-          <Card>
-            <CardHeader>
-              <CardTitle>Company Information</CardTitle>
-              <CardDescription>Basic company details</CardDescription>
-            </CardHeader>
-            <CardContent className="space-y-4">
-              <div className="grid grid-cols-2 gap-4">
-                <div>
-                  <Label>Company Name</Label>
-                  <Input defaultValue="QuickLogistics Pro" />
-                </div>
-                <div>
-                  <Label>Contact Email</Label>
-                  <Input defaultValue="contact@quicklogistics.com" />
-                </div>
-                <div>
-                  <Label>Phone</Label>
-                  <Input defaultValue="+1-555-QUICK" />
-                </div>
-                <div>
-                  <Label>Website</Label>
-                  <Input defaultValue="https://quicklogistics.com" />
-                </div>
+          {/* Company Information — the page's single emphasis zone */}
+          <EmphasisPanel>
+            <h2 className="text-base font-semibold text-text-primary">Company Information</h2>
+            <p className="text-sm text-text-secondary mb-4">Basic company details</p>
+            <div className="grid grid-cols-2 gap-4">
+              <div>
+                <Label>Company Name</Label>
+                <Input defaultValue="QuickLogistics Pro" />
               </div>
-            </CardContent>
-          </Card>
+              <div>
+                <Label>Contact Email</Label>
+                <Input defaultValue="contact@quicklogistics.com" />
+              </div>
+              <div>
+                <Label>Phone</Label>
+                <Input defaultValue="+1-555-QUICK" />
+              </div>
+              <div>
+                <Label>Website</Label>
+                <Input defaultValue="https://quicklogistics.com" />
+              </div>
+            </div>
+          </EmphasisPanel>
 
           <Card>
             <CardHeader>

package/src/movethewheels/pages/TrackingPage.tsx

@@ -10,6 +10,7 @@ import { MapPin, Search, Package, Truck, Clock, CheckCircle, AlertCircle } from
 import { PageLayout, EmptyState } from '../components/PageLayout';
 import { StatusBadge } from '../components/StatusBadge';
 import { Card, CardContent, CardHeader, CardTitle, Button, Input } from '../components/ui';
+import { EmphasisPanel, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { useOrderTracking } from '../hooks/useTracking';
 import { formatDate, formatAddress } from '../utils/formatters';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
@@ -56,6 +57,13 @@ export default function TrackingPage() {
         </Button>
       }
     >
+      <PagePurpose icon={<MapPin size={18} />}>
+        {t(
+          'movethewheels.tracking.purpose',
+          'Look up any single shipment by its tracking number or order ID to see exactly where it is, its progress through pickup and delivery, the current location and any alerts — the same view you can share with a customer.'
+        )}
+      </PagePurpose>
+
       {/* Search Form */}
       <Card>
         <CardContent className="p-6">
@@ -120,55 +128,50 @@ export default function TrackingPage() {
         <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
           {/* Main Tracking Info */}
           <div className="lg:col-span-2 space-y-6">
-            {/* Status Card */}
-            <Card>
-              <CardHeader>
-                <div className="flex items-center justify-between">
-                  <CardTitle className="flex items-center gap-2">
-                    <Package size={20} />
-                    {t('movethewheels.tracking.orderLabel', 'Order')} {order.orderNumber}
-                  </CardTitle>
-                  <StatusBadge status={order.status} type="order" />
+            {/* Status Card — the page's single emphasis zone */}
+            <EmphasisPanel>
+              <div className="flex items-center justify-between mb-4">
+                <h2 className="flex items-center gap-2 text-base font-semibold text-text-primary">
+                  <Package size={20} />
+                  {t('movethewheels.tracking.orderLabel', 'Order')} {order.orderNumber}
+                </h2>
+                <StatusBadge status={order.status} type="order" />
+              </div>
+              <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+                <div>
+                  <p className="text-sm text-text-secondary">
+                    {t('movethewheels.tracking.details.trackingNumber', 'Tracking Number')}
+                  </p>
+                  <p className="font-mono font-medium">{order.trackingNumber}</p>
                 </div>
-              </CardHeader>
-              <CardContent>
-                <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
-                  <div>
-                    <p className="text-sm text-text-secondary">
-                      {t('movethewheels.tracking.details.trackingNumber', 'Tracking Number')}
-                    </p>
-                    <p className="font-mono font-medium">{order.trackingNumber}</p>
-                  </div>
-                  <div>
-                    <p className="text-sm text-text-secondary">
-                      {t('movethewheels.tracking.details.estimatedDelivery', 'Estimated Delivery')}
-                    </p>
-                    <p className="font-medium">
-                      {tracking.estimatedArrival
-                        ? formatDate(tracking.estimatedArrival, 'full')
-                        : order.scheduledDelivery
-                          ? formatDate(order.scheduledDelivery, 'full')
-                          : t('movethewheels.tracking.details.tbd', 'TBD')}
-                    </p>
-                  </div>
-                  <div>
-                    <p className="text-sm text-text-secondary">
-                      {t('movethewheels.tracking.details.items', 'Items')}
-                    </p>
-                    <p className="font-medium">
-                      {order.items.length}{' '}
-                      {t('movethewheels.tracking.details.itemsSuffix', 'items')}
-                    </p>
-                  </div>
-                  <div>
-                    <p className="text-sm text-text-secondary">
-                      {t('movethewheels.tracking.details.lastUpdated', 'Last Updated')}
-                    </p>
-                    <p className="font-medium">{formatDate(tracking.lastUpdated, 'relative')}</p>
-                  </div>
+                <div>
+                  <p className="text-sm text-text-secondary">
+                    {t('movethewheels.tracking.details.estimatedDelivery', 'Estimated Delivery')}
+                  </p>
+                  <p className="font-medium">
+                    {tracking.estimatedArrival
+                      ? formatDate(tracking.estimatedArrival, 'full')
+                      : order.scheduledDelivery
+                        ? formatDate(order.scheduledDelivery, 'full')
+                        : t('movethewheels.tracking.details.tbd', 'TBD')}
+                  </p>
                 </div>
-              </CardContent>
-            </Card>
+                <div>
+                  <p className="text-sm text-text-secondary">
+                    {t('movethewheels.tracking.details.items', 'Items')}
+                  </p>
+                  <p className="font-medium">
+                    {order.items.length} {t('movethewheels.tracking.details.itemsSuffix', 'items')}
+                  </p>
+                </div>
+                <div>
+                  <p className="text-sm text-text-secondary">
+                    {t('movethewheels.tracking.details.lastUpdated', 'Last Updated')}
+                  </p>
+                  <p className="font-medium">{formatDate(tracking.lastUpdated, 'relative')}</p>
+                </div>
+              </div>
+            </EmphasisPanel>
 
             {/* Progress Timeline */}
             <Card>

package/src/movethewheels/pages/VehicleDetailsPage.tsx

@@ -15,6 +15,7 @@ import {
   Badge,
   Progress,
 } from '../components/ui';
+import { EmphasisPanel, NextSteps, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { useVehicle } from '../hooks/useFleet';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate } from '../utils/formatters';
@@ -26,6 +27,7 @@ export default function VehicleDetailsPage() {
   const { vehicle, isLoading, error, refetch } = useVehicle(vehicleId);
 
   const goBack = () => navigate?.(joinPath(basePath, 'fleet/vehicles'));
+  const goTo = (path: string) => navigate?.(joinPath(basePath, path));
 
   if (isLoading) return <LoadingState message="Loading vehicle details..." />;
   if (error || !vehicle) return <ErrorState title="Vehicle not found" onRetry={refetch} />;
@@ -52,33 +54,56 @@ export default function VehicleDetailsPage() {
         </div>
       }
     >
+      <PagePurpose icon={<Truck size={18} />}>
+        The full record for this vehicle — specs, capacity, fuel and mileage, maintenance schedule
+        and current location. Use it to confirm a vehicle is fuelled, serviced and the right size
+        before dispatching it on a delivery.
+      </PagePurpose>
+
+      <NextSteps
+        storageKey="movethewheels-vehicle-details"
+        steps={[
+          {
+            id: 'assign',
+            label: 'Assign to a delivery',
+            description: 'Put this vehicle on an order that fits its capacity.',
+            icon: <MapPin size={16} />,
+            onClick: () => goTo('orders'),
+          },
+          {
+            id: 'maintenance',
+            label: 'Schedule maintenance',
+            description: 'Keep it road-ready and compliant.',
+            icon: <Wrench size={16} />,
+            onClick: () => {},
+          },
+        ]}
+      />
+
       <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
         <div className="lg:col-span-2 space-y-6">
-          <Card>
-            <CardHeader>
-              <CardTitle>Vehicle Information</CardTitle>
-            </CardHeader>
-            <CardContent>
-              <div className="grid grid-cols-2 md:grid-cols-4 gap-6">
-                <div>
-                  <p className="text-sm text-text-secondary">Type</p>
-                  <p className="font-medium capitalize">{vehicle.type}</p>
-                </div>
-                <div>
-                  <p className="text-sm text-text-secondary">Make</p>
-                  <p className="font-medium">{vehicle.make}</p>
-                </div>
-                <div>
-                  <p className="text-sm text-text-secondary">Model</p>
-                  <p className="font-medium">{vehicle.model}</p>
-                </div>
-                <div>
-                  <p className="text-sm text-text-secondary">Year</p>
-                  <p className="font-medium">{vehicle.year}</p>
-                </div>
+          {/* Vehicle Information — the page's single emphasis zone */}
+          <EmphasisPanel>
+            <h2 className="text-base font-semibold text-text-primary mb-4">Vehicle Information</h2>
+            <div className="grid grid-cols-2 md:grid-cols-4 gap-6">
+              <div>
+                <p className="text-sm text-text-secondary">Type</p>
+                <p className="font-medium capitalize">{vehicle.type}</p>
               </div>
-            </CardContent>
-          </Card>
+              <div>
+                <p className="text-sm text-text-secondary">Make</p>
+                <p className="font-medium">{vehicle.make}</p>
+              </div>
+              <div>
+                <p className="text-sm text-text-secondary">Model</p>
+                <p className="font-medium">{vehicle.model}</p>
+              </div>
+              <div>
+                <p className="text-sm text-text-secondary">Year</p>
+                <p className="font-medium">{vehicle.year}</p>
+              </div>
+            </div>
+          </EmphasisPanel>
 
           <Card>
             <CardHeader>