How I made a themeable Design System for my Professional Brand — OSKRHQ.DS

… More specifically a Design Guide and a React Component Library with a very unique SASS architecture.

UPDATE: I am working on the 2.0 version.

This is a continuation of a series of posts I made last year about Design Systems. Because the best product is the one created by its user, and because I like to talk the talk and walk the walk. In this post, I will be walking you through the process of creation and maintenance of OSKRHQ.DS, my own Design System crafted from those earlier postings.

Note: This post gets a little technical but the principles are easy to pick up.

OSKRHQ.DS is a themeable and accessible Design Guide + Component Library written in React with a unique SASS architecture based on The Anatomy of UI.

1) Foundation

Everything in Design should start with a “Why”? For me, it was a combination of a few things:

• 1) I wanted to create a System of Design that would allow me, as a Designer and Developer, to have a cohesive experience for my audiences throughout all of my media and print outputs.
• 2) I wanted to showcase the process of crafting a Brand Identity and translate it into code with a system.

I am big on Branding. I think it is one of those things we don’t talk enough about in Product Design. I see a lot of talk about creating “delightful experiences” for users, but not enough discussions about how those experiences are part of a good Brand. A User Experience is an extension of your brand. Products themselves are extensions of a Brand. Just like a logo is or the messaging we use for our marketing.

A Brand is not what you say you are but rather what your users/clients say you are. It is what they feel when your name comes up.

Because of this, I always start here. Check out this post I made about a technique I use with my clients. From exercises like these, I come up with a Brand Identity or personality which I translate into Color, Type, Motion, Depth, Space by creating a Style Sheet — a dead design asset for my Styling.

After defining my Style Sheet, I was able to start systematizing design by translating its content into code using The Anatomy of UI as a framework. Let’s talk about that next.

2) The Anatomy of the User Interfaces

I needed to architect the System in a way that would make sense for Designers and Developers; the primary users of a Design System. Since I had written about this thing I call The Anatomy of UI, I decided to take that as a framework for the system. As a Designer, you have to consciously or unconsciously think about the five parts that make up every interface, digital or analog; Color, Space, Typography, Depth, and Motion. As a Developer, you also have to think about those in the form of CSS declarations. So it made sense to me to create a shared language based on these parts.

If you were to look into OSKRHQ.DS’ code, you will see that the package is organized like this:

lib
├── components
└── styles
    ├── 0-plugins
    ├── 1-themes
    ├── 2-base
    ├── 3-components
    └── styles.scss

Note: I wanted the system to be completely decoupled from whatever UI Framework I happened to use. There is a components folder that contains the React component library, and there is a styles folder containing the systematization of the Anatomy.

Taking advantage of the cascading nature of CSS, the organization of the styles folder is as such:

• 0-plugins are third-party libraries you might want to use like Neat, Bootstrap, Foundation, etc.
• 1-themes this is the entry point of the system. This is the only place where you will find absolute values in the system. All CSS declared after this point is relative to the values I have specified in my theme.
• 2-base contains the data and SASS utility functions and mixins used to construct interfaces.
• 3-components contains the stylesheets for each component in the system.

The Anatomy of the UI lives in the 2-base folder. The SASS functions, mixins and utility classes in this folder ensure consistency and make the job of a developer much easier. As an example, take a look at the SASS function below. It automatically changes a foreground color given a certain background color when there isn’t enough contrast. This is great when you have text sitting in front of a colored background like my button components.

3) UI Controls — Components

Once I systematized design, I moved into creating a Component Library in React. I chose React because I really like it, but again, you can use the system with any UI framework. Below, you can see the React Button component markup.

Now, let’s look at the system in action in the Button’s SCSS markup.

The single most important thing to notice here is that nothing is hard-coded. Nothing is absolute. Everything is relative to my Brand identity and personality. A robust SASS architecture limits developers on what CSS values they can hard-code. If they must hard-code values, they must do so consciously since that goes against the symbiosis of a system. After all, a System is a set of connected things or parts forming a complex whole. Additionally, each sub-atomic definition follows predictable and logical scales. If you want to know more about this, check out the System’s website. I explain this in detail there. From the Button’s SASS stylesheet we can see that each CSS declaration is connected to the system via the utility functions and mixins I created. Visually it looks like this…

The button and any other UI element I created is composed using the Type, Space, Color, Motion and Depth in the system and I never had to think in absolute values other than when I created my theme. If you would like to know how to theme the system you can check out this video I created. Below you can see an example of theming in action.

As soon as I had a few components constructed, I published the design system as a Node package. This way I could import it as a dependency for every project I create in the future, also allowing others to consume it or “fork” it. The first product consuming the system was the Design System’s website and the second was my portfolio. Both look like simple websites but they are actually React applications built using Gatsby.js.

Now if I make any updates to Color, Typography, Space, Motion, Depth or Iconography in my system, or if I just want to theme my system, the updates will be reflected on all the products consuming it. Although most of the time I would want to upgrade all products to the latest version of the system, OSKRHQ.DS follows semantic versioning so I don’t have to upgrade if I don’t want to.

And that is it. After about 16 weekends, I had a system. There is a lot more to the system than what I shared in this post so I encourage you to download it in any application, dig through the code, and maybe contribute to it 🤓. Just run npm install oskrhq-design-system or yarn add oskrhq-design-system. For documentation, check out its Github repo and to see the system check out its website and code.

The system’s code