iTranslated by AI
Design guidelines help make web application designs more consistent. However, if you have an operating service and establish design guidelines later, you need to update existing components. In this article, I would like to explain the specific procedure for updating existing components using design guidelines, taking Zenn as an example.
TL;DR
Narrow down the scope of modifications, search the source code for that theme, and review, consider, and apply the modifications for every hit.
Background and History
As most of you know, Zenn was originally released as a solo project by catnose and later joined Classmethod, Inc. through an acquisition. I also joined Zenn's development at that time.
Time passed... although catnose has moved away from the forefront of Zenn, he has energetically created various products, including Shizukana Internet. As for Zenn, he continues to contribute as an advisor. By the way, the term "advisor" might sound like a formal title, but in catnose's case, it is very helpful because he points out risks early on that might cause problems later if left alone, and sometimes he even lends a hand in coding.
However, relying solely on him makes it difficult to scale future development, so we decided that the Zenn team would handle most of the maintenance of core functions and new development from here on. One of the big challenges there was how to maintain Zenn's design. Design is an element directly linked to insights such as experience, air, atmosphere, and brand. But even if I know it's important in my head, when I actually work on it, it inevitably ends up looking like a retread of existing screens.
Formulating Design Guidelines
After getting many stakeholders involved, we were able to have designer @fujisawa join us. When we shared Zenn's challenges, he immediately started discussing them with catnose and creating design guidelines. At present, we have applied two guidelines to production.
Guideline creation was primarily led by fujisawa-san, and by having team members participate in discussions on Figma, the results are something we are all convinced of. Thank you.
Part of the design guideline deliverables @Figma
Flow of Application
Since the product existed first and the design guidelines were established later, it was necessary to review existing components. Please take the following flow as one sample that the Zenn team followed.
- Identify the CSS to apply the guidelines to
- Add review comments to all relevant locations for the identified CSS
- Conduct a review
Example of commenting on the box-shadow for a registered credit card
Narrowing Down the Modification Targets (CSS in this case)
Design guidelines are just guidelines; they need to be implemented. Depending on the case, you might need to reorganize components, rethink the API design, or even discuss whether the function itself is necessary. However, the major purpose of creating design guidelines this time was to maintain and verbalize Zenn's design. When considering the benefits for development members, we thought CSS was the area with the highest cost-effectiveness. As a starting point for applying the guidelines, we narrowed the modification targets to CSS.
Review: Discovering Exceptions and Oversight
It would be best if design guidelines could be applied instantly without any hesitation, but it does not go that smoothly. There are things that cannot be judged by the guidelines alone, and there are components that were not anticipated. In some cases, it is necessary to go back to the design guidelines and make corrections, so we thought it necessary to review every target one by one.
Applying Drop Shadow Guidelines
Drop shadows control what is known as lifting or elevation. While I leave the details to fujisawa-san's article, we organized what should be lifted and what should not be in the guidelines. We then applied this.
Identifying CSS
In terms of CSS, it is box-shadow. It's easy to understand. Since there was nothing new to be lifted this time, reviewing the existing box-shadow was enough.
Creating a Pull Request for Reviewing How to Handle box-shadow
We created a pull request for review, adding opinions such as whether to fix it, not fix it, or if we were unsure. Developer opinions are noted as source code comments so that the diffs are visible.
There were 154 files changed
Developer modifications and opinions were left as source code comments, and interactions and decisions during the review were left as comments on the GitHub pull request. Final modifications were not made in this pull request but in a separate one, and the pull request used for the review was closed as is. By doing this, if we have a box-shadow in the future where we wonder, "Huh? Why is it like this?", we can look back at the pull request to understand the background.
Review and Release
fujisawa-san and I reviewed the pull request from top to bottom. It took about 3 hours.
Main review topics:
- There were differences in perception of things that mimic physical objects
- A discussion occurred on whether to add a
box-shadowto sticky elements (those that follow when scrolling) - We decided how to deal with components that become hard to distinguish from the background if
box-shadowis removed - It was pointed out that we also need to modify zenn-content-css, which applies to HTML after Markdown conversion, not just the main body
We left the background in the pull request and established the policy. After the review, we created a pull request for merging and released it.
By leaving the background of the review in the pull request, you can trace the history later
Applying Corner Radius Guidelines
The flow is the same as for shadows. For rounded corners, search for border-radius and apply the guidelines.
The number of files changed (subject to review) was 201
Reviewing took a total of about 4 hours. Thank you for your time.
Main review topics:
- Even with small rounded corners (
border-radius: 4px), if the rectangle is small, it looks slightly rounded, so we defined a2pxcorner radius - Be careful not to miss partial rounded corners like
border-top-left-radius(my apologies) - Since the Publication landing page was the only one that fujisawa-san wanted to decide by discussing individual elements one by one in addition to the guidelines, we did so
Changes Resulting from Applying the Guidelines
In my opinion, I feel that the return on the cost invested was more than enough.
Feature Development is 1 Business Day Faster
Until now, modifications involving screen changes were done by pulling from existing CSS and imitating it. It sometimes went smoothly, but if a discussion about UI arose during the review, individual preferences would diverge due to a lack of a base concept or anchor point, often leading to things being carried over to the next day... resulting in a feeling that merging was delayed by about one business day.
Not only did this reduce hesitation for the members doing the work, but it also served as a perspective for reviews, speeding up the time until pull requests are merged.
Gained Better Knowledge of Existing Components
In Zenn's frontend, many components are extracted into files, and using them appropriately can cut down on development effort. However, if you don't know they exist, you can't use them, and I was often searching for "are there any reusable components?". With the application of these design guidelines, I have been able to look at existing components in a somewhat comprehensive manner, and I think I will be able to reduce the time spent searching. Definitely a nice side benefit.
Increased Ability to Explain Zenn's Insights
Since the design guidelines were written by fujisawa-san based on an existing product, it can be said to be a kind of reverse engineering. As a result, I am now able to explain the insights that I previously felt intuitively, such as "Zenn has a somewhat gentle atmosphere, but it's geared toward professionals."
- The gentle atmosphere is expressed by using blue as the base color to provide a sense of calm, and the four corners of each component area are rounded rather than right-angled to suppress a sharp impression.
- On the other hand, book cover images evoke physical books by making full use of shadows and gradients, and by making "Like buttons, share buttons, and the table of contents" follow the scroll on article pages, it ensures that the actions readers want are always displayed on the screen (directly linked to UX), thus providing professional-oriented details.
These are my own verbalizations and not the consensus of the team. The point I want to make is that by putting things into words like this, it becomes possible to analyze and discuss insights.
He Implemented This as a Solo Project...
Recently, as I have deepened my understanding of these UI aspects, I have realized once again how amazing catnose-san is for having built Zenn's insights on his own.
Conclusion
It took a fair amount of time to create and apply the guidelines, but when I think about how it will affect all future development, I look back and feel glad we did it early on. The design guidelines are not yet finished. I want to work together as a team to continue building them, and further deepen and expand Zenn's worldview.
Discussion