Collaboration on UX

So, I have a pet thesis…. it goes something like this… Open Source, as we know it out there in the wild, is a code-centric pursuit. Its roots are in code, the culture is all about developers solving problems, the tooling is code-centric, and the culture values code above all else. That is not a very controversial thesis so far. However, I have experienced a lot of kickback when I get to the next bit… and that is, open source has both succeeded and failed because of the these characteristics.  It has succeeded to produce a lot of code, and a lot of tools and libraries that developers need, but it has failed in any category of software where the primary beneficiaries of the software are not developers.

To me it makes sense. But bringing it up has produced so much blowback, notably from long-time open source practitioners, that it only reinforces to me the truth in the mini thesis. There is a huge blind spot in open source culture that does not recognise where it has failed. It is a pity because I believe the first step in succeeding in these areas is to recognise why open source has failed. Only then can you fix it.

I believe it will take a long time to change this and I once had aspirations to be part of the fix-it movement, but I think it’s too long a game so I have elected instead to play a part in addressing these issues in realms where I know I can have an immediate effect. Hence, in Coko,  a not for profit I co-founded,  we are spending a lot of time to see how we can create an open source project that values all contributions as much as traditional open source values code contributions.

Part of this is making way for UX design. It is pretty much the high-value role, when it comes to conquering the most obvious limitations in open source, since it is where the rubber hits the road when it comes to ‘user’ meets software.

In the Coko community, Julian Taquet and Nick Duffield (eLife) are putting a lot of time into this with the able assistance of Yannis Barlas (there has also been a lot of excellent input from Sam and Tam from YLD and others). I’ve shepherded the process from a distance – setting the scene and making the space for the right people to do the right work and making sure this work has the right value accorded to it in the Coko culture.

So, in essence, we have realised that collaboration in UX comes down to three things:

  • identifying the common ground
  • tooling
  • process

Common Ground

Identifying the common ground actually took some discussion. We initially thought the common ground – think of it as UX space shared across projects – was on the page-level. We thought, for example, one org would need a dashboard and so they make it and others can use it. While this is true for a limited number of specific page level components it soon became obvious that there was a higher opportunity for reuse should we break the page-level components down into smaller components. We then had a short period of lexicon confusions (“duh. what sort of component is a login?”) until we settled on Brad Frost’s atoms and molecules concepts and lexicon.

After that, we could make faster progress as we had identified, and could talk about, a new level of component that had infinitely more opportunities for reuse across projects.

That was the highest level common ground we identified.


Next, we moved onto tooling… there had been a lot of discussion about this. The trick was to get the designers to experiment with and understand the options. It also highlighted the fact that in each collaborating org there was a different workflow that might play into some discussions and not into others. For example, Julian from Coko does as much of the tweaking of CSS variables and values in the code, whereas Nick from eLife does the design and then hands these designs to others to implement. So, in many ways, the questions about tooling are informed by these workflows ;and different people, even if identified as having the same kind of role, have very different questions and needs. This is important to take into account and we will need to keep this very much in focus as we go forward. One easy way to keep issues of this in focus is to always insist that any discussion, workflow change or feature that affects design workflow must include the designers in that conversation. You get better results and people are much happier! Not to mention that it saves a lot of time as there is more informed discussion as you progress and fewer possibilities for major rollbacks because someone wasn’t looped in.

This conversation on tooling took quite a few weeks; there were many options on the table and we wanted to make sure the right people were in the right conversations. It came to a close, for at least the foundational stage, when Nick and Julien met with Yannis in Athens for a 3 day UX meet and nailed down the final agreements on tooling (amongst other things). This highlights to me also the need for periodic in person meets if you can manage it, as required. You can clear out a lot of ‘hanging issues’ in one swoop if you meet in person for short focused bursts.

Below are some pics from this very important meet in Athens showing Nick, Julien, and Yannis at work on the whiteboard in our Athens office.




We now have general agreement on the use of CSS styled components, as well as an understanding of what a basic atom or molecule would look like, a high-level list of agreed design principles, an approach to ‘plain vanilla’ theme with org-specific overrides, and a prescribed set of common CSS variables.

You can see the embryonic documentation about design decisions here –

So, the crew nailed down the tooling with a few things left to discuss. There are many tools in the design/UX workflow. Unfortunately, there are not many good open source tools to support open source design workflows. That is because of the limited scope of open source projects to involve designers as I mentioned above. So design has not been seen as a priority and, consequently, the tooling is not there. You can see this in GitHub and GitLab – where are the tools that support designer workflow?


Which brings me to the final item – process. We are still working this out, but essentially each org will design components as needed, and then scope these to common established CSS variables, and then ask for feedback through Mattermost. When agreed, the component will be built and committed to the common styleguide for reuse. When the flow is established it should be a pretty fast way of working. The idea being, in essence, that atoms and molecules are developed for a target, common, ‘plain vanilla’ theme, and then each org can have their own theme that will use those common components and apply their own CSS values to the common variables.

After writing the above I asked Julien if it all looked ok, he wanted to make the following additional point about tooling and sharing design ideas and mocks:

For now, we’ve stopped the conversation at ‘let’s share svg through syncyng folders and see how it goes’.

The only things that will stay in the library of components, shared for all Pubsweet apps (from Coko and others), is the code. Therefore, since there is no easy way to test mockups with different themes (which is the thing that we would need), we will end up sharing png and discussions (for which, the Increment project could be helpful:

So for now, I don’t think we can say more, specifically if we don’t want to force the user on a specific tool.

In other words, the atoms and molecules will go into the shared component library, but the mocks and discussions leading up to the creation of the components will occur elsewhere. This is because the current open source software development tools don’t support these processes (collaboration around iterative design in a live environment).  Julien also makes the point that the mocks will also be shared as SVG since that allows each org to decide for themselves which environment (design software) they will use to create the mocks, so SVG, in a way, acts as an interface between the collaborating designers.

It sounds simple, but it takes time to work out simple solutions. We are also finding that there are no established models for collaborating on open source UX that we know of that we can follow… so discovery always comes with an overhead but it’s also exciting to be leading, in some small way, with creating a demonstrable real ‘in the wild’ example of how to collaborate across orgs on UX design in an open source project.  That comes with its own challenges, and with its own sense of satisfaction.

Atoms, Molecules, Patterns

I’ve just had a rather interesting dive into the world of components. At Coko we are breaking down the PubSweet components, essentially browser views, into smaller ‘sub-components’. So we looked at the language, best practices, and tools in this arena.

The outcomes are pretty simple but also interesting. We decided to use React-Styleguidist for the management of these sub-components.

But the discussion around what should constitute a component/pattern is in itself interesting. There is some interesting theory around it, probably the most compelling document I found was the Atomic Design article/thesis by Brad Frost. It is a compelling language / framework for understanding and discussing the creation and use of reusable components.

There are two questions that seem fundamental to a sub-components (patterns) approach:

  1. at what level do you describe something as a (singular) ‘component’?
  2. when should something become a component?

The first is very much the topic of the Atomic Design book linked to above. Brad Frost uses the metaphor of chemistry to describe the basic component types, the first being an atom. An atom is the most basic element that you will find on a web interface (his language is very much built around web interfaces and HTML elements).

atoms include basic HTML elements like form labels, inputs, buttons, and others that can’t be broken down any further without ceasing to be functional.

So, a button could be a component, and if so it would be the most basic type – an atom. That makes intuitive sense to me and its an interesting way to talk about things. We all know atoms are the most basic form of matter, so using the term to describe the most fundamental form of UI element is an easy translation. It is also a nice language to adopt because in the world of atomic theory atoms exist in isolation but they also exist in clusters and there is a language for that too. Two or more atoms that exist together form a molecule.

molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule.

That also translates pretty easily. There are other layers after this. The ‘next layer up’ (so to speak) Brad Frost calls an ‘organism’:

Organisms are relatively complex UI components composed of groups of molecules and/or atoms and/or other organisms. These organisms form distinct sections of an interface.

I can almost buy the ‘organism’ terminology but not quite. I would prefer something like ‘compound’. This makes more intuitive sense to me. As the Free Dictionary states:

Consisting of two or more substances, ingredients, elements, or parts.

So, I would prefer – Atoms, Molecules, and Compounds. I’m not going to nit pick Brad Frosts essays, it’s a brilliant piece of work. I guess I’m just pondering about the consistency and intuitiveness of his chosen lexicon. Atoms and molecules work for me, compound feels easier than organism…anyways, I got into the weeds,

The point is, each of these is a component but this gives us the language to talk about different types of components – which is very important.

Incidentally, Brad Frost defines two more layers – Templates, and Pages. I’m still pondering these. I’m, for now, mostly interested in atoms, molecules and organisms/compounds.

So, this is nice. I felt this framework made immediate sense when I first came across the idea (recommended by Paul Shannon from eLife) and, further, I felt the stress disappear caused by the struggle of talking about ‘different types of components’ without being able to name them.

Which leads me to the second question I asked above – when does something become a component. In other words, when do you spend the time to make the component a component, whether it would be an atom, molecule or compound component. For this, I am very grateful for an insightful and brief chat I had with Brian Muenzenmeyer who maintains the node version of PatternLab (Brad Frost is also part of the PatternLab team).

Brian made this very nice point:

I recall a friend explaining to me to start worrying about making something a pattern at all only after you use it three times. First time, it’s a one off. second time, you have a convenient template to copy/paste from. third time, it becomes a maintainability issue

It is a very salient point as it also points out, implicitly, that patterns are emergent and it doesn’t pay to be over zealous when breaking something down into an individual component/pattern. I think that is smart. Having said that, we possibly occupy a smaller % of software spectrum where re-use is more fundamental to our work than, say, someone building a company website. This is because we are building for reuse. Coko produces systems so that others can inherent or build their own publishing platforms. So, to support the later (build your own publishing platform) I think it is important for us to build reusable components from the get go to make it easier for developers to roll their own platform ie. we should create reusable components whenever possible as a matter of course.

Lastly, while PatternLab has Brad Frost’s logic built into it, there is no need to use PatternLab to make atoms, molecules and compound ‘stores’ for components. These can be established in the naming and categorization by convention in other tools eg React-Stylguidist (our choice of tool). This is not to say PatternLab is a bad tool, it is a great tool, but if you subscribe to Brad Frost’s ideas, or some version of them, you don’t need PattenLab to achieve this. You can choose the tool you want based on other requirements.

Anyways…that is my thinking on it so far. Pretty interesting topic. I am grateful for the language and clarity that Brad Frost provides and a few sage words on when to think about making something into a component from Brian Muenzenmeyer. Still pondering all this. It’s a very interesting area.