feat: add theme settings screen and implement theme preference management

- Introduced ThemeSettingsScreen for user-selectable theme options (system, light, dark).
- Integrated theme preference into app state management.
- Updated TimerScreen to utilize theme colors for improved UI consistency.
- Created color definitions for light and dark themes.
- Implemented theme resolution logic based on user preference and system settings.
- Added tests for theme resolution functionality.
- Enhanced documentation to reflect new theme features and user feedback mechanisms.

Author: Lalit Sharma

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.28] — 2026-02-26
+
+### Added
+- Added a new `Settings` parent screen that links to `Theme Settings`, `Notification/Alarm Settings`, and `Location Settings`.
+- Added a dedicated `Theme Settings` screen with persisted `System`, `Light`, and `Dark` appearance options.
+- Added centralized mobile theme infrastructure (`apps/mobile/src/theme/colors.ts`, `apps/mobile/src/theme/resolveAppTheme.ts`, `apps/mobile/src/theme/useAppTheme.ts`) and app-state support for storing theme preference.
+- Added a theme-resolution regression test (`apps/mobile/tests/theme-resolution.test.ts`).
+- Added archived internal testing feedback report at `documents/reports/testing-feedback_2026-02-26.pdf`.
+
+### Changed
+- Reorganized side-menu navigation to expose a single `Settings` destination, with notification/location settings moved under the parent settings flow.
+- Wired React Navigation container theming to app preference + system appearance and updated shared/shell styling (`BurgerButton`, `Landing`, `Timer`, `Notification/Alarm Settings`, `Location Settings`) to use theme tokens for light/dark support.
+- Updated Timer favorite empty-state guidance path to `Menu > Settings > Location Settings`.
+- Updated `documents/planning/tech-debt.md` with internal testing feedback mapping and new tracked backlog items (`ADD-11`..`ADD-15`, `IMP-28`..`IMP-29`).
+- Bumped `apps/mobile` version to `1.1.28`.
+
+### Tests
+- Verified mobile checks pass after these changes: `pnpm -C apps/mobile typecheck`, `pnpm -C apps/mobile test`, and `pnpm -C apps/mobile lint`.
+
 ## [1.1.27] — 2026-02-24
 
 ### Fixed

apps/mobile/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eclipse-timer/mobile",
-  "version": "1.1.27",
+  "version": "1.1.28",
   "private": true,
   "main": "index.js",
   "scripts": {

apps/mobile/src/components/BurgerButton.tsx

@@ -1,10 +1,15 @@
+import { useMemo } from "react";
 import { Pressable, StyleSheet, View } from "react-native";
+import { useAppTheme } from "../theme/useAppTheme";
 
 type BurgerButtonProps = {
   onPress: () => void;
 };
 
 export default function BurgerButton({ onPress }: BurgerButtonProps) {
+  const { colors } = useAppTheme();
+  const styles = useMemo(() => createStyles(colors), [colors]);
+
   return (
     <Pressable
       onPress={onPress}
@@ -19,22 +24,24 @@ export default function BurgerButton({ onPress }: BurgerButtonProps) {
   );
 }
 
-const styles = StyleSheet.create({
-  button: {
-    width: 40,
-    height: 40,
-    borderRadius: 10,
-    borderWidth: 1,
-    borderColor: "#2f2f2f",
-    backgroundColor: "#171717",
-    alignItems: "center",
-    justifyContent: "center",
-    gap: 4,
-  },
-  line: {
-    width: 18,
-    height: 2,
-    borderRadius: 2,
-    backgroundColor: "white",
-  },
-});
+function createStyles(colors: ReturnType<typeof useAppTheme>["colors"]) {
+  return StyleSheet.create({
+    button: {
+      width: 40,
+      height: 40,
+      borderRadius: 10,
+      borderWidth: 1,
+      borderColor: colors.inputBorder,
+      backgroundColor: colors.surfaceMuted,
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 4,
+    },
+    line: {
+      width: 18,
+      height: 2,
+      borderRadius: 2,
+      backgroundColor: colors.textPrimary,
+    },
+  });
+}

apps/mobile/src/navigation/RootNavigator.tsx

@@ -13,6 +13,9 @@ import type {
 import {
   type LinkingOptions,
   NavigationContainer,
+  DarkTheme as NavigationDarkTheme,
+  DefaultTheme as NavigationLightTheme,
+  type Theme as NavigationTheme,
   useFocusEffect,
   useIsFocused,
   useNavigationContainerRef,
@@ -44,10 +47,13 @@ import EclipsePreviewScreen, { type PreviewPayload } from "../screens/EclipsePre
 import LandingScreen from "../screens/LandingScreen";
 import LocationSettingsScreen from "../screens/LocationSettingsScreen";
 import NotificationSettingsScreen from "../screens/NotificationSettingsScreen";
+import SettingsScreen from "../screens/SettingsScreen";
+import ThemeSettingsScreen from "../screens/ThemeSettingsScreen";
 import TimerScreen from "../screens/TimerScreen";
 import { syncWearPreviewRouteState } from "../services/wearPreviewPublisher";
 import { startWearLiveSync } from "../services/wearSync";
 import { type FavoriteLocation, useAppState } from "../state/appState";
+import { useAppTheme } from "../theme/useAppTheme";
 import { localYmdNow } from "../utils/date";
 import { kindCodeForRecord, kindLabelFromCode } from "../utils/eclipse";
 import SideMenu, { type MenuRouteName } from "./SideMenu";
@@ -58,6 +64,8 @@ type RootStackParamList = {
   Landing: undefined;
   Timer: undefined;
   Preview: { payload: PreviewPayload };
+  Settings: undefined;
+  ThemeSettings: undefined;
   NotificationSettings: undefined;
   LocationSettings: undefined;
 };
@@ -68,6 +76,8 @@ const linking: LinkingOptions<RootStackParamList> = {
     screens: {
       Landing: "landing",
       Timer: "timer",
+      Settings: "settings",
+      ThemeSettings: "settings/theme",
       NotificationSettings: "notifications",
       LocationSettings: "locations",
     },
@@ -90,6 +100,14 @@ type PreviewRouteProps = NativeStackScreenProps<RootStackParamList, "Preview"> &
   onOpenMenu: () => void;
 };
 
+type SettingsRouteProps = NativeStackScreenProps<RootStackParamList, "Settings"> & {
+  onOpenMenu: () => void;
+};
+
+type ThemeSettingsRouteProps = NativeStackScreenProps<RootStackParamList, "ThemeSettings"> & {
+  onOpenMenu: () => void;
+};
+
 type RouteWithMenuProps = {
   onOpenMenu: () => void;
 };
@@ -119,22 +137,43 @@ function filterLandingEclipses(
   });
 }
 
-function StartupLoadingScreen({ message }: { message: string }) {
+function StartupLoadingScreen({
+  message,
+  colors,
+}: {
+  message: string;
+  colors: ReturnType<typeof useAppTheme>["colors"];
+}) {
   return (
-    <View style={styles.startupSafe}>
-      <View style={styles.startupCard}>
+    <View style={[styles.startupSafe, { backgroundColor: colors.background }]}>
+      <View
+        style={[
+          styles.startupCard,
+          {
+            backgroundColor: colors.surface,
+            borderColor: colors.border,
+          },
+        ]}
+      >
         <Image source={APP_LOGO} style={styles.startupLogo} resizeMode="contain" />
         <ActivityIndicator />
-        <Text style={styles.startupTitle}>Eclipse Timer</Text>
-        <Text style={styles.startupSubtitle}>{message}</Text>
+        <Text style={[styles.startupTitle, { color: colors.textPrimary }]}>Eclipse Timer</Text>
+        <Text style={[styles.startupSubtitle, { color: colors.textMuted }]}>{message}</Text>
       </View>
     </View>
   );
 }
 
 function toMenuRouteName(route: keyof RootStackParamList): MenuRouteName | null {
   if (route === "Landing" || route === "Timer") return route;
-  if (route === "NotificationSettings" || route === "LocationSettings") return route;
+  if (
+    route === "Settings" ||
+    route === "ThemeSettings" ||
+    route === "NotificationSettings" ||
+    route === "LocationSettings"
+  ) {
+    return "Settings";
+  }
   return null;
 }
 
@@ -425,6 +464,29 @@ function PreviewRoute({ navigation, route, onOpenMenu }: PreviewRouteProps) {
   );
 }
 
+function SettingsRoute({ navigation, onOpenMenu }: SettingsRouteProps) {
+  return (
+    <SettingsScreen
+      onOpenMenu={onOpenMenu}
+      onOpenThemeSettings={() => navigation.navigate("ThemeSettings")}
+      onOpenNotificationSettings={() => navigation.navigate("NotificationSettings")}
+      onOpenLocationSettings={() => navigation.navigate("LocationSettings")}
+    />
+  );
+}
+
+function ThemeSettingsRoute({ onOpenMenu }: ThemeSettingsRouteProps) {
+  const { state, actions } = useAppState();
+
+  return (
+    <ThemeSettingsScreen
+      onOpenMenu={onOpenMenu}
+      preference={state.themePreference}
+      onSetThemePreference={actions.setThemePreference}
+    />
+  );
+}
+
 function NotificationSettingsRoute({ onOpenMenu }: RouteWithMenuProps) {
   const { state, actions } = useAppState();
 
@@ -456,11 +518,33 @@ function LocationSettingsRoute({ onOpenMenu }: RouteWithMenuProps) {
 
 export default function RootNavigator() {
   const { state: appState, actions } = useAppState();
+  const { colors, resolvedTheme } = useAppTheme();
   const navigationRef = useNavigationContainerRef<RootStackParamList>();
   const pendingFeaturedDeepLinkActionRef = useRef<FeaturedEclipseDeepLinkAction | null>(null);
   const [catalog, setCatalog] = useState<EclipseRecord[] | null>(null);
   const [isMenuOpen, setIsMenuOpen] = useState(false);
   const [currentRouteName, setCurrentRouteName] = useState<keyof RootStackParamList>("Landing");
+  const navigationTheme = useMemo<NavigationTheme>(() => {
+    const base = resolvedTheme === "light" ? NavigationLightTheme : NavigationDarkTheme;
+    return {
+      ...base,
+      colors: {
+        ...base.colors,
+        primary: colors.primary,
+        background: colors.background,
+        card: colors.surface,
+        border: colors.border,
+        text: colors.textPrimary,
+      },
+    };
+  }, [
+    colors.background,
+    colors.border,
+    colors.primary,
+    colors.surface,
+    colors.textPrimary,
+    resolvedTheme,
+  ]);
 
   useNotificationScheduler(
     appState.notificationSettings,
@@ -628,13 +712,14 @@ export default function RootNavigator() {
   }, [handleIncomingUrl]);
 
   if (!catalog) {
-    return <StartupLoadingScreen message="Loading eclipse catalog..." />;
+    return <StartupLoadingScreen message="Loading eclipse catalog..." colors={colors} />;
   }
 
   return (
     <NavigationContainer
       ref={navigationRef}
       linking={linking}
+      theme={navigationTheme}
       onReady={onNavigationReady}
       onStateChange={syncWearPreviewWithRoute}
     >
@@ -649,6 +734,12 @@ export default function RootNavigator() {
           <Stack.Screen name="Preview">
             {(props) => <PreviewRoute {...props} onOpenMenu={openMenu} />}
           </Stack.Screen>
+          <Stack.Screen name="Settings">
+            {(props) => <SettingsRoute {...props} onOpenMenu={openMenu} />}
+          </Stack.Screen>
+          <Stack.Screen name="ThemeSettings">
+            {(props) => <ThemeSettingsRoute {...props} onOpenMenu={openMenu} />}
+          </Stack.Screen>
           <Stack.Screen name="NotificationSettings">
             {() => <NotificationSettingsRoute onOpenMenu={openMenu} />}
           </Stack.Screen>