Client design guidelines¶
This document lays out a set of guidelines for designing Modern XMPP clients. For contributions, please open an issue or pull request at Github for discussion.
At initial startup, a client should present a welcome screen, to prompt the user for their JID, and a password. Optionally, a button or link to provide other forms of credentials may be included.
If the client has an out-of-band configuration mechanism, or it can query the OS for sensible defaults, it may use these.
List recommended configuration options.
|JID||The user's JID|
|Password||The user's password|
Support for these options is OPTIONAL. If included in the client, they MUST NOT be requested by default at startup, but should be accessible through an advanced options interface.
|Connect host||The network hostname to connect to|
|Connect port||The network port to connect to|
|TLS Mode2||Multiple choice: "STARTTLS" or "Direct TLS"|
Support for these options is NOT RECOMMENDED.
|Resource||The resource to request from the server||see Resource generation|
|Priority||The priority to include in presence||0|
The client, by default, MUST NOT include any status messages in its presence, unless they are chosen by the user. Built-in status messages that convey the same meaning as the user's selected 'show' value (e.g. "Available", "Do not disturb") are not allowed.
Allowing the user to set a status message is an OPTIONAL feature.
In its interface, the client MUST NOT use the technical term "roster", but MUST instead use the term "contact list" (or a suitable translation) where necessary. See the main "Terminology" section for more information.
The client MUST display offline contacts by default, and allow sending messages to them, as for online contacts..
Sorting of contact list¶
The client MUST sort the contact list. Either in lexicographical order by contact name or chronologically by the time of the last message exchanged with that contact.
Historically, some clients have sorted by presence (available, offline, busy, etc.) as a secondary sorting category. Due to the rise in mobile clients which always consider themselves "available", presence is not always a reliable indicator that a contact is available to chat.
If sorting chronologically and/or by presence, clients MUST NOT rearrange the contacts list while fetching history, or when the contact list has focus. The definition of "focus" depends on the context, but may be the cursor hovering over the list, the list pane being visible, or the list being selected in a screen reader or during tab selection.
The client MUST display status messages of contacts when present. It MAY also provide visual indication of the contact's status ('show'), but SHOULD NOT rely on color alone to distinguish different status values1.
Describe how to display multiple remote resources.
A client must be able to unambiguously display the following outgoing message states:
- Message pending delivery
- Message delivered to server
- Message delivered to contact
- Message read by contact
- Delivery error for message
Add table or flowchart
Carbons, notifications for new messages in MAM
Obey error types (modify, cancel, wait, etc.)
Do display error text
Support for multiple accounts is OPTIONAL.
Research recommendations for the best way to handle multiple accounts. E.g. merge contacts, or not. Not required. Describe how to display multiple accounts in a single client?
You can find more details about group chats here.
Clients should have documentation covering essential functionality, including:
List of recommended documentation topics, e.g. how to add a contact
Clients must not reveal full JID. Don't query unsubscribed contacts.
Probably belongs in protocol reference. Probably some things relevant to UI that should be mentioned, however.
When displaying messages received from a remote JID, either within a one-to-one or multi-user chat, clients need to show a human-readable name for that sender.
There are multiple sources for such a display name, which depend on the context (e.g. whether the conversation is one-to-one or a group chat).
Valid sources are:
- If the contact is in the user's roster, and the user has set a custom name.
- Address book
- Platform-dependent. If the application is somehow linked to the user's address book and is able to access a contact's information there.
- User nickname
- A nickname published by the sender in PEP per XEP-0172.
- The resource of the sending JID.
- Local part
- The part of a bare JID before the '@' symbol.
- Bare JID
- The sending JID with any resource removed.
The kind of view where a name is displayed decides which sources should be used. Since most sources are optional, they should be checked in the order described by the table below, displaying the first one available.
|View type||Name priorities|
|Conversation - normal||Roster name, (Address book), User nickname, Local part|
|Conversation - group||Roster name, (Address book), User nickname, Resource (*)|
|Conversation - channel||Resource|
|Contact list||Roster name, User nickname, Bare JID|
|User profile||Roster name, User nickname, Bare JID|
(*) Mentions refer to resource. if you do proper references you can live replace it with the 'nice' name.
Avatar display should follow the same order
A client may want to associate a color with a user. Example use cases for this include, but are not limited to:
- Dummy avatars in contexts where an avatar cannot be or has not yet been retrieved
- Coloring the user name in a conversation log (be aware that this needs to be done very carefully to be accessible!)
To generate a color for a user, the algorithm described in XEP-0392 MUST be used.
Generator input based on context¶
The generator described in XEP-0392 needs a text input to operate and for which a deterministic color will be generated.
The following table lists which strings to use as input for the generator:
|View type||Generator Input|
|Conversation - normal||Normalised Bare JID|
|Conversation - group||Normalised Bare JID|
|Conversation - channel||Resource|
|Contact list||Normalised Bare JID|
|User profile||Normalised Bare JID|
Contrast ratio considerations¶
To provide a good contrast ratio for accessibility of the resulting user interface, the guidelines from 1 should be obeyed. XEP-0392 intentionally allows the implementation to pick a saturation and lightness value based on the environment to allow for high contrast.
Contrast considerations apply between the generated color and the background, as well as for text rendered on top of the generated color (for example in a dummy avatar).
Resources for the use of color in interface design:
This is presented as a multiple-choice option. A checkbox labeled e.g. "Direct TLS" may confuse users by implying that the opposite of "Direct TLS" is potentially "No TLS". Security is not an option, and TLS is always used. This option is about what style the server supports. ↩