Announcing aragonUI 1.0

The first major version of aragonUI is finally out, and what a journey it has been! This post is meant to expose some of the principles we followed, what we’ve introduced, how to upgrade to 1.0, and where aragonUI is headed next.

If this is the first time you’ve heard of aragonUI, you can get started right away by reading the new “getting started” page.

A short history of aragonUI

When we started this project two years ago, the idea was to make a generic UI toolkit aiming to include any component related to Aragon projects: the website, the client, the apps, and maybe more. One library for everything: one look, one feel, one way to build interfaces. We wanted it to excel when applied to any of those contexts.

This vision worked great for a while, until it began to become apparent that a realignment was needed. On one side, the websites were evolving, dissociating their visual identity from our products. On the other side, it started to become clear that the main purpose of aragonUI was to assist Aragon app authors in building great UI experiences. That became the intent that would drive the next decisions for aragonUI.

Being able to build an Aragon app without aragonUI, and even without React, ensures that we maintain a diverse and future-proof ecosystem. This is why the idea of making aragonUI a mandatory library to build Aragon apps has always been avoided. Instead, we wanted to make its experience so good that it would become the default choice for many app authors, bringing in the process a great amount of visual consistency to the Aragon ecosystem.

Enter aragonDS

Earlier this year, we initiated one of our most ambitious projects, UI-wise: initiating a complete overhaul of the way we approach our interfaces, starting with what would become a complete design system for Aragon products: aragonDS.

As we fleshed out our design system, it became apparent the Aragon client and its apps would need to go through a complete overhaul, with aragonUI implementing the changes needed in parallel, to mirror the component specifications defined by the design system. More than an independant UI library, aragonUI would become a reference implementation of aragonDS's component library. In the process, some components evolved while others were created or deprecated.

This effort was also an excellent opportunity to improve the focus of aragonUI: we wanted to reach a new level in developer experience for building Aragon apps. Authors shouldn’t have to wrap their app in anything more than a single component or worry too much about spacing or responsiveness. Components should be looking good by default. By making it about apps, it became possible to provide simple component names, like Header, where the context of a component is already implied.

We decided that once finalized, this aragonUI conversion would be released as aragonUI 1.0.

But what is aragonUI?

The question might seem odd. After all, we can agree that aragonUI is a JavaScript library for React, targeting web environments. This is entirely correct. But none of these characteristics are truly part of what defines aragonUI. One day, we might see other implementations appear, based on other libraries than React, written in other languages than JavaScript, or targetting non-web environments.

Any project of this nature requires making frequent decisions at various levels. Even the smallest contribution can become quite challenging without a clear understanding of where the project is heading, what is urgent, or what is important. This is why having a clear and common understanding of what the project is, and often more importantly, what it is not, can help to focus the energy and start shaping a common vision about the project.

Up to this point, aragonUI was relying on a series of ideas that could be described as its DNA. They touch different areas and by no means constitute an exhaustive list. You can see it as a series of principles and ideas that act as a backbone for aragonUI.

A great UI library requires high quality parts

Pointing at things that could be improved in a user interface is often a much easier task than dissecting a great UI and understanding the pieces that work. This is because the details of a great interface tend to be dissimulated by their integration into the whole piece and the overall context being served.

Excellent UI platforms generally maintain a high and consistent level of quality at different levels: performance, animations, visual precision, quality of interactions, complete documentation, and API design. This is the kind of constant, global quality that aragonUI is aiming for.

Accessibility is an essential ingredient

The last idea of the Aragon Manifesto is stated as:

We are committed to a world in which every person can participate in these new organizational structures.

Our mission as Aragon contributors is to empower humankind as a whole, not only a fraction of it. This is only one of the reasons why the accessibility level of Aragon products will always be a priority. It obviously applies to aragonUI, which will keep progressing in that direction. Ensuring we are not excluding individuals is essential to the success of the Aragon mission.

Interactions should feel good

We humans tend to project our imagination onto the interfaces we use, to the point where pressing a virtual button on a cold, flat smartphone screen can sometimes feel oddly similar to the sensation of interacting with a real, physical button.

Shigeru Miyamoto, one of the most accomplished game designers in the world, describes this connection by using the japanese term Tegotae, which could be translated literally as “the hand feel”:

Tegotae is the word that you’re describing when you talk about that feel of a Nintendo game and it goes back to the focus on the notion of pressing a button and what happens on screen and how do you feel.

This powerful idea applies to any kind of virtual interaction. We want users to feel that Aragon interfaces are looking and behaving “right”.

Firstly, transitions should be fast, consistent, and natural. Thanks to the excellent react-spring, this is an achievable goal. Transitions should also work out of the box, so that authors can focus on their apps rather than solving animation problems.

Secondly, the interface should react immediately, the same way physical objects do. The UI should never freeze for any perceptible amount of time.

Thirdly, interactions should be predictable. Users shouldn’t be surprised by an object moving in an unexpected way or by an element behaving in a way different than what most people would expect.

Components should be adaptive

aragonUI is responsive out of the box, without much extra work from the author’s side. This is because every component is responsible for adapting itself to the environment. Not only do they adapt to the viewport size, but they can also adapt based on the context they are displayed in.

The general idea is to provide great defaults while always making sure that an override is accessible to an author if needed. For example, the Button component used in the Header will automatically show either its label or its icon, depending on the horizontal space available. But authors can override this behavior by setting its display prop to something other than auto. These cases are documented per component.

Button adapts to the screen size when used in Header, without any code change.Some other things that are coming soon:To sum up channel of If you feel like contributing in any way to aragonUI, a good start would be to have a look at the To know more about it, please consult This component has been designed to cover many cases, and could be described as a hybrid between a table-like layout or a list-like layout − depending on the screen size. section of the website. It will help you to get more familiar with this new set of components and how to use them.. And if you feel like contributing in a full time manner, All the components are now using the new theming system, and their implementation has been modernized in the process. Most components are responsive by default, and can adapt to many different scenarios. We also made sure that keyboard navigation was enabled everywhere by default.upgrade guideExtra props are passed downReducing the package sizethe css prop of styled-components.Minimal set of featuresPrinciple of least surpriseProvide a way to connect aragonAPI to aragonUI components with a minimal amount of boilerplate..Composition over inheritanceWhat’s new in the 1.0 release?This new version includes a new theming system, built around React hooks. It allows changes to the theme at runtime and includes a dark mode out of the box.Aragon Chatupgrade instructionsThis might be the most important change of this version: most components have been updated based on the aragonDS component specifications.We tried to make the transition to 1.0 as smooth as possible, with the general idea being to maintain the compatibility with deprecated components for this version in order to let authors progressively adopt any new props or components.on Github for an even better development experience.Box, Split, Header, Bar and othersA good way to avoid a bloated library is to avoid adding complex features in the first place. To do so, we make sure no feature gets added without at least one use case behind it.However, it’s likely some manual updates will be needed. After having updated the aragonUI version in your project, please have a look at the Instead of trying to guess what authors could need, we generally prefer to build things in a way that gives them enough freedom to extend the components and their features − at which point it could make sense to contribute the feature back to aragonUI.DataView composition good first issues.API design requires the greatest attentionGetting StartedGood APIs are essential to the health of a project like aragonUI. A problematic implementation can be fixed, but a broken API used by many apps can not be changed easily.The new DataView component is central to the way data is represented in Aragon apps.How to upgrade to 1.0When talking about APIs, banality is not necessarily something to be avoided. In aragonUI, the choice of a name is often made in a way that would favor the most obvious choice − not necessarily the most correct. Ideally, a new component should feel immediately familiar to app authors using aragonUI already.Please don’t hesitate to reach out if you have any questions, remarks, criticisms, or if you just want to say hi :). You can contact us directly in the Numerous components made their appearance in this version. Rather than listing them individually here, I invite you to have a look at the This is particularly useful to extend the styles of a component, by passing either style or className to it. When combined with we’re hiring UI engineersThis is it for the 1.0 release! We hope that you’ll enjoy using this new version as much as we’ve enjoyed building and using it internally.A #dev-frontendNew theming systemWhat’s coming next?.Babel plugin the upgrade guide Immediately, one of the first things you might notice is the deprecation of the AppView component. There is no replacement for it, as apps are now adapting to the horizontal space by default. Since Aragon 0.8, the top bar is now part of the client, which makes things much simpler for apps.!aragonUI uses aragonDS redesignThis was an important step, but this version of aragonUI is only the start of a new era. In about three months from now (February 2020), we will remove the deprecated props and components predating aragonUI 1.0. whenever possible, which often offers interesting levels of extensibility.This is the reason why we use slots in many components. Slots don’t really exist in React: this is only a name we use to describe props expecting a React node to be passed and used in the internal tree, like children, but without being limited to a single prop. or the colors documentation or the  or Unifying the documentation of aragonDS and aragonUI.Extra props are generally passed to the main element of a component, without any filtering. This allows authors to extend this internal component if needed, even if the stability of this “internal API” can not be guaranteed.We design APIs in a way that tries to keep them minimal, extensible, and familiar. Here is a list of some of the specific principles we follow:, it becomes really powerful.