refactor(a11y): comprehensive WCAG 2.2 AA accessibility improvements (#924)

* refactor(a11y): comprehensive WCAG 2.2 AA accessibility improvements

Add skip-to-content link, landmark regions, ARIA attributes, keyboard
navigation, focus styles, reduced-motion support, and i18n keys across
all layouts, partials, shortcodes, and JS components.

- Add skip nav link in baseof.html and id="content" on all <main> tags
- Fix 404 page lang/dir attributes and add <main> landmark
- Add aria-label to banner close, PDF iframe, search input/results
- Remove aria-hidden from back-to-top button
- Add aria-hidden to decorative external link icon
- Add role="tablist" to tabs, aria-expanded to filetree/dropdowns
- Wrap mermaid diagrams in role="img", asciinema in role="region"
- Change theme toggle <p> items to <button role="menuitem"> with
  full keyboard navigation (Arrow/Home/End/Escape)
- Add arrow-key keyboard navigation to tabs component
- Separate sidebar collapsible button from link for independent
  keyboard access with aria-expanded sync
- Sync aria-expanded on all dropdown toggles (theme, lang, navbar,
  hamburger, page context menu)
- Add aria-live search status announcements
- Add 13 new i18n keys, replace hardcoded aria-label strings
- Add prefers-reduced-motion CSS override and focus-visible base styles
- Add aria-label swap on code copy ("Copied!" feedback for AT)
- Add aria-current to active TOC links
- Wrap filetree in <ul> container for proper list semantics
- Add unique aria-label to blog "Read more" links
- Document accessibility guidelines in AGENTS.md

* feat(a11y): enhance focus styles and accessibility for various components

- Add focus-visible styles to badges, buttons, and links for improved keyboard navigation.
- Update breadcrumb, sidebar, and TOC components to include focus-visible outlines.
- Introduce new classes for focus states in the badge and tabs shortcodes.
- Ensure consistent focus styles across all interactive elements to meet WCAG 2.2 AA standards.

* feat(a11y): implement new focus-visible utilities and enhance accessibility styles

- Introduce new utility classes for focus-visible states to improve keyboard navigation.
- Update various components including badges, buttons, and search inputs to utilize new focus-visible styles.
- Refactor existing focus styles to ensure consistency and compliance with accessibility standards.
- Enhance breadcrumb, sidebar, and TOC components with updated focus-visible classes for better user experience.

* chore: add .gitattributes to collapse generated files in PR diffs

* fix: enhance accessibility and improve documentation

- Added alt attributes to images in multiple language documentation files for better accessibility.
- Updated the navbar title partial to remove unnecessary title attribute.
- Improved search input accessibility by adding autocomplete="off".
- Enhanced search partials in both navbar and sidebar with location context.
- Updated SVG icons in various components to include aria-hidden and focusable attributes for improved accessibility compliance.

* fix: improve giscus theme toggle functionality

- Updated the theme toggle options selector to use a data attribute for better specificity.
- Modified the event listener to use a setTimeout for the theme update, ensuring smoother transitions when the theme switcher is clicked.

* fix: resolve axe-core WCAG AA violations across docs pages

Add aria-labels to Hugo task list checkboxes, fix asciinema player
timer accessible names, make Jupyter output cells keyboard-focusable,
and add missing heading hierarchy in shortcodes docs for fa/ja/zh-cn.

* feat: integrate accessibility testing with Playwright and enhance CI workflow

- Added Playwright configuration for accessibility testing.
- Implemented accessibility tests using axe-core for all English pages.
- Created a GitHub Actions workflow to automate accessibility tests on pull requests.
- Updated package dependencies to include @axe-core/playwright and @playwright/test.
- Enhanced sidebar component with data attributes for improved accessibility styling.

* fix: update base URL and improve accessibility labels across multiple languages

- Changed the base URL in Playwright configuration and CI workflow from localhost:3000 to localhost:1313.
- Added accessibility labels for screen readers in various language files, enhancing user experience for visually impaired users.
- Updated the Asciinema script to dynamically set the playback time label for better accessibility compliance.

* refactor: reorganize accessibility tests and update test directory structure

- Moved accessibility tests from the e2e directory to a new tests directory for better organization.
- Updated the test directory path in Playwright configuration.
- Refactored the accessibility test implementation to improve code clarity and maintainability.

* chore: update .gitignore to include Playwright test output directories

- Added entries for 'playwright-report/' and 'test-results/' to the .gitignore file to prevent cluttering the repository with test artifacts.

* refactor: enhance accessibility and improve focus styles across components

- Removed unused utility for focus visibility in CSS and consolidated focus-visible styles for better maintainability.
- Updated various components to use `role` attributes for improved accessibility, including menu items and buttons.
- Enhanced theme toggle and language switch components with appropriate ARIA roles and attributes for better screen reader support.
- Improved the handling of focus states in the navigation and context menus to ensure a consistent user experience.

* chore: update dependencies and enhance accessibility features

- Updated the 'serve' package version in package.json and package-lock.json for improved performance.
- Removed unused 'xml2js' dependency to streamline the project.
- Enhanced the Playwright configuration to better manage the web server setup for testing.
- Improved accessibility in the language switcher and navigation menu by refining focus management and keyboard interactions.
- Updated the back-to-top button to manage tabindex for better accessibility compliance.

* feat: enhance mobile menu accessibility and keyboard interactions

- Added ARIA attributes to manage visibility of the sidebar on mobile devices.
- Implemented focus management for the sidebar when the menu is toggled.
- Introduced keyboard support to close the menu with the Escape key.
- Improved overall accessibility for the hamburger menu and sidebar interactions.

* fix: refine mobile menu keyboard interaction and enhance navbar accessibility

- Updated the Escape key functionality to close the menu only on mobile devices.
- Added a new ARIA attribute to the hamburger menu button for improved accessibility.

docs/content/docs/getting-started.fa.md

@@ -14,7 +14,7 @@ prev: /docs
 
 می‌توانید با استفاده از مخزن قالب فوق به سرعت شروع به کار کنید.
 
-<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
+<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="صفحه مخزن GitHub که دکمه Use this template را نشان می‌دهد">
 
 ما یک [گردش کار GitHub Actions](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) ارائه کرده‌ایم که می‌تواند به صورت خودکار سایت شما را ساخته و در GitHub Pages مستقر کند و به صورت رایگان میزبانی کند.
 برای گزینه‌های بیشتر، [استقرار سایت](../guide/deploy-site) را بررسی کنید.
@@ -201,4 +201,4 @@ git submodule update --remote themes/hextra
   {{< card link="../guide/organize-files" title="سازماندهی فایل‌ها" icon="document-duplicate" >}}
   {{< card link="../guide/configuration" title="پیکربندی" icon="adjustments" >}}
   {{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
-{{< /cards >}}
+{{< /cards >}}

docs/content/docs/getting-started.ja.md

@@ -14,7 +14,7 @@ prev: /docs
 
 上記のテンプレートリポジトリを使用して、すぐに始めることができます。
 
-<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
+<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="Use this template ボタンが表示された GitHub リポジトリページ">
 
 [GitHub Actions ワークフロー](https://docs.github.com/ja/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)を提供しており、サイトを自動的にビルドして GitHub Pages にデプロイし、無料でホストすることができます。
 その他のオプションについては、[サイトのデプロイ](../guide/deploy-site)を確認してください。
@@ -201,4 +201,4 @@ git submodule update --remote themes/hextra
   {{< card link="../guide/organize-files" title="ファイルの整理" icon="document-duplicate" >}}
   {{< card link="../guide/configuration" title="設定" icon="adjustments" >}}
   {{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
-{{< /cards >}}
+{{< /cards >}}

docs/content/docs/getting-started.md

@@ -14,7 +14,7 @@ prev: /docs
 
 You could quickly get started by using the above template repository.
 
-<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
+<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="GitHub repository page showing the Use this template button">
 
 We have provided a [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) which can help automatically build and deploy your site to GitHub Pages, and host it for free.
 For more options, check out [Deploy Site](../guide/deploy-site).

docs/content/docs/getting-started.zh-cn.md

@@ -14,7 +14,7 @@ prev: /docs
 
 您可以通过使用上述模板仓库快速开始。
 
-<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500">
+<img src="https://docs.github.com/assets/cb-77734/mw-1440/images/help/repository/use-this-template-button.webp" width="500" alt="显示“Use this template”按钮的 GitHub 仓库页面">
 
 我们提供了一个[GitHub Actions工作流](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)，可以帮助自动构建并将您的站点部署到GitHub Pages，并免费托管。
 更多选项，请查看[部署站点](../guide/deploy-site)。
@@ -201,4 +201,4 @@ git submodule update --remote themes/hextra
   {{< card link="../guide/organize-files" title="组织文件" icon="document-duplicate" >}}
   {{< card link="../guide/configuration" title="配置" icon="adjustments" >}}
   {{< card link="../guide/markdown" title="Markdown" icon="markdown" >}}
-{{< /cards >}}
+{{< /cards >}}

docs/content/docs/guide/shortcodes/others.fa.md

@@ -9,6 +9,8 @@ next: /docs/guide/deploy-site
   این شورتکدها کمتر پایدار در نظر گرفته می‌شوند و ممکن است هر زمان تغییر کنند.
 {{< /callout >}}
 
+## نشان
+
 ### أمثلة
 
 {{< badge "default" >}}&nbsp;
@@ -124,4 +126,4 @@ next: /docs/guide/deploy-site
 
 مثال:
 
-{{< pdf "https://upload.wikimedia.org/wikipedia/commons/1/13/Example.pdf" >}}
+{{< pdf "https://upload.wikimedia.org/wikipedia/commons/1/13/Example.pdf" >}}

docs/content/docs/guide/shortcodes/others.ja.md

@@ -9,6 +9,8 @@ next: /docs/guide/deploy-site
   これらのショートコードは安定性が低く、いつでも変更される可能性があります。
 {{< /callout >}}
 
+## バッジ
+
 ### 例
 
 {{< badge "default" >}}&nbsp;
@@ -124,4 +126,4 @@ PDF ショートコードを使用すると、コンテンツ内に PDF ファ
 
 例:
 
-{{< pdf "https://upload.wikimedia.org/wikipedia/commons/1/13/Example.pdf" >}}
+{{< pdf "https://upload.wikimedia.org/wikipedia/commons/1/13/Example.pdf" >}}

docs/content/docs/guide/shortcodes/others.zh-cn.md

@@ -9,6 +9,8 @@ next: /docs/guide/deploy-site
   这些短代码稳定性较低，可能随时变更。
 {{< /callout >}}
 
+## 徽章
+
 ### 示例
 
 {{< badge "default" >}}&nbsp;
@@ -124,4 +126,4 @@ next: /docs/guide/deploy-site
 
 示例：
 
-{{< pdf "https://upload.wikimedia.org/wikipedia/commons/1/13/Example.pdf" >}}
+{{< pdf "https://upload.wikimedia.org/wikipedia/commons/1/13/Example.pdf" >}}

docs/hugo_stats.json

@@ -30,6 +30,7 @@
       "h5",
       "h6",
       "head",
+      "header",
       "hr",
       "html",
       "iframe",
@@ -147,10 +148,13 @@
       "hextra-scrollbar",
       "hextra-search-input",
       "hextra-search-results",
+      "hextra-search-status",
       "hextra-search-wrapper",
       "hextra-sidebar-active-item",
+      "hextra-sidebar-children",
       "hextra-sidebar-collapsible-button",
       "hextra-sidebar-container",
+      "hextra-sidebar-item",
       "hextra-steps",
       "hextra-success-icon",
       "hextra-tabs-panel",
@@ -160,10 +164,12 @@
       "hextra-toc",
       "hide-tail",
       "highlight",
+      "hover:hx:no-underline",
       "hx:-mb-0.5",
       "hx:-ml-2",
       "hx:-mr-2",
       "hx:-mt-20",
+      "hx:-translate-y-1/2",
       "hx:absolute",
       "hx:active:bg-gray-400/20",
       "hx:active:opacity-50",
@@ -212,6 +218,7 @@
       "hx:bg-yellow-50",
       "hx:block",
       "hx:border",
+      "hx:border-0",
       "hx:border-amber-200",
       "hx:border-b",
       "hx:border-b-2",
@@ -294,9 +301,9 @@
       "hx:dark:border-white/10",
       "hx:dark:border-yellow-200/30",
       "hx:dark:contrast-more:border-neutral-400",
-      "hx:dark:focus:bg-dark",
-      "hx:dark:focus:ring-primary-800",
+      "hx:dark:focus-visible:bg-dark",
       "hx:dark:from-gray-100",
+      "hx:dark:group-hover:text-gray-50",
       "hx:dark:hidden",
       "hx:dark:hover:bg-gray-100/5",
       "hx:dark:hover:bg-neutral-700",
@@ -358,11 +365,19 @@
       "hx:flex",
       "hx:flex-col",
       "hx:flex-wrap",
-      "hx:focus:bg-white",
-      "hx:focus:hextra-focus",
-      "hx:focus:outline-hidden",
-      "hx:focus:ring-4",
-      "hx:focus:ring-primary-300",
+      "hx:focus-visible:bg-primary-500",
+      "hx:focus-visible:bg-white",
+      "hx:focus-visible:fixed",
+      "hx:focus-visible:font-medium",
+      "hx:focus-visible:left-2",
+      "hx:focus-visible:not-sr-only",
+      "hx:focus-visible:px-4",
+      "hx:focus-visible:py-2",
+      "hx:focus-visible:rounded-md",
+      "hx:focus-visible:text-sm",
+      "hx:focus-visible:text-white",
+      "hx:focus-visible:top-2",
+      "hx:focus-visible:z-50",
       "hx:font-bold",
       "hx:font-extrabold",
       "hx:font-medium",
@@ -383,10 +398,13 @@
       "hx:group",
       "hx:group-[.copied]/copybtn:block",
       "hx:group-[.copied]/copybtn:hidden",
+      "hx:group-data-[active=true]:dark:text-primary-600",
+      "hx:group-data-[active=true]:text-primary-800",
       "hx:group-data-[theme=dark]:hidden",
       "hx:group-data-[theme=light]:hidden",
       "hx:group-data-[theme=system]:hidden",
       "hx:group-hover/code:opacity-100",
+      "hx:group-hover:text-gray-900",
       "hx:group-hover:underline",
       "hx:group-open:before:rotate-90",
       "hx:group/code",
@@ -403,6 +421,8 @@
       "hx:h-[18px]",
       "hx:h-full",
       "hx:h-px",
+      "hx:hextra-focus-visible",
+      "hx:hextra-focus-visible-inset",
       "hx:hidden",
       "hx:hover:bg-gray-100",
       "hx:hover:bg-gray-800/5",
@@ -462,13 +482,17 @@
       "hx:ltr:pl-5",
       "hx:ltr:pl-6",
       "hx:ltr:pl-8",
-      "hx:ltr:pr-0",
+      "hx:ltr:pr-1",
       "hx:ltr:pr-2",
       "hx:ltr:pr-4",
+      "hx:ltr:pr-8",
       "hx:ltr:pr-9",
       "hx:ltr:right-1.5",
+      "hx:ltr:right-2",
       "hx:ltr:right-3",
       "hx:ltr:rotate-180",
+      "hx:ltr:rounded-l-lg",
+      "hx:ltr:rounded-r-lg",
       "hx:ltr:text-right",
       "hx:m-[11px]",
       "hx:max-h-(--menu-height)",
@@ -554,6 +578,7 @@
       "hx:overflow-y-hidden",
       "hx:overscroll-contain",
       "hx:overscroll-x-contain",
+      "hx:p-0",
       "hx:p-0.5",
       "hx:p-1",
       "hx:p-1.5",
@@ -608,14 +633,17 @@
       "hx:rtl:before:rotate-180",
       "hx:rtl:border-r",
       "hx:rtl:left-1.5",
+      "hx:rtl:left-2",
       "hx:rtl:left-3",
       "hx:rtl:md:right-auto",
       "hx:rtl:ml-auto",
       "hx:rtl:mr-1",
       "hx:rtl:mr-3",
       "hx:rtl:mr-auto",
+      "hx:rtl:pl-1",
       "hx:rtl:pl-2",
       "hx:rtl:pl-4",
+      "hx:rtl:pl-8",
       "hx:rtl:pl-9",
       "hx:rtl:pr-12",
       "hx:rtl:pr-16",
@@ -625,6 +653,8 @@
       "hx:rtl:pr-6",
       "hx:rtl:pr-8",
       "hx:rtl:rotate-270",
+      "hx:rtl:rounded-l-lg",
+      "hx:rtl:rounded-r-lg",
       "hx:rtl:text-left",
       "hx:scroll-my-6",
       "hx:scroll-py-6",
@@ -688,6 +718,7 @@
       "hx:text-yellow-900",
       "hx:to-gray-600",
       "hx:top-0",
+      "hx:top-1/2",
       "hx:top-16",
       "hx:top-8",
       "hx:top-[40%]",