UI Style Guide

User Interface Style Guide

This is a draft style guide covering the Wesnoth game user interface. For general C coding guidelines, see CodingStandards. There are some typography issues also covered in this guide, but please cross-refer to the Typography Style Guide as well.

The Wesnoth UI (user interface) has a mixed setup. Most of the layout and text is stored in WML files in the 'data/gui/' directory tree, which can be altered without having to recompile the program (press F5 on the title screen to rebuild the cache, but for UI you'll likely have to restart Wesnoth before the changes take effect). Part of it is hard-coded within the game's source code, which means you need to be able to at least read C program code to understand what is going on. Removing existing components from a UI dialog will normally require changes to the C code, as it the C code generally treats missing components as an error.

General Principles

The guiding principle of UI design is to make sure that all windows and icons follow the same style. Buttons and icons are consistent, sliders are always used in the same circumstances for the same reasons, and so on. There are also cases where Wesnoth may deliberately break the theoretical ideal; those are documented here, along with the reasons for doing so.

UI Style Violations

The game currently has a small number of areas where the UI intentionally breaks 'best practice'. The two main ones are the 'Languages' button on the main screen, and the 'Advanced Preferences' tab.

'Languages' should really be stored as a sub-menu under the 'Preferences' button, but instead we put it in the main Wesnoth window to make it easier for non-English speakers to find and change the game's language settings.

'Advanced Preferences' is a scrolling menu with a multi-purpose checkbox which changes its function depending on which advanced preference is selected. This is a coding shortcut to handle a growing number of custom options without having to create the several extra preferences windows that would otherwise be needed.

A minor niggle is that some of the buttons in the Wesnoth main menu ought to be marked with ellipses because they open sub-windows.

Situations

Window Titles

Window titles use title case, which means all words are capitalised except for articles, prepositions, and conjunctions. In the standard UI, window titles are in larger text in a gold colour:(Image to follow) Window titles should be short and declarative, no more than 3-5 words. Do not use a window title for a question.

For example, do not use 'Are You Sure You Want to Delete This File?' as a title. Instead, the title should be 'Delete File', or similar, and the subhead should contain the question.

If the 'window' is a non-interactive progress bar, a window title is not required.

If the window is usually non-interactive, but does have a Cancel button, give it a short title.

Example:

Title: Loading Addons
Subhead: Loading [programmatically generated name of the add-on currently being processed]

Window Subheads

Window subheads usually contain a single sentence, in larger than usual white text. The subhead should tell the user what to do, or ask them a direct question. When giving an instruction, ideally the first word should be 'Choose', 'Select', 'Delete', 'Load', 'Save', 'Confirm' or similar, and if there's a button the user has to click in order to do whatever-it-is, the verb on the button should match the imperative word used in the subhead.

If you are asking the user a question, use a question mark. If you are giving the user an instruction, use an imperative form and end with an colon. If you are giving the user information about what the computer is doing, end with an ellipsis.

Examples:

Title: Language
Subhead: Choose your preferred language:

Title: Load Game
Subhead: Choose the game to load:

Title: Delete Game
Subhead: Do you really want to delete this game?

Title: [None]
Subhead: Loading files and creating cache...

Typography Summary

Within the UI, there are only a handful of special characters needed. Use the correct Unicode symbol for the minus sign − U+2212 (8722) when listing ToD penalties and resistances, and the en dash – U+2013 (8211) when listing weapon damage/strikes values. These corrections are already in progress throughout the game. Other symbols, such as sexed quotation marks are unlikely to be needed anywhere; refer to the Typography Style Guide if necessary. We do not currently plan to use the ellipis character … U+2026 (8230), so three dots continues to remain acceptable for an ellipsis. If you want to use more than three dots, to indicate progress, it would be preferable to use a proper progress bar. Otherwise, start with three dots and add extras one at a time.

Buttons

A button should say what it does with a single verb. The current preferred list of button words is as follows:

• Back
• Cancel
• Delete
• Load
• Next
• Save
• Select
• (more to follow)

Please avoid using 'OK' in favour of a specific word indicating what will happen when the button is clicked.

If clicking a button will open a new window, add an unspaced ellipsis, except on the Wesnoth main menu, where ellipses are never used because it looks untidy.

Tables With Columns

When data is formatted into columns using separate UI components, for example the in-game Statistics Table, then the labels should not have colons. This also applies to the table headings, for example the in-game Status Table.

Tables In Plain Text

Sometimes data is concatenated into text, with one "Label: Value" pair on each line, but for some reason it isn't formatted into a table with columns. The label should be in sentence case, unless the label's string is itself data (a terrain type name, damage type, etc).

For translation, the label should include the colon, but ideally not the whitespace.

_("Weapon range:")
_("Damage type:")

Alternatively, make the entire line one string using interpolation. This is preferred when the value should include a measurement unit or a percentage sign:

_("Required XP: $xp")
_("Chance to hit: $chance|%")
_("Reward: $amount| gold")

Sliders

A slider should include a text label on the left describing the value it contains, followed by a colon. The label should be in sentence case. On the right, the current numeric slider value should be given, with units, if any. The labels and the values should be left-aligned; the sliders should all be vertically aligned with one another. The existing UI widgets library already handles the alignment issues for you. Use the floating tooltip function to explain what the slider is for, the units, and the maximum, minimum and default permissible values. Where the function of the slider is glaringly obvious, you can just provide the minimum, maximum and default values.

Examples:

Players:    ====|========= 3
Map width:  ========|===== 50 hexes
Map height: ======|======= 40 hexes
Hilliness:  ===|========== 40

Checkboxes

Checkbox labels use sentence case. Use the floating tooltip function to explain what the checkbox is for, if it isn't obvious, and the default value. Do not just paraphrase the checkbox label text, instead try to answer the question of what a player actually sees when the option is turned on.

Example:

Do not use:

_X_ Floating labels
Tooltip: Turns on floating labels

Instead use:

_X_ Floating labels
Tooltip: Show floating text above a unit when it is damaged or healed

Menus

The game's pull-down menus use title case. The key shortcut for a function is pulled from the hotkeys configuration file. Related functions should be grouped together. Frequently-used or important functions should be near the top of the list, 'dangerous' functions should be moved to the end of the list. 'Quit' is considered dangerous, which is why it is moved as far wy from the top of the menu as possible. As far as possible, try to ensure that accidentally missing the menu option you wanted to select by one row is harmless. Where no more obvious order is apparent, list items in alphabetical order.

Tooltips

Tooltips use sentence case, but the last sentence in any tooltip does not have a full stop. Try to add a tooltip to every button. At the very minimum, the tooltip should show either the default value, the current value, or the minimum and maximum values, depending on what is most useful. Where a button or checkbox's function is not immediately obvious, phrase the tooltip to describe what happens when the option is turned on.

Tooltips should contain no more than one or two lines of text.

Examples:

name=_"Ping timeout (seconds)"
description=_"How long to wait for a ping reply before giving up. 0 means wait indefinitely"

name=_"Auto-open whisper windows in lobby"
description=_"When you are sent a whisper message, it appears in a pop-up window"

(WML code)

Default Values

While it might be nice to display the default value for every checkbox, widget and so on a player might alter, this can make the tooltips needlessly untidy. The recommended practice is not to mindlessly add this information to every tooltip, but to provide it wherever a changed setting could cause unexpected behaviour, or wherever the original value is hard to retrieve. For example, it's easy to tell whether 'Floating Labels' is on or off. On the other hand, the name (and possibly port number) for the default add-on server should be stored in the tooltip, so that a user can restore it if necessary.