diff --git a/project/frontend_guidelines.rst b/project/frontend_guidelines.rst new file mode 100644 index 0000000000000000000000000000000000000000..b5976a02c5cfc26f22e3bd83bbe86dde7c5cf8eb --- /dev/null +++ b/project/frontend_guidelines.rst @@ -0,0 +1,91 @@ +Goals +===== + +- uniform +- accessible +- “beautiful†+- understandable +- concise + +Layout +====== + +- Mobile First development + + - The layout should look best on mobile devices as most users use them. + - Exceptions exist (e.g. timetable creation is desktop only). + +- Show the same information on all screen sizes. +- Don’t overwhelm users with too much information. +- Hover is not accessible for mobile devices, don’t require it. + +Navigation +========== + +- On a detail view, add a possibility to go back to the list view + without using the browser history (most PWAs don’t have browser + navigation). +- Scrolling is better/easier than clicking (→ The fewer clicks the + better). +- Keyboard navigation does need to be tested as well. + + - Use CSS class ``.focusable`` if the focused component has no + built-in focus styles. + +Color +===== + +- Use colors for accents, actions or important info, but only in small + amounts (e.g. no filled cards). +- Never convey information solely by color, as this is not accessible. +- User-defined colors need to be subject to the accessibility datacheck + (see Core). +- Only the primary action on the page (usually one action) should + be primary-colored. +- Destructive actions (deletions, cancellations, etc) should be colored + in the ``error`` color. +- Never use hard-coded colors (e.g. #da1f3d) (exceptions exist). +- (Almost) never use soft-hard-coded colors (e.g. ``orange`` or + ``pink lighten-5``). +- Theme colors are accessible (and can adapt e.g. to a dark mode), so + use them. + +Reusable Frontend +================= + +- DRY (Don’t repeat yourself). +- Try to reuse existing components (like CRUD lists, the generic + buttons, predefined form fields, etc.). +- It is forbidden to use a ``v-btn`` instead of our generic ones. +- Custom CSS: + + - Don’t use custom CSS if possible (use Vuetify helper classes). + - The less absolute values (“magic numbersâ€) and units (rather em, + rem, vh, vw, % in oppose to pixels, cm, inch etc) the better. + +- Use generic colors (see color section). +- Use generic icons where possible, probably everywhere. +- Couple new layouts out into reusable components. + +Make Smart Choices +================== + +- Think about semantics and user experience when making choices. +- Examples: + + - Use semantically correct HTML tags instead of thousands of nested + divs. + - Use correct components for selectable values (switches for bool, + checkboxes for bool or multiple, radio for single choice with + n<=3, selects: probably never, autocomplete: choice with large n). + - Hide unnecessary things for screen readers and keyboard navigation. + +Test Extensively +================ + +- Test frontend changes at least on a phone, a tablet and a desktop + size. +- Try to get an opinion of “normal†users about big UI changes. +- Test usability with keyboard navigation. +- Use the built-in Firefox accessibility checker (it will highlight + probems in keyboard navigation, etc.).