CC Open Source Blog
CC Vocabulary is a new design system for Creative Commons
With the development period of GSoC 2019 well under way, a number of new and improved Creative Commons apps are navigating their way to production and worldwide reception. With all this development comes one obvious challenge: consistency (not to mention a number of other challenges such as internationalisation and modularity).
The idea of a design system, to have a collection of elements and components designed cohesively to be used across the body of applications of a particular brand, is not new or even remotely my original. In fact, every organisation with more than one application should have a design system. My last project was backed by its own component library and it saved my team countless hours of bikeshedding and repetitive design iterations.
Contributing to CC Search in the period before GSoC made me realize the numerous areas of the project that would benefit from a pre-built library and prompted the proposal that eventually became my project. I'll cite the same example that I used in my proposal because it so clearly shows a problem and its solution.
Consider for example the header and footer. All CC apps have a header and a footer developed along the lines of the homepage, albeit to varying extents. However, due to the lack of a common component, every app develops its own and they end up looking like these. Calling them inconsistent would be an understatement.
The footer on the CC homepage
The footer in the CC Search app
The footer on the CC Open Source site
Enter CC Vocabulary
CC Vocabulary solves precisely that. It is a set of components, elements and patterns that unite Creative Commons' applications in terms of look and feel, while encapsulating and abstracting basic functionality that need not be reinvented per-app.
Now CC Vocabulary provides a footer (ready to use today!) that can be used on all three of the above sites, conveying the same information in the same consistent layout.
"What about the different contents in the footers?", you ask.
As for the different content in all three footers, the third column is 100% customisable. So whether crediting the developers of the website, attributing the icon artists or licensing the content therein, the footer just works. And when it comes to translations, Vocabulary has you covered. Lastly, to embody the colorful world of creativity, every CC Vocabulary component can be colored. So from the blue header of CC Search to the orange one on the homepage, there's a component for everybody.
The footer provided by CC Vocabulary
The footer provided by CC Vocabulary customised for the CC Open Source site
The footer provided by CC Vocabulary in Hindi
Let's get to the nerdy stuff, the development details. Here's the good, the bad and the ugly of Vue development and also how all three adjectives fail to embody the one constant feeling: challenging!
As you've already seen, the prospects of the library in making the CC codebase modular, cleaner and i18n-ready are huge. And being written in Vue has a ton of perks, not the least of which is a future-ready, progressive framework to back the project!
Development in Vue is even more different, and even even more so when building a
Webpack-based app with Vue CLI, which takes a different approach compared to
React CRA. For one, there is no option to eject! So any changes to the Webpack
config have to be submitted via an object in
vue.config.js and deep merged
with the existing config.
Then there are plugins. Plugins for Vue CLI are few and far in between but those
that are work extremely well and integrate with the Vue UI, a web based
management tool for Vue projects. Both Vue Styleguidist, the plugin used to
generate the styleguide and Vue i18n, the plugin used to provide translations
work seamlessly with Vue and, with the exception of having to manually enable
i18n in Styleguidist by extending the renderer in
on that later), with each other.
So by the end of week one, I had a styleguide with a Heading component and a Docker setup to boot. I also had a ridiculously large smile from all the learning that I did. By the end of three weeks, I was the proud developer of a world-class web component framework that was beginning to have some real footing, something I had not even dreamed possible!
Pro-tip: If you haven't seen or experienced Vue UI, you should. It will change your opinion of Vue for the better, as it did mine.
[user cc-vocabulary]$ vue ui
In week 2, I had to develop a number of components and incorporate design
tokens, a practice with origins at Salesforce. Folks wiser than myself at
Salesforce came up with the idea of using design tokens to keep constants out of
the design and frontend development process, abstracting the actual nitty gritty
of colors and border radii behind semantic names such as
Hardcoding every single color and every single dimension in YAML files manually
from little to no reference at all was a very low point in an already low week.
The reason behing this pain is CC's color
palette which provides all values
#abcdef for the close to forty colors in the palette. Were they HSL
values, it would have been extremely easy to shade the colors. If any brand aims
to redo its colors, I would suggest using HSL wherein HS is used to determine a
color and L is varied to determine its shades.
Another strange decision taken by Vue is that Vue components use a Single File
Component scheme making use of
.vue files that Webpack processes using the
vue-loader package. Now Styleguidist and Vue i18n both add their own tags to
the mix such as
<i18n> making one component file go to hundreds
or even thousands of lines! In a world that taught us to decouple style from
functionality, this mushing of languages did not sit too well with me and I kept
contemplating what reasons would have prompted the developers to take this step.
Also Styleguidist comes with a very bland default style so to make it barely presentable, one needs to override a lot of CSS styles that have absurdly high specificities. Thankfully the default design is bland, not ugly otherwise the whole thing would have been an ugly, miserable affair.
Pro-tip: This catastrophe could have become ugly were it not for the
src attribute supported by some Vue tags. I had known this for
merely seconds when I found myself breaking my components down using
<style scoped lang="stylus" src="./Component.styl"></style>
to store CSS separately and
to keep translations outside of my code, thus making the file much more
manageable. There is still no way to split the JS
<script> from the HTML
<template> without losing all autocompletion features provided by the IDE.
Incorporating translations into the project was the weirdest. With two or three commands maximum, the Vue website had translations enabled and was working perfectly. But the Styleguide would just not render translations at all!
It took close to three days to even figure out why. Once I misinterpreted the cause of the error, broke the entire styleguide and had to
[user cc-vocabulary]$ git reset --hard HEAD
to even get things to work. "Use VCS.", proved one again.
Finally I had to register the i18n plugin separately for the styleguide, install the middleware on all components and add a locale selector to every preview box across the styleguide by extending and overriding the preview component. The good folks at Styleguidist had provided for that functionality, and it revealed itself to me as I was at the very brink of losing my mind.
To add insult to injury, translations have to be done by hand. I know this is how the world of i18n works but it would be really magical if we had a service to do the translations automatically. Now I can write in two languages, and will translate components to the other one as best as I can. But I urge you to contribute too. Together we can make CC components globally local.
Languages that follow an alternate orientation, such as top-to-bottom or right-to-left would pose significant difficulty to implement, having to manually render everything in an opposite or perpendicular direction gives me the chills. It's gonna be ugly.
Pro-tip: I learned that flags are a terrible way to represent language. Many languages are spoken more widely outside countries of origin (think English) and many countries are home to several languages (think India). Many large websites make the mistake of using flag alongside language names and that seems so stupid in retrospect.
Also one should use the native name of the language in the selector (like हिन्दी) and the universal translation icon (or some stylistic variant thereof).
The project which takes out a lot of the hard work from frontend development has its fair share of hard work cut out for itself. The challenges ahead are plentiful, but the solutions they inspire are diamonds in their own right. It is safe to say that I can attribute my complete understanding of Vue, i18n, component libraries, styleguides and design systems to CC Vocabulary.
Before we move on, let me tell you the bad and the ugly are not the norm. The good was the major portion of the project.
So as you can see CC Vocabulary represents a huge leap forward for the web-facing Creative Commons. I can't wait to see the new generation of apps by Creative Commons, powered by CC Vocabulary.
CC Vocabulary is out now, with its code, design and translations on GitHub and a live styleguide hosted on GitHub pages. Please check it out and join the discussions. Since it is too early to even call it a beta, your feedback is crucial in shaping its future and with it, the future of all Creative Commons apps.
Here's a sneak peek!
Say hello to CC Vocabulary!
See GitHub commits for in-depth logs.
- Set up the Vue CLI 3 project
- Installed and customised Styleguidist
- Dockerised the setup for ease of setup and development
- Developed a home page for the project
- Developed simple components, called elements, like Heading and Paragraph
- Added design tokens and Theo workflow
- Converted all constants to design tokens: color, fonts and dimensions
- Wrote some, not all and definitely not enough, tests
- Added elements like Container and Badge
- Added complex components, called patterns, like Hello, Header and Footer
- Deployed styleguide to GitHub Pages
- Added color to patterns in a reusable way
- Added i18n capabilities and initiated translation to Hindi in the Footer
- Developed the Locale switcher and integrated with Styleguidist
See proposal for in-depth goals.
- Integrate the library, gradually, with CC Search
- Add more generic components
- Go to point 1
- Develop a non-Vue vanilla CSS + JS based version of the library