chore(skill): make redesign-page a real UI/UX review harness

The skill's driver could not log in any more: its default credentials were
a user the scenario seeder wiped, so every command died on ERR_AUTH_005
before taking a single screenshot. Defaults now point at a user the seeder
actually creates, and the failure message says how to rebuild the users.

A page was also being judged on one screenshot. Dark mode and compact
density are real settings in this panel and mobile is where an RTL,
table-heavy admin breaks, so `variants` now captures all four and the theme
is written to the ui store rather than only stamped on the element — the
attribute alone is overwritten at hydrate. Narrow shots enable device
metrics, without which pointer:coarse media queries never fire and the
44px touch targets stay invisible.

Every shot now probes the live DOM for the things no grep can see:
horizontal overflow, nameless icon buttons, unlabelled fields, controls
under 32px. The static audit gained Gregorian dates, native date inputs,
icon buttons with no aria-label, and .seg without an on/active class.

`ds` prints the tokens and the shared components with their props, so a
redesign starts from what exists instead of inventing a second Modal.

Also corrected a stale claim: the suite has no pre-broken tests — it is
100 files / 660 passing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
hamed
2026-08-02 14:27:23 +03:30
co-authored by Claude Opus 5
parent 444ebc897a
commit 1c4f2a2451
2 changed files with 333 additions and 93 deletions
+133 -78
View File
@@ -1,165 +1,220 @@
---
name: redesign-page
description: بازطراحی UI/UX یک صفحه از پنل ادمین ClinicPro از روی URL آن — اسکرین‌شات گرفتن از صفحه، نگاشت URL به فایل سورس، آدیت انحراف‌ها از دیزاین‌سیستم، و بازنویسی صفحه با کامپوننت‌ها و توکن‌های موجود. استفاده کن وقتی کاربر یک URL از /admin می‌دهد و می‌گوید «این صفحه ui/ux خوبی ندارد»، «این صفحه را بازطراحی کن»، «redesign this page»، «این قسمت را درست کن»، یا «screenshot این صفحه».
description: نقد و بازطراحی حرفه‌ای UI/UX یک صفحه از پنل ادمین ClinicPro از روی URL آن — اسکرین‌شات در چهار نما (روشن، تیره، فشرده، موبایل)، پروبِ دسترسی‌پذیری روی DOM زنده، نگاشت URL به فایل سورس، آدیت انحراف از دیزاین‌سیستم، و بازنویسی با کامپوننت‌ها و توکن‌های موجود. استفاده کن وقتی کاربر یک URL از /admin می‌دهد و می‌گوید «این صفحه ui/ux خوبی ندارد»، «این صفحه را بازطراحی کن»، «این صفحه را نقد کن»، «redesign this page»، «UI/UX review»، «این قسمت را درست کن»، یا «screenshot این صفحه».
---
# بازطراحی صفحه پنل ادمین ClinicPro
# نقد و بازطراحی صفحهٔ پنل ادمین ClinicPro
نقش: متخصص ارشد UI/UX. هدف **بهبود تجربهٔ کاربری در چهارچوب تم فعلی** است، نه ساختن
هویت بصری جدید. هر تغییری که با دیزاین‌سیستم فعلی ناسازگار باشد، رد است.
پنل ادمین یک SPA کلاینت‌ساید است (React 19 + Webpack Encore، سرو شده از `/admin/*`).
یعنی `curl` و فلگ `--screenshot` کروم به درد نمی‌خورند: هر دو روی فرم لاگین می‌نشینند،
چون توکن JWT در `localStorage['clinicpro-auth']` است.
درایور این skill آن کار را انجام می‌دهد: با API لاگین می‌کند، `localStorage` را seed
می‌کند، بعد ناوبری و اسکرین‌شات می‌گیرد — با CDP روی `WebSocket` نیتیو Node 22،
**بدون هیچ وابستگی npm** (نه playwright، نه puppeteer).
چون توکن JWT در `localStorage['clinicpro-auth']` است. درایور این skill آن کار را
می‌کند: با API لاگین می‌کند، `localStorage` را seed می‌کند، تم/تراکم را می‌نشاند، بعد
ناوبری و اسکرین‌شات می‌گیرد — با CDP روی `WebSocket` نیتیو Node 22، **بدون هیچ وابستگی
npm** (نه playwright، نه puppeteer).
مسیرها نسبت به `clinicpro/` هستند.
## پیش‌نیازها
هیچ نصبی لازم نیست. فقط این دو:
هیچ نصبی لازم نیست:
```bash
ddev describe | head -3 # باید بالا باشد: https://clinic-pro.ddev.site
ls "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
```
کروم در مسیر دیگری است؟ `CHROME_BIN` را ست کن.
کروم جای دیگری است؟ `CHROME_BIN` را ست کن.
## گردش کار
### ۱. اسکرین‌شات صفحه فعلی
### ۰. اول دیزاین‌سیستم را بخوان — قبل از هر چیز
**منبع حقیقتِ توکن‌ها `assets/admin/styles.css` است**، نه `docs/admin-ui/ui-design-spec.md`
(آن سند قدیمی است و پالت بنفشش با کد شیپ‌شده نمی‌خواند).
```bash
node .claude/skills/redesign-page/driver.mjs shot \
"https://clinic-pro.ddev.site/admin/appointments" --out /tmp/before.png
node .claude/skills/redesign-page/driver.mjs ds # توکن‌ها + کلاس‌ها + کامپوننت‌ها
node .claude/skills/redesign-page/driver.mjs ds tokens # فقط توکن‌ها
node .claude/skills/redesign-page/driver.mjs ds components # فقط کامپوننت‌های مشترک با Props
```
**بعد حتماً تصویر را با ابزار Read باز کن و نگاه کن.** بدون دیدنِ صفحه، بازطراحی
یعنی حدس زدن.
خروجی واقعی: `TOKENS (57)` و `SHARED COMPONENTS (26)`. قانون ترتیب:
**اول کامپوننت موجود، بعد توسعه/عمومی‌کردنش، در آخر ساخت کامپوننت جدید** — و دلیلش را بنویس.
فلگ‌ها: `--w 1440 --h 900` (سایز ویوپورت)، `--wait 4000` (میلی‌ثانیه صبر برای رندر)،
`--full` (کل صفحه، نه فقط ویوپورت).
موبایل هم ببین — این پنل RTL و پرجدول است و بیشتر مشکلات ریسپانسیو آنجاست:
### ۱. چهار نمای اجباری
```bash
node .claude/skills/redesign-page/driver.mjs shot \
"https://clinic-pro.ddev.site/admin/appointments" --w 390 --h 844 --out /tmp/mobile.png
node .claude/skills/redesign-page/driver.mjs variants \
"https://clinic-pro.ddev.site/admin/resources" --dir /tmp/clinicpro-review
```
### ۲. نگاشت URL به سورس + آدیت
چهار فایل می‌سازد: `-light` · `-dark` · `-compact` · `-mobile`. **هر چهار را با ابزار
Read باز کن و نگاه کن.** قضاوت با یک اسکرین‌شات یعنی صفحه‌ای که در سه نمای دیگر خراب است.
تم تیره و تراکم فشرده در این پنل تنظیمات واقعی کاربرند، نه فرض.
تک‌نما:
```bash
node .claude/skills/redesign-page/driver.mjs inspect \
"https://clinic-pro.ddev.site/admin/clinics/41e325c4-e825-4067-8438-5d828ecaee09"
node .claude/skills/redesign-page/driver.mjs shot "<url>" --out /tmp/x.png \
--theme dark --density compact --w 390 --h 844 --full --wait 6000
```
فلگ‌ها: `--w/--h` ویوپورت · `--wait` میلی‌ثانیه · `--full` کل صفحه ·
`--theme light|dark` · `--density comfortable|compact` · `--context clinic|personal` ·
`--no-probe`.
هر `shot` یک **پروب رانتایم** هم می‌زند که فقط روی DOM رندرشده دیدنی است:
```
RUNTIME
⚠ 2 form field(s) with no label
```
چه چیزهایی می‌گیرد: سرریز افقی، دکمهٔ آیکونیِ بی‌نام (بدون `aria-label`/`title`
فیلد بدون لیبل، و کنترل کوتاه‌تر از ۳۲px (هدف لمسی ۴۴px است).
### ۲. نگاشت URL به سورس + آدیت ایستا
```bash
node .claude/skills/redesign-page/driver.mjs inspect "https://clinic-pro.ddev.site/admin/resources"
```
خروجی واقعی:
```
route clinics/:uuid
component ClinicDetailPage
file assets/admin/pages/ClinicDetailPage.tsx
components ConfirmDialog, Modal, PageHeader, SearchableSelect, NotificationMobileCard
lines 1035
route resources
component ResourcesPage
file assets/admin/pages/ResourcesPage.tsx
components PageHeader, DataTable, ResourceBlocksModal, ConfirmDialog, SearchableSelect, …
lines 278
test assets/admin/pages/ResourcesPage.test.tsx
AUDIT
assets/admin/pages/ClinicDetailPage.tsx:242 hand-rolled overlay — use the shared <Modal>
AUDIT clean
```
روی هر فایل دلخواه هم مستقیم:
روی هر فایل مستقیم:
```bash
node .claude/skills/redesign-page/driver.mjs audit assets/admin/pages/AppointmentsPage.tsx
node .claude/skills/redesign-page/driver.mjs audit assets/admin/pages/ClinicDetailPage.tsx
# AUDIT
# assets/admin/pages/ClinicDetailPage.tsx:242 hand-rolled overlay — use the shared <Modal>
```
### ۳. قبل از نوشتن کد، دیزاین‌سیستم را بخوان
آدیت این‌ها را می‌گیرد: `<select>` نیتیو، `.btn` بدون واریانت، هگز هاردکد، overlay دستی،
`<label>` داخل `.field`، تاریخ میلادی، `type="date"`، دکمهٔ آیکونی بدون `aria-label`،
توکن تعریف‌نشده، و `.seg` بدون کلاس `on/active`.
**منبع حقیقتِ توکن‌ها `assets/admin/styles.css` است** — نه `docs/admin-ui/ui-design-spec.md`
(آن سند قدیمی و پالت بنفشش با کد شیپ‌شده نمی‌خواند).
### ۳. گزارش — همیشه با این ۹ بخش
```bash
sed -n '/^:root/,/^}/p' assets/admin/styles.css | head -60 # توکن‌ها
ls assets/admin/components/ui/ # کامپوننت‌های آماده
```
۱. تحلیل صفحه چه کاری برای چه کاربری؛ جریان اصلی
۲. مشکلات UI سلسله‌مراتب بصری، فاصله، تایپوگرافی، رنگ، انحراف از DS
۳. مشکلات UX جریان کار، تعداد کلیک، حالت‌های Loading/Empty/Error، ریسپانسیو، دسترسی‌پذیری
۴. پیشنهادهای بهبود برای هر مشکل، یک راه‌حل مشخص و قابل اجرا
۵. ساختار جدید صفحه چیدمان پیشنهادی، در چهارچوب همین تم
۶. کامپوننت‌های قابل استفادهٔ مجدد از components/ui که همین حالا جواب می‌دهند
۷. کامپوننت‌های نیازمند بهبود کدام Props/API باید عمومی‌تر شود و چرا
۸. کامپوننت‌های جدید فقط در صورت ضرورت، با دلیل نبودِ جایگزین
۹. دلیل هر تغییر چرا این تغییر تجربه را بهتر می‌کند
```
قانون: **اول کامپوننت موجود، بعد توسعه‌اش، در آخر ساخت کامپوننت جدید** — و دلیلش را بنویس.
هر یافته باید به `file:line` وصل باشد یا به یکی از اسکرین‌شات‌ها. یافتهٔ بی‌ارجاع، حدس است.
### ۴. بازنویسی، سپس مقایسه
بعد از ادیت، دوباره اسکرین‌شات بگیر و با `before.png` مقایسه کن:
```bash
yarn dev # یا: yarn watch
node .claude/skills/redesign-page/driver.mjs shot "<همان url>" --out /tmp/after.png
ddev exec yarn dev
node .claude/skills/redesign-page/driver.mjs variants "<همان url>" --dir /tmp/clinicpro-review-after
```
before/after را کنار هم بگذار. اگر تفاوتی دیده نمی‌شود، باندل قدیمی است.
### ۵. تست + تایپ‌چک (بدون این، تسک تمام نیست)
```bash
npx tsc --noEmit -p tsconfig.json
npx vitest run assets/admin/pages/<YourPage>.test.tsx
ddev exec npx tsc --noEmit --project tsconfig.json
npx vitest run # روی هاست، نه داخل ddev
```
توجه: سوییت کامل همین الان **۲۱ تست از پیش شکسته** دارد (`api.test.ts`، `LoginPage`،
`PatientDetailPage`، …) که ربطی به کار تو ندارند. قبل از شروع یک‌بار `npx vitest run`
بگیر و عدد پایه را یادداشت کن، وگرنه خطاهای موجود را به گردن تغییر خودت می‌اندازی.
خط پایه در ۲۰۲۶-۰۸-۰۲: **۱۰۰ فایل، ۶۶۰ تست، همه سبز.** هر شکستی مالِ توست.
(نسخهٔ قبلی این سند از «۲۱ تست از پیش شکسته» می‌گفت — دیگر درست نیست.)
## چک‌لیست بازطراحی
درایور موارد گرپ‌شدنی را می‌گیرد؛ این‌ها را باید خودت با چشم ببینی:
درایور موارد گرپ‌شدنی و DOMی را می‌گیرد؛ این‌ها را باید خودت با چشم ببینی:
- **`.field` در مقابل `.field-block`** — `.field` یک باکس افقی بوردردار است که لیبل
*داخلش* می‌نشیند. اگر `<label>` داخل `.field` بگذاری، لیبل کنار اینپوت می‌چسبد؛ و اگر
`SearchableSelect` داخلش بگذاری، دو باکس تودرتو می‌شود. برای «لیبل بالای فیلد» از
`.field-block` استفاده کن.
- **`className="btn"` بدون واریانت** بی‌رنگ و بدون بوردر رندر می‌شود عملاً نامرئی.
همیشه `btn primary` / `btn ghost` / `btn soft` / `btn danger`.
- **دکمه‌های فقط-آیکون** → `mini-btn`، نه `btn ghost sm` با پدینگ دستی.
- **توکن مرده** — مثلاً `var(--error)` وجود ندارد (`--danger` درست است). درایور این را می‌گیرد.
- **سلسله‌مراتب** — عنوان صفحه در `PageHeader` بیاید و در کارت زیرش تکرار نشود.
- **`.field` در مقابل `.field-block`** — `.field` خودش باکسِ بوردردار اینپوت است. لیبل
داخلش یعنی لیبل چسبیده به اینپوت؛ `SearchableSelect` داخلش یعنی دو باکس تودرتو.
«لیبل بالای فیلد» → `.field-block`.
- **`.card` پدینگ ندارد** — `card-pad` آن را می‌دهد.
- **`className="btn"` بدون واریانت** بی‌رنگ و بی‌بوردر رندر می‌شود، عملاً نامرئی.
همیشه `btn primary` / `btn secondary` / `btn ghost` / `btn danger`.
- **دکمهٔ فقط-آیکون** → `mini-btn`، نه `btn ghost sm` با پدینگ دستی.
- **`.seg`** فقط `button` و `a` را می‌شناسد و کلاس فعالش `on` است (`active` هم alias شد).
تبِ فعالِ بی‌کلاس یعنی هیچ نشانه‌ای ندارد.
- **سلسله‌مراتب** — عنوان در `PageHeader` بیاید و در کارت زیرش تکرار نشود.
- **صفحهٔ زیرمجموعه** حتماً `backTo` یا `<BackButton fallback=…>` دارد.
- **وضعیت لیست در URL** — جستجو/فیلتر/صفحه با `useUrlState`، نه `useState`؛ وگرنه
«بازگشت» نما را می‌پراند.
- **RTL/جلالی** — رشته‌های جدید فارسی، تاریخ‌ها جلالی، اعداد با `formatNumber`/`formatRial`.
- **دارک‌مود** — چون توکن استفاده می‌کنی خودکار درست است؛ هگز هاردکد آن را می‌شکند.
- **دارک‌مود** — با توکن خودکار درست است؛ یک هگز هاردکد آن را می‌شکند.
- **سه حالت داده** — Loading / Empty / Error هر سه باید طراحی داشته باشند، نه فقط حالت پر.
## Gotchas
- **ریدایرکت خاموش نقش‌ها.** `RoleRoute` کاربری که نقشش اجازه ندارد را بی‌صدا به
`/admin/dashboard` می‌برد. یعنی یک اسکرین‌شات کاملاً سالم از **صفحهٔ اشتباه** می‌گیری.
درایور مسیر نهایی را با مسیر درخواستی مقایسه می‌کند و هشدار می‌دهد:
- **کاربر پیش‌فرض درایور با دیتابیس فعلی هماهنگ است، ولی دیتابیس عوض می‌شود.**
پیش‌فرض `0912000201` / `QaTest@1234` (پزشکِ مالک کلینیک) است. اگر لاگین `ERR_AUTH_005`
داد، دیتابیس دوباره seed شده: `ddev exec php bin/console app:seed-scenarios --reset -n`.
در اجرای ۲۰۲۶-۰۸-۰۲ کاربر `0912000301` (مالک غیرپزشک) **رمز نداشت** و لاگینش رد شد؛
از `0912000201` یا `0912000101` استفاده کن.
- **ریدایرکت خاموش نقش‌ها.** `RoleRoute` کاربرِ بی‌مجوز را بی‌صدا به `/admin/dashboard`
می‌برد — یعنی یک اسکرین‌شات کاملاً سالم از **صفحهٔ اشتباه**. درایور مقایسه می‌کند:
```
⚠ WRONG PAGE: asked for /admin/clinics/…, landed on /admin/dashboard
```
کاربر پیش‌فرض (`09390039833`) نقش **doctor** دارد. صفحات ادمین/کلینیک با آن باز نمی‌شوند.
برای آن‌ها `CLINICPRO_USER` / `CLINICPRO_PASS` را ست کن.
- **محیط کاری، نه نقش.** کاربری که هم مطب شخصی دارد هم کلینیک، پیش‌فرض روی مطب می‌نشیند و
صفحهٔ منابع/سرویس‌های کلینیک **خالی** می‌آید. این باگ نیست: `--context clinic` بده.
- **کاربران تستی ممکن است seed نشده باشند.** `TEST_USERS.md` ادمین `09100000001` با رمز
`Test@1234` را مستند می‌کند، ولی روی این دیتابیس وجود نداشت و لاگین `ERR_AUTH_005` داد.
ساختنشان: `ddev exec php create_test_users.php` (دیتابیس را می‌نویسد — اول بپرس).
- **مودال نصب PWA جلوی صفحه را می‌گیرد.** درایور `pwa-dismissed=1` را seed می‌کند. با
کروم خام، این مودال وسط تصویر است.
- **مودال نصب PWA جلوی صفحه را می‌گیرد.** درایور `localStorage['pwa-dismissed']='1'` را
seed می‌کند. اگر با کروم خام اسکرین‌شات بگیری، این مودال وسط تصویر است.
- **تم فقط با صفت `data-theme` نمی‌ماند** — بعد از hydrate از `localStorage['clinicpro-ui']`
دوباره خوانده می‌شود. درایور هر دو را می‌نویسد و بعد از رندر یک بار دیگر صفت را می‌گذارد.
- **موبایل بدون `Emulation.setDeviceMetricsOverride` فقط «پنجرهٔ باریک» است** — مدیا
کوئری‌های `pointer: coarse` خاموش می‌مانند و ارتفاع لمسی ۴۴px دیده نمی‌شود. درایور برای
عرض ≤۴۸۰ خودش این را روشن می‌کند.
- **کپچا (altcha) لوکال اجباری نیست.** `POST /api/v1/user/login` بدون فیلد `altcha` هم
توکن می‌دهد؛ درایور به همین تکیه می‌کند. اگر روی محیطی که کپچا را اجبار می‌کند اجرا شود، می‌شکند.
توکن می‌دهد؛ درایور به همین تکیه می‌کند و روی محیطی که کپچا را اجبار کند می‌شکند.
- **سرت ddev را Node رد می‌کند** (`UNABLE_TO_VERIFY_LEAF_SIGNATURE`). درایور فقط برای
هاست‌های `*.ddev.site` / `localhost` تأیید TLS را خاموش می‌کند، نه برای هر مبدأ.
`*.ddev.site` / `localhost` تأیید TLS را خاموش می‌کند، نه برای هر مبدأ.
- **صفحهٔ نوبت‌ها خودش اسکرول می‌شود** به ساعت جاری، پس ویوپورت وسط تایم‌لاین می‌افتد.
برای دیدن هدر از `--full` استفاده کن.
- **صفحهٔ نوبت‌ها خودش تا ساعت جاری اسکرول می‌کند**، پس ویوپورت وسط تایم‌لاین می‌افتد.
برای دیدن هدر `--full` بده.
- **بیلد CSS داخل ddev خطای نیتیو `lightningcss` می‌دهد** — از قبل وجود دارد و جلوی
کامپایل JS/TS را نمی‌گیرد. خطاهای TypeScript همچنان در خروجی `tsc` می‌آیند.
- **منوی تنظیمات دو مصرف‌کننده دارد** — `settingsMenu.ts` منبع واحد است؛ سایدبار دسکتاپ و
فهرست موبایل هر دو از آن می‌خوانند. در موبایل کل منو **بالای** محتوا می‌نشیند، پس صفحهٔ
تنظیماتی در نمای ۳۹۰px یعنی ۱۵ آیتم منو قبل از رسیدن به محتوا. در نقد موبایل حتماً ببینش.
- **بیلد CSS داخل ddev خطای نیتیو `lightningcss` می‌دهد** — از قبل هست و جلوی کامپایل
JS/TS را نمی‌گیرد؛ خطاهای TypeScript همچنان در خروجی `tsc` می‌آیند.
## Troubleshooting
| علامت | علت / راه‌حل |
|---|---|
| `login failed for 0912000201: … ERR_AUTH_005` | دیتابیس دوباره seed شده. `ddev exec php bin/console app:seed-scenarios --reset -n` یا `CLINICPRO_USER`/`CLINICPRO_PASS` را ست کن. |
| `Chrome did not expose CDP on :9333` | نمونهٔ کروم قبلی زنده مانده. `CDP_PORT=9444` بده یا پروسه را بکش. |
| `login failed: … ERR_AUTH_005` | کاربر seed نشده یا رمز فرق دارد. `TEST_USERS.md` را ببین. |
| `redirected to /login` | توکن رد شد؛ معمولاً یعنی JWT منقضی شده — دوباره اجرا کن. |
| `⚠ redirected to /login` | توکن رد شد؛ معمولاً JWT منقضی شده — دوباره اجرا کن. |
| `WRONG PAGE` | نقشِ کاربر اجازه ندارد، یا محیط اشتباه است (`--context clinic`). |
| `⚠ page text is only N chars` | صفحه خالی رندر شده. `--wait 8000` بده یا کنسول را چک کن. |
| اسکرین‌شات تغییرات را نشان نمی‌دهد | باندل قدیمی است. `yarn dev` بزن (یا `yarn watch` روشن باشد). |
| اسکرین‌شات تغییرات را نشان نمی‌دهد | باندل قدیمی است. `ddev exec yarn dev` (یا `yarn watch` روشن). |
| صفحهٔ کلینیک خالی است ولی خطا ندارد | محیط روی مطب شخصی است. `--context clinic`. |