Explanatory style - Wikipedia

Front-End Principles for Designers

LOCOMOTIVE SCROLL V3.0

A Complete Guide to useEffect

Writing Resilient Components

„Thinking in React Hooks“ by Amelia Wattenberger

If You’re Busy, You’re Doing Something Wrong: The Surprisingly Relaxed Lives of Elite Achievers

Gradient Magic - A Gallery of Fantastic and Unique CSS Gradients

How we make Web Apps lightning fast at Microsoft by Sean Larkin | JSCAMP 2019

Gatsby Theme Amsterdam

App Store UI using React and Framer Motion

Simplicity (II) by Bastian Allgeier

An HTML attribute potentially worth $4.4M to Chipotle

„The magnetic generosity of the network effect“ by Seth Godin

How to Design Great UX for Sign Up Form

The Part Time Creator Manifesto

Screen Size Map for Responsive Webdesign

Performance metrics for blazingly fast web apps

"OPEN SOURCE AND POWER WITH MATT MULLENWEG" by THE REWORK PODCAST

Design Systems for Developers

Virgil Abloh, "Insert Complicated Title Here"

Is It Worth the Time?

Marketing Examples

A guide to JavaScript Regular Expressions

Framer Motion x React Router

The ten minute rule of productivity

Design Principles

React Data Survival Kit

Fear of bad ideas

Practical Ways to Write Better JavaScript

JIMP - JavaScript Image Manipulation Program

react-use - a useful library of React hooks

Learn Regex in 4 tweets

While I am designing, I always have this quote in my mind.

> You are not the user

In this blog post I simply want to describe how I think about it. Explain why it is so important to me. And discuss how it makes me think differently.

---

It’s not my quote. It’s a quote from [Don Norman](https://en.wikipedia.org/wiki/Don_Norman). He is a famous American researcher. He influenced how we think about design. Especially User Centered Design or also called the User Experience.

The statement in the quote is so simple but powerful. It tells you everything you need to know in 5 words.

### Thinking and Assumptions

To keep it simple. If you think you can assume what the user wants and how he will act, then you are already wrong.

Here are just a couple examples:

- If you think or assume the button is clear to the user. You are wrong.
- If you think or assume the user does like the colour. You are wrong.
- If you think or assume the user will understand the website navigation. You are wrong.
- If you think or assume the user is used to websites and can understand your design. You are wrong.
- If you think or assume that it is clear to the user what he has to do on the website. You are wrong.

If you’re not comfortable with these statements. You probably are thinking to yourself: “Why am I wrong?” It’s not because these statements ultimately cannot have a piece of truth inside them. It’s because there is no evidence. It’s a thought. An assumption. **_It’s a claim without evidence._**

### Testing and proof

If you want to go from being wrong to being right. You need to offer evidence to a claim. To demonstrate the evidence you need to test. A test with a real user. Not a persona.

By proving that an assumption is right, we can validate our idea.

Let’s demonstrate how we can test and provide evidence to our previous examples.

- Claim: The button is clear to the user.
    - Proof: I tested a prototype with a user and they were able to reach a predefined goal.
    - Proof: I have conducted an A/B test with our current button description and a new version.
- Claim: The user does like the colour.
    - Proof: I tested a prototype with a user and they were able to reach a predefined goal.
    - Proof: I have conducted an A/B test with two different colour themes.
- Claim: The user will understand the website navigation.
    - Proof: I tested a prototype with a user and they were able to reach a predefined goal.
- Claim: The user is used to websites and can understand your design.
    - Proof: I tested a prototype of the website with a user and they were able to reach a predefined goal.
- Claim: It is clear to the user what he has to do on the website.
    - Proof: I tested a prototype of the website with a user and they were able to reach a predefined goal.

### Patterns instead of proof

_What if you don’t have the resources to conduct user research before or while developing a product?_

This is a real scenario for many projects. In this case, I would follow established patterns of User Experience Design. [Design it as simple as possible.](https://www.nngroup.com/articles/computer-skill-levels/) Especially if the demographics are very varied and involve all age groups I would recommend: “Even your grandmother should understand it” and that’s the right attitude for that case.

If the demographics is young and is already attached to modern technologies, go further. Be bold.

Follow established patterns that are accessible for the targeted demographic.

### Further readings

- [You Are Not the User: The False-Consensus Effect](https://www.nngroup.com/articles/false-consensus/)
- [The Distribution of Users’ Computer Skills: Worse Than You Think](https://www.nngroup.com/articles/computer-skill-levels/)
- [Myth #14: You are like your users](https://uxmyths.com/post/715988395/myth-you-are-like-your-users)



I simply want to describe how I think about assumptions. Explain why it is so important to me. And discuss how it makes me want to think differently.

“You are not the user”

**_WIP:_** _This articles is a work in progress and subjects to further updates._

--- 

## What is a style guide?

A style guide defines the visual language of a product. The tangible components of a style guide consist of these components:
- Colour Guide
- Typography
- Spacing
- UI Components
- Code components (CSS Variables)
- Brand Style Guide
- Accessibility

A style guide is the single source of truth that defines all these components. It should answer all the fundamental questions about how to approach the visual design of a product.
It will answer minor questions like:
- What color is this button?
- What font is this copy?
- What shadow do we use here?
- What radius is this corner?

By eliminating questions like these, we can focus on more substantial discussions and solving user problems.
A good style guide will:
- Save time
- Save money
- Enable faster development cycles
- Enable a higher level of consistency
- Provide a single source of truth

_A style guide is not a design system. It’s a smaller low level component of a design system. I will go in depth into design systems in another post._

<img src={files[0].url}/>

## What is a design token?

A design token is a single definition of a variable in the style guide. It is a single attribute of a component in the style guide.
Imagine it as a single value of brand colour, `brand-green` or `brand-red`. Or a definition of a font size like `xxl` or `s`.
In Figma this may look like the following collection of styles:
Tools like Figma, Adobe XD or Sketch provide these very useful variables for us, so we can keep our design consistent.

But there are still some important design tokens that these tools don’t support. These are:
- Spacing _(No tool support) The spacing on the horizontal or vertical axis between elements. In CSS this would translate to a `margin` or a `padding` value._
- Shadows _(Figma supports this)_
- Border Radius _(No tool support) In CSS this would translate to a `box-shadow` value._
- Layout Grid _(Figma supports this)_

## How to define design tokens?

There usually are three common starting points that I’ve experienced for a style guide:
1. **Fresh start: **You are starting out with a fresh slate, without any previous design documents like an Corporate Design – you will have a lot of freedom in choosing colours, typography and imagery. There are a few different approaches to establishing a visual language, but it would be too much for this article. _I personally like to start on a abstract level like mood boards or style scapes to identify the preferences of my client and their customers._
2. **In the middle:** You are in the middle of a new design. You’ve already tried out a couple of directions and now you have the consensus of the client for the direction. You want to take the new design and break it down and document it for the development cycle.
3. **Existing Corporate Design:** You are doing a redesign for an existing design. You need to follow an existing design, establish new rules and values for the development cycle.

### Breaking it down into actionable steps

_So you’ve got some colour and font choices?_
Let’s break it down into the smallest reusable parts.

If you have a single main colour like a `brand-green` , then you should break it down into multiple shades of the main value.

<SimpleGrid columns={[1,2]} spacing={[8]} alignItems='center'>
	<img src={files[1].url}/>

Break it down into a scale with 4 lighter and darker variations. In total you will have 9 shades of the main color. You can do this by hand or with a tool like the [Material.io Color Tool](https://material.io/resources/color/#!/?view.left=0&view.right=1). Another useful tool is the [Color Shades Generator for Tailwind CSS](https://javisperez.github.io/tailwindcolorshades/#/).
</SimpleGrid>

<SimpleGrid columns={[1,2]} spacing={[8]} alignItems='center'>
<img src={files[2].url}/>

Define the neutral colours and signal colours of your UI Elements.
Neutral colours are the different shades of grey that can be used between different brands.
Signal colours are used to inform the user about Tips, Notifications, Warnings or Errors.

</SimpleGrid>

<SimpleGrid columns={[1,2]} spacing={[8]} alignItems='center'>
<img src={files[3].url}/>

Define the allowed spacing values and the base spacing.
A common practice in digital product design is to use an 8px grid. All elements inside this grid should be aligned to this grid. This enforces a harmonic and clean looking UI.
</SimpleGrid>

<SimpleGrid columns={[1,2]} spacing={[8]} alignItems='center'>
<img src={files[4].url}/>

Define the primary and secondary font and the typographic elements.
Go through a list of commonly used typographic elements.
Example: Headlines, Body, Caption, Overline, Quote, Citation …
</SimpleGrid>

<SimpleGrid columns={[1,2]} spacing={[8]} alignItems='center'>
<img src={files[5].url}/>

Define the iconography that is going to be used across the product.
</SimpleGrid>

<SimpleGrid columns={[1,2]} alignItems='center'>
<img src={files[6].url}/>

Define the shadows. This translates to the `box-shadow` CSS property.
</SimpleGrid>

<SimpleGrid columns={[1,2]} alignItems='center'>
<img src={files[7].url}/>

Define the border radius and other shapes. This translates to the `border-radius` CSS property
</SimpleGrid>

<SimpleGrid columns={[1,2]} alignItems='center'>
<img src={files[8].url}/>

Define the layout grid.
This can be a custom grid layout or a standard 12 column bootstrap grid.
</SimpleGrid>

## How to translate design tokens into code

At this point you’ve got your style guide ready. It will be handed off to development, you work on it with a developer or you do it by yourself. Where do you start?
Well it depends – depending on your tools and your framework of choice. A simple framework-less and modern approach would be using CSS Variables. Many modern frameworks or tools accept JSON as an input. Some of you might still use SCSS. And some people like YAML.
In the end it depends on your choice and in this guide I will demonstrate an approach with CSS variables and JSON.

### How to use CSS variables for a design system

\[CSS variables are nowadays widely supported by most browsers.]\(https://caniuse.com/#search=css variable) They are very powerful, performant and efficient, as they don’t need any JS execution time or duplicate code to run.
Let’s define CSS Variables based on the design tokens we have defined earlier. You should keep a couple rules in mind when defining these:
1. **Keep the naming simple** I prefer simple number scales like `1 to 9` over a naming scheme like `xs to xxl` or `nano over big to jumbo`.
2. **Keep the names short** Short names are easier to scan, read and to process
3. **Use the power of shorthand CSS declarations for fonts** To enforce proper font usage I prefer the shorthand. It’s easer to read and also easier to reuse. This is the syntax: `font: font-style font-variant font-weight font-size/line-height font-family;`

```
:root {
/* Brand colour definitions */
--brand-green-100: #F4F9E8;
--brand-green-200: #E4F0C6;
--brand-green-300: ...;
--brand-green-400: ...;
--brand-green-500: #94C21C; /* Original brand colour */
--brand-green-600: ...;
--brand-green-700: ...;
--brand-green-800: ...;
--brand-green-900: ...;

/* Neutral color definitons */
--gray-100: ...;
--gray-200: ...;
--gray-300: ...;
--gray-400: ...;
--gray-500: ...;
--gray-600: ...;
--gray-700: ...;
--gray-800: ...;
--gray-900: ...;

/* Spacing definitions */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 24px;
--space-6: 32px;
--space-7: 64px;
--space-8: 128px;

/* Font definitions */
--desktop-h1: normal 300 48px/48px Roboto;
--desktop-h2: normal 500 36px/40px Roboto;
...
--desktop-button: normal 600 16px/24px Roboto;
...
--mobile-h1: ...;
--mobile-h2: ...;
...

/* Shadow definitions */
--shadow-0: inset 0px 2px 4px rgba(0, 0, 0, 0.06);
--shadow-1: 0px 1px 3px rgba(0, 0, 0, 0.1), 0px 1px 2px rgba(0, 0, 0, 0.06);
--shadow-2: 0px 4px 6px rgba(0, 0, 0, 0.1), 0px 2px 4px rgba(0, 0, 0, 0.06);
--shadow-3: 0px 4px 6px rgba(0, 0, 0, 0.05), 0px 10px 15px rgba(0, 0, 0, 0.1);
...

/* Border radius definitions */
--radius-1: 2px;
--radius-2: 4px;
--radius-3: 8px;
}
```

<img src={files[9].url}/>

Now let’s use these CSS variables for a button component in a simple example:

```
button.button-primary {
	font: var(--desktop-button);
	color: var(--brand-green-700);
	background-color: var(--brand-green-200);
	border: 1px solid var(--brand-green-400);
  	border-radius: var(--radius-2);
	padding: var(--space-2) var(--space-4);
}

button.button-primary:hover {
	box-shadow: var(--shadow-3);
}
```

[View in CodePen](https://codepen.io/simulieren/pen/vYNxMrV)

As we see in this example we don’t have a single raw CSS value and only variables. There are a couple major benefits in doing so:
1. Single source of truth based on the CSS variables that are based on the design tokens.
2. Global adjustments can be made in a single location. _Changing the button font everywhere only requires a change in 1 line of code._
3. Minor adjustments can be easily made consistent with the style guide. You need a bigger button? Change `padding: var(--space-2) var(--space-4);` to `padding: var(--space-3) var(--space-4);`. You need a different brand color? Change `--brand-green-...` to `--brand-red-...` or “–brand-blue-…\`.
4. Less questions like: _“What font to use?”_ and _“What hex colour is this button?”_ and _“What border radius is this button?”_

### How to use JSON for a design system

JSON (JavaScript Object Notation) is a type of data format. It is based on JavaScript Objects and therefore very common, especially web development. A couple frameworks use JSON files or JavaScript Objects for defining so-called themes. The values inside these files can then be accessed from the framework and then used for the styling of your frontend. The actual implementation and technical execution may vary strongly between frameworks, tools and libraries.
I’m most familiar with ReactJS and the surrounding ecosystem, as I have been working on various different projects ranging from simple React Applications with custom setups, React Sites based on GatsbyJS, Next.js and more. Therefore, I will show a simplified implementation that would look similar to a React project.
Let’s apply the same design tokens to a JSON File:

```
{
	// Color definitions
	"color": {
		// Brand color definitions
		"brand": {
			"green": {
				"100": "#F4F9E8",
				"200": "#E4F0C6",
				"300": "...",
				"400": "...",
				"500": "#94C21C",
				"600": "...",
				"700": "...",
				"800": "...",
				"900": "..."
			}
		},
		// Neutral color definitions
		"neutral": {
			"gray": {
				"100": "...",
				"200": "...",
				"300": "...",
				"400": "...",
				"500": "...",
				"600": "...",
				"700": "...",
				"800": "...",
				"900": "...",
			}	
		}
	},
	// Space definitions
	"space": {
		"1": 4,
		"2": 8,
		"3": 12,
		"4": 16,
		"5": 24,
		"6": 32,
		"7": 64,
		"8": 128,
	},
	// Font definitions
	"font": {
		"desktop": {
			"h1": "normal 300 48px/48px Roboto",
			"h2": "normal 500 36px/40px Roboto",
			...
		},
		"mobile": {
			"h1": "...",
			"h2": "...",
			...
	},
	// Box shadow definitions
	"box-shadow": {
		"0": "inset 0px 2px 4px rgba(0, 0, 0, 0.06)",
		"1": "0px 1px 3px rgba(0, 0, 0, 0.1), 0px 1px 2px rgba(0, 0, 0, 0.06)",
		"2": "0px 4px 6px rgba(0, 0, 0, 0.1), 0px 2px 4px rgba(0, 0, 0, 0.06)",
		"3": "0px 4px 6px rgba(0, 0, 0, 0.05), 0px 10px 15px rgba(0, 0, 0, 0.1)"
	},
	// Border radius definitions
	"border-radius": {
		"1": 2,
		"2": 4,
		"3": 8
	}
}
```

This configuration file is now the single source of truth. With JavaScript, we now can access all these values. As an example, if we want to access the green brand colour, we can write `color.green.brand.500`. If we want to get the `h1` font styling on desktop devices, we can write `font.desktop.h1`.

<img src={files[9].url}/>

Now let’s use these values for a button component in a simplified example with a JSX (JavaScript and XML from React) style syntax:

```
<Button 
	color="brand.green.700" 
	backgroundColor="brand.green.200" 
	border="1px solid transparent"
	borderColor="brand.green.400"
	borderRadius={2}
	py={2}
	px={4}
	font="button"
	whileHover={{ boxShadow: 2 }}
>Button Text</Button>
```

## Conclusion

Style guides and design tokens work really well, and they solve a big problem.
Creating and using a style guide and defining design tokens solves a lot of common problems and time wasters while designing and developing. By understanding how a style guide is created by a designer and by understanding how developers use their tools in 2020, we can make the hand-off seamless, frictionless and painless. Also, consecutive changes and decisions can be made more thoughtful. Especially when we understand how a change in a style guide can affect the final digital product. Designers can change design token values and explore the effects in a _“dev”-like_ environment.
The approach with CSS variables is pretty simple and universal and could be used across frameworks and products, regardless of your current implementation.



A short introduction to design tokens and CSS variables

Design Tokens and CSS Variables

Better products with Design Systems

My 3 step process

Define a roadmap

Create a standardized language

Design System

Support

What's inside?

Templates

Live Coaching-Sessions

1-on-1 Support

A clear process

Money-back guarantees

Measurable results

Bring your whole team

Access to video recordings

Remote Team-Workshops

The typical questions ...

🚀🚀Increase product quality

🗓🗓Reduce time to market

🤩🤩Increase brand consistency

💸💸Lower Opportunity Cost

🥳🥳Boost Team Happiness

Google Docs

Google Sheets

Airtable

GitHub

GitLab

Sketch

Adobe XD

Figma

Notion

FAQ

Have more questions?

Is this for me?

What do we do if we are unhappy with the content?

We don't have the resources. How are we going to get this on our roadmap?

Do we need to hire a new person for that?

How much does your service cost?

Is it actually worth it to start a design system?

Hey, I'm Simon!

Framer Motion x React Router

Design Principles

Gatsby Theme Amsterdam

Marketing Examples

A Complete Guide to useEffect

A guide to JavaScript Regular Expressions

🚀
🚀
Increase product quality

🗓
🗓
Reduce time to market

🤩
🤩
Increase brand consistency

💸
💸
Lower Opportunity Cost

🥳
🥳
Boost Team Happiness