feat: Themes

.kiro/specs/dynamic-theming/design.md

@@ -0,0 +1,168 @@
+# Design Document
+
+## Overview
+
+The dynamic theming system will extract color values from the existing style.css file and create a modular theme architecture. The system will use CSS custom properties (CSS variables) to enable runtime theme switching without page reloads. The architecture will consist of theme definition files, a theme manager service, and a user interface for theme selection.
+
+## Architecture
+
+### Theme Structure
+- **Theme Files**: CSS files containing CSS custom property definitions for each theme
+- **Base Variables**: Core CSS custom properties that all themes implement
+- **Theme Manager**: TypeScript service that handles theme loading and switching
+- **Theme UI**: Interface component for theme selection and preview
+
+### File Organization
+```
+public/assets/themes/
+├── base-variables.css    # Base CSS custom properties structure
+├── default.css          # Default theme extracted from current colors
+└── [future-themes].css  # Additional themes (e.g., dark.css, light.css)
+
+src/lib/
+└── theme-manager.ts      # Theme management service
+
+src/modals/
+└── theme-selector.ts     # Theme selection modal
+```
+
+## Components and Interfaces
+
+### Theme CSS Structure
+Each theme CSS file will define the same set of CSS custom properties:
+```css
+/* Example: default.css */
+:root {
+  /* Background colors */
+  --color-body-background: #eee;
+  --color-outliner-background: #fff;
+  --color-modal-background: #fff;
+
+  /* Text colors */
+  --color-primary-text: #222;
+  --color-secondary-text: #aaa;
+  --color-link: #098bd9;
+  --color-link-visited: #b26be4;
+
+  /* Interactive states */
+  --color-cursor-background: #000;
+  --color-cursor-text: #fff;
+  --color-selected-background: #000;
+  --color-selected-text: #fff;
+
+  /* UI elements */
+  --color-border: #ddd;
+  --color-button-background: #eee;
+  --color-button-hover: #f4f4f4;
+
+  /* Specialized elements */
+  --color-date-header-background: #547883;
+  --color-table-header-background: #666;
+  --color-strikethrough: #808080;
+  --color-code-background: #eee;
+}
+```
+
+### Theme Metadata Structure
+Theme metadata will be embedded in CSS file headers using comments:
+```css
+/*
+name: Default Theme
+author: Original Author
+version: 1.0.0
+description: The original color scheme extracted from style.css
+*/
+
+:root {
+  /* CSS custom properties... */
+}
+```
+
+### Theme Metadata Interface
+```typescript
+interface ThemeInfo {
+  name: string;
+  author?: string;
+  version?: string;
+  description?: string;
+  filename: string;
+}
+```
+
+### Theme Manager Service
+```typescript
+class ThemeManager {
+  private currentTheme: string;
+  private availableThemes: ThemeInfo[];
+  private currentThemeLink: HTMLLinkElement | null;
+
+  async loadTheme(themeName: string): Promise<void>
+  async switchTheme(themeName: string): Promise<void>
+  getCurrentTheme(): string
+  getAvailableThemes(): ThemeInfo[]
+  private loadThemeCSS(filename: string): Promise<void>
+  private removeCurrentTheme(): void
+  private parseThemeMetadata(cssContent: string): ThemeInfo
+  private discoverAvailableThemes(): Promise<ThemeInfo[]>
+  private persistThemePreference(themeName: string): void
+  private loadThemePreference(): string
+}
+```
+
+## Data Models
+
+### Theme Storage
+- **Location**: `public/assets/themes/` directory
+- **Format**: CSS files with CSS custom property definitions
+- **Naming**: `{theme-name}.css` (e.g., `default.css`, `dark.css`)
+
+### Theme Loading Mechanism
+- **Dynamic Loading**: Themes loaded by injecting `<link>` elements into document head
+- **Theme Switching**: Remove previous theme link and add new theme link
+- **CSS Cascade**: Theme CSS custom properties override base styles automatically
+- **Metadata Parsing**: Fetch theme CSS files to extract metadata from header comments
+- **Theme Discovery**: Scan themes directory for available CSS files and parse their metadata
+
+### Theme Persistence
+- **Storage**: localStorage
+- **Key**: `outliner-theme-preference`
+- **Value**: Theme name string
+
+## Error Handling
+
+### Theme Loading Failures
+- **Fallback**: Always fall back to default theme if requested theme fails to load
+- **CSS Load Detection**: Monitor link element load/error events
+- **User Feedback**: Display error messages for failed theme operations
+
+### Missing Theme Files
+- **Detection**: Handle CSS file 404 errors gracefully
+- **Recovery**: Provide list of available themes if requested theme is missing
+- **Logging**: Log theme-related errors for debugging
+
+### CSS Variable Support
+- **Browser Compatibility**: Detect CSS custom property support
+- **Graceful Degradation**: Fall back to static CSS if variables not supported
+- **Progressive Enhancement**: Enhance experience for modern browsers
+
+## Testing Strategy
+
+### Unit Tests
+- **Theme Manager**: Test theme loading, switching, and persistence
+- **CSS Loading**: Test dynamic CSS file loading and error handling
+- **Theme Detection**: Test available theme discovery
+
+### Integration Tests
+- **Theme Switching**: Test complete theme switching workflow
+- **UI Integration**: Test theme selector modal functionality
+- **Persistence**: Test theme preference saving and loading
+
+### Visual Testing
+- **Theme Consistency**: Verify all UI elements update correctly with theme changes
+- **Color Contrast**: Ensure accessibility standards are met for all themes
+- **Interactive States**: Test hover, selected, and cursor states across themes
+
+### Browser Compatibility
+- **CSS Variables**: Test in browsers with and without CSS custom property support
+- **Theme Persistence**: Test localStorage functionality across browsers
+- **Performance**: Measure theme switching performance impact

.kiro/specs/dynamic-theming/requirements.md

@@ -0,0 +1,57 @@
+# Requirements Document
+
+## Introduction
+
+This feature will extract color values from the existing style.css file and create a separate theme system that allows for dynamic stylesheet swapping. The system will enable users to switch between different color themes (starting with a "default" theme) without requiring application restarts or page reloads.
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a user, I want to be able to switch between different color themes, so that I can customize the visual appearance of the application to my preferences.
+
+#### Acceptance Criteria
+
+1. WHEN the application loads THEN the system SHALL apply the default theme automatically
+2. WHEN a user selects a different theme THEN the system SHALL update the visual appearance immediately without requiring a page reload
+3. WHEN a theme is changed THEN the system SHALL persist the user's theme preference for future sessions
+
+### Requirement 2
+
+**User Story:** As a developer, I want color values to be centralized in theme files, so that I can easily create and maintain different color schemes.
+
+#### Acceptance Criteria
+
+1. WHEN creating a new theme THEN all color values SHALL be defined in a single theme file
+2. WHEN the main stylesheet is loaded THEN it SHALL reference theme variables instead of hardcoded color values
+3. WHEN a color needs to be updated THEN it SHALL only require changes in the theme file, not the main stylesheet
+
+### Requirement 3
+
+**User Story:** As a user, I want the theme system to preserve all existing visual functionality, so that changing themes doesn't break the application's appearance or usability.
+
+#### Acceptance Criteria
+
+1. WHEN any theme is applied THEN all existing visual elements SHALL maintain their intended styling and layout
+2. WHEN switching themes THEN interactive states (hover, selected, cursor) SHALL continue to work correctly
+3. WHEN a theme is applied THEN all color-dependent features (search results, node states, dates) SHALL remain visually distinct and functional
+
+### Requirement 4
+
+**User Story:** As a user, I want a theme selection interface, so that I can easily choose and preview different themes.
+
+#### Acceptance Criteria
+
+1. WHEN accessing theme settings THEN the system SHALL provide a user interface for theme selection
+2. WHEN previewing a theme THEN the system SHALL show the theme name and allow immediate application
+3. WHEN a theme is selected THEN the interface SHALL provide visual feedback confirming the selection
+
+### Requirement 5
+
+**User Story:** As a developer, I want the theme system to be extensible, so that new themes can be added easily in the future.
+
+#### Acceptance Criteria
+
+1. WHEN adding a new theme THEN it SHALL only require creating a new theme file following the established structure
+2. WHEN a new theme file is added THEN the system SHALL automatically detect and make it available for selection
+3. WHEN defining theme variables THEN the system SHALL use a consistent naming convention that maps clearly to CSS properties

.kiro/specs/dynamic-theming/tasks.md

@@ -0,0 +1,68 @@
+# Implementation Plan
+
+- [x] 1. Extract colors from existing style.css and create base theme structure
+  - Analyze current style.css to identify all color values used throughout the application
+  - Create themes directory structure at `public/assets/themes/`
+  - Create default.css theme file with metadata header and CSS custom properties extracted from style.css
+  - _Requirements: 2.1, 2.2_
+
+- [x] 2. Modify main stylesheet to use CSS custom properties
+  - Update style.css to replace hardcoded color values with CSS custom property references
+  - Ensure all color-dependent styles use the new CSS variables
+  - Test that visual appearance remains identical with the new variable-based approach
+  - _Requirements: 2.2, 3.1, 3.2_
+
+- [x] 3. Implement theme manager service
+  - Create ThemeManager class in `src/lib/theme-manager.ts`
+  - Implement theme metadata parsing from CSS file headers
+  - Implement dynamic CSS loading and switching functionality
+  - Add theme preference persistence using localStorage
+  - _Requirements: 1.1, 1.3, 2.1_
+
+- [ ] 4. Add theme discovery and initialization
+  - Implement theme discovery mechanism to scan available theme files
+  - Add theme manager initialization to main client.ts
+  - Implement automatic default theme loading on application startup
+  - Add error handling for theme loading failures with fallback to default
+  - _Requirements: 1.1, 5.2_
+
+- [ ] 5. Create theme selection modal interface
+  - Create theme selector modal component in `src/modals/theme-selector.ts`
+  - Implement theme list display with metadata (name, author, version)
+  - Add theme preview and selection functionality
+  - Integrate theme selector with existing modal system
+  - _Requirements: 4.1, 4.2, 4.3_
+
+- [ ] 6. Add keyboard shortcut for theme selection
+  - Add new keyboard shortcut definition for opening theme selector
+  - Integrate theme selector shortcut with existing keyboard shortcut system
+  - Update help modal to include theme selection shortcut
+  - _Requirements: 4.1_
+
+- [ ] 7. Implement theme switching functionality
+  - Connect theme selector UI to theme manager service
+  - Implement immediate theme application without page reload
+  - Add visual feedback for successful theme changes
+  - Ensure theme persistence works correctly across sessions
+  - _Requirements: 1.2, 1.3, 4.3_
+
+- [ ] 8. Add comprehensive error handling and validation
+  - Implement CSS file loading error detection and handling
+  - Add validation for theme metadata format
+  - Implement graceful fallback to default theme on errors
+  - Add user-friendly error messages for theme-related issues
+  - _Requirements: 3.1, 3.2, 3.3_
+
+- [ ] 9. Create unit tests for theme system
+  - Write tests for ThemeManager class methods
+  - Test theme metadata parsing functionality
+  - Test theme switching and persistence mechanisms
+  - Test error handling and fallback scenarios
+  - _Requirements: 2.1, 1.2, 1.3_
+
+- [ ] 10. Verify theme system integration and functionality
+  - Test complete theme switching workflow end-to-end
+  - Verify all UI elements update correctly with theme changes
+  - Test theme persistence across browser sessions
+  - Ensure all interactive states (hover, selected, cursor) work with new themes
+  - _Requirements: 3.1, 3.2, 3.3, 1.2_