mirror of
https://codeberg.org/forgejo/forgejo.git
synced 2024-11-26 06:52:45 +00:00
Improve frontend guidelines (#23007)
Some were out-dated, some are added.
This commit is contained in:
parent
dc9cebdf45
commit
e7be610d57
|
@ -39,12 +39,20 @@ We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/h
|
||||||
### Gitea specific guidelines:
|
### Gitea specific guidelines:
|
||||||
|
|
||||||
1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
|
1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
|
||||||
2. HTML ids and classes should use kebab-case.
|
2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords.
|
||||||
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
|
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
|
||||||
4. jQuery events across different features could use their own namespaces if there are potential conflicts.
|
4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful.
|
||||||
5. CSS styling for classes provided by frameworks should not be overwritten. Always use new class-names with 2-3 feature related keywords to overwrite framework styles.
|
5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data.
|
||||||
6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`
|
6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
|
||||||
7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
|
7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`.
|
||||||
|
8. Use semantic elements, prefer `<button class="ui button">` instead of `<div class="ui button">`.
|
||||||
|
9. Avoid unnecessary `!important` in CSS, add comments to explain why it's necessary if it can't be avoided.
|
||||||
|
|
||||||
|
### Accessibility / ARIA
|
||||||
|
|
||||||
|
In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework.
|
||||||
|
Gitea uses some patches to make Fomantic UI more accessible (see the `aria.js` and `aria.md`),
|
||||||
|
but there are still many problems which need a lot of work and time to fix.
|
||||||
|
|
||||||
### Framework Usage
|
### Framework Usage
|
||||||
|
|
||||||
|
|
|
@ -1,8 +1,35 @@
|
||||||
**This document is used as aria/a11y reference for future developers**
|
**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
|
## ARIA Dropdown
|
||||||
|
|
||||||
There are different solutions:
|
There are different solutions:
|
||||||
* combobox + listbox + option
|
* combobox + listbox + option
|
||||||
* menu + menuitem
|
* 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 -->
|
<div class="ui dropdown"> <!-- focused here, then it's not perfect to use aria-activedescendant to point to the menu item -->
|
||||||
<input type="hidden" ...>
|
<input type="hidden" ...>
|
||||||
<div class="text">Default</div>
|
<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 active selected">Default</div>
|
||||||
<div class="item">...</div>
|
<div class="item">...</div>
|
||||||
</div>
|
</div>
|
||||||
|
@ -38,7 +65,7 @@ At the moment, `menu + menuitem` seems to work better with Fomantic UI Dropdown,
|
||||||
<input type="hidden" ...>
|
<input type="hidden" ...>
|
||||||
<input class="search" autocomplete="off" tabindex="0"> <!-- focused here -->
|
<input class="search" autocomplete="off" tabindex="0"> <!-- focused here -->
|
||||||
<div class="text"></div>
|
<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 selected">...</div>
|
||||||
<div class="item">...</div>
|
<div class="item">...</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
Loading…
Reference in a new issue