PLAN.md

Implementation Plan: Redesign Work Hours Conversion UI (#75)

Overview

Redesign the price conversion display to use a modern badge design with clock icon for better visual distinction and improved user experience.

Architecture Analysis

Current State

• Price conversions displayed using basic text replacement via domModifier.js
• Simple CSS class (CONVERTED_PRICE_CLASS) for styling
• Inline CSS injection through content script
• No visual distinction beyond text formatting

Target State

• Badge-style component with integrated clock icon
• Modern, accessible design with proper contrast ratios
• Responsive across different screen sizes
• Performance-optimized with minimal layout impact
• Cross-site compatibility maintained

Technical Approaches

Approach 1: CSS-in-JS Badge Component (Recommended)

Advantages:

• Encapsulated styling prevents conflicts with host sites
• Dynamic theming based on host site background
• Better performance with style caching
• Easier maintenance and testing

Implementation:

• Create BadgeComponent class in new file src/content/badge.js
• Generate inline styles programmatically
• Use CSS custom properties for theming
• Shadow DOM for style isolation (if supported)

Trade-offs:

• Slightly more complex than pure CSS
• Requires JavaScript for style generation
• Small runtime overhead for style computation

Approach 2: External CSS with BEM Methodology

Advantages:

• Simpler implementation
• Better browser caching
• Familiar CSS workflow

Implementation:

• Create src/content/css/badge.css
• Use BEM naming convention for class isolation
• Inject CSS once per page load

Trade-offs:

• Higher risk of style conflicts
• Less flexible theming
• Harder to maintain cross-site compatibility

Approach 3: Hybrid Approach with CSS Variables

Advantages:

• Combines benefits of both approaches
• Good performance characteristics
• Flexible theming system

Implementation:

• Base CSS structure with CSS custom properties
• JavaScript sets theme variables dynamically
• Icon embedded as data URI or SVG

Selected Approach: CSS-in-JS Badge Component

Based on the extension's requirements for cross-site compatibility and the existing architecture, the CSS-in-JS approach provides the best balance of flexibility, performance, and maintainability.

Implementation Steps

Phase 1: Badge Component Foundation

1. Create Badge Component (src/content/badge.js)

   • Define badge HTML structure
   • Implement CSS-in-JS style generation
   • Add clock icon (SVG data URI)
   • Provide theme customization API

2. Update Constants (src/utils/constants.js)

   • Add badge-specific CSS classes
   • Define design tokens (colors, spacing, typography)
   • Add accessibility constants

3. Integrate with DOM Modifier (src/content/domModifier.js)

   • Replace current text conversion with badge creation
   • Maintain existing price detection logic
   • Add badge cleanup on removal

Phase 2: Visual Design & Accessibility

1. Design System Implementation

   • Define color palette with WCAG AA compliance
   • Create responsive typography scale
   • Implement consistent spacing system

2. Icon Integration

   • Embed clock icon as optimized SVG
   • Ensure proper icon scaling
   • Add fallback for icon loading failures

3. Theme Adaptation

   • Detect host site background colors
   • Calculate optimal contrast ratios
   • Implement light/dark theme switching

Phase 3: Performance & Compatibility

1. Performance Optimization

   • Implement style caching mechanism
   • Minimize layout thrashing
   • Optimize for paint and composite layers

2. Cross-Site Testing

   • Test on major e-commerce sites
   • Validate responsive behavior
   • Ensure no style conflicts

3. Accessibility Enhancements

   • Add proper ARIA labels
   • Implement keyboard navigation support
   • Test with screen readers

Phase 4: Testing & Documentation

1. Comprehensive Testing

   • Unit tests for badge component
   • Integration tests with price detection
   • DOM tests for visual verification
   • Performance benchmarks

2. User Testing

   • A/B test badge vs current display
   • Gather feedback on visual clarity
   • Validate accessibility improvements

Detailed Technical Specifications

Badge Component API

class PriceBadge {
  constructor(originalPrice, convertedHours, settings) {
    this.originalPrice = originalPrice;
    this.convertedHours = convertedHours;
    this.settings = settings;
    this.element = null;
  }

  render(container) {
    // Create badge DOM element
    // Apply styles
    // Insert into container
  }

  updateTheme(backgroundColor) {
    // Adapt colors based on host site
  }

  destroy() {
    // Clean up resources
  }
}

CSS Design Tokens

const DESIGN_TOKENS = {
  colors: {
    primary: '#2563eb',
    primaryContrast: '#ffffff',
    surface: '#f8fafc',
    surfaceContrast: '#1e293b',
  },
  spacing: {
    xs: '4px',
    sm: '8px',
    md: '12px',
    lg: '16px',
  },
  typography: {
    fontSize: '12px',
    fontWeight: '500',
    lineHeight: '1.2',
  },
  animation: {
    duration: '150ms',
    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
  },
};

Clock Icon Specification

• Format: Optimized SVG (< 1KB)
• Size: 16x16px at 1x density
• Colors: Monochrome with CSS color inheritance
• Accessibility: Proper title and desc elements

Testing Strategy

Unit Tests

• Badge component creation and destruction
• Style generation logic
• Theme adaptation algorithms
• Icon rendering

Integration Tests

• Badge integration with price detection
• Settings synchronization
• DOM mutation handling
• Performance impact measurement

DOM Tests

• Visual rendering verification
• Responsive behavior testing
• Cross-browser compatibility
• Accessibility compliance

Performance Tests

• Style computation benchmarks
• Memory usage monitoring
• DOM manipulation impact
• Page load time effects

Risk Mitigation

High Priority Risks

1. Style Conflicts with Host Sites

   • Mitigation: Extensive CSS isolation, shadow DOM where possible
   • Testing: Comprehensive cross-site validation

2. Performance Impact

   • Mitigation: Style caching, lazy loading, performance budgets
   • Testing: Continuous performance monitoring

3. Accessibility Regressions

   • Mitigation: WCAG compliance testing, screen reader validation
   • Testing: Automated accessibility test suite

Medium Priority Risks

1. Browser Compatibility

   • Mitigation: Progressive enhancement, feature detection
   • Testing: Cross-browser test matrix

2. Icon Loading Failures

   • Mitigation: Inline SVG data URIs, text fallbacks
   • Testing: Network throttling scenarios

Success Metrics

User Experience

• Improved price conversion recognition (measurable via user studies)
• Reduced visual confusion with host site elements
• Better accessibility scores

Technical Performance

• No measurable impact on page load times
• Memory usage within acceptable limits (< 5MB increase)
• Style computation time < 10ms per badge

Code Quality

• 100% test coverage for new components
• Zero style conflicts across test sites
• WCAG AA accessibility compliance

Timeline Estimate

• Phase 1: 3-4 days (Foundation & Integration)
• Phase 2: 2-3 days (Design & Accessibility)
• Phase 3: 2-3 days (Performance & Compatibility)
• Phase 4: 2-3 days (Testing & Documentation)

Total: 9-13 days for complete implementation

Dependencies & Blockers

Prerequisites

• Issue #68 completion (Modularize Price Finder Logic)
• Stable testing infrastructure
• Cross-browser testing environment

External Dependencies

• Clock icon asset (can be created internally)
• Design system tokens definition
• Accessibility audit tools

Next Steps

1. Create feature branch: git checkout -b feature/75-badge-ui-redesign
2. Begin Phase 1 implementation with badge component foundation
3. Set up testing infrastructure for visual regression testing
4. Create design mockups for stakeholder review
5. Implement incremental rollout strategy for user testing