UI Kit

User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how they combine to describe the complete behavior from a small component such a button to larger components such as a login window. The example that will be used in each document is a user interface for a button component.

Model

Fundamentally, a UI is a visual representation of a set of data in a given state. The UI takes in that data upon initialization and transforms it based on external actions either provided by the user directly or some other external agent. In order for multiple UI components to work together, individual components signal when certain changes are made to that data or to the state of the component, which allows other UI components to respond and signal changes of their own. The complete description of the data a UI component operates on, the state of the component, as well as the signals it produces form the model and is typically documented in model.txt. For a simple component such as a button we'd expect to see a label displayed by the button, whether the button is responding to user inputs, whether the mouse is interacting with the button, and finally a signal indicating when the user clicks on it. This would be documented as follows:

Data:
  label: The text displayed in the button.
  enabled: Whether the button is responding to user actions.

State:
  hovered: Whether the mouse position is within the button's visible region.

Signals:
  clicked: Indicates the button was clicked by the user.

As a general matter, fields that go under Data are inputs that are provided externally to the UI component, whereas fields that go under State are internal to the component itself. Typically a button does not know what label it should display and does not manage changes to the label, some external component shall make use of a button and provide it with a label to display. Conversely the button can independently manage whether the mouse is hovered over it on its own by keeping track of the mouse position, it needs no external agent to inform it of this state.

User Flow

With the model defined, the user flow describes how the model is transformed based on external events. The flow chart is documented using software available at https://diagrams.net and consists of the following components:

The start state

Every UI component begins in the start state, it appears as a dark green circle and is typically either the left-most element of the user flow or the top-most element. It can also be formally distinguished by the fact that it's the only state that may not have any arrows pointing into it, arrows may only point away from it.

If the UI performs any kind of initialization then the start state should have a single arrow pointing towards a state that handles such initialization. Refer to the login window for an example.