Spec: Tutorial/Guided Mode

Overview

Provide an interactive tutorial system built into DigitalWorks that guides new users through circuit design concepts step-by-step, with hands-on exercises that teach tool usage and digital logic fundamentals simultaneously.

Motivation

• New users face a steep learning curve combining tool mechanics and digital logic concepts.
• Educators want structured lessons they can assign to students.
• Interactive tutorials are more effective than reading documentation.
• Reduces support burden by teaching users to be self-sufficient.
• Differentiator: most circuit simulators lack integrated learning paths.

Requirements

Functional Requirements

Tutorial System

1. Step-by-Step Guidance: Each tutorial consists of sequential steps with instructions and expected actions.
2. Highlighting: Highlight relevant UI areas (toolbox items, canvas regions, menu items) during each step.
3. Action Validation: Verify the user completed each step correctly before proceeding.
4. Undo Protection: Prevent users from accidentally undoing tutorial progress.
5. Progress Tracking: Remember completed tutorials and current position.
6. Restart/Resume: Users can restart or resume interrupted tutorials.
7. Skip Ahead: Allow experienced users to skip familiar steps.
8. Tooltips/Callouts: Floating instruction panels pointing to relevant areas.

Tutorial Content

9. Getting Started Series:
   • Tutorial 1: Navigating the interface (toolbox, canvas, menus).
   • Tutorial 2: Placing your first gate (AND gate).
   • Tutorial 3: Drawing wires and connections.
   • Tutorial 4: Running a simulation.
   • Tutorial 5: Using input switches and output LEDs.
10. Logic Fundamentals Series:
    • Tutorial 6: Building a NOT gate (inverter behavior).
    • Tutorial 7: AND, OR, NAND, NOR truth tables.
    • Tutorial 8: XOR and parity checking.
    • Tutorial 9: Building a half adder.
    • Tutorial 10: Building a full adder.
11. Sequential Logic Series:
    • Tutorial 11: D flip-flop and memory.
    • Tutorial 12: Building a counter.
    • Tutorial 13: Clock signals and timing.
12. Advanced Series:
    • Tutorial 14: Creating macros (sub-circuits).
    • Tutorial 15: Using the oscilloscope.
    • Tutorial 16: Test bench automation.

Sandbox Mode

13. Challenge Exercises: After each tutorial, present a challenge (e.g., "Build a 2-bit comparator").
14. Automatic Verification: Check if the user's circuit produces correct outputs for all inputs.
15. Hints System: Progressive hints (conceptual → specific → solution reveal).
16. Scoring: Optional scoring based on gate count, completion time, or elegance.

Tutorial Authoring

17. Tutorial File Format: Tutorials defined in structured files (JSON/YAML).
18. Custom Tutorials: Educators can create custom tutorials for their courses.
19. Template Circuits: Tutorials can include starter circuits (partially built).

Non-Functional Requirements

• Tutorials work without internet connection (bundled with app).
• Tutorial overlay does not interfere with circuit functionality.
• Tutorial system adds < 2MB to application package size.
• Custom tutorials can be shared as single files.
• Accessibility: tutorials work with keyboard-only and screen readers.

Design

Tutorial Definition Format

{
  "id": "getting-started-01",
  "title": "Your First Circuit",
  "description": "Learn to place an AND gate and connect inputs",
  "series": "Getting Started",
  "order": 1,
  "estimatedMinutes": 5,
  "prerequisites": [],
  "starterCircuit": null,
  "steps": [
    {
      "id": "step-1",
      "instruction": "Click the AND gate in the toolbox to select it.",
      "highlight": { "target": "toolbox.gates.and", "style": "pulse" },
      "validation": { "type": "mode", "expected": "PlaceComponent", "component": "AndGate" },
      "hint": "Look in the Gates section of the toolbox on the left."
    },
    {
      "id": "step-2",
      "instruction": "Click on the canvas to place the AND gate.",
      "highlight": { "target": "canvas", "style": "region" },
      "validation": { "type": "componentExists", "componentType": "AndGate", "minCount": 1 },
      "hint": "Click anywhere on the white canvas area."
    }
  ],
  "challenge": {
    "description": "Build a circuit that outputs HIGH only when both inputs are HIGH.",
    "verification": {
      "truthTable": { "inputs": ["A", "B"], "outputs": ["Y"], "expected": [[0,0,0],[0,1,0],[1,0,0],[1,1,1]] }
    }
  }
}

Tutorial Overlay UI

┌──────────────────────────────────────────────────┐
│ Tutorial: Your First Circuit          Step 2/8   │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌────────────────────────────────┐              │
│  │                                │              │
│  │       [Canvas Area]            │              │
│  │                                │    ┌──────┐  │
│  │          ↑ highlighted         │    │ Step │  │
│  │                                │    │ Info │  │
│  └────────────────────────────────┘    │ Panel│  │
│                                        └──────┘  │
│ [← Back]  ●●○○○○○○  [Skip →]   [Exit Tutorial] │
└──────────────────────────────────────────────────┘

Validation Engine

public interface ITutorialValidator
{
    bool Validate(Circuit circuit, ValidationRule rule);
}

public class TruthTableValidator : ITutorialValidator
{
    public bool Validate(Circuit circuit, ValidationRule rule)
    {
        // Run all input combinations through simulation
        // Compare outputs against expected truth table
        // Return true if all match
    }
}

Progress Persistence

// Stored in user settings
{
  "tutorialProgress": {
    "getting-started-01": { "completed": true, "completedAt": "2026-08-01T..." },
    "getting-started-02": { "completed": false, "currentStep": "step-4" },
    "logic-fundamentals-01": { "completed": false, "currentStep": null }
  },
  "challengeScores": {
    "getting-started-01": { "gateCount": 3, "time": 45, "stars": 3 }
  }
}

Implementation Tasks

1. Define tutorial file format (JSON schema) and author first tutorial.
2. Create TutorialEngine class (step management, progression, validation).
3. Implement tutorial overlay UI (step panel, highlight overlays, progress dots).
4. Implement highlighting system (pulse animation on target UI elements).
5. Implement step validation rules (mode check, component exists, wire connected, truth table).
6. Implement hints system (progressive reveal).
7. Create challenge mode with truth-table verification.
8. Author "Getting Started" tutorial series (5 tutorials).
9. Author "Logic Fundamentals" series (5 tutorials).
10. Author "Sequential Logic" series (3 tutorials).
11. Implement progress persistence and resume functionality.
12. Add Tutorial menu/button and welcome screen integration.
13. Create tutorial authoring documentation for educators.

Risks & Open Questions

• How much hand-holding vs. freedom? (strict step validation vs. freeform with hints)
• Should tutorials pause simulation or work alongside it?
• How to handle users who deviate from the expected path?
• Should there be a tutorial marketplace for educator-authored content?
• Localization: how to support tutorials in multiple languages?

Priority

Low — High value for onboarding but significant content-authoring investment.