add aria contents

Author: amir78729

.vitepress/config/fa.mts

@@ -110,5 +110,31 @@ function sidebar(): DefaultTheme.SidebarItem[] {
         },
       ],
     },
+    {
+      text: "روابط کاربری accessible",
+      base: "/topics/accessible-naming-screen-readers",
+      items: [
+        {
+          text: "ARIA و محاسبه نام accessible",
+          link: "/ARIA-accessible-name-computation",
+        },
+        {
+          text: "درخت accessibility",
+          link: "/the-accessibility-tree",
+        },
+        {
+          text: "تست راهکارهای ARIA",
+          link: "/testing-a-solution",
+        },
+        {
+          text: "تجربه بصری و غیر بصری",
+          link: "/visual-nonvisual-experience",
+        },
+        {
+          text: "فرمان‌ها و حالت‌های تعامل در screen reader",
+          link: "/screen-reader-commands-interaction-modes",
+        },
+      ],
+    },
   ];
 }

public/devtools-accessible-name.png

@@ -0,0 +1,48 @@
+# ARIA و محاسبه نام accessible
+
+**ARIA یا Accessible Rich Internet Applications**، یک مشخصه استاندارد برای مجموعه‌ای از ویژگی‌هاست که اطلاعات مربوط به accessibility را از طریق HTML منتقل می‌کند.
+
+ARIA شامل مفهومی مهم در نشانه‌گذاری HTML است: [accessible naming](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/).
+
+کنترل‌های فرم در HTML دارای نام هستند. لینک‌ها و دکمه‌ها نیز نام دارند. عناصر section و table‌ها هم همین‌طور. (اما عناصر DIV نام ندارند.)
+
+## نوشتن نام‌های accessible
+
+راه‌های مختلفی برای اختصاص نام به یک عنصر وجود دارد که بسته به نقش (role) عنصر، متفاوت است: محتوای متنی، عنصر `<label>` برای فرم، ویژگی‌های `aria-label` و `aria-labelledby`، و حتی ویژگی‌های `title` و `placeholder`.
+
+اما فقط یک نام در نهایت اعمال می‌شود. اگر چند ویژگی و محتوای متنی با هم استفاده شوند، کدام‌یک برنده می‌شود؟
+
+## نام‌های accessible چگونه انتخاب می‌شوند؟
+
+سندی به نام [Accessible Name and Description Computation](https://www.w3.org/TR/accname-1.2/) این فرآیند را استاندارد می‌کند تا از هرج‌ومرج در پلتفرم‌های مختلف جلوگیری شود.
+
+```html
+<label>
+    Zip Code
+    <input aria-label="zip-code" placeholder="00000" title="Zip code" type="number" />
+</label>
+```
+
+مشخصه Accessible Naming تعیین می‌کند که برای عناصر غیر مخفی که امکان نام‌گذاری دارند، ترتیب به چه صورت باشد: ابتدا `aria-labelledby`، سپس `aria-label`، بعد `title` یا `placeholder` یا تگ `<label>` فرم، و سپس برخی کنترل‌های فرزند، و در نهایت محتوای متنی.
+
+## توضیحات accessible چیستند؟
+
+توضیحاتی که با `aria-describedby` و `title` ارائه می‌شوند، مانند نام‌ها، توسط screen reader خوانده می‌شوند. اما این اتفاق با تأخیر اندکی انجام می‌شود و ممکن است بسته به تنظیمات کاربر اصلاً پخش نشود. بنابراین نمی‌توان همیشه روی شنیده شدن توضیحات حساب کرد.
+
+نام‌ها و توضیحات accessible در [مشخصه اصلی ARIA](https://www.w3.org/TR/wai-aria-1.2/#namecalculation) نیز توضیح داده شده‌اند. این اطلاعات ممکن است فنی باشند، اما هر توسعه‌دهنده‌ای باید با آن‌ها آشنا باشد.
+
+## متن قابل مشاهده را در اولویت قرار دهید
+
+استفاده از `aria-label` بسیار ساده است، ولی نباید به آن بسنده کرد. همیشه باید در صورت امکان متن‌های قابل مشاهده را در اولویت قرار داد تا تجربه‌ی بصری کاربران با آن‌چه توسط Assistive Technology دریافت می‌کنند، مطابقت داشته باشد.
+
+در بسیاری از مواقع، ویژگی `aria-label` بعد از تغییر محتوا به‌روزرسانی نمی‌شود و دیگر بیانگر چیزی که روی صفحه دیده می‌شود نیست. این مسئله موضوع یکی از موفقیت‌های معیارهای WCAG است: [Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html).
+
+## ابزار Accessibility در Chrome DevTools
+
+یکی از ابزارهای مورد علاقه من برای مشاهده نام‌ها و توضیحات قابل دسترس، Accessibility Inspector در Chrome DevTools است. این ابزار در کنار تب Styles در پنجره Elements قرار دارد. در سناریوهایی با چند ویژگی یا محتوای متنی، نشان می‌دهد که “کدام‌یک برنده می‌شود” — که بسیار مفید است.
+
+<figure className="my-6">
+    <img src="/devtools-accessible-name.png" alt="Chrome DevTools Accessibility Inspector on an icon button on StackBlitz" />
+</figure>
+
+یا ممکن است نشان دهد که ورودی فرم شما اصلاً نام accessible ندارد، چون id آن با هیچ labelای تطابق ندارد. 

public/geckoflow-ax-tree.png

@@ -0,0 +1,71 @@
+# فرمان‌ها و حالت‌های تعامل در screen reader
+
+در ادامه، نکات و فرمان‌هایی برای استفاده از انواع مختلف screen reader آورده شده است، از جمله VoiceOver برای MacOS و iOS، NVDA و JAWS در Windows و همچنین Android:
+
+## details VoiceOver برای MacOS
+- فعال‌سازی و غیرفعال‌سازی:
+    - کلید Command (⌘) + F5  
+    - در لپ‌تاپ‌ها: Fn + Command (⌘) + F5
+- استفاده از کلیدهای فعال‌سازی VoiceOver:
+    - Control + Option (VO)
+- ناوبری در صفحه:
+    - استفاده از کلیدهای TAB / Shift + TAB برای جابجایی بین عناصر قابل focus
+    - استفاده از کلیدهای جهت برای پیمایش بین بخش‌های مختلف محتوا (بسته به حالت فعال)
+    - نگه‌داشتن کلیدهای VO و استفاده از سایر فرمان‌ها. [cheat sheet](https://dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)
+    - اجرای VoiceOver Rotor:
+        - با VO فعال، کلید VO + U را بزنید. با کلیدهای جهت جابجا شوید.
+    - بستن بخش‌ها با کلید Escape (الگوی رایج)
+- ساکت کردن گفتار:
+    - نگه‌داشتن کلید Command هنگام صحبت screen reader باعث توقف فوری گفتار می‌شود (مناسب برای دمو)
+- تغییر سرعت گفتار screen reader:
+    - در برنامه VoiceOver Utility، بخش Speech
+
+[VoiceOver cheat sheet برای دسکتاپ](https://dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)
+
+## VoiceOver برای iOS
+
+در دستگاه‌های iOS، از بخش _Settings > Accessibility_ می‌توانید VoiceOver یا Switch Control را تنظیم کرده تا با سه بار فشار دادن دکمه پاور فعال شود.
+
+[VoiceOver cheat sheet برای iOS](https://dequeuniversity.com/screenreaders/voiceover-ios-shortcuts)
+
+## NVDA و JAWS برای Windows
+
+[NVDA](https://www.nvaccess.org/download/) و [JAWS](https://www.freedomscientific.com/products/software/jaws/) از پرکاربردترین screen readerها در Windows هستند.
+
+برای نصب NVDA روی Virtual Machine با Parallels (که نیاز به لایسنس Windows نیز دارد):  
+https://jerryjones.dev/2020/08/06/setting-up-nvda-on-parallels-with-macos/
+
+- [cheat sheet برای NVDA](https://dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)  
+- [cheat sheet برای JAWS](https://dequeuniversity.com/assets/pdf/screenreaders/jaws.pdf)  
+
+## Accessibility در اندروید
+
+- نکاتی برای تست در اندروید: https://developer.android.com/guide/topics/ui/accessibility/testing  
+- [TalkBack cheat sheet](https://dequeuniversity.com/screenreaders/talkback-shortcuts)  
+
+## حالت‌های تعامل در screen readerهای Windows
+
+در حالی که VoiceOver بیشتر با ترکیب‌های چندکلیدی کار می‌کند، NVDA و JAWS روی Windows رویکرد متفاوتی دارند. با فرمان‌های ساده‌تر، screen readerهای Windows دارای مفهومی به نام [_interaction modes_](https://tink.uk/understanding-screen-reader-interaction-modes/) هستند که مهندسان باید با آن آشنا باشند.
+
+<div className="float-right border-2 w-fit p-6 my-6 ml-6">
+    <h3 className="font-bold text-lg border-b-2 mb-6">مثالی از فرم</h3>
+    <label>
+        <div className="mb-2"><em>First Name</em></div>
+        <input type="text" placeholder="Rainier McCheddarton" />
+    </label>
+</div>
+
+حالت پیش‌فرض در NVDA، **Browse Mode** است. این حالت به کاربر امکان می‌دهد محتوای صفحه را بخواند و مثلاً با کلید H بین headings جابجا شود.
+
+وقتی فوکوس وارد یک ورودی فرم یا ویجت `contenteditable` می‌شود، حالت به **Forms Mode** یا همان **Focus Mode** تغییر می‌کند. در این حالت، مثلاً زدن حرف `H` باعث نوشتن آن حرف در فیلد می‌شود و دیگر به heading بعدی نمی‌رود. screen reader به‌صورت خودکار بر اساس role عنصر بین این دو حالت جابجا می‌شود.
+
+می‌توانید با فرمان `NVDA + Space` (که `NVDA` معمولاً کلید Insert است) به‌صورت دستی بین حالت‌ها جابجا شوید.
+
+## از نقش `role="application"` با احتیاط بسیار استفاده کنید
+
+⚠️ نقش `application` در ARIA کاربر را مستقیماً وارد حالت Focus می‌کند. در استفاده از این role بسیار محتاط باشید، چون در اصل بسیاری از فرمان‌های screen reader در Windows را غیرفعال کرده و keystrokeها را مستقیماً به مرورگر می‌فرستید.
+
+قبل از استفاده از این ویژگی، حتماً با کاربرانی که دائماً از screen reader استفاده می‌کنند تست انجام دهید. اشتباه در استفاده از آن بسیار آسان است و تجربه را به‌شدت می‌تواند خراب کند.
+
+مطالعه بیشتر از Marco Zehe:  
+https://www.marcozehe.de/if-you-use-the-wai-aria-role-application-please-do-so-wisely/

topics/accessible-naming-screen-readers/ARIA-accessible-name-computation.md

@@ -0,0 +1,26 @@
+# تست راهکارهای ARIA
+
+اشتباه در استفاده از ARIA بسیار رایج است، چون اکثر توسعه‌دهندگان استفاده از ویژگی‌ها را ساده‌تر از تست کردن آن‌ها می‌دانند. نباید آن‌قدر به تیم QA وابسته بود که انتظار داشته باشیم آن‌ها موارد خاص ARIA را بررسی کنند (حتی اگر تیم QA داشته باشید)، چون چرخه بازخورد در این حالت _بسیار غیرضروری و طولانی_ خواهد شد. به همین دلایل، تست کردن راهکارهای خودتان در مراحل اولیه و به‌صورت مکرر ضروری است.
+
+در ادامه چند نکته برای تست یک راهکار ARIA (پس از اینکه تمام گزینه‌های پیش‌فرض HTML را امتحان کرده‌اید):
+
+1. آمار سایت خود را با نتایج نظرسنجی [WebAIM درباره screen readerها](https://webaim.org/projects/screenreadersurvey9/) مقایسه کنید تا بدانید کاربران از چه ترکیب‌هایی از screen reader و مرورگر استفاده می‌کنند. این کار به اولویت‌بندی شما کمک می‌کند.
+
+همچنین می‌توانید به منابع زیر مراجعه کنید:
+
+3. بررسی [A11ySupport.io](https://a11ysupport.io) برای پشتیبانی از ویژگی‌های خاص.  
+4. راهنماهای ARIA Authoring Practices ممکن است پیشنهادهایی داشته باشند، اگرچه معمولاً برای استفاده در محیط production آماده نیستند.  
+5. بررسی issue tracker‌های ریپوی پروژه‌های مهم مانند: [NVDA](https://github.com/nvaccess/nvda)، [WAI-ARIA](https://github.com/w3c/aria)، [WCAG](https://github.com/w3c/wcag)، [WebKit و Safari](https://bugs.webkit.org/)، و دیگر موارد.  
+   - همچنین می‌توانید آرشیو گفت‌وگوهای [لیست ایمیل WebAIM](https://webaim.org/discussion/archives) را بررسی کنید یا در صورت نیاز، پرسش جدیدی مطرح نمایید.
+
+## به یاد داشته باشید: screen reader تنها بخشی از accessibility است
+
+توسعه‌دهندگان معمولاً سعی می‌کنند مسائل را با استفاده از ویژگی‌ها و نشانه‌گذاری‌ها حل کنند — که تأثیر آن عمدتاً متوجه کاربران screen reader است. اما فراموش نکنید که screen reader تنها یکی از بخش‌های accessibility است. باید به پشتیبانی از کیبورد، کنتراست بصری، reflow و zoom، و حتی ناوبری صوتی (که وابسته به HTML معنایی است) نیز توجه داشته باشید.
+
+لینک‌های پرش (skip links) نمونه خوبی هستند:
+
+> «چرا لینک‌های پرش باید قابل مشاهده باشند وقتی فقط برای کاربران screen reader هستند؟»
+
+در واقع، skip links برای همه کاربران کیبورد هستند. بسیاری از افراد باید آن‌ها را ببینند، و همچنین باید در screen reader هم قابل استفاده باشند.
+
+بخش‌های مختلفی از accessibility وجود دارد که باید هم‌زمان با سایر دغدغه‌های توسعه وب به آن‌ها رسیدگی کرد. بنابراین هنگام اولویت‌بندی وظایف با اندازه‌ها و پیچیدگی‌های متفاوت، گروه‌های متنوع کاربران و تأثیر مسائل بر accessibility را مد نظر داشته باشید.

topics/accessible-naming-screen-readers/screen-reader-commands-interaction-modes.md

@@ -0,0 +1,34 @@
+# درخت Accessibility
+
+Accessibility Tree ساختاری موازی با DOM است که توسط [APIهای دسترسی پلتفرم‌ها](https://www.smashingmagazine.com/2015/03/web-accessibility-with-accessibility-api/) و مرورگرهای وب ایجاد می‌شود تا اطلاعات مربوط به accessibility را به Assistive Technology (AT) منتقل کند. این ساختار تحت تأثیر HTML، ARIA و گاهی CSS قرار می‌گیرد. زمانی که تغییری در درخت ایجاد شود، مرورگر رویدادهایی را به AT ارسال می‌کند که بخش‌هایی از درخت به‌روزرسانی شده‌اند.
+
+این درخت، ساختاری را در اختیار AT قرار می‌دهد که عناصر غیرضروری مانند `style` و `script` و دیگر موارد حذف شده‌اند. APIهای دسترسی در macOS، iOS، Windows و سایر پلتفرم‌ها، نسخه‌های خاص خود از این درخت را ایجاد می‌کنند، به این معنا که نقش‌ها (roles) و سایر مشخصات ممکن است کمی متفاوت باشند.
+
+<figure className="my-6">
+    <img src="/geckoflow-ax-tree.png" alt="The Accessibility Tree flow in Firefox (Gecko)" />
+</figure>
+
+Accessibility Tree بیشتر در ابزارهایی مانند screen reader کاربرد دارد. (البته screen readerهای امروزی به‌طور هم‌زمان از DOM نیز استفاده می‌کنند. مثلاً JAWS برای بهبود تجربه در صفحات فاقد دسترسی مناسب از DOM کمک می‌گیرد.)
+
+## چگونه Accessibility Tree را مشاهده و تست کنیم؟
+
+در حال حاضر ابزارهای بسیار خوبی برای بررسی Accessibility Tree در اختیار داریم! همان ابزار Accessibility در Chrome DevTools که برای بررسی نام‌های قابل دسترس استفاده کردیم، در اینجا نیز کاربرد دارد. همچنین می‌توانید از Safari Developer Tools و Firefox Developer Tools استفاده کنید. یا یک screen reader اجرا کنید!
+
+DevTools مرورگرهای مدرن بسیار مناسب هستند برای اینکه نشان دهند چگونه Accessibility Tree با DOM در ارتباط است. این ابزارها اطلاعاتی مانند نام قابل دسترس، نقش، وضعیت مخفی بودن یا نبودن یک عنصر، یا اینکه آیا اطلاعاتی برای AT فراهم می‌کند یا نه، نمایش می‌دهند.
+
+<figure className="my-6">
+    <img src="/devtools-accessible-name.png" alt="Chrome DevTools Accessibility Inspector on an icon button on StackBlitz" />
+</figure>
+
+## چرا این موضوع اهمیت دارد؟
+
+با یادگیری نحوه عملکرد Accessibility Tree و ارتباط آن با DOM، درک بهتری از ARIA و رابطه‌اش با HTML خواهید داشت.
+
+یکی از سوء‌تفاهم‌های رایج در مورد ARIA، تفاوت میان ویژگی `disabled` در HTML و ویژگی `aria-disabled` برای ورودی‌های فرم و کنترل‌های دیگر است. تنها `disabled` روی focusپذیری و ظاهر عنصر در رابط بصری تأثیر می‌گذارد، در حالی که `aria-disabled` هیچ‌گونه تغییری در ظاهر یا تعامل قابل مشاهده ایجاد نمی‌کند. ویژگی ARIA فقط از طریق Accessibility Tree بر AT اثر می‌گذارد و هیچ تغییری در DOM ایجاد نمی‌کند.
+
+آگاهی از این تفاوت‌ها باعث می‌شود در استفاده از ویژگی‌ها در نشانه‌گذاری HTML خود دقت بیشتری داشته باشید و فرآیند تست نیز برایتان قابل پیش‌بینی‌تر و مؤثرتر خواهد بود.
+
+## لینک‌های مرتبط
+- https://marcysutton.com/accessibility-and-performance#What-impacts-the-accessibility-tree
+- https://www.smashingmagazine.com/2015/03/web-accessibility-with-accessibility-api/
+- https://marcysutton.com/accessibility-and-performance#What-impacts-the-accessibility-tree