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 addressed
    then use only the display name
    examples: 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 emphasized
    then
    • 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 names
      then only show the given names
    • else if the display name is part of the given names
      then 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:

    1. constructive

      • SHOULD be dark blue (btn-primary)

      • the icon SHOULD be a checkmark

      • least one of both MUST be true

    2. rather destructive (e.g. archiving of event)

      • MUST be red (btn-danger)

    3. reference-destructive

      • SHOULD be reversible using the logs

      • MUST be red (btn-danger)

      • SHOULD have the minus icon

    4. 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:

    1. going higher (backwards)

      • SHOULD be light white (btn-default)

      • SHOULD have

        • fa-times icon (cancel = form reset)

        • chevron-left icon

    2. keeping page (e.g. Download buttons) or going to similar page

      • including dynamic changes to selected items

      • SHOULD be white (btn-default)

    3. 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)

    4. 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