feat: comprehensive UI improvements and accessibility enhancements (Issue #55)

[AlexVOiceover]

Overview

Implements comprehensive UI improvements and accessibility enhancements as outlined in Issue #55. This PR introduces a dynamic font size control system with database persistence, enhances the help system with rich modal content, improves navigation with clickable breadcrumbs, and adds comprehensive action management capabilities.

Key Features:

• ✅ Persistent font size control with database storage
• ✅ Enhanced help system with modal support and rich content
• ✅ Clickable breadcrumb navigation replacing view headers
• ✅ Comprehensive action management (ActionsCRUD component)
• ✅ Improved accessibility with focus traps and keyboard navigation
• ✅ Better status indicators and terminology updates

---

Changes

Font Size & Accessibility

• Added dynamic font size control in header with accessibility features
• Implemented database persistence for user font size preferences
• Added CSS classes for 5 font size levels (extra-small to extra-large)
• Enhanced keyboard navigation and ARIA labels throughout

Help System Enhancement

• Created comprehensive help modal system with rich content
• Added contextual help buttons to view headers
• Implemented proper focus trapping with inert polyfill
• Added help content management system with JSON configuration

Navigation Improvements

• Replaced static view headers with clickable breadcrumb navigation
• Added responsive breadcrumb design with ellipsis for narrow screens
• Improved navigation UX with clear visual hierarchy

Action Management

• Built comprehensive ActionsCRUD component for managing follow-up actions
• Added form validation and race condition protection
• Implemented proper null safety and error handling
• Enhanced action status indicators and terminology

UI/UX Polish

• Changed completed question indicators from grey to teal/accent color
• Replaced "Archived" terminology with "Inactive" for better clarity
• Added status icons to question indicators
• Improved button sizing and layout consistency

Database & Infrastructure

• Added preferences JSONB column to profiles table
• Updated TypeScript types for new database schema
• Implemented async profile loading with preferences
• Enhanced test user selection to load full profile data

---

Closes #55

[claude]

Claude finished @AlexVOiceover's task —— View job

---

PR Review: Comprehensive UI Improvements and Accessibility Enhancements

I've completed my review of this PR. Overall, this is a well-structured implementation that brings significant improvements to the UI and accessibility features. Here's my detailed feedback:

Review Checklist:

• Read project conventions (CLAUDE.md)
• Review new components (ActionsCRUD, FontSizeControl, HelpModal, Breadcrumb)
• Check database changes and type safety
• Assess accessibility improvements
• Look for security concerns
• Evaluate error handling and race conditions
• Review CSS and styling changes
• Check for performance implications
• Assess test coverage needs

🟢 Strengths

Code Quality & Best Practices

• Excellent adherence to project conventions: Components follow the established naming patterns (PascalCase), use proper Svelte 5 syntax with $props, $state, and $derived
• Consistent state management: Properly uses context-based architecture as specified in CLAUDE.md
• Type safety: All new components have proper TypeScript types and interfaces
• Clean component structure: Components are properly categorized in the /ui folder as per project structure

Accessibility Excellence

• Focus management: HelpModal properly manages focus with previouslyFocused state and restores focus on close
• ARIA labels: All interactive elements have proper aria-labels (e.g., "Font size settings", "Increase font size")
• Keyboard navigation: Escape key handling, proper button types, and tabindex management
• Font size control: Implements 5 font size levels with persistent storage, helping users with visual impairments
• inert attribute: Properly uses document.body.inert to prevent background interaction when modal is open

Error Handling & UX

• Race condition protection: ActionsCRUD uses isCreating and isUpdating flags to prevent concurrent requests
• Input validation: Comprehensive validation in ActionsCRUD with length checks (3-500 chars)
• User feedback: Clear error messages with proper styling and loading states
• Optimistic updates: Font size changes apply immediately for better perceived performance

🟡 Potential Issues & Suggestions

Performance Considerations

1. Font size class application (FontSizeControl.svelte:84-87):

   $effect(() => {
     const root = document.documentElement;
     root.classList.remove('font-size-extra-small', 'font-size-small', 'font-size-medium', 'font-size-large', 'font-size-extra-large');
     root.classList.add(`font-size-${fontSize}`);
   });

   • Consider using a more efficient approach by tracking previous class:

   let previousFontSizeClass = $state<string>('');
   $effect(() => {
     const root = document.documentElement;
     if (previousFontSizeClass) {
       root.classList.remove(previousFontSizeClass);
     }
     const newClass = `font-size-${fontSize}`;
     root.classList.add(newClass);
     previousFontSizeClass = newClass;
   });

2. Breadcrumb async operations (Breadcrumb.svelte:17-23):

   • The effect fetches question title on every render when in detail view
   • Consider caching or memoizing the result

Security Considerations

1. Database preferences storage:

   • The JSONB column is properly typed and constrained ✅
   • Good use of TypeScript interfaces to enforce structure
   • No direct user input stored without validation

2. XSS Prevention:

   • All user inputs are properly escaped in templates ✅
   • No use of {@html} with user content

Code Improvements

1. ActionsCRUD component - Consider extracting validation:

   // Consider moving to a separate validation utility
   const ACTION_CONSTRAINTS = {
     MIN_LENGTH: 3,
     MAX_LENGTH: 500
   } as const;

2. Help content loading:

   • The help content JSON is loaded statically which is good
   • Consider lazy loading help content only when help modal is first opened

3. Breadcrumb navigation:

   • The component properly handles all navigation cases
   • Consider adding ARIA attributes for better screen reader support:

   <nav class="breadcrumb">
     <ol class="breadcrumb-list">

Test Coverage Recommendations

Based on the project's testing requirements (80% coverage for critical paths), I recommend adding tests for:

1. FontSizeControl:

   • Test preference persistence to database
   • Test font size class application
   • Test keyboard navigation

2. ActionsCRUD:

   • Test validation edge cases
   • Test concurrent request prevention
   • Test error handling and rollback

3. HelpModal:

   • Test focus trap functionality
   • Test escape key handling
   • Test inert attribute application

4. Breadcrumb:

   • Test navigation state changes
   • Test async question title loading
   • Test all view combinations

Example test structure:

describe('FontSizeControl', () => {
  test('persists font size preference to database', async () => {
    // Test implementation
  });
  
  test('applies correct CSS class to document root', () => {
    // Test implementation
  });
});

🔴 Critical Issues

None found. The implementation follows security best practices and handles edge cases appropriately.

📋 Summary

This PR successfully implements comprehensive UI improvements with excellent attention to accessibility. The code quality is high, following project conventions consistently. The implementation of persistent font size control, enhanced help system, clickable breadcrumbs, and action management significantly improves the user experience.

Recommendation: ✅ Approve with minor suggestions

The suggestions above are optional improvements that could be addressed in a follow-up PR. The current implementation is solid and ready for production.

Next Steps:

1. Add the recommended test coverage
2. Consider the performance optimizations for font size class switching
3. Document the new features in user-facing documentation

Great work on this comprehensive enhancement! The attention to accessibility and user experience is commendable. 🎉

[JasonWarrenUK]

The user preferences solution is really elegant

There's one slight bug with actions, but I'm gonna merge this because we can fix afterwards

The merge-base changed after approval.