Skip to content

Latest commit

 

History

History
390 lines (269 loc) · 14.3 KB

TODO.md

File metadata and controls

390 lines (269 loc) · 14.3 KB

Badge UI Redesign Engineering Plan

Philosophy: Ship fast, iterate, refactor elegant

SPRINT 0 (24 hours) - PROOF OF CONCEPT 🚀

Goal: Get a badge rendering SOMEWHERE to build confidence

  • S0.1 - Quick Win: Hardcoded badge in DOM ⚡

    • Action: Add a hardcoded badge element directly in domModifier.js - just HTML + inline styles
    • Success: Can see a badge render on ANY website when price detected
    • Time: 2 hours
    • No dependencies, no design tokens, just SHIP SOMETHING

  • S0.2 - Basic clock icon ⚡

    • Action: Find any clock SVG, embed as data URI, slap it in the badge
    • Success: Badge has a clock icon (ugly is fine)
    • Time: 1 hour

  • S0.3 - Manual test on Amazon ⚡

    • Action: Load extension, visit Amazon, see if badges appear
    • Success: Can screenshot working badge on real site
    • Time: 30 minutes
    • RESULT: Major UX issues identified - badges too long, layout breaking, visual clutter

🔄 SPRINT 0.5 (4 hours) - UX REDESIGN BASED ON REAL USAGE 🎯

Goal: Fix critical UX issues discovered in manual testing

Key Insights from Amazon Testing:

  • Current badges are 2-3x longer than original prices → layout breaks, text cuts off
  • Showing both prices simultaneously creates visual clutter and cognitive overload
  • Clock icon placement is illogical (between prices vs. with time)
  • "0h 15m" format is unnecessarily verbose when hours are zero
  • Blue badge background conflicts with host site design systems

New Strategy: Replace + Tooltip Approach

  • Replace price entirely with clean time conversion, show original in tooltip

  • Dramatically shorter, integrates better with existing layouts

  • More professional appearance, less intrusive to site design

  • S0.5.1 - Implement replace-only strategy 🔧

    • Action: Replace crossed-out price + badge with clean time-only display
    • Format: 🕐 3h 15m or 🕐 15m (omit hours when zero)
    • Success: Much shorter replacement that doesn't break layouts
    • Time: 2 hours

  • S0.5.2 - Add tooltip with original price 💡

    • Action: Show original price in tooltip on hover: "Originally $30.00"
    • Use browser native tooltip or simple positioned div
    • Success: Original price discoverable but not cluttering display
    • Time: 1.5 hours

  • S0.5.3 - Refine styling for host site integration ✨

    • Action: Remove blue badge background, use subtle styling that integrates better
    • Match host site text colors, use minimal visual distinction
    • Success: Conversions look native to the site rather than injected
    • Time: 30 minutes

SPRINT 1 (2-3 days) - FUNCTIONAL MVP 🎯

Goal: End-to-end working system, ugly but functional

  • S1.1 - Extract badge creation function

    • Action: Move hardcoded badge logic into createBadge(originalPrice, convertedHours) function
    • Success: Clean separation, easier to iterate
    • Time: 1 hour

  • S1.2 - Basic CSS-in-JS styling

    • Action: Generate inline styles programmatically, basic color/spacing constants
    • Success: Badge looks intentional, not broken
    • Time: 3 hours

  • S1.3 - Integrate with price detection flow

    • Action: Replace text modification in domModifier.js with badge creation
    • Success: All detected prices become badges automatically
    • Time: 4 hours

  • S1.4 - Cleanup on removal

    • Action: Track badge elements, remove when original price removed
    • Success: No orphaned badges, no memory leaks
    • Time: 2 hours

  • S1.5 - Test on 3 major sites

    • Action: Manual test on Amazon, eBay, general e-commerce
    • Success: Screenshots of working badges, note any major issues
    • Time: 1 hour

SPRINT 2 (2-3 days) - POLISH & EDGE CASES ✨

Goal: Looks professional, handles edge cases gracefully

  • S2.1 - Proper badge component class

    • Action: Refactor into PriceBadge class with constructor/render/destroy
    • Success: Clean OOP design, easier to extend
    • Time: 3 hours

  • S2.2 - Dynamic theme adaptation

    • Action: Detect background color, adjust badge colors for contrast
    • Success: Badge readable on light/dark backgrounds
    • Time: 4 hours

  • S2.3 - Responsive design

    • Action: Badge scales properly on mobile, different viewport sizes
    • Success: Looks good on phone/desktop
    • Time: 2 hours

  • S2.4 - Nice clock icon

    • Action: Create/find proper optimized SVG, color inheritance
    • Success: Professional-looking icon, scales well
    • Time: 2 hours

  • S2.5 - Style conflict prevention

    • Action: Use unique class names, CSS specificity, maybe Shadow DOM attempt
    • Success: Badge unaffected by host site styles
    • Time: 3 hours

SPRINT 3 (2-3 days) - PRODUCTION READY 🚢

Goal: Ship-quality code with tests and performance

  • S3.1 - Basic accessibility

    • Action: Add ARIA labels, screen reader friendly text
    • Success: Passes basic accessibility audit
    • Time: 2 hours

  • S3.2 - Performance optimization

    • Action: Style caching, avoid DOM thrashing, measure performance
    • Success: No noticeable performance impact
    • Time: 3 hours

  • S3.3 - Unit tests

    • Action: Test badge component creation, styling, cleanup
    • Success: Core functionality covered by tests
    • Time: 4 hours

  • S3.4 - Integration tests

    • Action: Test end-to-end price detection → badge creation flow
    • Success: Regression protection for core user journey
    • Time: 3 hours

  • S3.5 - Cross-site validation

    • Action: Test on 10+ e-commerce sites, document any issues
    • Success: Works reliably across different sites
    • Time: 2 hours

  • S3.6 - Feature flag

    • Action: Add setting to toggle old vs new badge display
    • Success: Easy rollback if needed
    • Time: 2 hours

BACKLOG (Future iterations) 📋

Nice-to-haves that don't block shipping

  • Visual regression testing infrastructure
  • [✓] Shadow DOM for perfect style isolation
  • [✓] Advanced theme detection (image backgrounds)
  • [✓] Animation/micro-interactions
  • A/B testing analytics
  • Custom badge styling options

ENGINEERING PRINCIPLES 🎯

Sprint 0: Prove it works ✅

  • Hardcode everything ✅
  • Copy-paste is fine ✅
  • Ugly code is acceptable ✅
  • Just get pixels on screen ✅
  • Real-world test early ✅ (Revealed critical UX issues)

Sprint 0.5: Fix UX based on real usage

  • Replace, don't augment (shorter is better)
  • Tooltip for secondary information
  • Integrate with host site design
  • Length/layout preservation is critical

Sprint 1: Make it functional

  • Extract reusable functions
  • Basic error handling
  • Works end-to-end
  • Still messy is OK

Sprint 2: Make it good

  • Proper abstractions
  • Handle edge cases
  • Professional appearance
  • Still some tech debt OK

Sprint 3: Make it right

  • Clean architecture
  • Comprehensive tests
  • Performance optimized
  • Production quality

DEFINITION OF DONE ✅

Sprint 0: Screenshot of badge on real website ✅ (COMPLETED - revealed major UX issues)
Sprint 0.5: Clean time-only replacements that don't break site layouts
Sprint 1: All detected prices show as time conversions with tooltips, no crashes
Sprint 2: Conversions look native and work across multiple sites
Sprint 3: Full test coverage and ready for user rollout

CRITICAL: CI/CD PIPELINE FAILURES 🚨

Status: BLOCKING MERGE - All failures must be resolved before merging to master

Categories: 40 test failures across multiple test suites

PRIORITY 1: Badge Display Mode Consistency Issues 🔥

Root Cause: Tests expect backward-compatible format but get modern hover toggle format

  • T1.1: Fix unit test badge display expectations in PriceBadge.vitest.test.js

    • File: src/__tests__/components/PriceBadge.vitest.test.js
    • Issue: Tests expect '3h 0m' but get '$30.00 (3h 0m)'
    • Action: Update tests to properly handle enableHoverToggle configuration
    • Lines: Icon toggle tests expecting time-only display

  • T1.2: Fix DOM conversion integration test expectations

    • File: src/__tests__/integration/content/dom-conversion.vitest.test.js
    • Issue: Tests expect prices in textContent but get time-only with whitespace
    • Action: Use .trim() and expect time-only format or configure tests for legacy mode
    • Error: expected 'Price: \n $199.99' to contain '$199.99'

  • T1.3: Audit all component tests for badge format assumptions

    • Files: Multiple component test files
    • Issue: Inconsistent expectations about badge content format
    • Action: Systematically review and fix all badge content assertions

PRIORITY 1: Async Test Issues 🔥

Root Cause: Tests not properly awaiting async destroy() method

  • T2.1: Fix PriceBadge destroy method test patterns

    • File: src/__tests__/components/PriceBadge.vitest.test.js
    • Issue: expected Promise{…} to be true - tests calling async method synchronously
    • Action: Add await to all badge.destroy() calls in tests
    • Count: 3 failing tests in Destroy Method section

  • T2.2: Audit all tests calling async badge methods

    • Files: All badge-related test files
    • Issue: Potential other async methods not being awaited
    • Action: Search for .destroy(), .update() calls and ensure proper async handling

PRIORITY 2: Icon Design Mismatch Issues 🎨

Root Cause: Tests expect specific SVG elements that don't match current implementation

  • T3.1: Update icon unit tests to match current SVG design

    • File: src/__tests__/unit/components/PriceBadge.icon.unit.vitest.test.js
    • Issues:
      • Expected r="0.8" not found (circle radius changed)
      • Expected stroke-linejoin="round" not found (SVG attributes changed)
      • Expected L6.2 5.8 not found (clock hand coordinates changed)
    • Action: Update test expectations to match current clock icon SVG

  • T3.2: Verify icon design requirements vs implementation

    • File: Current SVG in src/components/PriceBadge.js:_createClockIcon()
    • Issue: Tests suggest different design requirements than implemented
    • Action: Decide if tests should match implementation or implementation should match tests

PRIORITY 2: Style Generation Issues 🎨

Root Cause: Defensive styling generates complex CSS that doesn't contain expected simple properties

  • T4.1: Fix dark theme style detection test

    • File: src/__tests__/unit/utils/styleGenerator.unit.vitest.test.js
    • Issue: Expected color: #10b981 not found in complex defensive CSS string
    • Current: text-transform: none; letter-spacing: normal; word-spacing: normal; ... color: #059669 !important; ...
    • Action: Either update test to check for actual applied color or fix theme detection

  • T4.2: Fix responsive font-size detection test

    • File: src/__tests__/unit/utils/styleGenerator.responsive.unit.vitest.test.js
    • Issue: Expected font-size: 0.875rem not found in defensive CSS
    • Action: Update test to extract actual font-size from complex CSS string

  • T4.3: Create CSS property extraction helper for tests

    • Issue: Multiple tests expect simple properties in complex defensive CSS
    • Action: Create test utility to extract specific CSS properties from defensive style strings

PRIORITY 2: Responsive Sizing Issues 📱

Root Cause: Tablet sizes equal desktop sizes instead of being between mobile and desktop

  • T5.1: Fix tablet sizing to be between mobile and desktop

    • File: src/__tests__/unit/utils/styleGenerator.responsive.simple.unit.vitest.test.js
    • Issue: expected 0.75 to be less than 0.75 - tablet size equals desktop size
    • Action: Review responsive size calculation logic to ensure proper scaling

  • T5.2: Fix error handling size fallback

    • Same file as T5.1
    • Issue: expected '0.875rem' to be '0.75rem' - wrong fallback size
    • Action: Update fallback size logic for invalid size keys

PRIORITY 3: Settings Manager Error Handling 🔧

Root Cause: Spy call count expectations don't match actual behavior

  • T6.1: Fix settings manager error handling test
    • File: src/__tests__/integration/content/settingsManager.error.vitest.test.js
    • Issue: expected "spy" to be called +0 times, but got 1 times
    • Action: Review visibility change error handling logic and update test expectations

PRIORITY 3: Responsive Context Issues 📐

Root Cause: Test expectations about responsive context don't match implementation

  • T7.1: Fix responsive context default behavior test
    • File: src/__tests__/unit/utils/styleGenerator.responsive.unit.vitest.test.js
    • Issue: expected true to be false - responsive context enabled by default
    • Action: Review responsive context creation logic and update test

CROSS-CUTTING TASKS 🔄

  • T8.1: Audit all tests for .textContent vs .textContent.trim()

    • Issue: SVG whitespace causing textContent mismatches across multiple tests
    • Action: Systematically add .trim() where needed for badge content tests

  • T8.2: Create badge test utilities for consistent expectations

    • Issue: Inconsistent badge content testing patterns across files
    • Action: Create helper functions for common badge assertion patterns

  • T8.3: Document badge display mode test strategies

    • Issue: Tests unclear about when to expect modern vs legacy format
    • Action: Create testing guide for badge display mode configurations

COMPLETION CRITERIA ✅

All CI/CD Pipeline Checks Must Pass:

  • Unit tests: 0 failures
  • Integration tests: 0 failures
  • DOM tests: 0 failures
  • Lint: No errors
  • Build: Successful
  • Security scan: No vulnerabilities

Merge Readiness Checklist:

  • All 40+ test failures resolved
  • CI pipeline green on GitHub Actions
  • Manual verification on test sites
  • Performance regression check
  • Accessibility audit passes

ANTI-PATTERNS TO AVOID ⚠️

  • ❌ Waiting for perfect design before coding
  • ❌ Building test infrastructure before feature
  • ❌ Optimizing before measuring performance problems
  • ❌ Adding complexity that doesn't serve users
  • ❌ Perfectionism blocking iteration
  • ❌ Skipping real-world testing (Sprint 0 taught us our badge approach broke layouts)
  • ❌ Showing too much information simultaneously (original + converted prices created clutter)
  • ❌ Changing test expectations to match bugs (Fix implementation, not tests)
  • ❌ Ignoring CI failures (All tests must pass before merge)