---
phase: quick
plan: 260329-tk2
subsystem: ui/lesson
tags: [ux, companion, onboarding, child-friendly]
one_liner: "Added 2.5-second child-friendly German companion instructions before practice and words phases in the lesson screen"
key_files:
  modified:
    - src/ui/screens.ts
decisions:
  - "Companion text cleared before exercise starts (after delay) so it doesn't distract during actual typing"
  - "async/await conversion matches existing discover phase pattern for consistency"
metrics:
  duration: 5min
  tasks: 1
  files: 1
  completed: 2026-03-29
---

# Quick Task 260329-tk2: Ueben-Phase kindgerechte Erklaerung statt nichts

## Summary

Added child-friendly companion instructions at the start of the practice ("Ueben") and words ("Woerter") phases. Previously these phases showed no explanation, leaving a 7-year-old without guidance on what to do. Now each phase begins with a 2.5-second companion message before the exercise starts.

## Tasks Completed

| Task | Name | Commit | Files |
| ---- | ---- | ------ | ----- |
| 1 | Add companion instructions for practice and words phases | 4cb5fa6 | src/ui/screens.ts |

## Changes Made

**src/ui/screens.ts:**

- `runPracticePhase()` converted from callback-based `Promise<void>` return to `async function`
- Before exercise begins, shows: "Jetzt kannst du ueben! Druecke die Taste zu dem Buchstaben, der herunterfaellt."
- `runWordsPhase()` converted from callback-based to `async function`
- Before exercise begins, shows: "Jetzt kommen ganze Woerter! Tippe die Buchstaben nacheinander ein."
- Both functions display companion area, wait 2500ms, then clear text before starting exercise
- `cancelled` check after delay ensures clean abort if user navigates away during the intro

## Deviations from Plan

None - plan executed exactly as written.

## Verification

- `npx vitest run`: 85/85 tests passed
- `npx tsc --noEmit`: No TypeScript errors

## Known Stubs

None.