Add dark mode support

[aidandaly24]

Description

We need to add dark mode support to the CLI dashboard. The colors should be configurable and respect system preferences.

Requirements

• Add light and dark color palettes
• Create a ThemeContext for managing theme state
• Detect system color scheme preference
• Allow users to configure theme preference (light/dark/system)
• Update components to use theme-aware colors

Labels

enhancement, ui

[aidandaly24]

I have extensive context from the previous exploration. Let me review a few more files to complete my understanding before writing the plan.

[MEMORY: repo] TypeScript CLI for AWS AgentCore using Ink (React terminal UI), Commander.js, vitest. TUI in src/cli/tui/.
[MEMORY: issue] Need dark mode support: light/dark palettes, ThemeContext, system preference detection, user config (light/dark/system), update components to use theme-aware colors.
[MEMORY: pattern] Existing theme.ts has static color constants (STATUS_COLORS, INTERACTIVE_COLORS, TEXT_COLORS, THEME). Most components use hardcoded color strings ('cyan', 'green', 'red', etc.) instead of the THEME object. Context pattern exists in context/LayoutContext.tsx. App.tsx wraps in <LayoutProvider>.

Let me check a few remaining files I need for the plan:[MEMORY: pattern] AwsTargetConfigUI.tsx imports INTERACTIVE_COLORS from theme. So the theme.ts imports are: StepProgress.tsx (STATUS_COLORS, TEXT_COLORS), NextSteps.tsx (STATUS_COLORS), AwsTargetConfigUI.tsx (INTERACTIVE_COLORS), and src/cli/commands/status/constants.ts (STATUS_COLORS).

Now I have a complete picture. Let me also check a few screen files to see if they use colors:I now have a comprehensive understanding of the entire codebase. Let me write the implementation plan.

---

Implementation Plan: Add Dark Mode Support (Issue #2)

Summary

The CLI dashboard uses Ink (React for terminal) with a TUI layer in src/cli/tui/. Currently, colors are defined in a static theme.ts file with STATUS_COLORS, INTERACTIVE_COLORS, and TEXT_COLORS constants. However, most components (~25+) use hardcoded color strings ('cyan', 'green', 'red', etc.) directly in JSX rather than referencing the theme.

This plan introduces:

1. Light and dark color palettes in theme.ts
2. A ThemeContext (React context + provider) for managing theme state
3. System color scheme detection via COLORFGBG env var (standard terminal convention)
4. A useTheme() hook for components to access the active palette
5. User-configurable theme preference (light / dark / system)
6. Migration of all components from hardcoded colors to theme-aware colors

Files to Modify

New Files

1. src/cli/tui/context/ThemeContext.tsx — ThemeContext, ThemeProvider, useTheme() hook
2. src/cli/tui/context/__tests__/ThemeContext.test.tsx — Tests for ThemeContext

Modified Files (Core Theme Infrastructure)

3. src/cli/tui/theme.ts — Add ColorPalette type, light/dark palettes, system detection, getThemePreference()/setThemePreference() persistence
4. src/cli/tui/context/index.ts — Export ThemeContext, ThemeProvider, useTheme
5. src/cli/tui/App.tsx — Wrap <AppContent> in <ThemeProvider>

Modified Files (Components — update to use useTheme())

6. src/cli/tui/components/Cursor.tsx — Replace hardcoded "white"/"black" with theme colors
7. src/cli/tui/components/DeployStatus.tsx — Replace "cyan", "green", "gray", "red" with theme colors
8. src/cli/tui/components/DiffSummaryView.tsx — Replace "cyan", "green", "yellow", "red" with theme colors
9. src/cli/tui/components/FatalError.tsx — Replace "red", "blue" with theme colors
10. src/cli/tui/components/FullScreenLogView.tsx — Replace LOG_COLORS map and hardcoded colors with theme
11. src/cli/tui/components/LogPanel.tsx — Replace LOG_COLORS map with theme
12. src/cli/tui/components/MultiSelectList.tsx — Replace "cyan", "green" with theme
13. src/cli/tui/components/NextSteps.tsx — Already uses STATUS_COLORS; update to use useTheme()
14. src/cli/tui/components/PathInput.tsx — Replace hardcoded colors with theme
15. src/cli/tui/components/ResourceGraph.tsx — Replace many hardcoded colors with theme
16. src/cli/tui/components/Screen.tsx — No direct color usage (delegates to ScreenHeader)
17. src/cli/tui/components/ScreenHeader.tsx — Replace default color='cyan' with theme
18. src/cli/tui/components/ScrollableList.tsx — Replace "gray" scrollbar color with theme
19. src/cli/tui/components/ScrollableText.tsx — Replace "gray" scrollbar color with theme
20. src/cli/tui/components/SecretInput.tsx — Replace "cyan", "green", "red" with theme
21. src/cli/tui/components/SelectList.tsx — Replace "cyan" with theme
22. src/cli/tui/components/SelectScreen.tsx — No direct color usage (delegates)
23. src/cli/tui/components/StepIndicator.tsx — Replace "cyan", "green", "gray" with theme
24. src/cli/tui/components/StepProgress.tsx — Already uses STATUS_COLORS/TEXT_COLORS; update to useTheme()
25. src/cli/tui/components/TextInput.tsx — Replace "cyan", "green", "red" with theme
26. src/cli/tui/components/AwsTargetConfigUI.tsx — Already uses INTERACTIVE_COLORS; update to useTheme()
27. src/cli/tui/components/LogLink.tsx — Replace "gray", "cyan" with theme
28. src/cli/tui/components/CredentialSourcePrompt.tsx — Replace "cyan" with theme

Modified Files (Screens — update to use useTheme())

29. src/cli/tui/screens/home/HomeScreen.tsx — Replace "cyan", "yellow" with theme
30. src/cli/tui/screens/home/HelpScreen.tsx — Replace "cyan", "white", "yellow" with theme
31. src/cli/tui/guards/project.tsx — Replace "red", "blue" with theme

Modified Files (External theme consumers)

32. src/cli/commands/status/constants.ts — This file imports STATUS_COLORS from theme; keep working since STATUS_COLORS will remain as the "dark" default (backward compatible)

Implementation Approach

Step 1: Define Color Palette Types and Palettes in theme.ts

File: src/cli/tui/theme.ts

Expand the existing file to define:

/** Theme preference options */
export type ThemePreference = 'light' | 'dark' | 'system';

/** Complete color palette for a theme mode */
export interface ColorPalette {
  status: {
    success: string;
    error: string;
    warning: string;
    info: string;
    pending: string;
  };
  interactive: {
    selection: string;
    cursor: string;
    highlight: string;
  };
  text: {
    primary: string;
    muted: string;
    directory: string;
  };
  /** Cursor component colors */
  cursor: {
    background: string;
    foreground: string;
  };
  /** Semantic UI colors */
  ui: {
    border: string;
    accent: string;
    link: string;
  };
}

Define two palettes:

• DARK_PALETTE: Essentially the current colors (white text on dark bg) — primary: 'white', muted: 'gray', selection: 'cyan', cursor.background: 'white', cursor.foreground: 'black', etc.
• LIGHT_PALETTE: Inverted for light terminals — primary: 'black', muted: 'gray', selection: 'blue', cursor.background: 'black', cursor.foreground: 'white', etc. Adjust status colors for readability on light backgrounds (e.g., use darker green, darker red).

Keep the existing STATUS_COLORS, INTERACTIVE_COLORS, TEXT_COLORS, and THEME exports as-is for backward compatibility (they'll point to dark palette values). This ensures src/cli/commands/status/constants.ts continues to work without changes.

Add a system detection function:

/**
 * Detect system color scheme preference from terminal environment.
 * Uses COLORFGBG env var (format: "fg;bg") — bg >= 8 suggests dark terminal.
 * Falls back to 'dark' as most terminals are dark by default.
 */
export function detectSystemColorScheme(): 'light' | 'dark' {
  const colorfgbg = process.env['COLORFGBG'];
  if (colorfgbg) {
    const parts = colorfgbg.split(';');
    const bg = parseInt(parts[parts.length - 1] ?? '', 10);
    // Background color index: 0-6 are dark colors, 7+ are light
    if (!isNaN(bg) && bg >= 7 && bg <= 14) {
      // Light background (7=white, 8-14 are bright colors)
      // Actually: 0-6 dark, 7 = light gray (light), 8 = dark gray (dark), 9-14 bright (light)
      // Standard: bg < 7 = dark, bg === 7 or bg >= 9 = light
      return bg === 8 ? 'dark' : 'light';
    }
  }
  return 'dark';
}

Add helper to resolve palette from preference:

export function resolveColorPalette(preference: ThemePreference): ColorPalette {
  if (preference === 'system') {
    return detectSystemColorScheme() === 'light' ? LIGHT_PALETTE : DARK_PALETTE;
  }
  return preference === 'light' ? LIGHT_PALETTE : DARK_PALETTE;
}

Step 2: Create ThemeContext

File: src/cli/tui/context/ThemeContext.tsx

Create a React context that:

• Holds the current ThemePreference and resolved ColorPalette
• Provides a setThemePreference() function to change the preference
• Exposes a useTheme() hook that returns { colors: ColorPalette, preference: ThemePreference, setPreference: (p: ThemePreference) => void }

import { type ColorPalette, type ThemePreference, resolveColorPalette } from '../theme';
import React, { type ReactNode, createContext, useCallback, useContext, useState } from 'react';

interface ThemeContextValue {
  colors: ColorPalette;
  preference: ThemePreference;
  setPreference: (preference: ThemePreference) => void;
}

const ThemeContext = createContext<ThemeContextValue>({
  colors: resolveColorPalette('system'),
  preference: 'system',
  setPreference: () => {},
});

export function useTheme(): ThemeContextValue {
  return useContext(ThemeContext);
}

interface ThemeProviderProps {
  children: ReactNode;
  initialPreference?: ThemePreference;
}

export function ThemeProvider({ children, initialPreference = 'system' }: ThemeProviderProps) {
  const [preference, setPreferenceState] = useState<ThemePreference>(initialPreference);
  const colors = resolveColorPalette(preference);

  const setPreference = useCallback((newPreference: ThemePreference) => {
    setPreferenceState(newPreference);
  }, []);

  return (
    <ThemeContext.Provider value={{ colors, preference, setPreference }}>
      {children}
    </ThemeContext.Provider>
  );
}

Step 3: Update Context Exports

File: src/cli/tui/context/index.ts

Add exports:

export { LayoutProvider, useLayout, buildLogo } from './LayoutContext';
export { ThemeProvider, useTheme } from './ThemeContext';

Step 4: Wire ThemeProvider into App.tsx

File: src/cli/tui/App.tsx

Wrap the existing <LayoutProvider> with <ThemeProvider>:

import { LayoutProvider, ThemeProvider } from './context';

export function App() {
  return (
    <ThemeProvider>
      <LayoutProvider>
        <AppContent />
      </LayoutProvider>
    </ThemeProvider>
  );
}

Step 5: Update Components to Use useTheme()

For each component, the pattern is:

1. Import useTheme from the context
2. Call const { colors } = useTheme(); at the top of the component
3. Replace hardcoded color strings with colors.status.success, colors.interactive.selection, colors.text.primary, etc.

Detailed mapping of hardcoded colors → palette properties:

Hardcoded Color	Semantic Meaning	Palette Path
'cyan' (selection/accent)	Interactive selection, accent	colors.interactive.selection
'cyan' (links)	Link color	colors.ui.link
'green' (success)	Success status	colors.status.success
'red' (error)	Error status	colors.status.error
'yellow' (warning)	Warning status	colors.status.warning
'blue' (info/directory)	Info, directory, commands	colors.text.directory / colors.status.info
'gray' (muted)	Muted/secondary text	colors.text.muted
'white' (primary text)	Primary text	colors.text.primary
'white' (cursor bg)	Cursor background	colors.cursor.background
'black' (cursor fg)	Cursor foreground	colors.cursor.foreground
'magenta' (gateway)	Keep as-is (semantic resource color)	Keep hardcoded or add to palette
'gray' (border)	Border color	colors.ui.border

Key component changes (examples):

• Cursor.tsx (line ~27): backgroundColor="white" color="black" → backgroundColor={colors.cursor.background} color={colors.cursor.foreground}
• SelectList.tsx (line ~28): color={selected && !disabled ? 'cyan' : undefined} → color={selected && !disabled ? colors.interactive.selection : undefined}
• ScreenHeader.tsx (line ~12): color = 'cyan' default → color = colors.interactive.selection (but since it's a default prop, use useTheme() inside the component and apply if no color prop is passed)
• StepProgress.tsx: Replace TEXT_COLORS.muted / TEXT_COLORS.primary / STATUS_COLORS.* with colors.text.muted / colors.text.primary / colors.status.*
• DeployStatus.tsx: Replace ProgressBar colors ("cyan", "green", "gray") and status colors with theme equivalents
• ResourceGraph.tsx: Replace hardcoded resource type colors. Keep semantic resource colors (green=agent, blue=memory, yellow=credential, magenta=gateway) but source them from the palette or keep as-is since they're semantic, not theme-dependent. Replace "white" section headers and "gray" muted text with theme colors.
• HomeScreen.tsx: Replace "cyan" logo color, "yellow" warning, "cyan" accent with theme colors
• HelpScreen.tsx: Replace "cyan" header/selection, "white" non-selected items with theme colors

Important: For components that are not React components (pure functions like getStatusColor in DeployStatus.tsx or ResourceGraph.tsx), they cannot use hooks. These should accept a ColorPalette parameter or keep using the static constants for backward compatibility.

For non-component functions like getStatusColor() in ResourceGraph.tsx and DeployStatus.tsx, pass the palette as a parameter from the calling component.

Step 6: Handle Non-Component Color References

src/cli/commands/status/constants.ts: This file imports STATUS_COLORS from theme. Since we're keeping the existing static exports as backward-compatible aliases (pointing to dark palette), this file needs no changes. The colors will be correct for dark mode. For full theme support in this file, it would need to be refactored to accept a palette, but that's a larger change that can be deferred.

Step 7: Write Tests

File: src/cli/tui/context/__tests__/ThemeContext.test.tsx

Test cases:

1. useTheme() returns default colors when no provider (system preference)
2. ThemeProvider with initialPreference='dark' provides dark palette
3. ThemeProvider with initialPreference='light' provides light palette
4. ThemeProvider with initialPreference='system' detects system preference
5. setPreference() updates the active palette
6. detectSystemColorScheme() returns 'dark' when COLORFGBG is not set
7. detectSystemColorScheme() returns 'light' when COLORFGBG indicates light background
8. detectSystemColorScheme() returns 'dark' when COLORFGBG indicates dark background
9. resolveColorPalette() returns correct palette for each preference
10. Light and dark palettes have the same shape (all keys present)

File: src/cli/tui/theme.ts tests — Add tests for detectSystemColorScheme and resolveColorPalette as pure function tests (can be in a new src/cli/tui/__tests__/theme.test.ts).

Edge Cases & Risks

1. Backward compatibility of static exports: The existing STATUS_COLORS, INTERACTIVE_COLORS, TEXT_COLORS, and THEME exports in theme.ts must remain unchanged to avoid breaking src/cli/commands/status/constants.ts and any other consumers. They will continue to represent the dark palette values.

2. Non-component color usage: Functions like getStatusColor() in ResourceGraph.tsx and DeployStatus.tsx can't use React hooks. Solution: pass the palette from the parent component, or keep using static constants for these utility functions.

3. dimColor prop: Many components use Ink's dimColor prop which is theme-independent (it dims whatever color is set). This should continue to work correctly with both palettes.

4. Terminal compatibility: Light palette colors must be chosen carefully. On light terminals, 'white' text is invisible. The light palette should use 'black' for primary text. Similarly, 'yellow' may be hard to read on light backgrounds — consider using '#B8860B' (dark goldenrod) or keeping 'yellow' since Ink maps it to the terminal's yellow which is usually readable.

5. COLORFGBG detection: Not all terminals set this env var. The fallback to 'dark' is safe since most developer terminals use dark themes. The 'system' preference gracefully degrades.

6. Snapshot tests: The src/assets/ snapshot tests are for template files, not TUI components, so they should not be affected.

7. Existing test assertions: Some tests check for specific text content (e.g., lastFrame().toContain('Deploy')). These should not break since we're only changing color attributes, not text content. Tests that check for specific color values in rendered output (if any) may need updating.

8. Resource-type semantic colors (green=agent, blue=memory, yellow=credential, magenta=gateway in ResourceGraph.tsx): These are semantic and should remain consistent across themes. They can stay hardcoded or be added to the palette as resources.agent, resources.memory, etc.

Testing Strategy

1. Unit tests for theme utilities (src/cli/tui/__tests__/theme.test.ts):

   • detectSystemColorScheme() with various COLORFGBG values
   • resolveColorPalette() for each preference
   • Palette shape validation (both palettes have identical keys)

2. Unit tests for ThemeContext (src/cli/tui/context/__tests__/ThemeContext.test.tsx):

   • Default context values
   • Provider with different initial preferences
   • setPreference state updates
   • useTheme() hook returns correct values

3. Existing component tests: Run npm test to verify all existing tests pass. Since tests check text content (not colors), they should pass without modification. If any tests assert on color values, update them to use theme-aware expectations.

4. Manual verification:

   • Run npx tsx src/cli/index.ts in a dark terminal → verify dark palette
   • Set COLORFGBG=0;15 and run → verify light palette detection
   • Test all three preferences: light, dark, system

5. Build verification: Run npm run build and npm run typecheck to ensure no TypeScript errors.

6. Lint verification: Run npm run lint to ensure no ESLint violations (especially no any types).