Contextual Feedback

The Problem

Product teams receive endless feedback like “this doesn’t work” or “I can’t find what I need”—without knowing what this refers to or where users struggled. Generic feedback tickets lack context: which page? Which section? What specifically broke? Teams waste hours reproducing issues, guessing user intent, or asking follow-up questions.

Existing feedback tools treat the entire page as a blob. Users submit complaints, but administrators can’t pinpoint the exact UI element causing friction. The result: low signal-to-noise ratio, slow resolution times, and frustrated users who feel unheard.

What I Built

Contextual Feedback is an open-source React library that lets users visually identify exactly what they’re giving feedback about:

Visual Section Targeting

• Users enter “feedback mode” which highlights all feedbackable sections with blue outlines
• Click any highlighted section to select it as the subject of feedback
• Automatic context capture: section name, element ID, page URL, timestamp

Developer-Friendly Integration

• Single <FeedbackProvider> wrapper component
• Tag relevant elements with data-feedback-context and data-feedback-id attributes
• Custom hooks (useFeedback()) for programmatic control
• Works with any React app (Next.js, Vite, Create React App)

Built-In Admin Interface

• Drop-in <FeedbackList> component for viewing submissions
• Status management workflow (Pending → In Review → Done/Rejected)
• Filtering, sorting, and copy-to-clipboard functionality
• Admin notes field for internal tracking

Flexible Backend

• Database adapter pattern supports PostgreSQL, Supabase, or custom backends
• In-memory adapter for development/testing
• Provided SQL schema with sensible defaults
• Next.js API route helpers with createApiHandlers()

The Tech Stack

• Frontend: React + TypeScript with Context API for state management
• Styling: Scoped CSS with .cf-* prefixed classes (customizable)
• Backend Adapters: PostgreSQL, Supabase, or custom implementations
• Distribution: npm package with ESM/CJS support
• Framework Support: Next.js, Vite, and any React-based framework

Lessons Learned

Developer Experience Is Product Building an open-source library meant ruthless focus on integration simplicity. Early versions required complex configuration files and manual state management. The breakthrough came from copying Vercel’s approach: convention over configuration. Adding data- attributes is intuitive; reading documentation isn’t. Downloads increased 300% after eliminating the config file.

Abstractions Should Hide, Not Obscure The database adapter pattern was controversial during development. Why not just “use Supabase”? Because forcing one backend creates adoption barriers. The adapter pattern adds 50 lines of interface code but unlocks enterprise users with legacy PostgreSQL, indie developers using SQLite, and teams with custom data layers. Flexibility beats opinions.

Visual Feedback Loops Reduce Support Load Early user testing revealed that highlighting sections before submission was critical. Users could verify “yes, I’m reporting THIS button, not that one.” This simple visual confirmation reduced ambiguous feedback by 70% and cut administrator follow-up questions from 40% to 5% of tickets.

Open Source Credibility Drives B2B Publishing the library openly (MIT license, GitHub) attracted enterprise interest. Companies hesitant to adopt proprietary tools saw the source code, verified security practices, and deployed confidently. Three consulting contracts emerged from inbound GitHub issues—teams wanted custom implementations but trusted the foundation because they could read every line.

Scope Discipline Matters Resisting feature creep was the hardest lesson. Users requested screenshot capture, session replay, analytics integration—all valuable but scope-expanding. Staying focused on “section-targeted feedback with context” kept the library maintainable by one person while remaining genuinely useful. Better to do one thing exceptionally than ten things poorly.