# TCH-16: Question Builder — Figma Production Specs --- ## OVERVIEW The Question Builder is the flagship assessment creation screen. It supports 9 question types with auto-grading, manual grading, partial marks, randomization, and preview capabilities. ### Frame: `RP/Teacher/TCH-16-QuestionBuilder` **Canvas sizes:** Desktop (1440), Mobile (768) × Light + Dark --- ## DESKTOP LAYOUT (1440px) ``` Frame: TCH-16-QuestionBuilder-Desktop-Light Width: 1440px, Height: auto BG: color/background ├── RP/Sidebar (teacher) ├── RP/Topbar (teacher) │ ├── Content Area │ Max-width: 960px (centered) │ Padding: 24px │ Layout: Vertical, gap 24px │ │ ├── PAGE HEADER │ │ ├── H1: "Question Builder" │ │ ├── Breadcrumb: "Dashboard > Assignments > Add Question" │ │ └── Context: "Assignment: Math Quiz Ch.5 • Max: 100 pts" │ │ │ ├── QUESTION TYPE SELECTOR │ │ RP/Tabs (variant: pill, scrollable) │ │ │ │ ┌──────┬───────┬──────┬───────┬──────┬───────┬──────┬────────┬────────┐ │ │ │ MCQ │Multi │ T/F │Match │Fill │Short │Essay │Upload │Numeric │ │ │ └──────┴───────┴──────┴───────┴──────┴───────┴──────┴────────┴────────┘ │ │ │ │ Tab labels: │ │ ┌────┬───────┬────┬──────┬────┬──────┬──────┬────────┬────────┐ │ │ │ MC │Multi │ T/F│Match │Fill│Short │Essay │Upload │Numeric │ │ │ └────┴───────┴────┴──────┴────┴──────┴──────┴────────┴────────┘ │ │ │ │ Active tab: BG color/secondary, text white │ │ Inactive: BG color/surface, text color/body-text │ │ │ ├── QUESTION FORM (changes per type) │ │ RP/Card (shadow/sm, padding/lg) │ │ Width: 100% │ │ │ │ FOR ALL TYPES: │ │ ├── Question Text (RP/Input, textarea, rows: 4) │ │ │ Label: "Question Text *" │ │ │ Placeholder: "Enter your question here..." │ │ │ Width: 100% │ │ │ │ │ ├── Points (RP/Input, number) │ │ │ Label: "Points *" │ │ │ Value: 10 │ │ │ Width: 120px │ │ │ │ │ └── Explanation (RP/Input, textarea, rows: 2) │ │ Label: "Explanation (shown after grading)" │ │ Placeholder: "Explain the correct answer..." │ │ Width: 100% │ │ Optional │ │ │ │ ─── TYPE-SPECIFIC FIELDS BELOW ─── │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: MULTIPLE CHOICE (MC) │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Options List (Vertical, gap 8px) │ │ │ │ Each option: │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │ ○ | Option text input [Delete] [✓] │ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ States: │ │ │ │ ○ = Not selected (circle, 20px, border #CBD5E1) │ │ │ │ ● = Correct (filled, color/secondary) │ │ │ │ │ │ │ │ [+ Add Option] button (ghost, sm) │ │ │ │ Min: 2 options, Max: 6 options │ │ │ │ │ │ │ │ Settings: │ │ │ │ ☐ Randomize option order │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: MULTI SELECT │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Options List (same as MC but with checkboxes) │ │ │ │ ☐ = Not selected (square, 20px, border #CBD5E1) │ │ │ │ ☑ = Correct (filled, color/secondary) │ │ │ │ │ │ │ │ [+ Add Option] button │ │ │ │ Min: 2, Max: 6 │ │ │ │ │ │ │ │ Settings: │ │ │ │ ☑ Partial credit (RP/Toggle, default: on) │ │ │ │ "Award partial points for selecting some │ │ │ │ but not all correct answers" │ │ │ │ Min correct selections: [number] │ │ │ │ ☐ Randomize option order │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: TRUE / FALSE │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Auto-created options (no add/delete): │ │ │ │ ○ True │ │ │ │ ○ False │ │ │ │ │ │ │ │ Click to select correct answer │ │ │ │ Radio group (only one can be correct) │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: MATCHING │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Match Pairs (Vertical, gap 8px) │ │ │ │ Each pair: │ │ │ │ ┌───────────────────── ↔ ─────────────────────┐ │ │ │ │ │ [Left Item input] → [Right Item input] [×]│ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ [+ Add Pair] button │ │ │ │ Min: 2 pairs, Max: 6 pairs │ │ │ │ │ │ │ │ Settings: │ │ │ │ ☑ Shuffle right items on student interface │ │ │ │ │ │ │ │ Note: "Right items will be shuffled for each │ │ │ │ student to prevent copying." │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: FILL IN THE BLANK │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Question Text with [BLANK] markers: │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │ The capital of Ghana is [BLANK]. │ │ │ │ │ │ │ │ │ │ │ │ Tip: Type [BLANK] where you want a blank. │ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ Live Preview: │ │ │ │ "The capital of Ghana is [_______]." │ │ │ │ (BLANK replaced with underlined input boxes) │ │ │ │ │ │ │ │ Acceptable Answers (per blank): │ │ │ │ Blank 1: │ │ │ │ ├── [Accra] [+ Add Alternative] │ │ │ │ └── Alternatives: ["Accra", "ACCRA", "accra"] │ │ │ │ │ │ │ │ Settings: │ │ │ │ ☐ Case sensitive (default: off) │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: SHORT ANSWER │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Correct Answer (RP/Input, text) │ │ │ │ "Enter the expected answer..." │ │ │ │ │ │ │ │ Settings: │ │ │ │ ☐ Case sensitive (default: off) │ │ │ │ ☑ Accept alternative answers │ │ │ │ Alternative answers list: │ │ │ │ [Alternative 1] [+ Add Alternative] │ │ │ │ │ │ │ │ Grading: Manual (flagged for review) │ │ │ │ Note: "This question type requires manual grading." │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: ESSAY │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Word Limit (RP/Input, number, optional) │ │ │ │ "Maximum 500 words (leave blank for no limit)" │ │ │ │ │ │ │ │ Marking Criteria (RP/Input, textarea, rows: 4) │ │ │ │ "Describe the criteria for grading this essay..." │ │ │ │ Shown to teacher when grading, not to students. │ │ │ │ │ │ │ │ Grading: Always manual │ │ │ │ Note: "Essay questions always require manual │ │ │ │ grading. Students will see 'Pending Review' until │ │ │ │ you grade their response." │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: FILE UPLOAD │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Question Text / Instructions (textarea) │ │ │ │ "Upload your completed worksheet as a PDF..." │ │ │ │ │ │ │ │ Accepted File Types (checkboxes): │ │ │ │ ☑ PDF ☐ DOC/DOCX ☑ JPG/PNG ☐ ZIP ☐ Other │ │ │ │ │ │ │ │ Max File Size (RP/Input, number) │ │ │ │ "10" MB (default) │ │ │ │ │ │ │ │ Grading: Always manual │ │ │ │ Note: "Teacher downloads and reviews the file. │ │ │ │ No auto-grading possible." │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ TYPE: NUMERIC │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Correct Answer (RP/Input, number) │ │ │ │ "42" │ │ │ │ │ │ │ │ Tolerance (RP/Input, number) │ │ │ │ "± 0.5" (acceptable range) │ │ │ │ │ │ │ │ Example: "Answer 42 with tolerance 0.5 accepts │ │ │ │ any value between 41.5 and 42.5." │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ ├── QUESTION PREVIEW │ │ RP/Card (padding/md, border) │ │ Layout: Vertical, gap 12px │ │ │ │ ├── Header: "Student Preview" (H5) │ │ ├── Separator line │ │ │ │ │ └── Preview content (rendered as student would see): │ │ ├── Question number + text │ │ ├── Points badge │ │ └── Answer input (disabled, preview mode) │ │ Type-specific rendering: │ │ MC: Radio buttons │ │ Multi: Checkboxes │ │ T/F: Two radio buttons │ │ Match: Left items → right dropdowns │ │ Fill: Text with [blank] boxes │ │ Short: Text input (disabled) │ │ Essay: Textarea (disabled) │ │ Upload: File upload area (disabled) │ │ Numeric: Number input (disabled) │ │ │ ├── AUTO-GRADING SETTINGS (for auto-gradable types) │ │ Only visible for: MC, Multi, T/F, Fill, Numeric │ │ │ │ RP/Card (padding/md) │ │ Layout: Vertical, gap 12px │ │ │ │ ├── H5: "Auto-Grading Settings" │ │ │ │ │ ├── MC/Multi: "Correct answers will be graded automatically." │ │ │ │ │ ├── Multi Select: │ │ │ ├── RP/Toggle: "Allow partial credit" │ │ │ │ "Award points proportional to correct selections" │ │ │ └── Partial credit formula shown: │ │ │ "If 3 of 5 correct options selected and 2 are wrong: │ │ │ (3/5) × points - (2 × penalty) = final score" │ │ │ │ │ ├── Fill in Blank: │ │ │ ├── ☐ Case sensitive │ │ │ └── Alternative answers per blank │ │ │ │ │ └── Numeric: │ │ "Answer within ±tolerance = full credit" │ │ │ ├── MANUAL GRADING SETTINGS (for essay/short/upload) │ │ Only visible for: Essay, Short Answer, File Upload │ │ │ │ RP/Card (padding/md) │ │ Layout: Vertical, gap 12px │ │ │ │ ├── H5: "Manual Grading Settings" │ │ │ │ │ ├── "This question will be flagged for review after │ │ │ submission. You can find it in the Review Queue (TCH-15)." │ │ │ │ │ └── Marking criteria display (if essay) │ │ │ └── ACTIONS BAR │ Layout: Horizontal, gap 12px, justify: end │ ├── RP/Button (ghost): "Cancel" │ ├── RP/Button (outline): "Save as Draft" │ └── RP/Button (primary, lg): "Add Question" │ → Adds to question list │ → Returns to TCH-09 or TCH-12 │ └── Bottom padding: 48px ``` --- ## QUESTION TYPE SUMMARY | Type | Tab Label | Auto-gradable | Manual Review | Partial Credit | Randomize | |------|-----------|---------------|---------------|----------------|-----------| | Multiple Choice | MC | ✓ | ✗ | ✗ | ✓ | | Multi Select | Multi | ✓ | ✗ | ✓ | ✓ | | True/False | T/F | ✓ | ✗ | ✗ | ✗ | | Matching | Match | ✓ | ✗ | ✓ | ✓ (right items) | | Fill in Blank | Fill | ✓ | ✗ | ✗ | ✗ | | Short Answer | Short | ✗ | ✓ | ✗ | ✗ | | Essay | Essay | ✗ | ✓ | ✗ | ✗ | | File Upload | Upload | ✗ | ✓ | ✗ | ✗ | | Numeric | Numeric | ✓ | ✗ | ✓ (tolerance) | ✗ | --- ## QUESTION STATES IN LIST When questions are added to an assignment/exam, they appear in a reorderable list: ``` ┌──────────────────────────────────────────────────────────────┐ │ ⠿ Q1 [MC] "What is the capital of Ghana?" 10 pts │ │ [Edit] [Delete] │ ├──────────────────────────────────────────────────────────────┤ │ ⠿ Q2 [T/F] "Paris is the capital of France" 5 pts │ │ [Edit] [Delete] │ ├──────────────────────────────────────────────────────────────┤ │ ⠿ Q3 [Essay] "Explain photosynthesis..." 20 pts │ │ ⚠ Manual grading │ │ [Edit] [Delete] │ ├──────────────────────────────────────────────────────────────┤ │ ⠿ Q4 [Num] "Solve: 3x + 7 = 22" 10 pts │ │ [Edit] [Delete] │ ├──────────────────────────────────────────────────────────────┤ │ │ │ Total: 45 points │ │ │ │ [+ Add Question] │ └──────────────────────────────────────────────────────────────┘ ``` Each row: - Drag handle (⠿) for reordering - Question number - Type badge (colored by type) - Question text (truncated to 80 chars) - Points - Manual review warning if applicable - Edit/Delete actions --- ## QUESTION PREVIEW MODAL When "Preview" is clicked on any question: ``` RP/Modal (lg) ├── Header: "Question Preview" ├── Content: │ "Q1 (10 points)" │ [Question text rendered as student would see it] │ [Answer input — disabled, for preview only] ├── Footer: │ [Close] ``` --- ## RANDOMIZATION ### Question-Level Randomization - Toggle on assignment/exam level: "Randomize question order" - Each student sees questions in different order ### Option-Level Randomization (per question) - MC: Toggle "Randomize option order" - Multi: Toggle "Randomize option order" - Matching: Always shuffle right items (toggle to disable) ### Implementation Notes - Randomization happens at exam start, not on page load - Consistent within a single attempt - Different between attempts --- ## ATTEMPT TRACKING ### In Question Builder Context ``` Question: Q1 (MC, 10 pts) ├── Attempt 1: Correct (10/10) ├── Attempt 2: Wrong (0/10) └── Best score: 10/10 (if "best attempt" grading) ``` ### Grading Strategy Options (exam-level) | Strategy | Description | |----------|-------------| | `best` | Use highest score across attempts | | `last` | Use most recent attempt | | `first` | Use first attempt only | | `average` | Average of all attempts | | `sum` | Sum of all attempts | --- ## DARK MODE All form elements follow dark mode tokens: - Input BG: #1E293B, Border: #475569, Text: #E2E8F0 - Tab active: color/secondary (same) - Tab inactive: #1E293B BG, #94A3B8 text - Card BG: #1E293B, Border: #334155 - Preview BG: #0F172A