baya-monorepo/dev/post-phase/ui/ui-phase-12-copy-motion-and-polish.md

# UI Phase 12 — Copy, motion & final polish

> **Mission:** the closing sweep of the UI chain — make the product read and move as one: a checked-in
> Persian style guide enforced across both catalogs, the verified copy defects on trust-critical strings
> fixed, a restrained motion language behind a single reduced-motion gate, an accessibility pass, and a final
> four-axes QA of everything the chain touched. Copy is the cheapest trust lever Balinyaar has — and today
> the brand name is spelled two ways, a nurse-facing EVV error reads as "there is no game-entrance", and one
> BNPL sentence states the inverse of the intended risk allocation.
>
> **Track:** frontend · **Depends on:** all prior phases — [0](ui-phase-0-design-language.md) →
> [11](ui-phase-11-admin-and-partner-console.md) (run this last) · **Unlocks:** ships the chain — one voice, one motion language, verified on all axes.
> **Before you start, read [../../phases/_shared/agent-operating-rules.md](../../phases/_shared/agent-operating-rules.md) and invoke the frontend-designer skill — both are mandatory.**

## 1. Context — where this sits

Balinyaar is a trust-first product in a market where written register carries weight: families decide whether
to let a stranger into a parent's home partly on whether the product *sounds* careful. The catalogs are
already hand-written — the weaknesses are craft, not tone. Verified in `client/messages/fa.json` / `en.json`
(line numbers spot-checked 2026-07-16; earlier phases may shift them — grep the key, not the line):

- **The brand name is spelled two ways:** «بالین یار» (plain space) in 5 keys — `common.brand` (53),
  `auth.customer_title` (625), `auth.select_role_title` (645), `auth.account_error_body` (654),
  `verification.start_body` (663) — vs «بالین‌یار» (ZWNJ) in 17: login and escrow copy disagree on the name.
- **تأیید — the most frequent word in a verification product — appears 38× without hamza and 26× with**, no
  pattern (`bank.status_verified_title` vs `admin.ver_pass`); ~64 occurrences to sweep.
- **Two grammar bugs read as nonsense:** `booking.evv_no_open_check_in` (542) «ورود بازی برای ثبت خروج وجود
  ندارد» and `admin.alert_empty` (1360) «هشدار بازی وجود ندارد» — the indefinite ی attached to the wrong word.
  And a typo sits on a trust chip: `bank.status_verified_chip` (180) reads «تاییدشد» (missing final ه) — the
  chip a nurse stares at while IBAN ownership verification runs.
- **One en arrow points the wrong way:** `booking.continue_payment` (en 445) is "Continue to payment ←" while
  its sibling `payment.cta_pay` (577) is "…→". Five keys per catalog embed ←/→ literally (445, 577, 632, 633,
  1337) — directional glyphs inside translatable strings are how this bug happens.
- **fa lacks ICU plurals where en has them:** `search.cta_view_results` (fa 350) is «مشاهده {count} پرستار» —
  the primary search CTA can render «مشاهده ۰ پرستار»; en has ICU but its `=0` case renders "View no nurses".
- **BNPL copy is banker's language with an ambiguous pronoun:** `bnpl.ownership_note` (857) «…ریسک نکول مشتری
  کاملاً با اوست…» — «نکول» is credit-desk jargon and «با اوست» leaves the reader unsure whether the
  *customer* carries the default risk (the intended meaning: the provider does).
- **Policy numbers are hard-coded into legally-sensitive copy** the admin config panel can change: the ۷۲-hour
  dispute window (`payouts.explainer_point_2`, 958), the ۲۴-hour cancellation tiers (`refunds.lead_gt_24h/
  lead_lt_24h`, 789–790), the ۷–۱۰-day refund ETA (`refunds.eta_business_days`, 850). One config edit makes
  the UI lie — and **no public config read exists** (`platform_config/*` in `services/admin/` is admin-only).
- **Motion and live-region a11y are absent, app-wide:** zero `prefers-reduced-motion` handling and zero
  `aria-live` anywhere in `client/src`; `AppIconButton` names icon-only actions solely via Tooltip `title`,
  dropped entirely when disabled (`AppIconButton.tsx:89–95`).

**What already exists (do not rebuild):**

- Phase 0's token extension (motion/focus/elevation tokens in `theme/tokens.css`) and single-weight icon
  registry with a mirrored chevron — this phase *applies* motion tokens, it does not invent them.
- Phase 1's shared primitives: `utils/number.ts` `formatNumber` (replacing the 25+ inline `fa-IR` ternaries),
  the state-view kit, `CountdownTimer` v2, route-level `loading.tsx`/`error.tsx`.
- Full key parity between `fa.json` and `en.json` (28 namespaces) with complete loading/empty/error/confirm/
  toast coverage per namespace, and the trust copy that is already right (keep-list, §5):
  `payment.escrow_notice`, `payouts.explainer_point_1–3`, calming refund-status vocabulary, two-stage
  disclosure copy, the specific verification-failure reasons.
- Phases 4/6/8/9 may already have fixed items this phase lists conditionally (3.2 address hint, 3.5 pipeline
  naming, 3.7 cities, 3.10 desktop layouts) — **read their reports first** and skip what is done.

## 2. Required reading (do this first)

- [audit/microcopy.md](audit/microcopy.md) — the 16 copy problems + 7 opportunities this phase executes; its
  keep-list is binding. Then [audit/cross-cutting-ux.md](audit/cross-cutting-ux.md) — motion/a11y/responsive
  findings (AppIconButton, motion absence, desktop phone-column) and its keep-list.
- Prior phase reports in `../../shared-working-context/reports/` (`ui-phase-0` … `ui-phase-11`) — to learn
  which conditional items are already done and what naming phase 8 chose for the verification journey.
- `client/messages/fa.json` + `en.json` — read the namespaces you will sweep (booking, verification, payment,
  auth, common, bnpl, search, refunds, payouts, admin, shell, tickets, bank, address).
- Code (under `client/src/`): `components/common/AppIconButton/AppIconButton.tsx`,
  `components/CountdownTimer/`, `components/EscrowNotice/EscrowNotice.tsx`, `theme/tokens.css` (phase-0
  motion/focus tokens), `utils/number.ts` (phase-1 `formatNumber`), and for 3.10
  `app/[locale]/(private-routes)/(customer)/bookings/checkout/` + `…/(customer)/search/results/page.tsx`.
- Product: [../../../product/overview/platform-summary.md](../../../product/overview/platform-summary.md)
  §"Glossary" — consult it **before** deciding پرستار/مددجو/بیمار; the cancellation/refund docs under
  [../../../product/business/](../../../product/business/index.md) before touching policy-number copy.
- The design contract: [../../../.claude/skills/frontend-designer/SKILL.md](../../../.claude/skills/frontend-designer/SKILL.md)
  (§7 non-negotiables) and `client/CLAUDE.md` "Golden rules". REQ tracker:
  [../../shared-working-context/frontend/requests/for-backend.md](../../shared-working-context/frontend/requests/for-backend.md)
  — find the tail (REQ-038 at authoring time; earlier UI phases may have appended) and number onward.

## 3. Scope — build this

### 3.1 The Persian style guide — `client/messages/STYLE.md` + enforcement

Write a one-page style guide the catalogs are then swept against, fixing these decisions:

- **Brand = «بالین‌یار» (ZWNJ), always.** Sweep the 5 plain-space keys.
- **Hamza form «تأیید»** everywhere (~64 occurrences to normalize — the 38 hamza-less ones change).
- **One form of جستجو.** Standardize on «جستجو» (the 9-key majority; fold in the 2 «جست‌وجو» keys).
- **ZWNJ rules:** می‌ + verb, plural ها, compound adjectives («تأییدشده»); codify with examples.
- **Punctuation & quotes:** Persian «،» / «؛» / guillemets; en uses straight apostrophes (the admin
  namespace's curly 'don’t' normalizes to the file's straight-quote majority).
- **Domain glossary:** پرستار / بیمار vs مددجو — decide against the product glossary; «مددجو» appears exactly
  once (`booking.patient_label`), so adopt it consistently or drop the one-off. One status vocabulary shared
  by nurse-facing and admin-facing keys (see 3.5).
- **Shell naming system:** one metaphor per audience class instead of today's four (`shell.*`, fa 56–61:
  اپلیکیشن/نما/کنسول/پرتال). Recommended: end-user shells = «اپلیکیشن» (خانواده، پرستار), back-office
  shells = «کنسول» (مدیریت، همکار).
- **Register:** formal شما with polite imperatives (کنید) — already consistent; codify so it cannot drift.
- **Digits policy:** Persian digits in fa for both literals and interpolations (mechanics in 3.3).

**Enforcement:** add a ~30-line Node script (`client/scripts/check-copy.mjs`) that greps `fa.json` for the
banned variants (space-brand, hamza-less تایید, the «بازی» word-boundary trap, جست‌وجو, می‌گردد) and exits
non-zero; wire it as `npm run lint:copy` and into `npm run check`. 60+ scattered findings become a one-time
fix that cannot regress.

### 3.2 Verified copy-bug fixes (each independently shippable)

1. `booking.evv_no_open_check_in` → «ورودِ ثبت‌شده‌ای برای این ویزیت وجود ندارد؛ ابتدا ورود را ثبت کنید.»
   and `admin.alert_empty` → «هشداری برای رسیدگی نیست.»
2. `address.line_hint` «…برای یافتن در نیاز دارد» → «هر جزئیاتی که پرستار برای پیدا کردن منزل شما لازم
   دارد.» — **only if phase 9 didn't**. And `bank.status_verified_chip` «تاییدشد» → «تأییدشده».
3. Archaic passive «می‌گردد» → «می‌شود»: `refunds.confirm_restate` (814), `admin.mod_confirm_publish` (1314),
   `admin.cfg_save_confirm_body` (1333) — three occurrences, not one as the audit counted.
4. `tickets.thread_empty_body` comma splice → «هنوز پیامی نیست. هماهنگی را شروع کنید.»
5. en normalization: `auth.nurse_subtitle` "licence" → "license" (American throughout — the file already uses
   "center" 25×); straighten the admin namespace's curly apostrophes.
6. Introduce EVV in Persian once, then abbreviate: a first-occurrence key «ثبت حضور الکترونیکی (EVV) — ورود و
   خروج شما ثبت می‌شود تا ویزیت بدون اختلاف تأیید شود» on the nurse's visits surface (`booking.evv_*`, fa
   528–535), short chips («ثبت ورود») thereafter — EVV is why the nurse gets paid without arguments; sell it.

### 3.3 ICU plurals + designed zero cases

Every `{count}` key gets an ICU plural form in **both** catalogs with a designed `=0` case: fa
`search.cta_view_results` (350), `results_count` (352), `reviews_count` (364), `booking.session_count` (515)
plus a grep sweep for the rest. Zero states are copy, not numerals — «پرستاری یافت نشد» / "No nurses found";
also fix en's awkward `=0` label ("View no nurses"). Digits policy: fa interpolations render Persian digits —
use `{count, number}` / ICU `#` (locale-formatted by next-intl) in message keys, and phase 1's `formatNumber`
where a raw value is interpolated at a call site; verify one of each renders «۳» not "3".

### 3.4 Arrows out of strings

Remove the five literal ←/→ glyphs per catalog (`booking.continue_payment`, `payment.cta_pay`,
`auth.nurse_switch`, `auth.customer_switch`, `admin.cfg_history_change` — fa/en lines 445/577/632/633/1337)
and fix en 445's wrong-direction arrow by construction: direction moves into auto-mirroring `endIcon` slots
on the buttons involved (phase 0's chevron via the `AppIcon` registry; the RTL Emotion cache mirrors it).
`admin.cfg_history_change` «{old} ← {new}» becomes two interpolations joined by a component-rendered mirrored
arrow icon. Touch each call site; the strings become text-only.

### 3.5 Trust-moments copy pass

- **OTP screen reassurance:** `auth.customer_subtitle` (626) is just «با شماره موبایل خود وارد شوید» — add one
  warm trust line (verified nurses + escrow, e.g. «پرستاران تأییدشده، پرداخت امن نزد بالین‌یار»).
- **Checkout «چرا امن است»:** one line near the pay CTA linking escrow to the dispute process —
  *supplementing*, never replacing, `payment.escrow_notice` (§5). And **post-payment what-happens-next:** the
  confirmation states the next steps in order (nurse notified → coordination ticket → visit-day EVV).
- **BNPL de-jargon:** rewrite `bnpl.ownership_note` (857) reader-first, plainly allocating risk to the
  provider — e.g. «قسط‌ها را مستقیماً به {provider} می‌پردازید؛ بالین‌یار مبلغ کامل را همان ابتدا دریافت
  می‌کند و اگر قسطی پرداخت نشود، مسئولیت آن با ارائه‌دهنده است، نه شما و نه پرستار.» «نکول» disappears from
  the catalog.
- **Disambiguate the verification names:** «احراز هویت» names both the 7-step pipeline (`nav.verification`
  13, `verification.title` 658) *and* the KYC step inside it (`step_identity_kyc` 676, admin 1470). Rename
  the pipeline «تأیید صلاحیت»; the KYC step keeps «احراز هویت». **Coordinate with phase 8's journey naming**
  — if its report already renamed, adopt its term and only sweep stragglers.
- **One rejected-status vocabulary:** unify رد شد / ناموفق / ردشده into one nurse-facing and one
  admin-facing form (decide in STYLE.md; sweep `verification.*` and `admin.*` together — they cross-reference).

### 3.6 Config-served policy numbers (REQ + client single-sourcing)

Parameterize the hard-coded policy numbers: `payouts.explainer_point_2` takes `{hours}` (72),
`refunds.lead_gt_24h`/`lead_lt_24h` take `{hours}` (24), `refunds.eta_business_days` takes `{minDays}`/
`{maxDays}` (7–10). File a REQ (next free number) for a **public/authenticated policy-config read**
(dispute-window hours, cancellation tiers + percentages, refund ETA) — verify first that no existing endpoint
serves it (at authoring time only admin-scoped `platform_config/*` exists). Until served, single-source the
constants in `client/src/constants/policy.ts` with a comment linking the REQ, and feed the interpolations
from there. One config edit must never again silently make copy lie.

### 3.7 Honest search empty state

Replace `search.empty_suggest_city` (361, both catalogs) — «شهر نزدیک دیگری مانند مشهد، اصفهان یا شیراز را
امتحان کنید» is nonsense advice for a Tehran-launch user — with honest relaxations already next to it (clear
the district, widen filters) or interpolated actually-covered cities. **Only if phase 4 didn't.**

### 3.8 Motion pass — one restrained language

Apply phase 0's motion tokens app-wide; introduce nothing springy — this is a calm clinical product:

- Page/content transitions: 150–200ms fade + small slide on route-group content; skeleton → content
  crossfade (the phase-1 skeleton twins).
- Dialog/bottom-sheet enter/exit via `theme.components` defaults (one place, not per-dialog); list-entrance
  restraint — at most a subtle stagger on first paint, never re-animating on refetch.
- **`prefers-reduced-motion` is respected via a single media-query gate in one place** (a token/theme-level
  switch that zeroes durations) — today the app has zero handling; do not scatter per-component checks.

### 3.9 A11y sweep

- `AppIconButton`: add an `aria-label` passthrough that defaults from `title` and survives `disabled` (today
  the Tooltip — the only name source — is dropped when disabled; `AppIconButton.tsx:89–95`). Update its test.
- `aria-live` on the moments that change without focus: `CountdownTimer` (polite), async error/retry regions,
  payment-status polling. Today `aria-live` appears **nowhere** in `client/src`.
- Disclosure semantics (`aria-expanded` + `aria-controls`) on collapsibles — the earnings `ExplainerCard`
  pattern and any phase-built equivalents.
- Form label association audit (MUI does this when `label` is used — audit the hand-rolled ones); focus-visible
  coverage check (phase 0 tokenized the ring — verify interactive elements show it); contrast re-check on
  remaining terracotta *text* usages in both schemes.

### 3.10 Desktop-aware layouts — the two worst phone-column offenders (scope-boxed)

**Only if phases 4/6 didn't already:** above ~900px, (a) checkout (`(customer)/bookings/checkout/`) becomes
two-column with a sticky order summary; (b) search results (`(customer)/search/results/page.tsx`) uses the
width (wider cards or list + detail). Nothing else — a full responsive pass is (DEFERRED → post-chain).

### 3.11 Final QA — the closing walkthrough

Write a per-shell walkthrough checklist (customer funnel, nurse day-of + verification, admin desks, partner
portal, auth/first-run) × `/fa`+`/en` × light+dark × mobile+desktop. Run it end-to-end; fix what it finds
(anything non-trivial becomes a report note, not silent scope expansion). Attach the completed checklist to
the phase report — it is the chain's shipping evidence.

## 4. Mocks & seams in this phase

None introduced. UI stays mock-tolerant behind the existing `services/{domain}` seams. The one backend gap is
3.6's policy-config read: a REQ appended to
[for-backend.md](../../shared-working-context/frontend/requests/for-backend.md) (REQ-001…038 taken at
authoring time — check the tail for numbers earlier UI phases claimed, and number onward). Until delivered,
the client single-sources the numbers in `constants/policy.ts`; no mock flag changes.

## 5. Critical rules you must not get wrong

- **`payment.escrow_notice` and product-mandated strings change only with a flagged product note.** The
  escrow sentence, `payouts.explainer_point_1–3` (especially point 3's BNPL-fee-never-deducted guarantee),
  the two-stage disclosure copy (`booking.notes_hint` / `booking.disclosure_note`), and the verification-failure
  reasons are model trust writing — sweeps may normalize their spelling, never their meaning. If a rewrite
  seems needed, flag it in the report instead.
- **Don't regress the keep-lists** (both audit files): calming money-status vocabulary («در راه»، «نیازمند
  بررسی»), culturally-tuned gender copy, formal شما, complete per-namespace state strings, admin
  confirm-dialog operational candor, token discipline, RTL `dir="ltr"` islands, Shamsi-first formatting.
- **en stays hand-written-idiomatic** — no machine-translation tone ("Queue clear — nothing to review" is the
  bar). **Key parity fa/en stays absolute:** every add/rename lands in both catalogs in the same change.
- **Don't rename stable message keys casually.** A key rename must grep and update every `t('…')` usage; if a
  key's meaning is unchanged, keep its name and change only the value.
- **Design-contract non-negotiables** that bite here: tokens not hexes (motion durations/easings are tokens,
  not inline magic numbers); RTL logical props (arrows mirror by construction); dark mode on every touched
  surface; MUI v9 API only; co-located tests for touched shared components (`AppIconButton`,
  `CountdownTimer`, `EscrowNotice` all have `.test.tsx`); fetch/cookies rules untouched — no data-layer changes.
- **Reduced motion is a hard gate, not a nice-to-have** — every animation collapses to no-motion under
  `prefers-reduced-motion: reduce` via the single gate (3.8). **Frontend lane only:** the policy-config gap
  is a REQ, never a `server/` edit.

## 6. Definition of Done

On top of the shared [definition-of-done.md](../../phases/_shared/definition-of-done.md):

- [ ] `npm run check` green (now including `lint:copy`); `npm run test:ci` green for touched shared
      components (`AppIconButton`, `CountdownTimer`, any collapsible/state component touched).
- [ ] `client/messages/STYLE.md` exists; `scripts/check-copy.mjs` passes with **zero** banned variants —
      no plain-space brand, no hamza-less تایید, no «بازی» trap, no می‌گردد, one جستجو form.
- [ ] `en.json`/`fa.json` in key parity; every `{count}` key has ICU plural + designed `=0` in both catalogs;
      no literal ←/→ remains in either catalog (grep proves it).
- [ ] `bnpl.ownership_note` plainly allocates default risk to the provider; «نکول» absent from the catalog.
- [ ] Policy numbers interpolate from `constants/policy.ts`; the policy-config REQ is filed with a number.
- [ ] `prefers-reduced-motion: reduce` disables all chain-added motion; icon-only buttons have accessible
      names including when disabled; countdown/async-status regions have `aria-live`; touched collapsibles
      expose `aria-expanded`.
- [ ] Visual verification on the four axes — `/fa` + `/en` × light + dark — and mobile + desktop for 3.8/3.10
      surfaces; the completed 3.11 walkthrough checklist is attached to the phase report.

## 7. How to test (what a human can verify after this phase)

1. `cd client && npm run check` — passes, including the new copy lint. Temporarily add «بالین یار» to any fa
   value → `lint:copy` fails; revert.
2. Log in as a customer (`/fa`): login, checkout escrow copy, and refund screens all spell «بالین‌یار»
   identically; the OTP screen shows the new reassurance line.
3. Search with filters that match nothing → «پرستاری یافت نشد» (not «۰ پرستار»; not "View no nurses" on
   `/en`); counts render Persian digits on `/fa`.
4. As a nurse, attempt EVV check-out without a check-in → the corrected sentence (no «ورود بازی»); the bank
   screen's verified chip reads «تأییدشده»; the visits screen introduces «ثبت حضور الکترونیکی (EVV)» once.
5. On `/en` checkout, "Continue to payment" carries a mirrored end-icon pointing forward (→ in LTR, mirrored
   on `/fa`); grep both catalogs for `←|→` → zero hits.
6. Open the BNPL comparison → the ownership note reads plainly, no «نکول», risk clearly on the provider.
   Grep the catalogs for «۷۲ ساعته» → none; the keys take `{hours}` from `constants/policy.ts`; the REQ
   exists in the tracker.
7. Navigate between routes → 150–200ms calm fade/slide, skeletons crossfade into content; enable reduced
   motion in DevTools → everything appears instantly.
8. Inspect the a11y tree on a screen with icon-only buttons: each has a name, including a disabled one; a
   running countdown announces politely (`aria-live`).
9. Run the 3.11 checklist across all shells on the four axes + both widths; every row checked or fixed.

## 8. Hand off & document (close the phase)

- Update `client/CLAUDE.md`: mention `messages/STYLE.md` + `lint:copy` in the i18n/Golden-rules sections and
  the reduced-motion gate location; update "Project Structure" if `scripts/` or `constants/policy.ts` are new.
- Write the frontend report at `../../shared-working-context/reports/ui-phase-12-report.md`: the style-guide
  decisions taken (hamza form, جستجو form, shell naming, status vocabulary, digits policy), swept-key counts,
  conditional items skipped because an earlier phase did them, the completed QA checklist, and anything the
  walkthrough found but deferred. List the REQ(s) filed with their numbers.
- Save a memory note per operating-rules §8: the chain is complete — style guide + copy lint now enforce
  Persian orthography; motion and a11y gates exist; record the STYLE.md decisions so future copy follows them.