- Introduction
- Our mission
- Our audience
- Design Values
- Design Foundation
- Design Patterns
- Design Principles
- Our process
We at The Things Network aim to give you an excellent experience when using our products. To make sure that our product lives up to our own expectations of an outstanding product, it is important to define a set of principles and resulting recommendations that guide and inform our design and development during all stages of production.
We at The Things Network are strong believers in the power of enablement. With our great community, we have built a world-wide, decentralized, user-enabled data network – free and open for everyone. We strongly believe that the Internet of Things is a great facilitator in solving many of the problems of our modern age, which is why wanted to empower people from around the world to make use of this potential for their own means: helping their communities, solving big problems, and simply realizing new business opportunities.
Read more about the mission and vision of The Things Network in our manifesto.
In order to create a successful product, it is crucial to understand the types of users that are to engage with it. At The Things Network, we want everyone to be able to use our product and we regard it as part of our success, that we have been able to achieve this goal. When designing new solutions however, this constitution of our audience can pose challenges, since we don't want to oversimplify and thus turn off knowledgeable users, but we also don't want to overwhelm people with only moderate technical background.
Through a community study conducted in 2018 with 434 participants, we have a good starting point in understanding our audience. It can be divided in three distinct groups:
LoRaWAN and IoT have a great attractactiveness for technology enthusiastic hobbyists and people who share our community vision from around the world. Since we at The Things Network together with our world-wide communities have brought this technology to the masses, it is natural that this user group is making up a big part of our audience. The level of LoRaWAN proficiency can vary considerably in this group.
- Varying technical proficiency, though can be assumed medium in the mean
- Value ease-of-use, assistance and accessibility of technology
- Have generally simpler use cases and demands
This audience group has a medium to high knowledge about LoRaWAN and is using The Things Network to develop PoCs or mature products. The demand for product stability and feature-completeness of our product is particularly high for this group.
- Generally higher IoT/LoRaWAN proficiency
- Value stability, trust and security of our products
- Have elevated technical requirements
"LoRaWAN is here to stay" is one of the slogans often heard in our community. As the maturity of the technology progresses, researchers and educators from around the world are turning to LoRaWAN, making it part of their curriculas or investigating potentials for their companies. This audience cares a lot about accessibility and usability of our products to be able to grasp potentials and promote it further along their peers.
- Varying technical proficiencey, though can be assumed higher in the mean
- Values stability and accessibility of technology
- Have presumably simpler use cases and demands
Based on the insights about our user group as well as driven by our mission, we can describe three simple design values that we use to inform all of the design decisions we make now and in the future:
IoT and LoRaWAN are intricate fields with a growing amount of technicalities, driven by the aim to power of the standard further and further. We at The Things Network want to make sure that the power of LoRaWAN stays accessible for everyone and is not obstructed by the complexity behind the technology. It is important to us that people from all levels of proficiency with IoT will have the possibility to participate and profit from this amazing technology. Whether it is to simply learn and experiment – or to build a PoC for a business case, you should have all the tools at hand to get you there!
Since we started working on the Things Stack for LoRaWAN, we wanted to harness the advancing power of LoRaWAN. The LoRa Alliance has worked hard to progress the standard further and further, making it more flexible, versatile and secure. At The Things Network, we want to make sure that these improvements will be ready at your disposal, to improve your existing use cases – or to enable new ones.
The Things Network owes a lot of its success to you – the community. We believe in decentralization and the spirit of open source. What we build is for everyone and everyone should feel invited to support our efforts. The Things Stack for LoRaWAN is 100% Open Source and we encourage our users to join the development and assist with whatever skill they can bring to the table. It is for this reason that we want to offer solid development, design and usage documentation, so you can have an understanding of how we work and what principles inform our decisions. This guideline is one effort in this direction.
The Things Stack for LoRaWAN employs a set of design tokens that ensure a streamlined appearance throughout the product. These values are to be used exclusively, while deviations can be valid in special cases.
We use a sober and subtle color scheme that revolves around our brand colors as well as some grayscale tones to ensure proper contrast. We want to keep the console as clean as possible to also facilitate custom branding and alternative color schemes (like a dark mode) in the future. Our non-grayscale colors are used sparingly to focus attention.
For gradients, brand related colors and arbitrary coloring according to our brand, you can use our brand color scheme:
In our Web UIs, we use the following colors:
All fill colors may be shaded in both directions two times in discrete steps. This should only be done to improve an otherwise poor contrast situation or to produce :hover and :active color values
We use a classic 1140px, 12 column, 28px gutter responsive grid to arrange content horizontally and to ensure proper break and flow behavior in different screen dimensions. When used with a sidebar, the grid origin will move from the general center to the center of the layout area next to the sidebar.
In narrow mobile views, we use a two column grid. Extensive menus will collapse into toggle-able drawer and hamburger menus.
The console uses a relative scaling that makes use of the CSS rem unit. This ensures that all spacings are relative to the base font-size and enables a configuration-less accessibility scaling.
The base font size is 14px, which is hence the default value for 1rem.
Absolute spacing, using e.g. pixel values is to be avoided, unless measurements need to adhere to a certain absolute value (like when displaying video elements). Keep in mind that there are also other relative units (%, em, vh, vw) that might be appropriate.
To ensure a consistent spacing, a set of distinct spacings are used. Usage of different spacing is permitted, albeit only in 0.5rem steps and preferably in consistent extension of the scale ladder. The scaling is used for all paddings and margins, but can also be used as guidance for other visual spacings in the interface.
We make use of two different scale ladders, component scale and layout scale:
Component scale is used to arrange space within UI components or to distance related components from each other.
Layout scale is used to separate different, unrelated parts of the page layout, to structure the User Interface using whitespace and to provide visual breathing room.
Properly spacing texts in HTML/CSS can be challenging, since the spacings are not relative to the actual visual bounding box of the text. To mitigate, we apply special stylings such as line-height: 1 and special stylus text-margin mixins that help us mitigating this spacing problem to a certain degree.
The console typeface is Source Sans Pro, which is used for all text except code snippets, and byte arrays, in which case IBM Plex Mono is used.
We use three weights:
Regular, Semibold, Bold
The line-height for 14px font-size is 25px, equaling 1.785rem.
For the time being, we use Google Material Icons, but are currently looking into an icon set that suits our needs better.
Icons should be used
- in primary navigation
- to improve recall and recognition of common elements
- inline with text to improve clarity
- to replace words when space is scarce
- to represent common actions
Details to follow…
Details to follow…
The console should assist with textual info that is concise, sober and formal, helping the user completing his or her task.
- Do not use casual tone in all text relating to actions or tasks of the user
- Do not use direct address of the user except for dialogs (like modals:
Are you sure you want to…) - Do not use end-of-sentence periods, unless the text consists of multiple sentences
- Seek to find the least amount of words without sacrificing clarity or grammar
- Use inline documentation as long as it can be short and precise (e.g. field descriptions and notifications)
- Do not write lengthy descriptions and rather refer to our documentation
- Only first-level component names of The Things Stack for LoRaWAN (e.g.
Identity Server,Applicaiton Server,Console) are capitalized, otherwise normal sentence case is used - Do not shorten
end deviceto justdevice
Acknowledgement text increases the users awareness and confidence after an action has been performed successfully. For example after updating an entity, we show a toast notification confirming the success of the action. Keep in mind that by default, toast notifications dismiss themselves after a fixed amount of time (currently 4 seconds), so the text it displays should be as short as possible.
Acknowledgement text must
- be written in simple past tense
- use short and unambiguous language
- have a clear context of which action it was referring to, by mentioning the action and displaying it in temporal and/or spatial proximity of the action
| Do | Don't | Why? |
|---|---|---|
| End device updated | End device has been updated | Use simple past tense |
| Gateway deleted | Operation successful | Avoid ambiguity |
| Location updated | Location updated successfully | Use short language |
Error messages must
- be written in simple past tense
- provide users with a clear description of the problem, if applicable
- in best case, hint towards a resolution of the problem
- have a clear context of which action it was referring to, by mentioning the action and displaying it in temporal and/or spatial proximity of the action
- provide clarity as to what consequences the error had for the desired action
- not use any word shortening using apostrophes
- if possible, not be shown in toasts
| Do | Don't | Why? |
|---|---|---|
| An error occurred and the end device could not be created | There has been an error and the end device could not be created | Use simple past tense |
| An error occurred and the application could not be deleted | There was an error | State consequences of the failure |
| An error occurred and the changes could not be saved | An error occurred while saving the changes | State consequences unambiguously |
| Could not create Gateway: the ID is already taken | Could not create gateway | Provide reasons for the failure, if possible |
| An error occured and the organization could not be created | An error occured and the organization couldn't be created | No word shortening |
Form validation messages must
- be written in present tense
- avoid negative vocabulary e.g. (invalid, error, forbidden)
- provide info on what is a valid input
- be as specific as possible
- reference the field name if applicable
- use
mustand notshould
| Do | Don't | Why? |
|---|---|---|
| Password must match | Passwords should match | The condition must be true |
| End device ID is required | Field is required | Name the subject |
| Name must be less than 1024 characters | Name is too long | Inform about the precise limitation |
| Latitude must be a whole or decimal number between -90 and 90 | Latitude must be a valid value | Be as specific as possible |
Action text is text that is directly describing a related action of the User Interface. This usually refers to captions of common UI elements such as buttons, radio-buttons or checkboxes.
Action text must
- use short, imperative tense, e.g.
Save changes - always refer the concrete action and preferably the concrete subject
- not use title case
| Do | Don't | Why? |
|---|---|---|
| Create PubSub | Submit | Refer to precise action |
| Start process | Click here to start the process | Be concise |
| Save changes | Save Changes | Use sentence case |
By the very nature of our product, we employ a variety of forms as means to data manipulation. Good form design is a critical differentiatior for the perception of the user experience. We employ a set of rules to ensure the best compromise between maintainability and UX:
- Auto focus the first input when:
- The form is a create form
- It can otherwise be safely assumed that the user will fill the form in chronological order
- Use placeholders to
- Display example values (e.g.
my-new-webhook), when such would improve the understanding of a desired value structure - To inform about reasons for disabled fields
- Display example values (e.g.
- Use field descriptions
- To inform briefly about the purpose of the field
- Should always be set, unless the field is very trivial and/or not LoRaWAN-related (such as login fields)
- Use sensible defaults wherever possible
- Show submit errors at the top of the form and scroll the error into view if necessary
- Do not use toasts to display form errors
- In update forms, show success messages as toasts
- In create forms, forward the user either to the newly created record or to the list of records after successful creation; do not show a toast additionally
- Use headings to separate sections and structurize the form
- Hide form fields that are not relevant
- Consider splitting up complex forms into wizards or separate, independent forms within accordions. See also Divide and Structurize
Having defined our design values on a high level, we can continue to derive concrete recommendations and imperatives for our work on The Things Stack for LoRaWAN.
From the constitution of our audience, it becomes apparent that the technical proficiency of our users is very heterogenous. In everyday work, this makes us face a known quandary of human cumputer interaction called power/complexity trade-off. Simply forwarding all the complexity of LoRaWAN to the user will overwhelm the less knowledgeable, while simply limiting complex functionality will put power users off. To handle this problem, we aim to apply a couple of measures:
Progressive disclosure aims to only show advanced settings if the user has (explicitly or implicitly) indicated using them, thus reducing the congnitive load on the beginner user, while retaining the flexibility for those who need it.
Instead of explicitly forcing the user to make an input for every possible value, we need to look into defaults that would account for 80% or more of the cases that the value is set. This would help a lot of users that just want to get started without worrying about specifics (for the moment). While the decision about such default values can be delicate, the potential with regards to the UX can be huge.
While LoRaWAN can handle a countless number of use cases, there will be common scenarios that account for the majority of uses. It is important to investigate these common scenarios to be able to provide setup templates or canned solutions that can be applied quickly and take away the demand for extensive configuration from the user. Concretely, this could e.g. mean to provide device templates that the user can choose to prefill fields in the device creation form.
Instead of overwhelming our users with complex pages that just forward the underlying technical complexity, we need to try to make the experience as digestible as possible. In practice, that means to chunk up complex processes into graspable parts:
- Split up complex processes using the wizard pattern
- Chunk up lengthy forms into collapsible accordions (see also Progressive Disclosure)
- Use sidebars and tabs to organize different features
- Make use of whitespace as a means to avoid visual density by grouping visual elements meaningfully
- Use and maintain a clear layout grid
- Use concise inline documentation as much as possible, reference documentation where applicable
- Improve situational awareness using concise notifications, warnings and error messages
The pareto principle of user interface design says that 80% of usage is related to 20% of functionality. We have found out that this phenomenon holds true also for the console, where ~70% of users use the console to "check traffic and status". In that sense, we want to ensure that important features are easily accessible. We achieve this through:
- using overview pages in general, as well as for entities, that feature the most important information at a glance
- periodically reevaluating information to be placed in overview sections
- employ overview widgets that show most important info, while referencing advanced info inside respective subviews
Details to follow…
Details to follow…