Feedback Modal

  1. Overview
  2. Hand Off Documentation
  3. Player
  4. Feedback Modal

Feature Owner: Joshua Uriel Tribiana
Module: Player
Priority: P1
Week 5 Sprint: Implemented
Date: 06-30-2026

EXECUTIVE SUMMARY

What is this feature?
The Feedback Modal is the learner-facing overlay that appears after a question is submitted and provides contextual feedback for the selected answer. It is designed to reinforce correct understanding, explain mistakes, and guide the learner to the next step.

Why does it matter?
Feedback is a core part of the learning loop. Without a clear, visible response after an answer is submitted, learners can feel uncertain about their result or lose momentum. This modal turns the submission event into a purposeful moment of guidance.

What’s the MVP scope?
The current implementation includes:

  • A learner-facing feedback dialog after question submission

  • Status-based visual treatment for correct, partial, wrong, and default feedback

  • Integration with the quest player’s question state flow

  • A blocking experience that prevents accidental dismissal while feedback is visible

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Learners can answer a question but receive no structured, visible explanation of how their response performed. This makes the experience feel unfinished and can reduce confidence in the content.

Pain Point

  • Emotional: Confusion or uncertainty after answering a question

  • Functional: No immediate explanation tied to the learner’s choice

  • Business Impact: Lower engagement and weaker instructional clarity

Future State (With Feature)

After a learner submits an answer, they immediately see a clear feedback message that explains their result and helps them understand what to do next.

Marketing Hook

“Turn every answer into a learning moment with immediate, polished feedback.”

2. CODEBASE ASSESSMENT

Current Implementation Status

The feedback modal is already wired into the learner experience and appears as part of the question submission flow.

Primary Files

Current Behavior Summary

  • The modal becomes visible when a learner submits a question with feedback content

  • The feedback is derived from the selected choice, choice status, or hook-generated result logic

  • The modal uses a branded visual treatment depending on whether the result is correct, wrong, partial, or default

  • The dialog is intentionally non-dismissible through standard close interactions while feedback is active

Strengths Already Present

  • The modal is tightly coupled to the real learner flow rather than being a disconnected demo component

  • Status-based styling makes the experience visually intuitive

  • The current implementation supports both single-select and checkbox-style question flows

Gaps / Hardening Opportunities

  • The modal is currently driven entirely by client-side state and the current question payload

  • There is no dedicated analytics event for feedback modal views or acknowledgements

  • The experience could be extended to support richer feedback templates or richer CTA flows later

3. 4D FRAMEWORK MAPPING

Diagnose

Learners need immediate, clear confirmation after answering a question so they can understand whether they were successful and what to learn next.

Design

The modal offers a deliberate, high-contrast feedback moment with a focused message and a simple acknowledgement action.

Develop

The UI is implemented as a reusable learner component and pulled into the question-block experience with minimal friction.

Deliver

The learner sees a polished feedback moment immediately after submission, reinforcing the instructional intent of the question.

4. USER FLOWS

Entry Point

A learner is interacting with a question node inside the quest player.

Success Criteria

  • The learner sees feedback after submitting an answer

  • The feedback is relevant to the selected choice or answer outcome

  • The learner can acknowledge the feedback and continue the flow

Main Flow (Happy Path)

  1. Learner selects an answer choice

  2. Learner submits the question

  3. The quest player computes the appropriate feedback content and status

  4. The feedback modal opens with the message and result styling

  5. Learner clicks “Got it” to acknowledge and continue

Edge Cases

  • No feedback content available: The modal does not open and the flow continues quietly

  • Checkbox question: Feedback is derived from the combined selected choices and correctness rules

  • True/false question: Feedback is derived from the mapped answer status

  • No valid submission: The modal does not open because the submission state is invalid

Decision Points

  • IF feedback text exists → the modal opens

  • IF no feedback text is present → no modal appears

  • IF the learner acknowledges → the state clears and the journey continues

5. INFORMATION ARCHITECTURE

Primary Information (Always visible)

  • Feedback title such as “Correct!”, “Not quite…”, or “Partially correct”

  • The feedback body text

  • A single acknowledgement button

Secondary Information

  • Status-colored icon and container styling

  • Result-specific emphasis based on correctness state

Tertiary Information (Hidden until needed)

  • Internal state mapping of the question result

  • Choice status values used to compute the displayed feedback

Actions

Primary CTA:

  • Got it

Secondary Actions:

  • None in the current implementation

6. WIREFRAMES

Excluded — existing UI

Key Screens:

  1. Question card with answer choices

  2. Feedback modal overlay after submission

  3. Acknowledgement state that returns the learner to the normal flow

Annotations:

  • The modal appears only after a valid question submission

  • It is intentionally blocking to preserve focus on the feedback message

  • It uses high-contrast, status-aware styling for clarity

7. WIREFLOWS

 
 
Creator Setup
─────────────
 
+----------------------+
| Edit Decision Edge   |
+----------------------+
           |
           v
+----------------------+
| Enter Outcome Title  |
| & Feedback Text      |
+----------------------+
           |
           v
+----------------------+
| Save to Quest        |
| Database             |
+----------------------+
 
 
Learner Experience
──────────────────
 
+----------------------+
| Learner Reaches      |
| Decision Node        |
+----------------------+
           |
           v
+----------------------+
| Select Choice        |
+----------------------+
           |
           v
+----------------------+
| Retrieve Edge        |
| Feedback             |
+----------------------+
           |
           v
+----------------------+
| Display Feedback     |
| Modal                |
+----------------------+
           |
           v
+----------------------+
| Click Continue       |
+----------------------+
           |
           v
+----------------------+
| Navigate to Next     |
| Node                 |
+----------------------+
           |
           └───────────────► (Repeat until quest ends)

8. PROTOTYPE

Excluded — feature is fully implemented.

How to test:

  1. Open a learner quest with a question node

  2. Select an answer and submit it

  3. Confirm the feedback modal appears with the correct status styling

  4. Click “Got it” and confirm the experience returns to the normal question flow

9. FRONTEND STATE MODEL

Core State

The modal is controlled by two values in the quest player hook:

  • showingFeedback

  • currentFeedback

Shape of Feedback

The feedback object is currently modeled as:

export type Feedback = {
  text: string;
  status?: "correct" | "partial" | "wrong";
};

Source of Truth

  • The selected answer choice provides the feedback text in many cases

  • The question submission handler derives a status from the selected answer and its correctness metadata

  • The modal itself is stateless and only renders what it receives from props

10. COMPONENT RESPONSIBILITIES

FeedbackModal

Responsibilities:

  • Render the modal content

  • Apply status-specific styling and iconography

  • Ensure the feedback is shown in a focused, non-dismissible state

QuestionBlock

Responsibilities:

  • Render the question UI

  • Pass the current feedback state into the modal

  • Trigger the feedback modal when the learner submits

useQuestPlayer

Responsibilities:

  • Decide whether feedback should appear

  • Determine the feedback text and status for the current submission

  • Reset the modal state when the learner moves on or restarts the quest

11. VISUAL SYSTEM

Status Mapping

  • Correct: green treatment

  • Wrong: red treatment

  • Partial: yellow treatment

  • Default: blue treatment

UI Elements

  • Icon in a circular badge

  • Large heading label

  • Centered feedback message in a bordered card-like panel

  • Single CTA button labeled “Got it”

Interaction Rules

  • Standard close actions are prevented while the modal is open

  • The modal is meant to feel like a short, guided pause rather than a general-purpose dialog

12. DATA REQUIREMENTS

Frontend Needs

The UI needs:

  • The current feedback text

  • The feedback status for styling and labeling

  • A way to acknowledge the modal and clear the state

No Backend Requirements

This feature does not currently depend on any API route or persistence layer. It is entirely driven by the client-side quest flow.

13. SECURITY & AUTHORIZATION

Who can access this feature?

  • Learner: ✓

  • Creator: ✗

  • Reviewer: ✗

Authorization Logic

No special authorization is required. The modal is part of the learner experience and uses the currently active quest state.

14. ERROR HANDLING

Common Cases

  • No feedback text exists for the submitted choice

  • The modal is opened without a valid feedback object

  • The learner attempts to navigate while feedback is still active

Handling Guidance

  • Gracefully suppress the modal if no feedback is present

  • Keep the state transitions deterministic when the learner moves back or restarts the quest

15. TESTING CHECKLIST

Happy Path

  • Selecting and submitting a correct answer shows a feedback modal

  • Selecting and submitting an incorrect answer shows a feedback modal

  • The modal displays the expected title, message, and styling

  • The learner can acknowledge the modal and continue

Edge Cases

  • Questions without feedback text do not show the modal

  • Checkbox and true/false questions display the expected feedback behavior

  • Restarting or navigating backward clears the modal state correctly

16. OPEN QUESTIONS

For Frontend

  • Should the modal support richer actions such as “Try again” or “See explanation” in a later iteration?

  • Should feedback modal events be tracked for analytics and instructional tuning?

For Product

  • Should this modal become a reusable pattern for other learner interactions such as completion states or hinting?

17. OUT OF SCOPE (v1.1+)

Not planned in the current implementation:

  • Backend-stored feedback templates

  • Analytics dashboards tied to feedback modal interactions

  • Multi-step explanation flows inside the modal

18. SUCCESS METRICS

How will we know this experience is working well?

  • Learners clearly understand whether their answer was correct

  • Questions feel more instructional and less abrupt

  • The modal is acknowledged quickly and does not feel obstructive

19. DEPENDENCIES

This feature depends on:

  • The learner question state managed by the quest player hook

  • The feedback content attached to answer choices

  • The shared learner UI component system

These features depend on this:

  • The learner quiz and question experience

  • Any future instructional feedback system for quest content

20. TIMELINE & OWNERSHIP

Implementation Ownership

  • Owner: Joshua Uriel Tribiana

  • QA: Christian

Written by Uriel Last updated June 30, 2026
Was this article helpful?