Build A React Evaluation Feedback UI

🎯 Objective: Crafting User Feedback Components

This article details the plan to build React evaluation components for a web portal. The main goal is to collect user feedback on agent responses. We want to achieve this through a clean, easy-to-use, and accessible UI. The project is slated for Week 9, spanning from December 30, 2025, to January 3, 2026. This initiative is crucial, designated as P0 Critical, and will be spearheaded by the Principal Fullstack Engineer. The total estimated effort is one week, with a story point allocation of 13.

Why React for Feedback?

React's component-based architecture makes it ideal for building modular and reusable UI elements. This approach allows us to create specific feedback components (like the evaluation buttons) that can be easily integrated into different parts of the web portal. The use of React also facilitates a dynamic and interactive user experience, ensuring the feedback process is smooth and engaging. The chosen framework is also beneficial for implementing accessibility standards, such as ARIA labels and keyboard navigation, which are vital for inclusivity.

📋 Tasks: A Step-by-Step Guide

The project breaks down into several key tasks, each contributing to a functional feedback system. The initial phase focuses on developing the core React components.

Part 1: React Components (Days 1-2)

Creating the EvaluationButtons Component is the primary task here. This component requires three buttons: 'Helpful,' 'Not Helpful,' and 'Incorrect.' The design specifies button states (default, selected, disabled, and loading), Tailwind CSS styling, and support for dark mode. Accessibility is a key consideration, and we'll integrate ARIA labels and keyboard navigation to achieve it. Following this, button interactions will be added. This includes enabling single-click selection, disabling after submission, displaying a loading state, and providing visual feedback through color changes. We will integrate Toast Notifications. These will provide success and error messages. We will use the shadcn/ui toast component, designed to automatically disappear after three seconds. These components are essential for a good user experience.

Part 2: React Query Integration (Days 2-3)

This phase centers on integrating the React Query library for data fetching and mutations, which is crucial for handling API calls and managing the state of evaluation submissions. The focus is to use the useEvaluationMutation hook, which uses the useMutation hook from @tanstack/react-query. This hook will handle the POST /api/v1/evaluations API call. Error handling and success callbacks will be integrated to manage the results. We will also introduce the useEvaluationStats Hook to monitor the evaluation statistics. This will use useQuery to fetch data from a stats endpoint, which will auto-refresh every 30 seconds. We'll utilize cache management and the stale-while-revalidate strategy to optimize data freshness and performance. Another crucial aspect is creating an API Client that manages the communication with the backend. This setup includes Axios configuration, JWT authentication headers, request and response interceptors, and robust error handling. The API client is designed to facilitate seamless and secure communication with the backend, allowing efficient management of API calls and data handling.

Part 3: State Management (Days 3-4)

State management is vital for controlling how the application responds to user actions and data changes. The goal is to set up a way to keep track of the submitted evaluations and ensure they don't get submitted again. This section covers the setup of local and global state management using Zustand. Local state management involves the selectedRating state (null | 'helpful' | 'not_helpful' | 'incorrect'), the isSubmitting state, the error state, and a successMessage state. Global state management uses the evaluationStore with Zustand. The store will track submitted evaluations and persist them to localStorage to avoid duplicate submissions. This approach guarantees that user feedback is tracked properly and also provides a good user experience.

Part 4: Integration & Testing (Days 4-5)

The final phase combines all the components and ensures they work well together. We'll start by integrating the EvaluationButtons component into the IncidentDetailView, passing messageId and conversationContext props, positioning it below agent responses, and ensuring it is responsive. Next, we will create Storybook Stories. These stories will showcase different states of the component, including default, loading, selected (for each button), and error states, and dark mode variations. Unit Tests will verify component rendering, button click handlers, API mutation calls, state updates, and error handling. Finally, E2E Tests (Playwright) will be implemented to test the full user flow. These tests will verify the actions, such as user clicks on 'Helpful' and confirming that the API is called and a toast is shown. These E2E tests will also confirm that network errors are properly handled and that duplicate submissions are prevented.

🎨 Component Design: Detailed Breakdown

This section focuses on the structure and behavior of the EvaluationButtons Component.

EvaluationButtons Component

The EvaluationButtons.tsx file defines the EvaluationButtons component in the provided code. It imports necessary modules from React, and from other project files. The component uses the useEvaluationMutation hook, which handles the API calls. The handleEvaluate function submits the evaluation by calling submitEvaluation, passing along the required data. The component includes a success callback to show a success toast and the onEvaluationSubmitted callback to enable additional actions. In case of an error, it displays an error toast. The return part of the component includes the layout for the feedback buttons, including buttons for helpful, not helpful, and incorrect. Each button uses different variant based on the selectedRating state and is disabled during submission or if a rating is already selected. The component provides feedback to users during processing and when actions are successfully completed or encounter issues.

React Query Hook

The useEvaluationMutation hook handles the API interactions. It uses useMutation from @tanstack/react-query to perform the mutation. When the mutation succeeds, the hook invalidates queries and updates the application's cache, ensuring the data is fresh. The onSuccess callback triggers tracking of events using window.analytics?.track(). This allows us to track user actions, providing critical insights into user behavior and engagement.

TypeScript Types

Type definitions are essential for type safety and code quality. The EvaluationRating enum defines the rating options: HELPFUL, NOT_HELPFUL, and INCORRECT. The Platform enum specifies the platform from which the evaluation originates. The ConversationContext interface defines the context data. This includes the conversationId, incidentId, userQuery, agentResponse, and associated metadata. The EvaluationRequest interface defines the structure of data, including messageId, rating, platform, context, device information, and a timestamp. The EvaluationResponse interface defines the structure of the API responses, including id, status, message, and evaluationId. This structure promotes code maintainability and helps with API interactions.

🧪 Testing Requirements: Ensuring Quality

This section details testing requirements, which guarantee the reliability of the feedback system.

Unit Tests (Target: 85%+ coverage)

Unit tests are vital to confirm individual components and functions. The targets include: validating component rendering, button click handlers that trigger mutations, loading state display that shows a spinner, selected state that disables buttons, error state display that shows a toast, and success state display that shows a toast.

Integration Tests

Integration tests focus on testing the interactions between different components and modules. The targets for this category include: the API call with the correct payload, react query cache invalidation, local storage persistence, and analytics tracking.

E2E Tests (Playwright)

E2E (End-to-End) tests confirm the entire flow of user interactions. Key targets include verifying the full flow: clicking a button, API calls, toast notifications, and button disabling, as well as handling network errors and preventing duplicate submissions.

📐 Technical Specifications

This section highlights the technical specifics of the project, including dependencies and styling.

Dependencies

The project uses a set of key dependencies to function correctly. Some of the most important include: React for building UI components, @tanstack/react-query for handling data fetching and mutations, Axios for making API requests, Zustand for state management, lucide-react for icons, @radix-ui/react-toast for toast notifications, and Tailwind CSS for styling.

Styling (Tailwind CSS)

Tailwind CSS is used for styling the components. We define button states (hover, selected, and disabled) and dark mode variations. This approach allows for a consistent and accessible user experience.

✅ Acceptance Criteria: Project Validation

This section lists the criteria that must be met for the project to be considered successful:

• Functional EvaluationButtons component.
• Correct rendering of the three buttons.
• Functioning React Query mutation.
• Successful API calls.
• Display of Toast notifications.
• Working button states (default, selected, loading, disabled).
• Dark mode support.
• Accessibility compliant with WCAG 2.1 AA standards.
• Working keyboard navigation.
• Responsive design for mobile and desktop.
• Creation of Storybook stories.
• Unit test coverage of more than 85%.
• Passing E2E tests.
• Code review approval.

📊 Success Metrics: Measuring Impact

This section details the performance indicators used to measure the project's success:

• Component render time: less than 50ms.
• API call latency: less than 200ms (p95).
• User interaction time: less than 3 seconds.
• Test coverage of more than 85%.
• Zero critical bugs.
• Storybook coverage of 100% states.

🔗 Related Issues: Contextual Information

This section lists related issues and documentation to facilitate project understanding.

Depends On: #141 (Backend Evaluation API must be deployed)

Related:

• iOS Evaluation UI (to be created)
• Android Evaluation UI (to be created)
• Slack Evaluation Integration (to be created)

Documentation:

• EVALUATION_SYSTEM.md - Lines 462-733
• Fullstack README

Start Date: Dec 30, 2025 (Week 9)

Target Completion: Jan 3, 2026 (Week 9)

Review: Jan 3, 2026

---

For more details about React and its use in web development, you can visit the official React documentation.