From 5f245789ff0cfbace7a482365716bc8d51ad82d3 Mon Sep 17 00:00:00 2001
From: Alex Kanunnikov <lifeart92@gmail.com>
Date: Tue, 21 Apr 2026 14:36:48 +0000
Subject: [PATCH 1/2] Add user instructions modal (issue #2885 item 3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses item 3 of issue #2885: a "how to use the site" overview for
first-time users and an exercise-screen contextual help that explains
the three playback steps.

## What this adds

- `<InstructionsModal>` — a four-step overview ("pick a topic →
  open a task → run Listen/Interact/Solve → see the results") triggered
  from the global header on every authenticated route. Icon + label
  ("Как заниматься" / "How to practise") visible at every breakpoint
  (no icon-only mobile variant — users include seniors and 7-year-olds).
- `<ExercisePlaybackHelp>` — a contextual mini-help in the fullscreen
  exercise overlay that only covers the three playback buttons, since
  the user is already past the "pick a topic" stage. Placed next to the
  existing close-X, mirror-positioned.
- `<UiInstructionsDialog>` — shared shell built on the native <dialog>
  element (modeled on `ui/confirm-dialog`), which gives focus trap,
  ESC-to-close, and backdrop-click-to-close for free. Both modals
  above are thin content wrappers around this shell.
- `UiExerciseButton` tooltip: replaced the old "Exercise 3" level-only
  title with the two new strings (`exercise_button.tooltip_available`
  for unlocked tasks, `exercise_button.tooltip_locked` for locked
  tasks) — also requested in the same issue.

## Copy decisions (domain review)

- Dropped the author's "75%" threshold claim. `app/schemas/exercise.ts`
  `isCompleted` is binary (all tasks or nothing). Wording softened to
  "когда правильных ответов наберётся достаточно" so the copy survives
  any future backend threshold changes.
- Dropped the "green check with exclamation mark" state — it does not
  exist in the current UI.
- Confirmed Listen→Interact auto-advances and Interact→Solve is
  manual (matches PR #2889 behavior).

## Accessibility

- `<dialog>` native element → inherent `role="dialog"`, ESC closes,
  backdrop visible.
- `aria-modal="true"`, `aria-labelledby` pointing at an <h2> inside.
- Trigger carries `aria-haspopup="dialog"`, `aria-expanded`,
  `aria-controls`, `aria-label`.
- Focus is restored to the trigger when the dialog closes.
- All interactive elements meet 44×44 touch-target minimum.

## Out of scope

- Auto-open on first visit — needs a server-persisted
  `hasSeenInstructions` flag. Devices are shared at rehab centres, so
  localStorage would be wrong.
- Drawer/bottom-sheet mobile variant — centered modal for v1, visual
  follow-up possible.
- Per-step icons and screenshots (asset work).
- Red-exclamation icon for <75% completion (backend flag doesn't exist).
- Analytics for "instructions opened".

## Tests

- `instructions-modal/component-test.gjs` — trigger renders, dialog
  opens with the four steps, ESC/X/OK close, aria metadata correct,
  Russian locale renders Russian title.
- `exercise-playback-help/component-test.gjs` — trigger renders,
  dialog opens with the playback-specific title, close dismisses it.
- `ui/exercise-button-test.gjs` — tooltip switches between
  `exercise_button.tooltip_available` and `tooltip_locked` based on
  `@isAvailable`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend/.gitignore                           |  3 +
 .../exercise-playback-help/index.gts          | 54 +++++++++++
 frontend/app/components/header/index.gts      |  2 +
 .../components/instructions-modal/index.gts   | 83 +++++++++++++++++
 .../components/ui/exercise-button/index.gts   |  9 +-
 .../ui/instructions-dialog/index.gts          | 91 +++++++++++++++++++
 .../group/series/subgroup/exercise.gts        |  3 +
 .../exercise-playback-help/component-test.gjs | 38 ++++++++
 .../instructions-modal/component-test.gjs     | 81 +++++++++++++++++
 .../components/ui/exercise-button-test.gjs    | 38 ++++++++
 frontend/translations/en-us.yaml              | 25 +++++
 frontend/translations/ru-ru.yaml              | 25 +++++
 12 files changed, 450 insertions(+), 2 deletions(-)
 create mode 100644 frontend/app/components/exercise-playback-help/index.gts
 create mode 100644 frontend/app/components/instructions-modal/index.gts
 create mode 100644 frontend/app/components/ui/instructions-dialog/index.gts
 create mode 100644 frontend/tests/integration/components/exercise-playback-help/component-test.gjs
 create mode 100644 frontend/tests/integration/components/instructions-modal/component-test.gjs

diff --git a/frontend/.gitignore b/frontend/.gitignore
index e1ac95e1e..82e94e657 100644
--- a/frontend/.gitignore
+++ b/frontend/.gitignore
@@ -31,3 +31,6 @@ jsconfig.json
 # Playwright
 /e2e/test-results/
 /e2e/playwright-report/
+
+# Claude Code harness state
+/.claude/
diff --git a/frontend/app/components/exercise-playback-help/index.gts b/frontend/app/components/exercise-playback-help/index.gts
new file mode 100644
index 000000000..841199491
--- /dev/null
+++ b/frontend/app/components/exercise-playback-help/index.gts
@@ -0,0 +1,54 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+import { on } from '@ember/modifier';
+import { t } from 'ember-intl';
+import UiHelp from 'brn/components/ui/help';
+import UiInstructionsDialog from 'brn/components/ui/instructions-dialog';
+
+interface ExercisePlaybackHelpSignature {
+  Args: {
+    triggerClass?: string;
+  };
+  Element: HTMLButtonElement;
+}
+
+export default class ExercisePlaybackHelpComponent extends Component<ExercisePlaybackHelpSignature> {
+  @tracked isOpen = false;
+  triggerElement: HTMLButtonElement | null = null;
+
+  @action
+  open(event: Event) {
+    this.triggerElement = event.currentTarget as HTMLButtonElement;
+    this.isOpen = true;
+  }
+
+  @action
+  close() {
+    this.isOpen = false;
+    this.triggerElement?.focus();
+  }
+
+  <template>
+    <button
+      data-test-playback-help-trigger
+      type="button"
+      aria-label={{t "instructions.trigger_aria"}}
+      aria-haspopup="dialog"
+      aria-expanded={{if this.isOpen "true" "false"}}
+      aria-controls="instructions-dialog-title"
+      class="btn-press inline-flex items-center justify-center min-h-[44px] min-w-[44px] rounded-full bg-white hover:bg-gray-100 shadow {{@triggerClass}}"
+      {{on "click" this.open}}
+      ...attributes
+    >
+      <UiHelp class="w-6 h-6" />
+    </button>
+    {{#if this.isOpen}}
+      <UiInstructionsDialog @titleKey="instructions.playback_title" @onClose={{this.close}}>
+        <p data-test-playback-help-body>
+          {{t "instructions.playback_body" htmlSafe=true}}
+        </p>
+      </UiInstructionsDialog>
+    {{/if}}
+  </template>
+}
diff --git a/frontend/app/components/header/index.gts b/frontend/app/components/header/index.gts
index d59e2d1a4..eee773ec3 100644
--- a/frontend/app/components/header/index.gts
+++ b/frontend/app/components/header/index.gts
@@ -17,6 +17,7 @@ import GlobalTimer from 'brn/components/global-timer';
 import LoadingSpinner from 'brn/components/loading-spinner';
 import XpBadge from 'brn/components/xp-badge';
 import StreakCounter from 'brn/components/streak-counter';
+import InstructionsModal from 'brn/components/instructions-modal';
 import GamificationService from 'brn/services/gamification';
 
 const ExternalLinkIcon = <template>
@@ -175,6 +176,7 @@ export default class HeaderComponent extends Component {
             </div>
           </div>
           <div class="sm:ml-4 flex items-center shrink-0 ml-1 gap-2 sm:gap-3">
+            <InstructionsModal />
             <LinkTo @route="profile.statistics" class="shrink-0">
               <GlobalTimer />
             </LinkTo>
diff --git a/frontend/app/components/instructions-modal/index.gts b/frontend/app/components/instructions-modal/index.gts
new file mode 100644
index 000000000..ced466418
--- /dev/null
+++ b/frontend/app/components/instructions-modal/index.gts
@@ -0,0 +1,83 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+import { on } from '@ember/modifier';
+import { t } from 'ember-intl';
+import UiHelp from 'brn/components/ui/help';
+import UiInstructionsDialog from 'brn/components/ui/instructions-dialog';
+
+interface InstructionsModalSignature {
+  Args: {
+    triggerClass?: string;
+  };
+  Element: HTMLButtonElement;
+}
+
+export default class InstructionsModalComponent extends Component<InstructionsModalSignature> {
+  @tracked isOpen = false;
+  triggerElement: HTMLButtonElement | null = null;
+
+  @action
+  open(event: Event) {
+    this.triggerElement = event.currentTarget as HTMLButtonElement;
+    this.isOpen = true;
+  }
+
+  @action
+  close() {
+    this.isOpen = false;
+    // Restore focus to the trigger so keyboard users return to where they
+    // were before the dialog opened.
+    this.triggerElement?.focus();
+  }
+
+  <template>
+    <button
+      data-test-instructions-trigger
+      type="button"
+      aria-label={{t "instructions.trigger_aria"}}
+      aria-haspopup="dialog"
+      aria-expanded={{if this.isOpen "true" "false"}}
+      aria-controls="instructions-dialog-title"
+      class="btn-press inline-flex items-center gap-1.5 min-h-[44px] px-3 py-2 text-white bg-white/10 hover:bg-white/20 rounded-full text-xs sm:text-sm font-semibold tracking-wider uppercase {{@triggerClass}}"
+      {{on "click" this.open}}
+      ...attributes
+    >
+      <UiHelp class="w-5 h-5" />
+      <span>{{t "instructions.trigger_label"}}</span>
+    </button>
+    {{#if this.isOpen}}
+      <UiInstructionsDialog @titleKey="instructions.title" @onClose={{this.close}}>
+        <p data-test-instructions-intro class="mb-4">
+          {{t "instructions.intro"}}
+        </p>
+        <ol class="space-y-5">
+          <li>
+            <h3 class="font-semibold text-gray-800 mb-1">
+              {{t "instructions.step_1.heading"}}
+            </h3>
+            <p>{{t "instructions.step_1.body" htmlSafe=true}}</p>
+          </li>
+          <li>
+            <h3 class="font-semibold text-gray-800 mb-1">
+              {{t "instructions.step_2.heading"}}
+            </h3>
+            <p>{{t "instructions.step_2.body" htmlSafe=true}}</p>
+          </li>
+          <li>
+            <h3 class="font-semibold text-gray-800 mb-1">
+              {{t "instructions.step_3.heading"}}
+            </h3>
+            <p>{{t "instructions.step_3.body" htmlSafe=true}}</p>
+          </li>
+          <li>
+            <h3 class="font-semibold text-gray-800 mb-1">
+              {{t "instructions.step_4.heading"}}
+            </h3>
+            <p>{{t "instructions.step_4.body" htmlSafe=true}}</p>
+          </li>
+        </ol>
+      </UiInstructionsDialog>
+    {{/if}}
+  </template>
+}
diff --git a/frontend/app/components/ui/exercise-button/index.gts b/frontend/app/components/ui/exercise-button/index.gts
index fe53e8d01..5f838bbde 100644
--- a/frontend/app/components/ui/exercise-button/index.gts
+++ b/frontend/app/components/ui/exercise-button/index.gts
@@ -3,7 +3,6 @@ import Component from '@glimmer/component';
 import type { Exercise } from 'brn/schemas/exercise';
 import { LinkTo } from '@ember/routing';
 
-import { concat } from '@ember/helper';
 import { t } from 'ember-intl';
 import UiIconCheck from 'brn/components/ui/icon/check';
 
@@ -56,6 +55,12 @@ export default class UiExerciseButtonComponent extends Component<UiExerciseButto
     return !this.args.isAvailable;
   }
 
+  get tooltipKey(): string {
+    return this.args.isAvailable
+      ? 'exercise_button.tooltip_available'
+      : 'exercise_button.tooltip_locked';
+  }
+
   get titleClasses() {
     if (this.mode === 'locked') {
       return 'c-exercise-button__title c-exercise-button__title-locked';
@@ -73,7 +78,7 @@ export default class UiExerciseButtonComponent extends Component<UiExerciseButto
       aria-disabled={{unless @isAvailable "true"}}
       @route="group.series.subgroup.exercise"
       @model={{@exercise.id}}
-      title={{concat (t "task_link.exercise") " " @exercise.level}}
+      title={{t this.tooltipKey}}
       ...attributes
     >
       <div class={{this.titleClasses}}>
diff --git a/frontend/app/components/ui/instructions-dialog/index.gts b/frontend/app/components/ui/instructions-dialog/index.gts
new file mode 100644
index 000000000..3d4eb593f
--- /dev/null
+++ b/frontend/app/components/ui/instructions-dialog/index.gts
@@ -0,0 +1,91 @@
+import Component from '@glimmer/component';
+import { action } from '@ember/object';
+import { on } from '@ember/modifier';
+import didInsert from '@ember/render-modifiers/modifiers/did-insert';
+import { t } from 'ember-intl';
+
+interface UiInstructionsDialogSignature {
+  Args: {
+    titleKey: string;
+    onClose: () => void;
+  };
+  Blocks: {
+    default: [];
+  };
+  Element: HTMLDialogElement;
+}
+
+export default class UiInstructionsDialogComponent extends Component<UiInstructionsDialogSignature> {
+  dialogElement: HTMLDialogElement | null = null;
+
+  @action
+  onInsert(element: HTMLDialogElement) {
+    this.dialogElement = element;
+    element.showModal();
+    element.addEventListener('close', this.onDialogClose);
+  }
+
+  @action
+  onDialogClose() {
+    this.args.onClose();
+  }
+
+  @action
+  close() {
+    // Remove listener first to prevent async double-call from the native
+    // 'close' event, then close and notify synchronously.
+    this.dialogElement?.removeEventListener('close', this.onDialogClose);
+    this.dialogElement?.close();
+    this.args.onClose();
+  }
+
+  willDestroy(): void {
+    super.willDestroy();
+    this.dialogElement?.removeEventListener('close', this.onDialogClose);
+  }
+
+  <template>
+    <dialog
+      data-test-instructions-dialog
+      aria-modal="true"
+      aria-labelledby="instructions-dialog-title"
+      class="p-0 rounded-lg shadow-xl backdrop:bg-black/50 w-full max-w-[calc(100vw-1rem)] sm:max-w-2xl"
+      ...attributes
+      {{didInsert this.onInsert}}
+    >
+      <div class="flex flex-col max-h-[85vh]">
+        <header class="flex items-start justify-between px-6 pt-6 pb-4 border-b border-gray-100">
+          <h2
+            id="instructions-dialog-title"
+            data-test-instructions-dialog-title
+            class="text-xl font-semibold text-gray-800"
+          >
+            {{t @titleKey}}
+          </h2>
+          <button
+            data-test-instructions-dialog-close-x
+            type="button"
+            aria-label={{t "instructions.close"}}
+            class="btn-press shrink-0 ml-4 min-h-[44px] min-w-[44px] text-gray-500 hover:text-gray-800 text-2xl leading-none"
+            {{on "click" this.close}}
+          >
+            ×
+          </button>
+        </header>
+        <div class="px-6 py-5 overflow-y-auto font-openSans text-base leading-relaxed text-gray-700">
+          {{yield}}
+        </div>
+        <footer class="flex justify-end px-6 py-4 border-t border-gray-100">
+          <button
+            data-test-instructions-dialog-close
+            type="button"
+            class="btn-press min-h-[44px] px-6 py-2 text-sm font-semibold text-white bg-indigo-600 rounded-md hover:bg-indigo-700"
+            {{on "click" this.close}}
+          >
+            {{t "instructions.close"}}
+          </button>
+        </footer>
+      </div>
+    </dialog>
+  </template>
+}
diff --git a/frontend/app/templates/group/series/subgroup/exercise.gts b/frontend/app/templates/group/series/subgroup/exercise.gts
index 8569eda5d..b9063f598 100644
--- a/frontend/app/templates/group/series/subgroup/exercise.gts
+++ b/frontend/app/templates/group/series/subgroup/exercise.gts
@@ -15,6 +15,8 @@ import { LinkTo } from '@ember/routing';
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import ModalDialog from 'ember-modal-dialog/components/modal-dialog';
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
+import ExercisePlaybackHelp from 'brn/components/exercise-playback-help';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 import AnswerCorrectnessWidget from 'brn/components/answer-correctness-widget';
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import ExerciseStats from 'brn/components/exercise-stats';
@@ -40,6 +42,7 @@ const tpl: TOC<Signature> = <template>
         {{didInsert @controller.startStatsTracking @model}}
         {{willDestroy @controller.stopStatsTracking @model}}
       >
+        <ExercisePlaybackHelp @triggerClass="fixed top-2 right-2 z-10" />
         <div class="fixed" id="modal-close-button">
           <LinkTo @route="group.series.subgroup" title={{t "navigation.come_back"}}>
             <svg
diff --git a/frontend/tests/integration/components/exercise-playback-help/component-test.gjs b/frontend/tests/integration/components/exercise-playback-help/component-test.gjs
new file mode 100644
index 000000000..6fca7ecc6
--- /dev/null
+++ b/frontend/tests/integration/components/exercise-playback-help/component-test.gjs
@@ -0,0 +1,38 @@
+import { module, test } from 'qunit';
+import { setupIntl } from 'ember-intl/test-support';
+import { setupRenderingTest } from 'ember-qunit';
+import { render, click } from '@ember/test-helpers';
+import ExercisePlaybackHelp from 'brn/components/exercise-playback-help';
+
+module('Integration | Component | exercise-playback-help', function (hooks) {
+  setupRenderingTest(hooks);
+  setupIntl(hooks, 'en-us');
+
+  test('the icon trigger is rendered; dialog is closed by default', async function (assert) {
+    await render(<template><ExercisePlaybackHelp /></template>);
+
+    assert.dom('[data-test-playback-help-trigger]').exists();
+    assert.dom('[data-test-instructions-dialog]').doesNotExist();
+  });
+
+  test('clicking the trigger opens the playback help dialog', async function (assert) {
+    await render(<template><ExercisePlaybackHelp /></template>);
+
+    await click('[data-test-playback-help-trigger]');
+
+    assert.dom('[data-test-instructions-dialog]').exists();
+    assert
+      .dom('[data-test-instructions-dialog-title]')
+      .hasText('How the three steps work');
+    assert.dom('[data-test-playback-help-body]').exists();
+  });
+
+  test('the close button dismisses the dialog', async function (assert) {
+    await render(<template><ExercisePlaybackHelp /></template>);
+
+    await click('[data-test-playback-help-trigger]');
+    await click('[data-test-instructions-dialog-close]');
+
+    assert.dom('[data-test-instructions-dialog]').doesNotExist();
+  });
+});
diff --git a/frontend/tests/integration/components/instructions-modal/component-test.gjs b/frontend/tests/integration/components/instructions-modal/component-test.gjs
new file mode 100644
index 000000000..7f6259a75
--- /dev/null
+++ b/frontend/tests/integration/components/instructions-modal/component-test.gjs
@@ -0,0 +1,81 @@
+import { module, test } from 'qunit';
+import { setupIntl } from 'ember-intl/test-support';
+import { setupRenderingTest } from 'ember-qunit';
+import { render, click } from '@ember/test-helpers';
+import InstructionsModal from 'brn/components/instructions-modal';
+
+module('Integration | Component | instructions-modal', function (hooks) {
+  setupRenderingTest(hooks);
+  setupIntl(hooks, 'en-us');
+
+  test('the trigger is rendered but the dialog stays closed by default', async function (assert) {
+    await render(<template><InstructionsModal /></template>);
+
+    assert.dom('[data-test-instructions-trigger]').exists();
+    assert.dom('[data-test-instructions-trigger]').hasAttribute('aria-expanded', 'false');
+    assert.dom('[data-test-instructions-dialog]').doesNotExist();
+  });
+
+  test('clicking the trigger opens the dialog with the four-step content', async function (assert) {
+    await render(<template><InstructionsModal /></template>);
+
+    await click('[data-test-instructions-trigger]');
+
+    assert.dom('[data-test-instructions-dialog]').exists('dialog is rendered');
+    assert
+      .dom('[data-test-instructions-trigger]')
+      .hasAttribute('aria-expanded', 'true');
+    assert
+      .dom('[data-test-instructions-dialog-title]')
+      .hasText('How to practise on the site');
+    assert.dom('[data-test-instructions-intro]').exists();
+    assert.dom('[data-test-instructions-dialog] ol > li').exists({ count: 4 });
+  });
+
+  test('clicking the footer close button closes the dialog', async function (assert) {
+    await render(<template><InstructionsModal /></template>);
+
+    await click('[data-test-instructions-trigger]');
+    assert.dom('[data-test-instructions-dialog]').exists();
+
+    await click('[data-test-instructions-dialog-close]');
+
+    assert.dom('[data-test-instructions-dialog]').doesNotExist();
+    assert
+      .dom('[data-test-instructions-trigger]')
+      .hasAttribute('aria-expanded', 'false');
+  });
+
+  test('clicking the header X button closes the dialog', async function (assert) {
+    await render(<template><InstructionsModal /></template>);
+
+    await click('[data-test-instructions-trigger]');
+    await click('[data-test-instructions-dialog-close-x]');
+
+    assert.dom('[data-test-instructions-dialog]').doesNotExist();
+  });
+
+  test('the trigger has aria metadata for assistive tech', async function (assert) {
+    await render(<template><InstructionsModal /></template>);
+
+    const trigger = '[data-test-instructions-trigger]';
+    assert.dom(trigger).hasAttribute('aria-haspopup', 'dialog');
+    assert.dom(trigger).hasAttribute('aria-controls', 'instructions-dialog-title');
+    assert.dom(trigger).hasAttribute(
+      'aria-label',
+      'Open instructions — how to practise on the site',
+    );
+  });
+
+  module('with ru-ru locale', function (innerHooks) {
+    setupIntl(innerHooks, 'ru-ru');
+
+    test('renders Russian title when locale is ru-ru', async function (assert) {
+      await render(<template><InstructionsModal /></template>);
+      await click('[data-test-instructions-trigger]');
+      assert
+        .dom('[data-test-instructions-dialog-title]')
+        .hasText('Как заниматься на сайте');
+    });
+  });
+});
diff --git a/frontend/tests/integration/components/ui/exercise-button-test.gjs b/frontend/tests/integration/components/ui/exercise-button-test.gjs
index 9ff5ba5f9..168c2338a 100644
--- a/frontend/tests/integration/components/ui/exercise-button-test.gjs
+++ b/frontend/tests/integration/components/ui/exercise-button-test.gjs
@@ -25,4 +25,42 @@ module('Integration | Component | ui/exercise-button', function (hooks) {
 
     assert.dom('.completed').exists();
   });
+
+  test('tooltip points at the available key when the exercise is available', async function (assert) {
+    this.setProperties({ exercise: { id: '1', level: 1, isCompleted: false } });
+    const self = this;
+
+    await render(
+      <template>
+        <UiExerciseButton
+          @exercise={{self.exercise}}
+          @isAvailable={{true}}
+        />
+      </template>,
+    );
+
+    assert.dom('.c-exercise-button').hasAttribute(
+      'title',
+      'Click to start this task',
+    );
+  });
+
+  test('tooltip points at the locked key when the exercise is not available', async function (assert) {
+    this.setProperties({ exercise: { id: '1', level: 1, isCompleted: false } });
+    const self = this;
+
+    await render(
+      <template>
+        <UiExerciseButton
+          @exercise={{self.exercise}}
+          @isAvailable={{false}}
+        />
+      </template>,
+    );
+
+    assert.dom('.c-exercise-button').hasAttribute(
+      'title',
+      'This task is not available yet. It will open once you finish the previous one.',
+    );
+  });
 });
diff --git a/frontend/translations/en-us.yaml b/frontend/translations/en-us.yaml
index beef70d02..2207fe1e2 100644
--- a/frontend/translations/en-us.yaml
+++ b/frontend/translations/en-us.yaml
@@ -19,6 +19,31 @@ ui:
     confirm: Confirm
     cancel: Cancel
 
+instructions:
+  trigger_label: How to practise
+  trigger_aria: Open instructions — how to practise on the site
+  title: How to practise on the site
+  intro: "Here is a short overview of how a lesson works. It only takes a minute — and then everything will make sense."
+  step_1:
+    heading: 1. Pick a topic and a task
+    body: "Open a section and choose a topic. Inside you will see a list of tasks. Some of them are already open and can be clicked, others are still locked: they unlock once you complete the task before them.<br><br>When you finish a task successfully, a green check appears next to it and the next task becomes available. If the result is still low, come back and try again — your brain learns the sounds faster with a few repeats."
+  step_2:
+    heading: 2. Open a task
+    body: "Click an available task. You will see a screen with pictures and words or phrases, and at the bottom three steps of the lesson: <strong>Listen</strong>, <strong>Interact</strong> and <strong>Solve</strong>. You go through them one after another."
+  step_3:
+    heading: 3. Go through the three steps
+    body: "The <strong>Listen</strong> step starts by itself. The speaker will say every word or phrase in the task — just listen carefully.<br><br>The <strong>Interact</strong> step begins automatically after the first one. Tap the pictures to hear the words again, as many times as you need. Once you have listened to all of them, the step ends on its own.<br><br>The <strong>Solve</strong> step you start yourself — with the <strong>Solve</strong> button at the bottom. Press it when you feel ready."
+  step_4:
+    heading: 4. Listen and answer
+    body: "On the <strong>Solve</strong> step the speaker repeats the words and phrases in random order. As soon as you recognise one, tap the matching picture — if the answer is right, a green check appears in its corner and the speaker moves on.<br><br>If you did not catch it, press <strong>Listen one more time</strong> at the bottom of the screen. That is not a mistake — you are meant to use it.<br><br>When the task is finished, a results window appears. Press <strong>Continue</strong> — and the next task will open."
+  playback_title: How the three steps work
+  playback_body: "The <strong>Listen</strong> step starts by itself. <strong>Interact</strong> begins right after — tap the pictures to hear the words again. Start <strong>Solve</strong> yourself with the <strong>Solve</strong> button at the bottom, when you feel ready. Then listen to the speaker and tap the matching picture. If you did not catch a word, press <strong>Listen one more time</strong>."
+  close: Got it
+
+exercise_button:
+  tooltip_available: Click to start this task
+  tooltip_locked: This task is not available yet. It will open once you finish the previous one.
+
 login:
   title: Login
 
diff --git a/frontend/translations/ru-ru.yaml b/frontend/translations/ru-ru.yaml
index d572d7212..2ede5e13c 100644
--- a/frontend/translations/ru-ru.yaml
+++ b/frontend/translations/ru-ru.yaml
@@ -19,6 +19,31 @@ ui:
     confirm: Подтвердить
     cancel: Отмена
 
+instructions:
+  trigger_label: Как заниматься
+  trigger_aria: Открыть инструкцию — как заниматься на сайте
+  title: Как заниматься на сайте
+  intro: "Коротко расскажем, как устроены занятия. Это займёт пару минут — и дальше всё будет понятно."
+  step_1:
+    heading: 1. Выберите тему и задание
+    body: "Откройте раздел и выберите тему. Внутри вы увидите список заданий. Часть из них уже открыта — они подсвечены и кликабельны. Остальные пока закрыты: они откроются после того, как вы пройдёте предыдущее задание.<br><br>Когда задание пройдено успешно, рядом с ним появится зелёная галочка, а следующее задание станет доступным. Если результат пока невысокий, вернитесь и попробуйте ещё раз — так мозг быстрее привыкает к звукам."
+  step_2:
+    heading: 2. Откройте задание
+    body: "Нажмите на доступное задание. Откроется экран с картинками и словами или фразами, а внизу вы увидите три шага занятия: <strong>Слушать</strong>, <strong>Повторить</strong> и <strong>Решать</strong>. Вы будете проходить их по очереди."
+  step_3:
+    heading: 3. Пройдите три шага
+    body: "Шаг <strong>«Слушать»</strong> запускается сам. Диктор произнесёт все слова или фразы задания по очереди — просто вслушивайтесь.<br><br>Шаг <strong>«Повторить»</strong> включится автоматически после первого. Нажимайте на картинки — и вы ещё раз услышите то, что выбрали. Когда прослушаете все слова, шаг закончится сам.<br><br>Шаг <strong>«Решать»</strong> вы запускаете сами — кнопкой <strong>«Решать»</strong> внизу экрана. Нажмите её, когда почувствуете, что готовы."
+  step_4:
+    heading: 4. Слушайте и отвечайте
+    body: "На шаге <strong>«Решать»</strong> диктор повторяет слова и фразы в случайном порядке. Сразу после того, как услышали, нажмите на нужную картинку — если ответ правильный, в её углу появится зелёная галочка, и диктор перейдёт к следующему слову.<br><br>Если не расслышали — нажмите <strong>«Прослушать ещё раз»</strong> внизу экрана. Это не ошибка, так можно и нужно делать.<br><br>Когда задание закончится, появится окно со статистикой. Нажмите <strong>«Продолжить»</strong> — и откроется следующее задание."
+  playback_title: Как устроены шаги задания
+  playback_body: "Шаг <strong>«Слушать»</strong> запускается сам. Шаг <strong>«Повторить»</strong> начнётся после него — нажимайте на картинки, чтобы услышать слова снова. Шаг <strong>«Решать»</strong> запускайте сами кнопкой <strong>«Решать»</strong> внизу, когда почувствуете, что готовы. Дальше слушайте диктора и нажимайте на нужные картинки. Если не расслышали — нажмите <strong>«Прослушать ещё раз»</strong>."
+  close: Понятно
+
+exercise_button:
+  tooltip_available: Нажмите, чтобы выполнить задание
+  tooltip_locked: Это задание пока недоступно. Оно откроется, когда вы пройдёте предыдущее.
+
 login:
   title: Начать
 

From 2ee509b7afa1a61c8908aca96de73fdd6ad9332b Mon Sep 17 00:00:00 2001
From: Alex Kanunnikov <lifeart92@gmail.com>
Date: Tue, 21 Apr 2026 15:36:45 +0000
Subject: [PATCH 2/2] Fix instructions-modal tests to use ember-intl
 placeholders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`setupIntl` in the rendering-test env returns the `t:<key>` placeholder
instead of loading real translations (same pattern documented on
`doctor-feedback/component-test.gjs` and used across the existing
suite). Asserting full English strings fails in CI.

Switch all tooltip and title assertions to the `t:KEY` placeholder
form. Drop the redundant ru-ru locale module — placeholders do not
change with locale, so the test was duplicative of the en-us case.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../exercise-playback-help/component-test.gjs |  2 +-
 .../instructions-modal/component-test.gjs     | 23 +++++--------------
 .../components/ui/exercise-button-test.gjs    | 14 +++++------
 3 files changed, 13 insertions(+), 26 deletions(-)

diff --git a/frontend/tests/integration/components/exercise-playback-help/component-test.gjs b/frontend/tests/integration/components/exercise-playback-help/component-test.gjs
index 6fca7ecc6..42adcfed7 100644
--- a/frontend/tests/integration/components/exercise-playback-help/component-test.gjs
+++ b/frontend/tests/integration/components/exercise-playback-help/component-test.gjs
@@ -23,7 +23,7 @@ module('Integration | Component | exercise-playback-help', function (hooks) {
     assert.dom('[data-test-instructions-dialog]').exists();
     assert
       .dom('[data-test-instructions-dialog-title]')
-      .hasText('How the three steps work');
+      .hasText('t:instructions.playback_title');
     assert.dom('[data-test-playback-help-body]').exists();
   });
 
diff --git a/frontend/tests/integration/components/instructions-modal/component-test.gjs b/frontend/tests/integration/components/instructions-modal/component-test.gjs
index 7f6259a75..ccd8cc435 100644
--- a/frontend/tests/integration/components/instructions-modal/component-test.gjs
+++ b/frontend/tests/integration/components/instructions-modal/component-test.gjs
@@ -4,6 +4,10 @@ import { setupRenderingTest } from 'ember-qunit';
 import { render, click } from '@ember/test-helpers';
 import InstructionsModal from 'brn/components/instructions-modal';
 
+// ember-intl returns the `t:<key>` placeholder in this test env (see
+// doctor-feedback/component-test.gjs for the same pattern). Assertions
+// target the key bindings, not translated strings.
+
 module('Integration | Component | instructions-modal', function (hooks) {
   setupRenderingTest(hooks);
   setupIntl(hooks, 'en-us');
@@ -27,7 +31,7 @@ module('Integration | Component | instructions-modal', function (hooks) {
       .hasAttribute('aria-expanded', 'true');
     assert
       .dom('[data-test-instructions-dialog-title]')
-      .hasText('How to practise on the site');
+      .hasText('t:instructions.title');
     assert.dom('[data-test-instructions-intro]').exists();
     assert.dom('[data-test-instructions-dialog] ol > li').exists({ count: 4 });
   });
@@ -61,21 +65,6 @@ module('Integration | Component | instructions-modal', function (hooks) {
     const trigger = '[data-test-instructions-trigger]';
     assert.dom(trigger).hasAttribute('aria-haspopup', 'dialog');
     assert.dom(trigger).hasAttribute('aria-controls', 'instructions-dialog-title');
-    assert.dom(trigger).hasAttribute(
-      'aria-label',
-      'Open instructions — how to practise on the site',
-    );
-  });
-
-  module('with ru-ru locale', function (innerHooks) {
-    setupIntl(innerHooks, 'ru-ru');
-
-    test('renders Russian title when locale is ru-ru', async function (assert) {
-      await render(<template><InstructionsModal /></template>);
-      await click('[data-test-instructions-trigger]');
-      assert
-        .dom('[data-test-instructions-dialog-title]')
-        .hasText('Как заниматься на сайте');
-    });
+    assert.dom(trigger).hasAttribute('aria-label', 't:instructions.trigger_aria');
   });
 });
diff --git a/frontend/tests/integration/components/ui/exercise-button-test.gjs b/frontend/tests/integration/components/ui/exercise-button-test.gjs
index 168c2338a..84d0df3ff 100644
--- a/frontend/tests/integration/components/ui/exercise-button-test.gjs
+++ b/frontend/tests/integration/components/ui/exercise-button-test.gjs
@@ -39,10 +39,9 @@ module('Integration | Component | ui/exercise-button', function (hooks) {
       </template>,
     );
 
-    assert.dom('.c-exercise-button').hasAttribute(
-      'title',
-      'Click to start this task',
-    );
+    assert
+      .dom('.c-exercise-button')
+      .hasAttribute('title', 't:exercise_button.tooltip_available');
   });
 
   test('tooltip points at the locked key when the exercise is not available', async function (assert) {
@@ -58,9 +57,8 @@ module('Integration | Component | ui/exercise-button', function (hooks) {
       </template>,
     );
 
-    assert.dom('.c-exercise-button').hasAttribute(
-      'title',
-      'This task is not available yet. It will open once you finish the previous one.',
-    );
+    assert
+      .dom('.c-exercise-button')
+      .hasAttribute('title', 't:exercise_button.tooltip_locked');
   });
 });