User:Shadowm/UI Style Guide

As The Battle for Wesnoth has grown to become a massive project contributed to by thousands of people, both official developers and add-on creators, guidelines for consistent design in different areas have become necessary to maintain a level of quality and attention to detail that can set us apart from the rest.

This page lists basic guidelines to follow when designing user interface elements (in particular dialogs) both for the main game in C++, and for add-ons making use of the Lua engine to generate dynamic user interfaces.

TODO: FINISH THIS PAGE

Overview

As of version 1.11.17, the Wesnoth user interface remains a mildly fragmented ecosystem, as the limitations of being a purely volunteer-driven project hinder architectural progress in some areas. There are two homegrown UI frameworks in use throughout the game engine:

• GUI1 — fully hardcoded legacy toolkit, implements all logic and layout in C++; uses SDL_ttf/FreeType for font rasterization
  • Used by the in-game themeable UI (henceforth “Theme UI”) in addition to direct calls to the rendering engine
  • Some older dialogs using features not yet ported to GUI2 make use of it as well (Preferences, Add-ons Manager, Status Table, Load Game, default MP lobby, amongst others)
• GUI2 — hybrid new toolkit, implements logic in C++ and layout in WML; uses Pango/Cairo for font rasterization
  • Used by most code introduced since 2008
  • The cornerstone of the wesnoth.*dialog* set of Lua functions

The loading screen used to visualize WML and terrain processing progress uses neither toolkit, instead relying on direct rendering on the game screen.

Due to its flexible WML-based approach to layout and visual configuration for both dialogs and reusable widgets, GUI2 is greatly preferred for new UI code that does not depend upon unimplemented or unstable features (or dialog-specific hacks).

General Principles

The Wesnoth user interface should be:

1. Modern and easy to use, even for players who are not familiarized with their computing platform of choice
2. Visually appealing and free of unnecessary noise
3. Welcoming for players with special needs or preferences
4. Able to adapt to different operating environments, such as low-resolution devices and touch-based input
5. Consistent and uniform, to keep “surprises” to a minimum

File Locations

• GUI1: No specific location or naming convention; there are many different files under src/ housing the code for different dialogs
• GUI2:
  • Dialog layout: data/gui/default/window/ (WML)
  • Dialog logic and behavior: src/gui/dialogs/ (C++)
  • Widget layout/visuals: data/gui/default/widget/ (WML)
  • Widget logic and behavior: src/gui/widgets/, src/gui/auxiliary/widget_definitin/, src/gui/auxiliary/window_builder/ (TODO: DOCME) (C++)

Content Guidelines

• All references to the player must be done using gender-neutral wording.
• Grammatical contractions (“it’s”, “you’re”, etc.) should be avoided in UI text.

Typography Guidelines

For mainline Wesnoth developers (both WML and C++), there is an official Typography Style Guide, which is also recommended reading for UMC authors. The game UI follows the specifications laid out in the guide.

For convenient reference, here are some of the most important points to follow for UI text:

• Game-related negative values (resistances, defense ratios, etc.) should be rendered using U+2212 MINUS SIGN − instead of the ASCII equivalent, U+002D HYPHEN-MINUS -.
  Example: arcane -10%
• Game-related range/paired values (damage/strikes, etc.) should be rendered using U+2013 EN DASH –.
  Example: sword 12–5
• U+2014 EM DASH — should be used wherever a sequence of two U+002D HYPHEN-MINUS -- would be used.
• U+2018 LEFT SINGLE QUOTATION MARK and U+2019 RIGHT SINGLE QUOTATION MARK ‘ ’ should be used instead of U+0027 APOSTROPHE for quoting text.
  Example: The shortcut ‘Ctrl+A’ is already in use.
• U+201C LEFT DOUBLE QUOTATION MARK and U+201D RIGHT DOUBLE QUOTATION MARK “ ” should be used instead of U+0022 QUOTATION MARK for quoting text.
  Example: The add-on “Invasion from the Unknown” is already installed. Do you wish to overwrite it?
• Sequences of three dots remain in use throughout the game instead of U+2026 HORIZONTAL ELLIPSIS as of version 1.11.17.

Additionally, U+2019 RIGHT SINGLE QUOTATION MARK ’ should be used instead of U+0027 APOSTROPHE for rendering apostrophes in English text where necessary, notwithstanding the restrictions specified in the previous section.

Layout Guidelines

Definitions

• Title case: All words must be capitalized, except for articles, prepositions, and conjunctions.
• Sentence case: Only the first letter of a sentence, and subsequent proper names, may and must be capitalized.

Window Captions

Window captions use title case, large font size, and gold color TODO: relevant macros for GUI1 and GUI2 This is the default text style for GUI2 label widgets with definition=title.

All windows should have corresponding captions describing their purpose in concise and clear language. For example, a dialog that requires input from the player to choose an image file to read from disk could have “Load Image” as its caption. If more language is needed for the player to understand the dialog’s functionality, it should be provided in the description under the caption.

The caption must not be an interrogative sentence. Wrong: “Do You Want to Delete This File?” Good: “Delete File” “Do you wish to delete this file?”

Window Description

Window descriptions use sentence case, normal font size, and white color. This is the default text style for both GUI1 dialog contents, and GUI2 label widgets.

Only windows whose usage is not self-evident should include description text. For example, in Wesnoth 1.10, the Load Game dialog had “Choose the game to load” as its description. This was deemed too obvious and wasted precious vertical space at low resolutions, so the description was dropped in 1.11.x.

Wrong: “This dialog allows you to choose a unit type to spawn on the tile you selected.” Good: “Choose a unit type to spawn on the selected tile.”

Buttons

Button labels use title case.

Button labels must be short and concise, avoiding superfluous language that can be inferred from context. Often, a command button’s function can be reduced to one of a number of generic labels used in numerous places throughout Wesnoth:

• OK/Cancel
• Close
• Yes/No
• Load/Save/Delete
• Back/Next

Avoid using OK in favor of a more specific verb indicating what will happen when the button is clicked. Close should only be used in dialogs where it is the only option, that have no side-effects.

If clicking a button will open a new window, add an unspaced ellipsis after the verb. The exception to this rule is the title screen, where adding ellipses to every button would look unseemly.

Toggle Buttons

Toggle button labels use sentence case, smaller font size, and dull gold color. This is the default style for GUI1 and GUI2 toggle buttons.

GUI2 toggle buttons come in two basic varieties: the default (a basic checkbox), and the definition=radio version (a radio button). Checkboxes should be used wherever the user may choose any number of items, and radio buttons should be used when any single choice precludes the rest.

Sliders

Every slider should come accompanied by a text label to its left, in sentence case, and in the default font for its context. The label should contain short and concise language, and a trailing colon.

To the right of the slider there may be a label in sentence case specifying the current value and its measurement unit, if applicable. GUI2 sliders have a built-in label by default.

Slider labels should be left-aligned, and the sliders themselves should horizontally align with each other in a column.

Text Boxes

Every textbox should come accompanied by a text label to its left, in sentence case, and in the default font for its context. The label should contain short and concise language, and a trailing colon.