Mobile UX consolidated pass

DESIGN.md

@@ -427,3 +427,7 @@ Kilo voice is clear, technical, calm, and direct. Use concrete verbs and specifi
 - Invent status colors, spacing values, radii, or typography roles.
 - Nest cards or use shadows as the default source of depth.
 - Depend on color, hover, placeholders, or icon shape alone to convey meaning.
+
+## Mobile (Focus palette)
+
+The mobile app (`apps/mobile/`) intentionally does not use this token contract. It ships its own light/dark palette ("Focus", FL/FD) defined as CSS variables in `apps/mobile/src/global.css`, tuned for WCAG AA contrast against its own warmer neutral surfaces. This divergence is deliberate — mobile is not expected to converge onto the tokens above.

apps/mobile/src/app/(app)/(tabs)/(1_kiloclaw)/chat/[sandbox-id]/[conversation-id].tsx

@@ -6,10 +6,13 @@ import { captureEvent, SESSION_VIEWED_EVENT } from '@/lib/analytics/posthog';
 
 import { ChatSandboxRouteMounts } from '@/components/kilo-chat/chat-sandbox-route-mounts';
 import { ConversationScreen } from '@/components/kilo-chat/conversation-screen';
+import {
+  ConversationHistoryErrorView,
+  ConversationHistoryLoadingView,
+} from '@/components/kilo-chat/conversation-history-state-views';
 import {
   getConversationRouteDecision,
   getConversationRouteErrorMessage,
-  shouldRenderConversationScreen,
 } from '@/components/kilo-chat/conversation-route-state';
 import { useConversationDetail } from '@/components/kilo-chat/hooks/use-conversations';
 import { useKiloChatClient } from '@/components/kilo-chat/hooks/use-kilo-chat-client';
@@ -29,7 +32,11 @@ export default function ChatConversationRoute() {
   const conversationDetail = useConversationDetail(client, conversationId);
   const redirectPath = chatSandboxPath(sandboxId);
   const routeDecision = getConversationRouteDecision({
-    detail: conversationDetail,
+    detail: {
+      data: conversationDetail.data,
+      error: conversationDetail.error,
+      isError: conversationDetail.isError,
+    },
     routeSandboxId: sandboxId,
   });
 
@@ -43,24 +50,28 @@ export default function ChatConversationRoute() {
   }, [conversationDetail.data, conversationId, openedVia]);
 
   useEffect(() => {
-    if (conversationDetail.isError) {
-      toast.error(getConversationRouteErrorMessage(conversationDetail.error));
-      router.replace(redirectPath);
-      return;
-    }
     if (routeDecision === 'not-found') {
       toast.error('Conversation not found');
       router.replace(redirectPath);
     }
-  }, [conversationDetail.error, conversationDetail.isError, redirectPath, routeDecision, router]);
+  }, [redirectPath, routeDecision, router]);
+
+  if (routeDecision === 'pending') {
+    return <ConversationHistoryLoadingView />;
+  }
+
+  if (routeDecision === 'retryable-error') {
+    return (
+      <ConversationHistoryErrorView
+        message={getConversationRouteErrorMessage(conversationDetail.error)}
+        onRetry={() => {
+          void conversationDetail.refetch();
+        }}
+      />
+    );
+  }
 
-  if (
-    !shouldRenderConversationScreen({
-      detail: conversationDetail,
-      routeSandboxId: sandboxId,
-    }) ||
-    !conversationDetail.data
-  ) {
+  if (routeDecision !== 'ready' || !conversationDetail.data) {
     return null;
   }
 

apps/mobile/src/app/(app)/(tabs)/(1_kiloclaw)/chat/[sandbox-id]/index.tsx

@@ -6,10 +6,13 @@ import { useAllKiloClawInstances } from '@/lib/hooks/use-instance-context';
 
 export default function ChatSandboxIndex() {
   const { 'sandbox-id': sandboxId } = useLocalSearchParams<{ 'sandbox-id': string }>();
-  const { data: instances } = useAllKiloClawInstances();
+  const { data: instances, isPending: instancesPending } = useAllKiloClawInstances();
   const instance = instances?.find(i => i.sandboxId === sandboxId);
-  const sandboxLabel =
-    instance?.botName ?? instance?.name ?? instance?.organizationName ?? 'KiloClaw';
+  // Blank until instances resolve — never show a "KiloClaw" placeholder that
+  // then flashes to the real instance name once the query settles.
+  const sandboxLabel = instancesPending
+    ? ''
+    : (instance?.botName ?? instance?.name ?? instance?.organizationName ?? 'KiloClaw');
   return (
     <>
       <ChatSandboxRouteMounts />

apps/mobile/src/app/(app)/(tabs)/(1_kiloclaw)/chat/instance-picker.tsx

@@ -1,20 +1,59 @@
 import * as Haptics from 'expo-haptics';
-import { useLocalSearchParams, useRouter } from 'expo-router';
-import { Check } from 'lucide-react-native';
-import { Pressable, ScrollView, View } from 'react-native';
+import { type Href, useLocalSearchParams, useRouter } from 'expo-router';
+import { Check, Server } from 'lucide-react-native';
+import { Pressable, View } from 'react-native';
+import Animated, { FadeIn, FadeOut } from 'react-native-reanimated';
 
 import { StatusBadge } from '@/components/kiloclaw/status-badge';
+import { EmptyState } from '@/components/empty-state';
+import { PickerSheet } from '@/components/picker-sheet';
 import { QueryError } from '@/components/query-error';
+import { Button } from '@/components/ui/button';
 import { Skeleton } from '@/components/ui/skeleton';
 import { Text } from '@/components/ui/text';
-import { useAllKiloClawInstances } from '@/lib/hooks/use-instance-context';
+import { type ClawInstance, useAllKiloClawInstances } from '@/lib/hooks/use-instance-context';
 import { useThemeColors } from '@/lib/hooks/use-theme-colors';
 import { kiloclawInstanceSwitcherTitle } from '@/lib/kiloclaw-display';
 import { chatSandboxPath } from '@/lib/kilo-chat-routes';
 
+function InstanceRow({
+  instance,
+  isCurrent,
+  onSelect,
+}: {
+  instance: ClawInstance;
+  isCurrent: boolean;
+  onSelect: (sandboxId: string) => void;
+}) {
+  const colors = useThemeColors();
+  const title = kiloclawInstanceSwitcherTitle(instance);
+  return (
+    <Pressable
+      className="mx-4 mt-3 min-h-16 flex-row items-center gap-3 rounded-xl border border-border bg-card px-4 py-3 active:bg-secondary will-change-pressable"
+      onPress={() => {
+        onSelect(instance.sandboxId);
+      }}
+      accessibilityRole="button"
+      accessibilityLabel={`${title}${isCurrent ? ', current' : ''}`}
+    >
+      <View className="min-w-0 flex-1 gap-1">
+        <Text className="text-base font-semibold text-foreground" numberOfLines={1}>
+          {title}
+        </Text>
+        <View className="flex-row flex-wrap items-center gap-x-3 gap-y-1">
+          <Text variant="muted" numberOfLines={1}>
+            {instance.organizationName ?? 'Personal'}
+          </Text>
+          <StatusBadge status={instance.status} />
+        </View>
+      </View>
+      {isCurrent ? <Check size={18} color={colors.primary} /> : null}
+    </Pressable>
+  );
+}
+
 export default function InstancePickerScreen() {
   const router = useRouter();
-  const colors = useThemeColors();
   const { currentId } = useLocalSearchParams<{ currentId: string }>();
   const instancesQuery = useAllKiloClawInstances();
   const { data: instances } = instancesQuery;
@@ -29,71 +68,62 @@ export default function InstancePickerScreen() {
     router.push(chatSandboxPath(sandboxId));
   };
 
-  return (
-    <ScrollView className="flex-1 bg-background">
-      <View className="border-b border-border px-4 pb-3 pt-4">
-        <View className="h-11 flex-row items-center justify-center">
-          <Text className="text-lg font-semibold text-foreground">Switch Instance</Text>
-          <Pressable
-            onPress={() => {
-              router.back();
-            }}
-            hitSlop={8}
-            accessibilityRole="button"
-            accessibilityLabel="Done"
-            className="absolute right-0 rounded-full bg-secondary px-4 py-2 active:opacity-70 will-change-pressable"
-          >
-            <Text className="text-base font-medium text-foreground">Done</Text>
-          </Pressable>
-        </View>
-      </View>
+  const showList = !instancesQuery.isPending && !instancesQuery.isError;
+  const loadedInstances = instances ?? [];
 
+  return (
+    <PickerSheet
+      title="Switch instance"
+      onDone={() => {
+        router.back();
+      }}
+    >
       {instancesQuery.isPending ? (
-        <View className="gap-3 px-4 py-4">
-          <Skeleton className="h-16 rounded-xl" />
-          <Skeleton className="h-16 rounded-xl" />
-          <Skeleton className="h-16 rounded-xl" />
-        </View>
+        <Animated.View exiting={FadeOut.duration(150)}>
+          <Skeleton className="mx-4 mt-3 h-16 rounded-xl" />
+          <Skeleton className="mx-4 mt-3 h-16 rounded-xl" />
+          <Skeleton className="mx-4 mt-3 h-16 rounded-xl" />
+        </Animated.View>
       ) : null}
       {instancesQuery.isError ? (
         <QueryError
           className="py-12"
-          message="Could not load instances"
+          description="Could not load instances"
           onRetry={() => {
             void instancesQuery.refetch();
           }}
         />
       ) : null}
-      {!instancesQuery.isPending && !instancesQuery.isError
-        ? (instances ?? []).map(instance => {
-            const isCurrent = instance.sandboxId === currentId;
-            const title = kiloclawInstanceSwitcherTitle(instance);
-            return (
-              <Pressable
-                key={instance.sandboxId}
-                className="mx-4 mt-3 min-h-16 flex-row items-center gap-3 rounded-xl border border-border bg-card px-4 py-3 active:bg-secondary will-change-pressable"
-                onPress={() => {
-                  handleSelect(instance.sandboxId);
-                }}
-                accessibilityRole="button"
-                accessibilityLabel={`${title}${isCurrent ? ', current' : ''}`}
-              >
-                <View className="min-w-0 flex-1 gap-1">
-                  <Text className="text-base font-semibold text-foreground" numberOfLines={1}>
-                    {title}
-                  </Text>
-                  <View className="flex-row flex-wrap items-center gap-x-3 gap-y-1">
-                    <Text variant="muted" numberOfLines={1}>
-                      {instance.organizationName ?? 'Personal'}
-                    </Text>
-                    <StatusBadge status={instance.status} />
-                  </View>
-                </View>
-                {isCurrent ? <Check size={18} color={colors.primary} /> : null}
-              </Pressable>
-            );
-          })
-        : null}
-    </ScrollView>
+      {showList && loadedInstances.length === 0 ? (
+        <EmptyState
+          className="py-12"
+          icon={Server}
+          title="No KiloClaw instances"
+          description="Set up an instance to start chatting."
+          action={
+            <Button
+              variant="outline"
+              onPress={() => {
+                router.push('/(app)/onboarding' as Href);
+              }}
+            >
+              <Text>Set up KiloClaw</Text>
+            </Button>
+          }
+        />
+      ) : null}
+      {showList ? (
+        <Animated.View entering={FadeIn.duration(200)}>
+          {loadedInstances.map(instance => (
+            <InstanceRow
+              key={instance.sandboxId}
+              instance={instance}
+              isCurrent={instance.sandboxId === currentId}
+              onSelect={handleSelect}
+            />
+          ))}
+        </Animated.View>
+      ) : null}
+    </PickerSheet>
   );
 }

apps/mobile/src/app/(app)/(tabs)/(1_kiloclaw)/index.tsx

@@ -3,8 +3,12 @@ import { useCallback, useState } from 'react';
 import { Platform, View } from 'react-native';
 import Animated, { FadeIn, FadeOut, LinearTransition } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { toast } from 'sonner-native';
 
-import { EmptyStateContent } from '@/components/kiloclaw/empty-state-content';
+import {
+  EmptyStateContent,
+  resolveAccessRequiredSubcase,
+} from '@/components/kiloclaw/empty-state-content';
 import { getKiloClawEntryDecision } from '@/components/kiloclaw/instance-entry-state';
 import { InstanceListScreen } from '@/components/kiloclaw/instance-list-screen';
 import { QueryError } from '@/components/query-error';
@@ -28,7 +32,13 @@ export default function KiloClawTab() {
   const { byBadgeBucket: unreadByBadgeBucket } = useUnreadCounts();
   const refetchInstances = instancesQuery.refetch;
   const entryDecision = getKiloClawEntryDecision(instances);
-  const onboardingQuery = useKiloClawMobileOnboardingState(entryDecision.kind === 'empty');
+  // Always enabled (not just for the empty-list case) so a personal
+  // billing/access issue is still surfaced as a card annotation when the
+  // list is non-empty — see `personalAccessIssue` below.
+  const onboardingQuery = useKiloClawMobileOnboardingState();
+  const personalAccessIssue = onboardingQuery.data
+    ? resolveAccessRequiredSubcase(onboardingQuery.data)
+    : null;
   useForegroundInvalidateKiloclawState();
 
   const showInstanceSkeleton = entryDecision.kind === 'loading' || onboardingQuery.isPending;
@@ -40,30 +50,39 @@ export default function KiloClawTab() {
     void (async () => {
       setManualRefreshing(true);
       try {
-        await refetchInstances();
+        const result = await refetchInstances();
+        if (result.isError) {
+          toast.error('Could not refresh. Showing the last saved list.');
+        }
       } finally {
         setManualRefreshing(false);
       }
     })();
   }, [refetchInstances]);
 
-  const onboardingQueryEnabled = entryDecision.kind === 'empty';
+  // A background billing-check failure while the list is already showing
+  // shouldn't blank the screen — only block on it before we have any
+  // instances to show (preserve stale/cached data).
   const hasQueryError =
-    instancesQuery.isError || (onboardingQueryEnabled && onboardingQuery.isError);
+    instancesQuery.isError || (entryDecision.kind !== 'list' && onboardingQuery.isError);
 
   if (hasQueryError) {
     return (
       <View className="flex-1 bg-background">
         <ScreenHeader title="KiloClaw" size="large" showBackButton={false} className="px-[22px]" />
-        <Animated.View entering={FadeIn.duration(200)} className="flex-1">
+        <Animated.View
+          entering={FadeIn.duration(200)}
+          className="flex-1"
+          style={emptyStateContainerStyle}
+        >
           <QueryError
             className="flex-1"
             message="Could not load KiloClaw instances"
             onRetry={() => {
               if (instancesQuery.isError) {
                 void instancesQuery.refetch();
               }
-              if (onboardingQueryEnabled && onboardingQuery.isError) {
+              if (onboardingQuery.isError) {
                 void onboardingQuery.refetch();
               }
             }}
@@ -89,6 +108,7 @@ export default function KiloClawTab() {
         onCreate={() => {
           router.push('/(app)/onboarding' as Href);
         }}
+        personalAccessIssue={personalAccessIssue}
       />
     );
   }
@@ -98,10 +118,10 @@ export default function KiloClawTab() {
       <ScreenHeader title="KiloClaw" size="large" showBackButton={false} className="px-[22px]" />
       <Animated.View layout={LinearTransition} className="flex-1 px-4">
         {showInstanceSkeleton || onboardingQuery.data === undefined ? (
-          <Animated.View exiting={FadeOut.duration(150)} className="w-full gap-3 px-4 pt-5">
-            <Skeleton className="h-16 w-full rounded-xl" />
-            <Skeleton className="h-16 w-full rounded-xl" />
-            <Skeleton className="h-16 w-full rounded-xl" />
+          <Animated.View exiting={FadeOut.duration(150)} className="w-full gap-3 pt-5">
+            <Skeleton className="h-[72px] w-full rounded-2xl" />
+            <Skeleton className="h-[72px] w-full rounded-2xl" />
+            <Skeleton className="h-[72px] w-full rounded-2xl" />
           </Animated.View>
         ) : (
           <Animated.View