← Build log

Pragmatic Engineering: When "Good Enough" Is Perfect - The VoiceCatcher Hotkey Selector Journey

A Technical Product Manager’s perspective on shipping practical solutions over perfect ones

The Challenge: Interactive Hotkey Configuration

When building VoiceCatcher’s settings interface, we faced a seemingly simple requirement: allow users to configure their voice capture hotkey through an interactive input field. What started as a straightforward UI enhancement became a masterclass in pragmatic engineering decisions and the art of knowing when to accept tradeoffs.

Initial Vision: Live Keyboard Capture

Our first approach was technically elegant - create a real-time keyboard capture system that would detect any key combination as users pressed it:

// The "perfect" solution we initially pursued
const handleKeyDown = (e: KeyboardEvent) => {
  e.preventDefault();
  e.stopPropagation();

  const modifiers = [];
  if (e.ctrlKey) modifiers.push('CTRL');
  if (e.metaKey) modifiers.push('CMD');
  if (e.altKey) modifiers.push('ALT');
  if (e.shiftKey) modifiers.push('SHIFT');

  // Capture the actual key...
};

This approach felt right from a UX perspective - users could simply click the input field and press their desired hotkey combination. It was intuitive, modern, and exactly what you’d expect from a professional application.

Reality Check: Platform Constraints

However, we quickly discovered that “technically elegant” doesn’t always mean “practically viable.” Several critical issues emerged:

1. Electron’s Event Interception

Electron intercepted keyboard events before our React components could capture them. The very framework that powers our app was working against our implementation.

2. Browser Security Models

Modern browsers actively block global keyboard listeners for security reasons. Even when events did reach our component, modifier combinations were inconsistent or completely blocked.

3. Cross-Platform Inconsistencies

What worked on macOS failed on Windows. Key codes varied between platforms, and system-reserved shortcuts created unpredictable behavior.

4. The ESC Key Paradox

Ironically, the only key that worked reliably was ESC - the one key users would never want as their hotkey. Everything else was either intercepted, blocked, or inconsistent.

The Pivot: Embracing Pragmatism

After extensive debugging and testing, we made a crucial engineering decision: pivot from live capture to dropdown selection. This wasn’t admitting defeat - it was recognizing that the best solution is the one that actually works.

The Pragmatic Solution

const commonHotkeys = [
  'CTRL+F',
  'CTRL+G',
  'CTRL+H',
  'CTRL+J',
  'CTRL+K',
  'CTRL+SHIFT+A',
  'CTRL+SHIFT+B',
  'CTRL+SHIFT+C',
  'CTRL+ALT+V',
  'CTRL+ALT+B',
  'CTRL+ALT+N',
  // Platform-aware alternatives for Mac
  ...(isMac ? ['CMD+SHIFT+V', 'CMD+ALT+V'] : []),
];

Our final implementation featured:

  • Dropdown Selection: Curated list of safe, common hotkey combinations
  • Platform Awareness: Automatic CMD vs CTRL detection for Mac/PC
  • Manual Input Fallback: Text field for power users who know what they want
  • Validation System: Real-time checking against dangerous system shortcuts
  • Compact Design: Fits seamlessly within existing UI constraints

Engineering Insights: The Value of “Good Enough”

This journey highlighted several critical engineering principles:

1. Perfect Is the Enemy of Shipped

Our live capture system was technically superior but practically unusable. The dropdown solution was less elegant but infinitely more reliable.

2. Platform Constraints Are Features, Not Bugs

Instead of fighting Electron’s event handling, we worked with it. The constraints forced us toward a more maintainable solution.

3. User Experience Trumps Technical Elegance

Users don’t care about the implementation complexity. They want something that works consistently across all platforms.

4. Scope Management Prevents Feature Creep

Recognizing when “good enough” is actually perfect prevents endless optimization cycles that delay shipping.

Technical Implementation Details

The final HotkeyInput component (385 lines) includes:

  • Comprehensive Validation: Prevents users from selecting dangerous shortcuts like CMD+Q
  • Hybrid Approach: Dropdown for common cases, manual input for edge cases
  • Error Handling: Real-time feedback for invalid combinations
  • Accessibility: Proper ARIA labels and keyboard navigation
  • Responsive Design: Compact layout that respects container boundaries

The TPM Perspective: Shipping vs. Perfection

From a Technical Product Manager standpoint, this project exemplified the critical skill of knowing when to ship:

What We Shipped

  • ✅ Reliable hotkey configuration across all platforms
  • ✅ Intuitive dropdown interface with common options
  • ✅ Validation preventing dangerous system conflicts
  • ✅ Compact design fitting existing UI constraints
  • ✅ Zero platform-specific bugs or edge cases

What We Didn’t Ship (And Why That’s OK)

  • ❌ Live keyboard capture (unreliable across platforms)
  • ❌ Custom key combination detection (security limitations)
  • ❌ Perfect UX matching native OS dialogs (scope creep)

Future Enhancement Roadmap

While our current solution is production-ready and reliable, we’ve documented a clear path for future enhancement:

Native Hotkey Capture Integration

  • Investigate Electron’s native global shortcut APIs
  • Explore platform-specific implementations (macOS: Carbon, Windows: Win32)
  • Consider third-party libraries with proven cross-platform support
  • Implement as optional enhancement, keeping dropdown as fallback

This approach ensures we can ship now while maintaining a clear upgrade path for future iterations.

Key Takeaways for Engineering Teams

  1. Start with the simplest solution that works - You can always enhance later
  2. Platform constraints often guide you toward better architecture - Don’t fight them
  3. User feedback on working features beats perfect features that don’t ship - Ship early, iterate based on real usage
  4. Document your tradeoffs - Future you (or your team) will thank you
  5. “Good enough” for MVP is often perfect for production - Resist the urge to over-engineer

Conclusion: The Art of Engineering Judgment

The VoiceCatcher hotkey selector project demonstrates that senior engineering isn’t about writing the most sophisticated code - it’s about making informed decisions that balance technical idealism with practical constraints.

Sometimes the best engineering decision is knowing when to stop engineering and start shipping. Our dropdown-based hotkey selector isn’t the most technically impressive solution we could have built, but it’s the most reliable solution we did build.

And in the end, that’s what matters: software that works, ships on time, and solves real user problems.

This post is part of our ongoing series documenting the engineering decisions behind VoiceCatcher. For more insights into our development process, see our technical documentation and product roadmap.

Technical Specifications

Component: gui/components/HotkeyInput.tsx
Lines of Code: 385
Dependencies: React, TypeScript
Platform Support: macOS, Windows, Linux
Integration: Electron IPC for settings persistence
Testing: Manual validation across all target platforms

Git Commit: feat: implement pragmatic hotkey selector with dropdown interface
Branch: ui-transformation-shadcn-implementation
Files Changed: 3 files, 385 insertions, 42 deletions