User Experience Conventions¶
Todo
Add information on notification type semantics
Given Names & Display Name¶
For each person, the CdEDB allows to store two different forename fields: given_names
and display_name
(“Known as”, german: “Rufname”).
The former is meant to contain the person’s “official” forename(s), whereas the display_name
should be used to give the name, how the person wants to be called by others.
This may be the full given names, only a part of the given names or a completely different nickname.
Due to these possibilities, it is not trivial, where/when to use which of these two fields.
The following shall give a guideline on this topic, based on our discussion on Issue #2005.
To apply this logic in the web template and frontend code, there is the cdedb.frontend.common.make_persona_name()
helper function resp. the persona_name()
macro in the util.tmpl
template.
- if a person is addressed in a legal context (including postal addresses)then use only the given names: “{given_names} {family_name}”examples: letter address fields, assembly attendee list→
util.persona_name(persona, only_given_names=True)
- else if a user is directly addressedthen use only the display nameexamples: salutation in a event participation letter, login info in the main navigation bar→
util.persona_name(persona, only_display_name=True, with_family_name=False)
- else if a person’s name is presented to other users and the display name shall be emphasizedthen
- if the display name is part of the given names (or equal)then only show the display name
- else show the display name and the given names (typically: “{display_name}\n{given_names} {family_name}”)
example: paper nametags for events
- else if a person’s name is presented to other users and we explicitly want to display all their names (as on a business card)then
- if the display name is equal to the given namesthen only show the given names
- else if the display name is part of the given namesthen only show the given names, but emphasise the display name within the given names (e.g. via italic font)
- else show the given names and the display name in parentheses: “{given_names} ({display_name”}) {family_name}”
example: user profile page, orga realm (if not in lists)→util.persona_name(persona, given_and_display_names=True, with_titles=True)
- else
- if the display name is part of the given names (or equal)then only show the display name
- else only show the given names
example: event participation lists, email “To” headers, mailinglist subscriber lists→util.persona_name(persona)
Buttons¶
The styling of our buttons follows the semantics of the button. This should make it more predictable what a given button does, without the use of overlong titles.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, and “MAY” in this document follow the conventions of [RFC2119].
Colours & Icons¶
- effective actions
“have a persistent effect”
are divided into four subtypes:
- constructive
SHOULD be dark blue (btn-primary)
the icon SHOULD be a checkmark
least one of both MUST be true
- rather destructive (e.g. archiving of event)
MUST be red (btn-danger)
- reference-destructive
SHOULD be reversible using the logs
MUST be red (btn-danger)
SHOULD have the minus icon
- really destructive (deletes data)
MUST be red (btn-danger)
SHOULD have the trash-alt or fire icon (“fire” escalation of “trash”, deletes “larger” entities)
- progressive actions
“lead to a page to make a persistent effect”
if something will be edited
SHOULD be yellow/orange (btn-warning)
if something is created
SHOULD be green (btn-success)
if button submits information to the next step in a wizard
SHOULD be dark blue (btn-primary)
SHOULD have the icon “chevron-right”
exception: when submitting a search form
SHOULD be dark blue (btn-primary)
SHOULD have the search icon
- non actions (links)
“have no effect”
are dived into three subtypes:
- going higher (backwards)
SHOULD be light white (btn-default)
SHOULD have
fa-times icon (cancel = form reset)
chevron-left icon
- keeping page (e.g. Download buttons) or going to similar page
including dynamic changes to selected items
SHOULD be white (btn-default)
- going to similar page, while considering form inputs on local page (e.g. link to filtered list by selection)
SHOULD be light blue (btn-info)
- going deeper (forwards)
including links to documentation
SHOULD be light blue (btn-info)
MAY be dark blue if icon indicated read only (e.g. Show vote button upon secret entering)
Button Sizes¶
Buttons in the “action toolbar” below the heading MUST be btn-sm
Buttons in “inline forms” SHOULD be btn-sm
right-floated Buttons in lists SHOULD be btn-xs
other Buttons should be normal-sized