React-based UI Component Library: A Game-plan for User Experience Design Overhaul of MusicBrainz
Personal information
Name: Chhavi Shrivastava
IRC nick: chhavi_
Email: chhavi.justme@gmail.com
GitHub: https://github.com/chhavijustme
Personal Blog: https://medium.com/@chhavi.justme
LinkedIn: https://www.linkedin.com/in/chhavishrivastava
Proposal
Overview
MusicBrainz is aiming for a user experience overhaul. To keep design and development in sync, by thousands of contributors over the years, we need a design system in place. As my Google Summer of Code project, I would like to propose building a UI component library using React.js and React-storybook.
Challenges
The interface of MusicBrainz has been built out for functionality over usability over the year. While now we can boast of a thriving editor community, satisfied clients and sponsors and millions of users per year, the interface could use some love. Even the user survey conducted last year highlighted the barrier of complicated user experience for new users.
While redesigning, one of the major questions that are asked is, “Who are we designing for?” The answer for a MusicBrainz “user” is rather wide. It ranges from a seasoned editor who spends hours editing for novice users who land due to search engine results. To accommodate this spectrum, a thorough study followed by multiple iterations of mockups is required. The current site is a mixture of Perl, Template Toolkit and React. MusicBrainz is a joint effort of thousands of contributors in their free time over the years.
I feel having a well planned systematic strategy combined with targeted efforts for the redesign of the MusicBrainz site will be half the battle won!
Objectives
- Creating React-based UI Component Library
- Testing the components using React Storybook
- Documenting the usage of UI components
- Designing mockups for the entity pages
Possible extensions
- Creating contributing guidelines for designers and developers
- Extending the design system to other *Brainz projects
Setting up a Design System
The implementation of the design system can be divided into three major components. User Interface (UI) Design - Feedback - Implementation
PART 1: UI Design
As pointed out earlier, the redesigned interfaces need to cater to a broad spectrum of users: from the expert editors to first-time visitors. I ventured to make one of the first versions of the redesigned mockup of Artist Page during last September. Over the last few months, it has been a two-way process: where the community taught me how things work here and I responded with how we can make it better using design. Below is the evolution of mockups over the last few months.
The very first mockup I made, back in September, without knowing much.
Now, as of the sixth iteration from where we started!
The detailed mockups with discussion for the Artist page can be found in this JIRA ticket.
Some of the key points that these mockups revolve around is:
- Optimum balance between the functionality for new users and seasoned editors
- Highlight “missing” data points in our database through the interface
- Provide more call to actions to edit, rate, add to the database
- Make way for more integrated *Brainz collaboration
The Artist page is almost wrapped up. It took so long because we were redefining the framework. Now that we have the skeleton of framework up, I expect the other entity pages to follow the smooth trail we have created rather fast.
PART 2: Feedback
Creating a systematic feedback loop was very necessary. After much discussions, we decided not to introduce another project management tool and use the existing tool JIRA. I, along with the community members, came up with the workflow for a ticket of type “Design”. Almost all Brainz projects now can have tickets of type issue. Below is the workflow we decided on.
Further, I have organized a Kanban board which gives a clear overview of where we are with respect to tickets.
To keep the community updated on the progress, I usually post links to the ongoing design tickets as part of the meeting agenda item. So far this has been working out fine except that tracking long comments on JIRA is a bit cumbersome. We might switch to a more convenient tool or schedule design meetings in future, if and when required.
PART 3: Implementation
One way to approach this will be that once we have the mockups ready, someone, with some knowledge of how the code works, will slice it up into tickets. Design-person coordinates on making sure every ticket owner has what he/she/zhe needs. Design-person cross checks when it’s done. It goes up and live. Someone finds we used a different button somewhere. We have a ticket. Which then needs to be taken up by someone. And before we know it, we have huge piles of UX-debt. I feel this is a very probably scenario, seeing the huge scale of projects we have.
The very obvious solution that comes to mind
To maintain uniformity, static HTML/CSS document with all the components, buttons, colors, icons in it. Even code snippets with it. Developers can just copy paste from it. Something like this.
Problems with it
As soon as it’s completed, it will be outdated. Something would have had changed by then.
Say, we decide to make the all buttons round on MetaBrainz. We change it in our style guide. Changes don’t reflect everywhere. Some developers don’t even know, something needs to be changed. Also, it will be a pain to maintain it.
So what do we do about it? We want all our projects, which have been built as independent silos over time, to now have a same cohesive user experience. They need to belong to one family.
Here, I think we need a list of goals we wish to accomplish from this “style guide”
- Shared, single source of truth. If it’s there, it’s the one.
- Organised. I know exactly where I can find that one dropdown.
- In-sync. Changes should be updated real-time.
- Self-contained. Changes to it, shouldn’t break anything else.
On doing some (actually lot of) research, I figured what we need is a component-driven design system. Okay, what is that now? Let me explain it to you.
Component-Driven
It is a lot like the principles we are following in React. So designers still make mockups keeping the overall user flow in mind. They then break it down into elements and components.
We have elements. The Heading, links, grid icon, etc will all be treated as an element here.
And together, they make a “component”!
Before
Designer: This is the new feature. We have several same looking headers.
Developer: Hmm.
After
Designer: For this new feature, let’s plug in the CardHeader component here.
Developer: Okay!
What will happen
- All components are independent and reusable across various contexts. They speak the same design language.
- The designers can use components as the primary means of sharing the UI with application developers, instead of wireframes, mockups, style guides, or prototypes. We have a common language.
- We avoid the handoff process from designer to developer, it becomes continuous.
- A lot less dependency on designers.
- It will encourage contributors to contribute more freely to the library.
Design System
Very simply put, design system is a story about how we design and build products. It will be a breathing living entity of how we design and develop. This is how we use colors, this is how we use icons, this is how dropdowns are supposed to be, this is how buttons are to be. So if a new developer or designer comes in, it acts as a guide for them.
So now I hope, component-driven design system makes sense to you. Next thing will be how to implement it.
React Component Library
After exploring various options, the best-suited way for our context is to have a GitHub repository with all the React components, colors, iconography, typography, guidelines, etc. We can either
- publish it as an npm package using semantic versioning
- reference git repos in package.json without publishing to npm (pushing versions as tags)
I suggest it to be something like this.
The initial setup that I have started can be found in this PR.
For building the React components, we can either write our own or use some third party component library. This has to be carefully decided as both has it’s pros and cons. While writing out own components is much more work, using other library might end up being equal work if they aren’t enough components we need.
Component Testing
Running tests on these individual components will be a necessity. A few things to consider here will be:
• UI tests are brittle as they test assumptions about how the UI should be built; not what it looks like: a change to a class name or rearranging some DOM nodes should not break a UI test!
• Rather than helping to catch regressions that matter, like when text overflows and breaks out of its container, automated UI tests give you a proxy that your UI is rendering correctly. Look at this awesome mug below to see what I am talking about!
All of this will be particularly true about our React presentational components that are pure functions. When our code just renders the exact same result every time we pass the same props to it, there’s not a lot of logic to test.
After some research, I came across React Storybook. Basically, Storybook allows one to write visual tests in an isolated environment. With just a little bit of code, stories make it easy to mount a React components, mock any state, props or other application concerns and render it in isolation in a browser.
The major advantage I see for us here is the communication link between the designers, code newbies and developers. Having a common source of truth about how the component should look, behave and be placed will help us in the long run. It also allows it to be integrated to other Brainz projects much more smoothly.
If it still sounds very abstract to you, and you would like to see some examples, you can find them here:
The above proposal has been developed over a period of 5 months. We have found solutions to challenges as we encountered them, and have adopted our process to it. While this is a comprehensive methodology, I am fully prepared that a few more changes might happen. But overall, this should set the wheel in motion for our redesign! 
Okay, so what will I do in the Summer of Code?
Proposed Timeline
So I understand, this is quite an endeavour. I will chalk out my code goals of this summer of
Community Bonding (April 23 - May 14)
Spend this time learning React and deciding the component library we can use. This will involve making an inventory of UI components in the entity page mockups, and deciding whether writing our own components will be better than using an existing open source component library.
Phase 1 (May 14 - June 11)
Time to start coding! Setting up the component library will require majorly two steps:
-
Integrating a specification sheet for CSS. It will be probably written in less or Sass if we use Bootstrap v4.
-
Writing components in React.js. This will involve writing code, starting with small UI elements like buttons and links and moving on to cards and menus. A sample code snippet for a Button will look like this
import { Button } from 'react-bootstrap';
import '../../App.css';
import '../../css/bootstrap.min.css';
class ButtonBlock extends Component {
render() {
const wellStyles = { maxWidth: 400, margin: '0 auto 10px' };
return (
<div>
<div className="well" style={wellStyles}>
<Button bsStyle="primary" bsSize="large" block>
Block level button
</Button>
<Button bsSize="large" block>
Block level button
</Button>
</div>
</div>
);
}
}
export default ButtonBlock;
Phase 2 (June 12 - July 9)
Now that the library will start looking like one, I will start writing visual tests/stories for testing out individual UI components using react-storybook. The main objective will be to test out all states of a component that can be rendered. A sample code snippet for a story will look like this
storiesOf('Welcome', module).add('to Storybook', () => <Welcome showApp={linkTo('Button')} />);
storiesOf('Buttons', module)
.add('ButtonType',
withInfo('')
(() => <ButtonType {...buttonEvents}></ButtonType>))
.add('ButtonSize',
withInfo('Use appropriate button sized according to the context.')
(() => <ButtonSize onClick={action('clicked')}></ButtonSize>))
.add('ButtonBlock',
withInfo('')
(() => <ButtonBlock onClick={action('clicked')}></ButtonBlock>))
.add('ButtonState',
withInfo('Disabled Buttons may be used when the user cannot proceed until input is collected.')
(() => <ButtonState onClick={action('clicked')}></ButtonState>));
Phase 3 (July 10 - August 6)
React-storybook has a lot of cool add-ons that we can use. The one I particularly think, I will like to use is the info addon. It helps to document the usage along with the component. A sample code snippet of using the info addon.
.add('ButtonState',
withInfo('Disabled Buttons may be used when the user cannot proceed until input is collected.')
(() => <ButtonState onClick={action('clicked')}></ButtonState>));
It also documents the propTypes. The overall component documentation looks like this
I built a proof of concept which can be found here. It uses the styling from our Lobes Bootstrap theme, and react-bootstrap.
After Summer of Code
Continue working on our efforts of MusicBrainz redesign and ensure it’s smooth completion by being an effective communication link between design and development.
The above proposed GSoC project suits me as
• I get to learn JavaScript (React.js) under the guidance of this amazing community of developers
• The proposed project suits my expertise level and will help me further develop and hone my development skills, and
• It is feasible in the available time frame
Here is a more detailed week-by-week timeline of the 13 week GSoC coding period to keep me on track:
Week 1: Learn React from tutorials, blogs, etc and from my mentor/community members!
Week 2: Continue learning React, Start exploring open source component libraries and decide on one.
Week 3 & 4: Setup the system, create CSS stylesheets and start developing components.
PHASE 1 evaluation
Week 5 & 6: Continue developing the components
Week 7 : Start testing the components using React-Storybook
Week 8: CUSHION WEEK: If behind on stuff, then catch up. If not, then continue with developing component
Week 9: Taking mentor evaluation into account, fix stuff in code written so far and continue coding.
Week 10 & 11: Continue work on components, and start working on documentation as well.
Week 12: CUSHION WEEK: If behind on stuff, then catch up. If not, onwards!
Week 13: Pencils down week. Work on final submission and make sure that everything is okay.
More about this human
Detailed Information
I am a senior undergrad at the Indian Institute of Technology at Guwahati. My major is human-computer interaction design. I came across Metabrainz when a friend of mine from the community asked me to help them with the “UX”. Quite unfamiliar with music in general, I decided to give it a shot. The community made me fall in love with them, and I just kept getting more and more involved. It has been a two-way learning process. Applying for Google Summer of Code is a testament to that. I look forward to learning React under the mentorship of our awesome community!
I also have an active blog, where I wrote a Beginner’s Guide to MusicBrainz Entities. Blogging more about our community and my GSoC journey is definitely on the list.
Question: Tell us about the computer(s) you have available for working on your SoC project!
I have a MacBook Pro running macOS.
Question: When did you first start programming?
I learned C++ in my high school and went as far as building a library management system. This will be my second (or fifth, I don’t remember) attempt to start programming again!
Question: What type of music do you listen to?
I have a rather “underdeveloped” taste in music, thanks to YouTube autoplay. I have had phases, I am in an Ed-Sheeran-phase as of now. With Galway Girl (f7ea961e-fe9f-4ab2-8a42-e001560675a0), and Perfect (b84dd2d1-2bf1-4fcc-aadc-6cc39c36ba35) running on loop presently!
Question: Have you ever used MusicBrainz to tag your files?
Yes, I have used Picard and it has been a part of more conversations about it than one would imagine!
Question: Have you contributed to other Open Source projects? If so, which projects and can we see some of your code?
I am an active member of the Fedora Diversity team, it was my foray into the world of Open Source. I strongly believe in building a more inclusive open source society and have been doing my bit with an awesome team there.
Question: What sorts of programming/design projects have you done on your own time?
I have added a design there, as you can see. As my thesis, I am working with the community health workers in India to build educational modules based on VR. Apart from that, I have experience working on a lot of UX-overhaul projects and collaborating with cross-functional teams!
Question: How much time do you have available, and how would you plan to use it?
I am free during most of the coding period and can work full time (45-50 hrs per week) on the project.
Question: Do you plan to have a job or study during the summer in conjunction with Summer of Code?
I have a potential intern starting July, but there are no confirmed plans.!