From e7be610d5773e69abbfb98d19e23112dfad6dfcc Mon Sep 17 00:00:00 2001
From: wxiaoguang <wxiaoguang@gmail.com>
Date: Tue, 21 Feb 2023 14:13:37 +0800
Subject: Improve frontend guidelines (#23007)

Some were out-dated, some are added.
---
 web_src/js/features/aria.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

(limited to 'web_src/js')

diff --git a/web_src/js/features/aria.md b/web_src/js/features/aria.md
index ecd25ddb30..a55344de47 100644
--- a/web_src/js/features/aria.md
+++ b/web_src/js/features/aria.md
@@ -1,8 +1,35 @@
 **This document is used as aria/a11y reference for future developers**
 
+# Checkbox
+
+## Accessibility-friendly Checkbox
+
+The ideal checkboxes should be:
+
+```html
+<label><input type="checkbox"> ... </label>
+```
+
+However, related styles aren't supported (not implemented) yet, so at the moment, almost all the checkboxes are still using Fomantic UI checkbox.
+
+## Fomantic UI Checkbox
+
+```html
+<div class="ui checkbox">
+  <input type="checkbox"> <!-- class "hidden" will be added by $.checkbox() -->
+  <label>...</label>
+</div>
+```
+
+Then the JS `$.checkbox()` should be called to make it work with keyboard and label-clicking, then it works like the ideal checkboxes.
+
+There is still a problem: Fomantic UI checkbox is not friendly to screen readers, so we add IDs to all the Fomantic UI checkboxes automatically by JS.
+
+# Dropdown
+
 ## ARIA Dropdown
 
-There are different solutions: 
+There are different solutions:
 * combobox + listbox + option
 * menu + menuitem
 
@@ -27,7 +54,7 @@ At the moment, `menu + menuitem` seems to work better with Fomantic UI Dropdown,
 <div class="ui dropdown"> <!-- focused here, then it's not perfect to use aria-activedescendant to point to the menu item -->
   <input type="hidden" ...>
   <div class="text">Default</div>
-  <div class="menu transition hidden" tabindex="-1">
+  <div class="menu" tabindex="-1"> <!-- "transition hidden|visible" classes will be added by $.dropdown() and when the dropdown is working -->
     <div class="item active selected">Default</div>
     <div class="item">...</div>
   </div>
@@ -38,7 +65,7 @@ At the moment, `menu + menuitem` seems to work better with Fomantic UI Dropdown,
   <input type="hidden" ...>
   <input class="search" autocomplete="off" tabindex="0"> <!-- focused here -->
   <div class="text"></div>
-  <div class="menu transition visible" tabindex="-1">
+  <div class="menu" tabindex="-1"> <!-- "transition hidden|visible" classes will be added by $.dropdown() and when the dropdown is working -->
     <div class="item selected">...</div>
     <div class="item">...</div>
   </div>
-- 
cgit v1.2.3