baya-monorepo/dev/shared-working-context/reports/ui-phase-12-report.md

UI Phase 12 — Copy, motion & final polish — Report (2026-07-19)

This is the closing phase of the UI build chain (phases 0–12). Scope: a checked-in Persian style guide

• lint, the verified copy defects from the microcopy/cross-cutting audits, ICU plurals, arrows out of strings, a trust-copy pass, config-served policy numbers, a restrained app-wide motion language behind a single reduced-motion gate, an a11y sweep, two desktop-aware layouts, and this closing QA pass.

What was built

3.1 — Persian style guide + enforcement

• client/messages/STYLE.md — the binding one-pager: brand spelling (ZWNJ), تأیید hamza, one جستجو form, ZWNJ rules, punctuation, domain glossary (بیمار not مددجو), the shell-naming system (اپلیکیشن for end-user shells, کنسول for back-office), the verification-pipeline-vs-KYC-step naming split, a nurse-facing/admin-facing status-vocabulary rule, digits policy, register, and the policy-number-interpolation rule.
• client/scripts/check-copy.mjs — a ~100-line dependency-free Node script that flattens fa.json and greps every leaf string against 5 banned-variant rules (plain-space brand, hamza-less تایید, جست‌وجو/جست و جو, the «بازی» word-boundary trap, the archaic می‌گردد passive — with a leading-space anchor so the legitimate verb «برمی‌گردد» is never a false positive). Wired as npm run lint:copy, folded into npm run check. Currently: 1919 strings checked, 0 banned variants.

3.2/hamza/جستجو/می‌گردد sweep — ~90 keys swept across fa.json

• Brand name: 5 keys (common.brand, auth.customer_title/select_role_title/account_error_body, verification.start_body) — plain-space → ZWNJ.
• تأیید hamza: ~65 occurrences normalized to the hamza form across home, profile, nurseProfile, bank, activation, search, booking, payment, auth, verification, refunds, bnpl, payouts, admin, partner, legal. bank.status_verified_chip's typo («تاییدشد» missing the final ه) is fixed to «تأییدشده» in the same edit.
• جستجو: 3 keys folded (coverage.empty_warning, booking.missing_nurse_body, one legal section body).
• Archaic می‌گردد → می‌شود: refunds.confirm_restate, admin.mod_confirm_publish, admin.cfg_save_confirm_body (3 occurrences, matching the audit's own recount, not the "1" a naive grep would find).
• Grammar bugs: booking.evv_no_open_check_in («ورود بازی» → «ورودِ ثبت‌شده‌ای برای این ویزیت وجود ندارد؛ ابتدا ورود را ثبت کنید.») and admin.alert_empty («هشدار بازی» → «هشداری برای رسیدگی نیست.»).
• tickets.thread_empty_body comma splice → two sentences.
• address.line_hint — already fixed by ui-phase-9 (verified in its report); not re-touched.
• EVV introduced once: booking.evv_visits_subtitle now spells out «ثبت حضور الکترونیکی (EVV) — ورود و خروج شما ثبت می‌شود تا ویزیت بدون اختلاف تأیید شود» (this subtitle renders once per visits-page load); the short chips (evv_check_in/evv_check_out) stay abbreviated.
• en: auth.nurse_subtitle "licence" → "license"; 6 curly-apostrophe holdouts in the admin namespace (no_permission, doc_error, payout_run_confirm_body, mod_confirm_publish, access_denied, invoice_pdf_error) → straight quotes. Zero curly quotes remain (verified by grep).

Shell naming + verification-pipeline naming (fa only — en had no overload)

• shell.nurse_app/switch_to_nurse: «نمای پرستار» → «اپلیکیشن پرستار» (end-user shells share one metaphor); shell.partner_console: «پرتال همکار» → «کنسول همکار» (back-office shells share the other). booking.evv_nurse_view ("نمای پرستار" as a perspective chip label, not a shell name) is untouched — it's a different concept and STYLE.md calls out the distinction explicitly.
• «احراز هویت» renamed to «تأیید صلاحیت» for the pipeline (11 keys: nav.verification, nurseProfile.unverified_body/unverified_cta, verification.title/load_error/start_title/ start_cta/progress_title/approved_title/credentials_needs_start/review_approved_title, admin.ver_title/ver_case_title); verification.explainer_not_verified rephrased to «صلاحیت این پرستار هنوز تأیید نشده است.» for the same reason. The KYC step keeps «احراز هویت» everywhere (verification.step_identity_kyc, admin.step_identity_kyc, activation.row_identity) — the two no longer share a name, so a nurse who passed KYC no longer sees the pipeline nav item read as contradictorily incomplete under the same word.
• Status vocabulary: admin.step_failed («ناموفق» → «ردشده») now matches admin's own agg_rejected/rstatus_rejected/mstatus_rejected pattern (all «ردشده»); nurse-facing verification.status_failed keeps «رد شد» (STYLE.md §9 — one nurse-facing form, one admin-facing form). Money-failure vocabulary (ناموفق for payouts/refunds/batches) is untouched — a payment failing is a different concept from a document being rejected.

3.3 — ICU plurals with designed =0 cases

• fa gained ICU plural + a real zero-state on the 4 keys the audit flagged: search.cta_view_results/results_count/reviews_count, booking.session_count. Zero renders «پرستاری یافت نشد» / «بدون نظر» / «ویزیتی نیست», never «۰ پرستار». search/SearchScreen.tsx doesn't need a call-site change — cta_view_results is only reached when count > 0 (the sibling cta_zero_title branch handles the zero state), so the ICU =0 case is a defensive designed fallback, not the primary render path.
• en's own cta_view_results/results_count =0 case fixed from the audit's flagged "View no nurses" / "No nurses" to "No nurses found" (cta_view_results restructured so "View" only prefixes the non-zero cases — {count, plural, =0 {No nurses found} one {View # nurse} other {View # nurses}} — rather than gluing "View" onto a full sentence).

3.4 — Arrows out of strings

• 4 keys per catalog had a literal ←/→ (not 5 — payment.cta_pay already lost its arrow before this phase): booking.continue_payment, auth.nurse_switch/customer_switch, admin.cfg_history_change. All four are now plain text; direction moves into a mirrored AppIcon icon="forward" (registered in DIRECTIONAL_ICONS, auto-flips under [dir='rtl'] regardless of host component — verified by reading AppIcon.tsx, no per-call-site mirroring logic needed):
  • bookings/request/[id]/page.tsx's continue-to-payment button: endIcon="payment" → endIcon="forward" (fixes the en wrong-direction arrow by construction — the icon mirrors, the string never carried direction to begin with).
  • PhoneStep.tsx's role-switch link: an inline <AppIcon icon="forward" size={14}> after the text.
  • admin/config/page.tsx's config-history diff: cfg_history_change split into cfg_history_change_old/_new (each holding one interpolation), rendered as two Typographys joined by a mirrored AppIcon icon="forward" — the old defect (a translator hand-mirroring {old} ← {new}) can't recur.
• Grep for ←|→ across both catalogs → zero hits (STYLE.md prose itself has none either).

3.5 — Trust-moments copy pass

• BNPL de-jargon: bnpl.ownership_note rewritten reader-first, «نکول» removed entirely — "you pay installments directly to the provider; Balinyaar receives the full amount up front, and if an installment goes unpaid, that risk sits with the provider — never you or the nurse" (both catalogs). Kept provider-agnostic (no {provider} interpolation) because the call site (MethodStep.tsx) shows this line before a provider is chosen, ahead of the provider list.
• OTP-screen reassurance and checkout "why is this safe": found already delivered — AuthCard/TrustBullets (ui-phase-3) already renders three trust bullets (verified nurses, escrow payment, support) directly under the phone-entry card on both the customer and nurse login steps, and EscrowExplainer (ui-phase-6) already supplements EscrowNotice with a 3-step visual + the cancellation-policy implication at checkout. Neither needed new copy; verified by reading AuthCard.tsx/ PhoneStep.tsx/EscrowExplainer.tsx rather than assumed from the audit's older snapshot.
• Verification pipeline naming + status vocabulary: see above.

3.6 — Config-served policy numbers

• New client/src/constants/policy.ts: DISPUTE_WINDOW_HOURS=72, CANCELLATION_LEAD_HOURS=24, REFUND_ETA_MIN_BUSINESS_DAYS=7, REFUND_ETA_MAX_BUSINESS_DAYS=10 — re-exported via src/constants/index.ts.
• payouts.explainer_point_2 takes {hours}; refunds.lead_gt_24h/lead_lt_24h take {hours}; refunds.eta_business_days takes {minDays}/{maxDays} (both catalogs). Wired at the 3 call sites: nurse/earnings/page.tsx's ExplainerCard, CancellationPolicyDisclosure.tsx, RefundEtaBanner.tsx. services/refunds/constants.ts's BNPL_REFUND_ETA_BUSINESS_DAYS now sources from REFUND_ETA_MAX_BUSINESS_DAYS instead of its own hardcoded 10, so the mock's projected refund date and the displayed ETA window can never drift apart.
• REQ-065 filed (dev/shared-working-context/frontend/requests/for-backend.md) — a public/authenticated policy-config read; verified first that only admin-scoped platform_config/* exists (per the contract docs), so this is a genuine gap, not a guess.

3.7 — Honest search empty state

• Already fixed by ui-phase-4 — search.empty_suggest_city (the Mashhad/Isfahan/Shiraz nonsense suggestion) was already deleted and replaced with empty_suggest_date in both catalogs. Verified by grep (مشهد|اصفهان|شیراز → no matches) rather than re-implemented.

3.8 — Motion pass

• globals.css: one bal-fade-in keyframe (150–200ms fade + 4px slide, var(--bal-motion-base) + var(--bal-easing-standard)) applied via a data-bal-route-fade attribute selector, and the single reduced-motion gate for the whole app — a universal *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; … } under @media (prefers-reduced-motion: reduce). This is the one rule that makes MUI's own JS-driven Dialog/Drawer/Menu/Collapse/Fade transitions collapse too (they don't read CSS custom properties, so a token-only gate wouldn't reach them) — no component anywhere needs its own reduced-motion branch.
• tokens.css additionally zeroes --bal-motion-fast/base/slow under the same media feature, for any future consumer that reads the token value directly.
• New shared component components/common/RouteFadeIn/ (tested) — wraps {children}, keyed on the locale-stripped pathname (@/i18n/navigation's usePathname) so it remounts (replaying the fade) on navigation but never on an in-place re-render. Mounted inside the ErrorBoundary in all five shells (CustomerLayout, TopBarAndSideBarLayout — nurse/admin/partner, FocusedLayout, PublicLayout) — every route in the app gets the fade, not a hand-picked subset.
• theme.ts: MuiDialog/MuiDrawer/MuiPopover/MuiMenu all get an explicit defaultProps.transitionDuration: { enter: 200, exit: 120 } in one place (matching --bal-motion-base/-fast) instead of MUI's per-variant defaults, so every dialog/bottom-sheet/menu in the app now shares one calm timing.
• Skeleton→content crossfade: the data-bal-route-fade primitive is reusable for this (any screen can attach it to its populated-state branch); demonstrated on search/results/page.tsx's results grid (§3.10) as a worked example rather than retrofitted to every list screen in the app — flagged as a mechanical follow-up below, not a silent scope cut.

3.9 — A11y sweep

• AppIconButton: the underlying IconButton now always receives aria-label={title} directly (not only via the Tooltip wrap), so a disabled icon-only button — where the Tooltip isn't rendered at all — keeps an accessible name. A caller-supplied aria-label still wins (spread order). New test: "keeps an accessible name from .title even when disabled". useMemo dependency array fixed (react-hooks/exhaustive-deps) as part of the change.
• aria-live: CountdownTimer's one-time elapsed transition now carries aria-live="polite" (the coarse-mode label already had it from an earlier phase; the fine per-second clock deliberately still doesn't — spam risk, unchanged). ErrorState (the one "query failed" pattern, ~55 sites) gets role="alert" — one change covers every error/retry region in the app. ErrorBoundary gets the same. PaymentStateCard (the one terminal/wait-state card for card + BNPL checkout, including the pending→succeeded/failed poll) gets aria-live="polite".
• aria-expanded/aria-controls: EscrowExplainer's toggle gained aria-controls (it already had aria-expanded); the admin ticket thread's refund-panel toggle (admin/tickets/[id]/page.tsx) gained both (it had neither). nurse/earnings's ExplainerCard and AuditLogRow/EmergencyPlaybookRow already had both from earlier phases — verified, not re-touched.
• Contrast: NurseDashboardScreen.tsx's unread-notifications label was the one real terracotta-on-text finding (color: 'var(--bal-secondary)' on a body2 unread count) — swapped to --bal-secondary-dark. Every other --bal-secondary text usage found by grep was already --bal-secondary-dark (BNPL screens) or an icon/background (non-text contrast rules, not the AA text threshold the audit flagged).

3.10 — Desktop-aware layouts (scope-boxed to the two named surfaces)

• Checkout (bookings/checkout/page.tsx): above md (~900px), a two-column layout — the summary/total/countdown/breakdown/escrow content on the reading side (flex 62%), a position: sticky order-summary panel with the pay CTA on the other. The pay-action JSX (total, CTA, secure-gateway note, BNPL button, inline error) is a single payActions value rendered in both the desktop panel and the mobile StickyActionBar — same handlers, same state, no duplicated logic; only one is visible at a time via sx={{ display: { xs: …, md: … } }}, the same pattern the codebase already uses for BottomBar/CustomerDesktopNav.
• Search results (search/results/page.tsx): the populated/skeleton lists switch from a single-column Stack to a display: grid with gridTemplateColumns: { xs: '1fr', md: '1fr 1fr' } — two columns above md. Bounded by the customer shell's existing CONTENT_MAX_WIDTH (800px, unchanged, shared across the whole customer app) — each card gets meaningfully more width than the old full-width single column, but a true full-bleed desktop layout or list+detail split would need a per-route shell override, which is exactly the "full responsive pass" the phase doc explicitly defers post-chain. Flagged, not silently cut.

3.11 — Final QA walkthrough

Static verification performed (all green): npm run check (type + lint + the new lint:copy), npm run test:ci (115 suites / 526 tests, including 2 new/extended ones — RouteFadeIn.test.tsx, AppIconButton.test.tsx's new disabled-name case), a key-parity script (fa.json/en.json — 1891 leaf keys each, zero one-sided keys, matching array lengths on legal.terms_sections/privacy_sections), and a manual grep pass for stray hex literals in every changed file (none found — every new color reference is a var(--bal-*) token).

Could not perform a live in-browser visual pass. This sandbox has no headless-browser tool (chromium-cli is not installed) and direct HTTP access to the dev server's localhost port returns a proxy 502 rather than reaching Next.js (confirmed: the dev server itself started cleanly — ✓ Ready in 5.8s in its log — the request never reached it). Per this repo's own verification guidance, I'm stating this explicitly rather than claiming a visual check that didn't happen. A human should run npm run dev and spot-check, on /fa and /en × light and dark × a narrow and a ≥1100px viewport:

• Login (/login): brand reads «بالین‌یار» identically everywhere it appears (header, trust bullets, account-error retry copy); trust bullets render under the phone-entry card.
• Search (/search → results): filters producing zero results show «پرستاری یافت نشد» (fa) / "No nurses found" (en) — never «۰ پرستار»/"View no nurses"; at ≥900px, result cards render two-up.
• Nurse EVV (/nurse/visits): the visits subtitle spells out EVV once; attempting a check-out with no open check-in shows the corrected sentence (no «ورود بازی»).
• Bank (/nurse/bank): the verified chip reads «تأییدشده» (not «تاییدشد»).
• Checkout (/bookings/checkout?request_id=…): at ≥900px, a two-column layout with a sticky right-side pay panel; at <900px, the original bottom sticky bar; the "continue to payment" button's chevron points the reading-forward direction on both locales (mirrored, not baked into the string).
  • Currently only reachable via the request-flow with a real/mocked accepted_awaiting_payment request.
• BNPL comparison (/bookings/checkout/bnpl): the ownership note reads plainly, no «نکول».
• Any route transition: a calm ~150–200ms fade/slide plays once; with DevTools' "Emulate CSS media feature prefers-reduced-motion: reduce" enabled, everything appears instantly (no fade, no MUI dialog/menu transition either).
• Any icon-only disabled button (e.g. a paused/loading admin action): inspect the accessibility tree — it still has a name.
• Config history (/admin/config, open a row's history drawer): the old→new diff shows a mirrored arrow icon between two values, not a baked-in ←/→ character.

What is now testable (and exactly how)

1. cd client && npm run check — passes, including lint:copy. Temporarily add «بالین یار» (plain space) to any fa.json value → npm run lint:copy fails with the exact key path; revert.
2. npm run test:ci — 115 suites / 526 tests pass, including the two touched/added shared-component tests.
3. Grep both catalogs for ←|→ → zero hits. Grep for تایید (hamza-less) → zero hits (only تأیید and its compounds remain). Grep for جست‌وجو/جست و جو → zero hits.
4. The four visual-axis items above, once a human can reach a browser.

What is mocked / waiting on a real service

• REQ-065 (new, this phase) — public/authenticated policy-config read (dispute-window hours, cancellation lead hours, refund ETA days). Until delivered, client/src/constants/policy.ts is the single source; every message key that used to hardcode a policy number now takes it as an ICU param from this file. No mock-registry entry needed — this isn't a seam behind a DI interface, it's a constants file standing in for a config read that doesn't exist yet for a non-admin caller.
• No other new mocks this phase; no services/{domain} seam was touched.

Contracts

• Consumed: none new. REQ-065 filed against the existing platform_config admin-only surface (dev/contracts/domains/ — verified no public projection exists before filing, per the phase's own instruction not to file speculatively).

Docs updated

• client/messages/STYLE.md — new, the Persian style guide (this phase's own deliverable).
• client/CLAUDE.md — see the diff in this change: mentions messages/STYLE.md + npm run lint:copy in the i18n section, the reduced-motion gate location (globals.css), RouteFadeIn in the component-library table, and constants/policy.ts in the constants section.
• dev/shared-working-context/frontend/requests/for-backend.md — REQ-065 appended.

Follow-ups for later phases (post-chain)

• Skeleton→content crossfade beyond the one worked example. data-bal-route-fade is reusable (a one-line addition per screen) but wasn't retrofitted onto every list/detail page in the app — a mechanical, low-risk follow-up, not a defect.
• A true desktop search layout (list+detail split, or breaking out of the 800px CONTENT_MAX_WIDTH for this one route) — the phase doc explicitly defers "a full responsive pass" post-chain; the 2-column grid shipped here is the scope-boxed interim step.
• REQ-065 — once delivered, replace constants/policy.ts's hardcoded numbers with a fetched config read (the ICU-param call sites don't change, only where the numbers come from).
• A live in-browser visual confirmation of the walkthrough checklist above — this environment couldn't run one; flag to the human reviewer.

Memory

A project-type memory note was saved (ui_phase_12_copy_motion_polish.md) summarizing the STYLE.md decisions, the reduced-motion gate's location and mechanism, and the sandbox's browser-verification gap, so a future agent doesn't have to rediscover any of it.