```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2Fa5a4089d-0c6b-4961-937d-ea98297f4e36.jpg?alt=media&token=d1f218b7-54cc-40c6-b7d6-a58f079793da","id":"a5a4089d-0c6b-4961-937d-ea98297f4e36","width":3240,"height":2160,"filename":"atomic-design-thumbnail.jpg","type":"image/jpeg","caption":"The atomic design process with a scribble through it","border":false}]}
```

I think it might be time to reconsider whether atomic design helps or hinders the creation of designs and systems.

It’s been the de facto rule for looking at interfaces for a long time, but I find that sometimes it can actually create more confusion.

Atomic design is great! The issue we face though is that it’s best suited for frontend code architecture, and not necessarily within design files. It helped me understand the construction and component composability at a foundational level, but I want to flip the script a bit.

> Before we start, I’d encourage you to read the blog post if you haven’t yet: [https://bradfrost.com/blog/post/atomic-web-design](https://bradfrost.com/blog/post/atomic-web-design/).

### The structure

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2F50457a6c-64f5-4408-8d7c-545d3603a2a1.jpg?alt=media&token=79c51ab0-6b00-4696-9f6e-5ea16a4839bc","id":"50457a6c-64f5-4408-8d7c-545d3603a2a1","width":3240,"height":2160,"filename":"atomic-design-flow.jpg","type":"image/jpeg","caption":"The atomic design process","border":false}]}
```

Until now, we’ve followed the “atomic structure”, with the proposal being:

1. Atoms – Singular components (button)

2. Molecules – Groups of atoms (input + button)

3. Organisms – Groups of molecules (menu)

4. Templates – Page layouts

5. Pages – Template instances, custom content

I find it breaking down for a few reasons:

1. An atom in HTML isn’t an atom in design

2. Atoms are way more flexible than their definition

3. Organisation within design tooling can be confusing

4. Translating “templates” into design implies components – not technically correct

### The challenge

An atom in HTML isn’t an atom in a design tool.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2F2d9fc601-2a47-4cdd-8a9c-0fd79d92cfbc.jpg?alt=media&token=0bc61b33-1a8a-4dc1-b710-6324f2981ef0","id":"2d9fc601-2a47-4cdd-8a9c-0fd79d92cfbc","width":3240,"height":2160,"filename":"atomic-design-code.jpg","type":"image/jpeg","caption":"A vertical side by side of a code block showing an HTML input field, and the same element but in Figma.","border":false}]}
```

Call me particular, but an HTML input field in HTML is one thing, but in Figma at least two. We have the frame on the outside, and the text node inside. This is technically now a molecule, but we must convince ourselves it’s an atom.

Let’s say this input field now had an email icon.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2F8ac0c1ab-8fff-4a8f-a5b4-2167808b2a22.jpg?alt=media&token=cc9b93dd-79a8-4f9c-b09c-05d968fda6e8","id":"8ac0c1ab-8fff-4a8f-a5b4-2167808b2a22","width":3240,"height":2160,"filename":"atomic-design-layers.jpg","type":"image/jpeg","caption":"A vertical side by side showing an HTML input field with a <span> for an icon, alongside the Figma version","border":false}]}
```

```
This is just one way of coding it, and there's probably a better way!
```

Is that two elements or three? In HTML it could be either, depending on whether you position the icon within the field using CSS or have it in the HTML.

The structure in design and dev is inherently different! As we strive for 1:1 design/code parity, our ambitions fall apart when think about these (simple) atomic use cases.

This then cascades down/up to our larger component sets and the concepts become harder to grapple with.

### Props

The more we think this through, the more challenges we find.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2Fab10d71c-4024-4b25-9b4d-54447a167c40.jpg?alt=media&token=68f1fb65-4b55-41c2-aec2-eab714890465","id":"ab10d71c-4024-4b25-9b4d-54447a167c40","width":3240,"height":2160,"filename":"atomic-design-props.jpg","type":"image/jpeg","caption":"A component and instance in Figma of an input field, alongside the properties panel. The panel is showing a boolean prop for toggling on/off an icon.","border":false}]}
```

What about component props? There have been calls to include tokens/styles as a layer beneath atoms (subatomic, ions, quarks, etc) but a prop is a way to think about an "under layer" too. I'm confused.

Props can increase or decrease component contents, often changing an atom to a molecule, or a molecule to an organism. If we decide to ship the visibility on or off, we'd also be changing the composition of its atomic structure.

### Design tools

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2Ffc1ca369-23b5-4210-8e38-f121ee23f394.jpg?alt=media&token=d391cb54-f880-4777-ab3c-7d3fd6e9481a","id":"fc1ca369-23b5-4210-8e38-f121ee23f394","width":3240,"height":2160,"filename":"atomic-design-pages.jpg","type":"image/jpeg","caption":"A side by side \"or\" proposal for page structure in Figma. The left side showing an atom-based approach, the right showing a group system.","border":false}]}
```

The organisation of assets within design tooling can be confusing.

I’m asked a lot about the best way to organise an atomic system and I don’t think there is one, because we gain little benefit from introducing atomic page/frame/section structure.

With this framing, it becomes more cumbersome to navigate, rather than structure aiding comprehension.

Is it more beneficial to group by intent, or by underlying atomic concept? I’d go for the former because of how you navigate elements within design tools.

Understanding the structure of a component does not equal how it is organised, and that’s totally fine!

### Templates

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2F73374515-79d2-4936-a0c6-21fa0baa3340.jpg?alt=media&token=067e2ed6-98b6-4727-9799-22349b693395","id":"73374515-79d2-4936-a0c6-21fa0baa3340","width":3240,"height":2160,"filename":"atomic-design-screens.jpg","type":"image/jpeg","caption":"A web design mocked up in Figma, presented as a component.","border":false}]}
```

Translating “templates” into design implies components, which is not technically correct. I'm sure you've turned a full screen into a component for repeatability before!

I dream of a world where non-component templates can be built within design tools, a bit like a synced block in Notion, but we’re not there yet.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2Fdd44b7ab-a553-48ae-8140-b32331eea1d1.jpg?alt=media&token=03232089-8414-4e2b-aa1f-8a47941180c0","id":"dd44b7ab-a553-48ae-8140-b32331eea1d1","width":3240,"height":2160,"filename":"atomic-design-content.jpg","type":"image/jpeg","caption":"3 identical web designs in Figma, but with different imagery.","border":false}]}
```

It means that to follow the template workflow, all templates must be components, which disrupts the system.

### The proposal

Maybe I should propose something!

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F1xlNiLqg4sqANNtNX8xw%2Fec7fcdb2-9dd9-41ee-8b95-b3ee3d176824.jpg?alt=media&token=fd7b5102-1fe6-44bd-b9db-a2fe9dffa327","id":"ec7fcdb2-9dd9-41ee-8b95-b3ee3d176824","width":3240,"height":2160,"filename":"atomic-design-proposal.jpg","type":"image/jpeg","caption":"Luis' proposal for simplyfing atomic design","border":false}]}
```

I think we can simplify by flattening atoms, molecule, organism into a single “component”. Those component groups are then called “patterns”. Template is still tricky, but we need a term for full designs, hence “screen”.

As you can see, I haven't named this. Perhaps it doesn't need a name 🤔.

I do however, believe an acronym will work: **CPS**.

**C:** Components\
**P:** Patterns\
**S:** Screens

> Further reading
>
> This was also explored in Andrew Couldwell's book [designsystemfoundations.com](http://designsystemfoundations.com), where he proposed:
>
> 1. Screens
>
> 2. Features
>
> 3. Patterns
>
> 4. Components
>
> 5. Foundations

## **Where do tokens fit in?**

After publishing the original post, I received a few responses asking about tokens / variables and their proximity to the proposed system. I didn't include them originally for a few reasons, but most importantly:

1. Not everything is a component – this can be debated in a future post 😈

2. Tokens / variables have their own complexity when it comes to structure, organisation, syntax, and other developer-y things

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Frethinking-atomic-design%2F46ef2a9e-7d0b-4a9d-b208-220f128cb1b7.jpg?alt=media&token=e649cc51-2d79-44df-8b3a-a3bf3be52ff1","id":"46ef2a9e-7d0b-4a9d-b208-220f128cb1b7","width":6480,"height":4320,"filename":"atomic-design-tokens.jpg","type":"image/jpeg","caption":"The CPS flow alongside the same flow but with tokens at the start. There is an arrow from left to right pointing from tokens into components.","border":false}]}
```

Logically, we would insert tokens at the start of the flow. We have tokens, then components, then patterns, then screens...right? Well, not quite. Tokens flowing from the start would present us with TCPS:

**T:** Tokens\
**C:** Components\
**P:** Patterns\
**S:** Screens

The issue I immediately find is that tokens aren't **just** for components, they permeate entire products and websites, regardless of whether everything is a component or not.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Frethinking-atomic-design%2F5b6a0812-780b-4ce5-b99b-d1685bf1c30b.jpg?alt=media&token=70ba1e9a-7c9c-4dd2-aa6f-65c13a10607b","id":"5b6a0812-780b-4ce5-b99b-d1685bf1c30b","width":6480,"height":4320,"filename":"atomic-design-tcps.jpg","type":"image/jpeg","caption":"The CPS flow alongside the same flow but with tokens at the start. There is an arrow from left to right pointing from tokens into components.","border":false}]}
```

This means that instead of a single TCPS acronym, we are presenting tokens as an **and**, versus alongside.

**T:** Tokens\
**and**\
**C:** Components\
**P:** Patterns\
**S:** Screens

We now have **T+CPS**. It looks like a scientific formula, I kind of like it.

### The split

The arrows imply that tokens always flow into a component, but we might want to consider splitting tokens out and feeding them into components, patterns, and screens independently.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Frethinking-atomic-design%2Ff69481d7-b7f1-4b80-91b7-f96d1cb2367c.jpg?alt=media&token=66bb94ee-3678-4762-8afe-e75f064c7b31","id":"f69481d7-b7f1-4b80-91b7-f96d1cb2367c","width":6480,"height":4320,"filename":"atomic-design-background.jpg","type":"image/jpeg","caption":"An example website screen for an ecommerce store, with an arrow pointing to its background color. Alongside the arrow is a label \"Background/Primary\". Underneath the label reads: (not a component).","border":false}]}
```

An example: your body colour.

This isn't a component, and therefore doesn't fit into the CPS (components, patterns, screens) flow. Therefore, we need the mental model to shift and for tokens to sit outside of those guidelines.

> I will park the argument about surface vs background or default vs primary for the naming conventions here, this is more about what is or isn't a component!

The tokens for our page background, our containers, sections, or pretty much any HTML element that isn't set up as a repeatable component still needs to be stored and (re)used, and forcing ourselves into a "tokens are for components" mindset can trip us up later on.

### Functional and presentational tokens

Perhaps it's time to consider splitting out what we need on component-like elements, and what we need for non-components?

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Frethinking-atomic-design%2F9ed92e3d-5fe3-4280-b2cb-34b015c55062.jpg?alt=media&token=93c0dfb4-9a3b-4367-a3fa-0226194c5395","id":"9ed92e3d-5fe3-4280-b2cb-34b015c55062","width":6480,"height":4320,"filename":"atomic-design-functional.jpg","type":"image/jpeg","caption":"❖ Functional tokens: components, and ☀ Presentational tokens: non-components.","border":false}]}
```

This is why I'm opting to describe tokens as either:

1. ❖ Functional i.e. components

2. ☀ Presentational i.e. not for components

I'm still figuring the definitions out, but I think this makes sense to help aid the example I just shared. With this in mind, perhaps it's also time we interrogated how our aliasing system is structured to aid the two different (semantic) outputs.

As an example, would it be easier to iterate on screens and new components independently if we could use more tightly scoped tokens? The risk we always face with a more generic semantic token – for example, background-default –  is not having a wider view of the impact when you change its value. You might need a background-default that has is slightly darker for a specific use case. The temptation here might be to create a hyper specific component token, but what if it's not a component? I could ask questions all day here, but let's carry on.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Frethinking-atomic-design%2F26664ab1-c74e-483b-8f3c-af9efdde6a9d.jpg?alt=media&token=53a5b971-0887-49bf-a4ff-b12d3dffa083","id":"26664ab1-c74e-483b-8f3c-af9efdde6a9d","width":6480,"height":4320,"filename":"atomic-design-primitives.jpg","type":"image/jpeg","caption":"Mono/100 being split into a functional menu/background and a presentational screen/background.","border":false}]}
```

A functional vs presentational split could look something like:

Primitive: Mono/100\
↪️ Menu/Background\
↪️ Screen/Background

Again, the naming conventions here are examples and are probably not great. However, menus and backgrounds make up a significant part of interfaces. Popover would be another good one, or card!

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Frethinking-atomic-design%2F259be22c-f0ff-4b06-8340-9b0c5fc6b2cc.jpg?alt=media&token=435f2936-f921-46f0-a97a-7cd3ce8f5ba8","id":"259be22c-f0ff-4b06-8340-9b0c5fc6b2cc","width":6480,"height":4320,"filename":"atomic-design-presentational.jpg","type":"image/jpeg","caption":"Mono/100 being split into functional and presentational tokens for a menu, action, and screen.","border":false}]}
```

Extending the logic, our primitive may be extended like this:

Primitive: Mono/100\
↪️ Menu/Background\
↪️ Action/Background\
↪️ Screen/Background

A simplification, but hopefully you are following the logic here.

### This sounds like duplication

Hang on, one primitive being split into 3 identical backgrounds, isn't that inefficient? Yes and no.

I'd wager that it's faster and easier to build a muscle memory for searching "*action-background*" than wrestling the cognitive arm of "does *background-default* mean white, or that light grey that we use, or is default something we shouldn't be using a lot?".

A generic, widely applicable token system is the dream-state, but I'm not sure we can get there in organisations that aren't very tightly intertwined. Additionally, for the scenario where you *do* need to use a light grey instead of a white, would you instinctively know that you should be applying (for example) *background-secondary*? Or is it *background-tertiary* because that's how you've split lightness within colour ramps? I don't know, and your design team likely don't either.

It's way easier to search for a **component** *background-action* or a **presentational** *background-page* than to remember that there is one token to rule them all. This supports the ability to iterate and test new concepts faster too.

Let me know what you think!

### Canonical

This was originally posted as two threads:

1. [Atomic design](https://x.com/disco_lu/status/1654479672984457217)

2. [Atomic design and tokens](https://x.com/disco_lu/status/1658475897811517442)

Loose thoughts: Rethinking atomic design

When it comes to components, performance is incredibly important and there's a very common question when planning systems.

What's more performant? 

1. A single (mega) variant

2. Nested and bubbled instances

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F2D9KaCLJfq6y8LHFBQRE%2F5f94cd58-4cdc-401e-a998-dad76737bdc4.jpg?alt=media&token=dedc720b-7275-41a0-8a85-6afc4e0a3af9","id":"5f94cd58-4cdc-401e-a998-dad76737bdc4","width":1920,"height":1080,"filename":"variant-nested.jpg","type":"image/jpeg","caption":"A comparison between a (mega) variant and a nested instance approach to building components.","border":false}]}
```

### Let's analyse!

Here's what we're trying to achieve – an avatar component with:

1. 30 different avatar options

2. 3 shapes – circle, square, rectangle

3. 5 sizes – x small, small, medium, large, x large 

In the single variant option, this ends up with **319 components**. In the bubbled instance we have **41 components** (30 options plus the variant options).

Immediately, we can see a maintenance win, but is it more performant? Let's take a look at the layers.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F2D9KaCLJfq6y8LHFBQRE%2F4ab63b3f-67fd-4926-86b7-ec655ceb1723.jpg?alt=media&token=d28e86c8-09c0-4b4a-a952-12a4e448f0b6","id":"4ab63b3f-67fd-4926-86b7-ec655ceb1723","width":1920,"height":1080,"filename":"layer-comparison.jpg","type":"image/jpeg","caption":"A comparison of the numbers of layers between each approach.","border":false}]}
```

For the Single variant – **5,120 layers**.\
For the nested instance approach – **4,482 layers**.

This is a nearly **15% increase** in size! It's worth thinking about this at scale within a file. With tonnes of instances in a file, you can imagine how this would bubble out into your file's performance at scale.

So that settles it! The nested instance approach is way more performant 🎉

### Wait there's more

I might have tricked you on this one. For the avatar component example, this is probably not the best way to build that specific component. Given it's a large list of images, it can be made way more performant with...styles!

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F2D9KaCLJfq6y8LHFBQRE%2F58562e72-2253-46f7-a8e1-abcd52c6223d.jpg?alt=media&token=4679f877-4c0f-4248-8b14-168d630dec8b","id":"58562e72-2253-46f7-a8e1-abcd52c6223d","width":1920,"height":1080,"filename":"styles.jpg","type":"image/jpeg","caption":"The layer size of a reduced component set, where you use styles for variation","border":false}]}
```

Reducing the variant set down to the compositional changes – size and radius – allows you to offload the stylistic variations within the avatars to your styles. Each avatar can be created as a style, and your designers can swap them out!

### And there's even more

Variables! If your avatar is consolidated into a single shape with incremental radii as it gets larger/small – then you can use variable modes to reduce the component set even more.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2F2D9KaCLJfq6y8LHFBQRE%2F1bffbb93-156a-4598-bd8a-47b8ed274a94.mov?alt=media&token=8d0e67ce-7a88-4546-9291-3722e6f9175c","id":"1bffbb93-156a-4598-bd8a-47b8ed274a94","width":4096,"height":2206,"filename":"Screen Recording 2024-11-22 at 17.02.18.mov","type":"video/quicktime","caption":"A video showing the variable setup for the hyper consolidated approach","border":false}]}
```

Of course, this is stylistically very different to the first options, but worth considering is consistency and performance are your ultimate goals!

💡Loose thoughts: Variants, nesting, and component performance in Figma

Grab a drink, we have many words to read.

If you're working in a team with either multiple brands, multiple platforms, multiple densities, or perhaps all of the above you may be stuck trying to figure out how to structure your system/s in Figma. Here are some loose thoughts on how I'd go about approaching the problem.

### **Starting with small wins**

Organising and creating tokens in a design system is a 2-month or 2-year project, and you can start anywhere from documentation to auditing to creation. A useful starting point is to try and work from a position of low hanging fruit – are there any quick wins? 

For example, are there any colours in your system that are already close to how you’d expect the end token to look?

I’m talking specifically about the Figma side here, where perhaps you’re looking at a transformation project to convert Styles into Variables. What I’ve seen is that this project seems simple, but opens large cans of worms with regards to naming conventions alone.

Perhaps you already have a `background-page` style, which will auto convert into a variable of the same name? Or you have a very consistent 4px radius on your main components – this is a moment where you could plan, create, add, and publish the radius Variable with little disruption to existing workflows. 

Log these wins and aim to tackle them first.

### **Pipelines**

A key consideration to make throughout your token project is to define what level of automation you need. Honestly, I don’t think most teams need an automated pipeline of in/out changes from the design tool to the code repository. 

Why? I doubt tokens are changing all that often! The energy to create a workflow may be better spent on other parts of your project to begin with, and trying to build better communication channels across your cross-functional partners.

### **Global or local libraries**

I believe that Variables are the “trojan horse” for a flexible system (shout out to [Giuseppe Perri](https://www.linkedin.com/in/giuseppeperri) for using the trojan horse phrase during a recent call), where we can be sure from a brand and systems point of view that the values are fixed, but introduce flexibility in their expression via team-level or local component explorations.

Knowing that all the colors, radius, sizes etc are consistent allows us to move away from the idea that the system is limiting creativity. It flips the idea so that we position components as something designers control, and tokens are something the system controls.

I believe this would promote higher adoption of consistent values and decrease the likelihood of value deviation.

At this point, we have the opportunity to consider what is indeed a global Variable, and what is more locally scoped to a platform, project, or feature. This is a significant ask, and may take time, but effectively the question is: what Variables and components does every platform use out of the box?

On a semantic level, within a multi-platform (mobile, web, car, watch, tv) system, you are likely to find that the values within each semantic Variable need to differ. For example, the screen quality of your car dashboard and mobile phone screen are likely to differ widely, so your `bg-danger` on mobile may alias `red-600`, but in the car you may need a higher contrast `red-700`. This technically can be handled by modes, but I’d like to question whether they should even be using the same primitive foundation at all?

For situations where your different brands or platforms do indeed need to use different primitive values, it might be worth considering using groups as a way to prefix Variables within Figma collections. For example, a group for Car, a group for Web, and a group for iOS. When aliasing these later on, you will be able to filter down to `Car/red-500`, which has a different contrast to `iOS/red-500`. 

> For those interested, Figma has a different light and dark primitive ramp! You can see this in the published [UI2 community file](https://www.figma.com/community/file/1271813911103366792), on the page titled Color.

The challenge central to a goal of “one semantic for all” I think lies in sizing, specifically font sizes, density, and target sizes. Comparing a watch interface with a tv one will immediately make life challenging. A `heading-hero` font size will vary massively across platforms, so we need to decide if we want to maintain separate style libraries for these different platforms, or rely on a mode-based approach to handle all of the individual values. 

A curve ball option on this too is to use components for your text styles, which might actually align tighter with your code implementation anyway!

The pro of centralising all of your values (using modes for platform switching) is that you are tightening the screws of control within the system. This is great! For you, the system maintainer 😉. You minimise risk of duplication, and align closer to code implementation.

On the con side of the equation, you expose all designers to all modes. A designer working on mobile still has access to the car, tv, and watch Variable modes. To me, that’s quite a high risk of walking into a mixed mode world, where we push a piece of work to production using the wrong colour values. 

Perhaps I’m being dramatic, but it’s potentially expensive. Additionally, depending on how clear you are with your mode names, a darker shade of red might “just look better in a different mode” for a designer, again risking mixed modes.

In a highly functioning or tightly knit team, this risk is small because communication and documentation can discourage the mixed mode approach, but it’s still a risk.

**Splitting libraries**

With these considerations, we might then want to explore splitting our platforms into separate Variable libraries. One central library is great in theory, but the volume of Variables you’d have to maintain in a single collection across many themes, brands, and platforms could soon explode.

Inefficiency is the canary in the coal mine of an ambitious systems team, but I believe that sometime debt or less efficient approaches to management can help unlock way larger efficiency in our dependent design teams.

Similar to the concept of snowflake components, we may be enabled to manage platform-specific Variables if we opt for a split library approach. Say our watch interface has a specific `pill` component for `alerts`, this doesn’t need to be global and in fact may cause disruption if it is. 

Additionally, because it’s a platform-specific component with its own behaviour, we have the opportunity to debate whether component-specific Variables would help us release and manage this too. Component Variables are given a bad rap, a lot [by me](https://youtu.be/M0NU5QFLCl4?si=ip-ijUmNuZWGXADL&t=607), but they have their place. Perhaps more on this in another article.

### **Design and code deviations** 

Within Figma right now, there’s no ability to:

1. Add percentage Variables (for things like line height)

2. Add opacity as an override to a Variable

Because of this, we have to accept that Variables in design, and tokens in code, will differ. We have a few workarounds, but fundamentally we have a deviation.

On the line height side, I currently do not use Variables for line height in my text styles. I add a % value manually, unless working with a strict pixel based system of course!

For opacity, I do one of two things:

1. Create an additional primitive. For example, our `red-500` example may need a version that’s 70% opacity. For this, I would create a new Variable called `red-500-70` and then alias this into my semantic Variable. The benefit of this is that we can remap or reconfigure the semantic Variable later, because we know where the primitive is applied

2. Alias in my `red-500` Variable to the semantic one, and then detach the Variable. I then set the 70% opacity on the raw hex value. This idea may raise your eyebrows, but it’s a quick and dirty way to prevent the need for additional primitives. This is the approach I have taken in the [shadcn UI kit](https://www.figma.com/community/file/1414738876845632189) I've been working on

Both of these options are likely not how we would be managing things in code, so do bear that in mind at the point of build. Communication between teams may be a quick way to resolve this.

### **A quick moment of existential thought**

It is an existential question, but at these points of deviation it does beg the question – do design and code *need* to be 1:1 aligned? Is Figma the exact replication of what you have in code, or is Figma the playground for ideas, perhaps in a different way? 

Parity here means we might need to bend over backwards to ensure naming conventions and values are very tightly matched, whereas answering no might mean "hey we don’t even have half of the Variables in Figma", and they have different names altogether because designers think in a different way.

All of this will also be defined by who we decide is responsible for maintaining and updating Variables and / or tokens. If it’s all the design side, you may have flexibility. If all on the developer side, you may need to align a lot closer. Or not! 

Again, a conversation may help resolve a lot of these potential concerns.

### **A Mille-Feuille of Variables**

Classically, we look at the 3 layers of Variables being primitive, semantic, and component, but in order to build truly multi-dimensional setups within Figma we might have to introduce many more. 

With Figma’s Extended Collections feature being delayed, we have to explore different ways of managing multiple dimensions within our Variable setups. 

> [Kish](https://x.com/IAmByDesign1) explores an option over on [YouTube](https://www.youtube.com/watch?v=zCCEn6zFlDY) if you want to see how he is thinking about things.

To me the simplest way to introduce complexity to enable complexity is to consider a middle layer of “brand” within our setup. Perhaps we go from primitive into brand, where we introduce light / dark, and *then* into semantic. That middle layer is where we can use modes for different brand (or perhaps platform!) specific definitions of our Variables. 

This is definitely tricky, as we could end up maintaining duplications of the same Variables across different collections, but enables us to manage primitives, colour modes, and semantic naming conventions within a single system without exhausting the modes available to us.

```
I'm fully aware that this is probably best served with a demo, so I might add one in later.
```

Once again, this is not how we would handle things in code, so bear that in mind! It is worth considering if this is actually a problem if at the point of inspection your values present on components are correct and your developers can see them.

### **Mega components?**

A central system dream state will be where you pull in a component from the library, and you’re able to switch it to a different platform, mode, or density quickly and with great performance. 

Whilst this is technically possible, there are a few ways to get there:

1. A variant component containing all brand, platform, and density expressions. AKA the *mega component*

2. Using Variables and modes build multi-dimensional setups like we mentioned before

Option 1 is definitely the pre-2023 logical approach, but do bear in mind that in Figma, every single component variant is loaded onto the canvas when you insert them. This means that a large variant set potentially has the ability to slow your file down with a large amount of inserts.

Option 2, whilst desirable, lands us in the situation mentioned before with the need to create multiple levels of aliasing to achieve the desired approach.

A third option is to maintain many, seemingly identical component libraries. This impacts every decision from text styles to component composition to library permissions to naming conventions to code parity. 

That’s a lot to consider! But, I would like to propose it at least as something to think about. Why? Versioning! 

When working on multiple different codebases and platforms, with different release cycles, you may end up in a sticky situation where a single component for everyone doesn’t allow you to release the next version for a specific platform. 

Does your card on v4 of the web app need a button at the bottom, but you don’t need it on iOS? Sure, you could introduce a boolean toggle in the main component, but nothing will prevent a designer toggling it on accidentally for the web. To me, this suggests an iOS-specific card component, even though the radius, colours, spacing, and states may be identical.

Mmm, but what about discoverability? Two seemingly identical component libraries might cause a headache when trying to find the right component. Technically yes, this is true. We can move around it with library permissions (switching on the iOS library for iOS designs), but for those that work across multiple platforms within the same file, we will still have the issue.

This is perhaps where name spacing can help. Does `card – web`, `card – iOS` allow you to manage these independently, whilst aiding discovery? It does vary on how your designers find components as well – do they use sticker sheets, copying and pasting between files? Or do they search in the assets panel for specific components? Either option may help or hinder this idea.

It’s worth mentioning – and I promise I’m not trying to sell here – that [Code Connect](https://www.figma.com/blog/introducing-code-connect/) within Dev Mode may make this redundant too. If you are connecting the correct coded component to a Figma one, naming conventions may not need to be aligned at all. `Card` may be called `Tile` in code, and that might be an issue if, when inspecting, your developers can see the correct code regardless of name.

### **Naming convention comprehension**

Something to bear in mind from a systems perspective is whether people even understand what your agreed names even mean. Of course, “naming is hard” etc, but understanding differs within seniority and interest levels. 

1. Does a junior designer understand what `bg-default` means? 

2. Does a senior designer know that `bg-danger-tertiary` should only be used in combination with `fg-danger-tertiarty`? 

We must anticipate these differing levels of knowledge when it comes to naming conventions, and try to build systems to support. Sure, the easy out here is to write documentation on how and when to use specific Variables, but I’d challenge it. 

Do we then need to be in a position where we’re managing multiple levels of naming, to aid the rapid iteration of design ideas? Is it actually *that bad* if someone prefers searching for `orange` instead of `bg-notice`?

### **Surprise! We have a design system**

Lastly, I think, is that as with any significant project rollout, we must be mindful of anticipated reception. 

Does your design team know you are working on a large Variables project, and that what they are currently doing is due to change? If they do not know, then tell them immediately! And do it so often they get bored. 

The worst thing for a project is to have the recipients feel like the rug has been pulled from underneath their feet, and especially when an organisation is moving at pace.

\--

Questions? You know where to find me 👋

Loose thoughts: Variables considerations for multi-faceted systems

The more I talk to hiring managers and senior designers about what they are looking for in designers, the more I back up the theory that portfolios shouldn't be X, Y, Z case studies, but explorations of your obsession with details.

Showing deep, deep examinations of your solutions AND what you didn't deliver is a really great way to show how you approach solving a problem. A slideshow of solutions doesn't show anything below the surface, just a public-facing polished mockup.

But! Jumping incredibly deep into your rough work can show that you really do take the end to end product process into consideration when solving a problem.

"This didn't work, because..." is a fascinating discussion that I know would be way more interesting than "here's a flow" during a conversation with a hiring manager.

The question is therefore: How can you prove that you are "obsessed" with the details? Craft is becoming a key differentiator in software products, and design (AKA you) has the power to drive this forward, how will you enable this company to push the boundaries of quality?

The good news is that I'm confident this works in designer's favour! So many designers explain that they can't build a portfolio because "they don't have much to show", but what if you flipped it?

Take a single element on a single screen from a single feature. How much detail went into this? How granular can you get with the pixel-level detail of your every move?

\-

A few examples of deep dives:

1. Building auto suggest https://www.mrbrianmorris.com/work/query-formulation

2. Spotify changing their color: https://spotify.design/article/better-in-black-rethinking-our-most-important-buttons

Portfolios: Prioritise pixels over presentations

A living, breathable list of what I believe makes great products.

 1. Trust your gut

 2. Test with the real product

 3. Craft over consistency

 4. Experience matters

 5. Focus on problems that matter

 6. No one owns ideas

 7. Technical debt is a good thing

 8. Don’t reinvent the wheel

 9. Be in the right place at the right time

10. Keep the team as lean as possible

11. Avoid over-optimisations, focus on business value

12. MVPs should not be abandoned

13. Would we be satisfied if we could never update this again?

My work in progress approach to product

Versioning components is a tricky one. Versioning files (or designs) arguably even harder, especially with design artifacts increasing on a daily basis.

Figma is "always on", so does this mean that we shouldn't even try to version? Always live, all the time sounds fantastic and gone are the days of exports and imports and PNGs and PDFs and server storage, but we still have a big problem – maybe we *want* or *need* to freeze work.

When approaching versioning, it's useful to consider both sides of the collaborative equation – designers and developers.

Here are some useful questions to ask to establish some foundations before considering what level of versioning we might need:

**Design**

*Components*

1. Do you need to manage multiple component versions at the same time?

2. Do designers need to create work using multiple component versions?

3. Do designers need future versions of components before they are committed to handoff?

4. Do we want to version by component, by pattern, or by library?

*Screens*

1. Do we need a "source of truth" of our entire product / app / website? Be careful with an immediate "yes" here; some of the largest and most respected companies do *not* maintain large truth files

2. How long should a file last? Yes, this may be an impossible question to answer

3. Do we need to reference flows within flows? For example, a log in flow that's consistently referred to from within other larger flows. Again, likely yes

For screens organisation, it's worth checking out my file structure community file: [figma.com/community/file/1004041613962064465/file-structure-best-practice-guide](https://www.figma.com/community/file/1004041613962064465/file-structure-best-practice-guide).

For the "repeat flow" problem check this one out: [figma.com/community/file/1179022882729015433/repeat-flow-components](https://www.figma.com/community/file/1179022882729015433/repeat-flow-components)

I'll likely write another post about this, as it's a lengthy topic in itself.

**Development**

1. How do your developers version components?

2. How often do you release major/minor versions?

3. Do your Figma and code libraries differ in what components are available

4. Do you create components in Figma that you don’t need in code?

5. Do you create components in code that you don't need in Figma?

This is a lot of questions, but clarifying the answers should hopefully help provide some grounding for you to approach a solid versioning system.

### The contribution process

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FIcru9vdcRCHNw8iMLSfl%2F60b19f7e-ced2-42a5-b7a1-7162ff5c2d00.jpg?alt=media&token=08a54932-d090-4f54-89e8-6365c43bfd52","id":"60b19f7e-ced2-42a5-b7a1-7162ff5c2d00","width":1080,"height":1080,"filename":"Design component process.jpg","type":"image/jpeg","caption":"Diagram showing a flow from design file to new feature to component library","border":false}]}
```

Typically, we have our central design file which we then update with new features as they are prioritised. From here, we create new components for either efficiency gains or to live within the design system eventually. Then we move these components to the design system, and publish those out to the wider team.

This in theory works great! But in practice, we enter a world where we chase our tails trying to stay on top of component creation and contribution back to the system.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FIcru9vdcRCHNw8iMLSfl%2F907589dc-3484-4f67-bf2d-0bdca58ddc0b.jpg?alt=media&token=84baa715-40cf-447f-8275-f2030bb086ed","id":"907589dc-3484-4f67-bf2d-0bdca58ddc0b","width":1080,"height":1080,"filename":"Design component process overload.jpg","type":"image/jpeg","caption":"A flowchart of the complicated process of multiple design files trying to contribute back to the design system all at the same time.","border":false}]}
```

We therefore end up in a situation of constant creation, moving, publishing. In a small team, this is manageable, but as soon as we introduce different releases per team or timezone we end up in a world of pain.

Back to the topic, it makes versioning harder too. If my team needs to ship a feature that uses version 1, and your team needs to support version 2 because you're releasing much further in the future, how do we manage that with a single component in a single library?

As soon as we update the component to version 2 in our library and hit the publish button, every single designer is grandfathered into the newest version. This should be sending alarm bells to us all!

We need the ability to maintain two separate versions of the same component, but unfortunately this isn't possible within Figma **yet**.

As a result, we need to think laterally to figure out a solution for all.

### What options do we have?

**Option #1 – More components**

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FIcru9vdcRCHNw8iMLSfl%2F3adc606e-bf1d-47af-883e-4b3c49473020.jpg?alt=media&token=86c11a58-da9b-47f5-9663-87db616d0e95","id":"3adc606e-bf1d-47af-883e-4b3c49473020","width":1080,"height":1080,"filename":"Design component process more components.jpg","type":"image/jpeg","caption":"Visual showing two components being published into a single design file. The first component has a label \"version 1\" and the second \"version 2\". There is an arrow pointing towards the \"version 1\" shape with a label reading \"6 month deprecation plan\".","border":false}]}
```

It might sound counterintuitive, because of the live nature of Figma, but perhaps the easiest way to manage (major) component changes it to...make more components.

For minor updates to components, editing the same component may be just fine, but for larger structural or theming changes, it's probably best to isolate this change in a controlled way.

That might mean adding another variant to your component set, or a new component set entirely if the changes are significant.

*Pros*

1. You can independently manage versions of components, providing teams with the ability to switch to the newest version when they need to

2. Existing in progress work will not be disrupted with the newer version

*Cons*

1. It's perhaps inefficient to maintain components with the same in the same library. It could cause confusion for finding the correct version. To get around this, you could add the a label or word modifier to the new component, perhaps "future", adding an emoji to the end of the component name, or using the actual version number e.g. "Card v4"

**Option #2 – More design files**

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FIcru9vdcRCHNw8iMLSfl%2F2315934b-5a76-4ad7-bc9e-3de30e359bf7.jpg?alt=media&token=4076e317-2a3a-4df5-8d97-e4b254bcf521","id":"2315934b-5a76-4ad7-bc9e-3de30e359bf7","width":1080,"height":1080,"filename":"Design component process more files.jpg","type":"image/jpeg","caption":"A flowchart showing a single component being updated twice. For each update, it is consumed within a different design file. There are design files named by quarter – Q1 2024, Q2 2024, Q3 2024. As each update of the component happens, it is pushed into a newer design file.","border":false}]}
```

I raised the question earlier about how long design files should last for. This is, most of the time, an impossible question to answer because of course project lengths differ.

Centrally though, I believe we should strive for a world where design files are throwaway deliverables, versus an ongoing "forever file" that's constantly updated. I appreciate that in larger, more traditional industries, this is more like blue sky thinking than a worthy reality, but it's definitely worth striving for.

Once the work has been done, do we really need to refer back to that piece of work again if the production product is our source of truth? How often, realistically, are we going to be updating the entirety of that user flow? As the answer gets closer to "not that often", the higher the chance we can create new files for newer features.

With this method, there might be a scenario where you can create a new design (feature) file for each major piece of work you're creating. This could align with dates, for example Q1, Q2, Q3 etc. Or it could align with flows, for example "onboarding" or "settings". As we create more files, we can more easily inherit updated component versions too.

As our table component updates to version 4, our new(er) design file can inherit it without the concern that we're conflicting versions within a legacy design file that was created 2 years ago.

Smaller and more frequent files, less headaches.

```
A word of warning: if you use pages for versions, be mindful that as soon as you update the file with changes from your component library, every single component will be updated to the latest version. This will mean your versioned pages are all in fact now the latest version.
```

### **Option #3 – Staging libraries**

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FIcru9vdcRCHNw8iMLSfl%2F538fbbce-3f9c-447c-91c6-84e36d6ce649.jpg?alt=media&token=b18353cf-dd4f-4df5-9ac6-3d746832c58d","id":"538fbbce-3f9c-447c-91c6-84e36d6ce649","width":1080,"height":1080,"filename":"Design component process staging libraries.jpg","type":"image/jpeg","caption":"A visual representation of the \"production\" and \"staging\" Figma library concept, showing a publishing flow from the two separate libraries into a single Figma file. The Figma file also contains a label for \"local components\".","border":false}]}
```

This one is more likely to be possible with a larger product organisation that can't bet on small files being created for every piece of work.

There's a scenario where we want to contribute frequently to our system, but at the same time not move too far ahead what versions our developers are expecting. Designers typically work way ahead of time with new feature work compared to the designs the development team are implementing. Conflating these versions could be an expensive mistake!

With this in mind, we could introduce staging component libraries to help us stay ahead with future work, but without compromising the current state within our system.

A staging library is any components which aren't quite ready for production, but are ready to be used.

1. Future components, not ready for implementation

2. Newer major versions that you need to test in design files

3. Component tests that need to be isolated

4. A/B test components

Pulling these components into their own staging, or "sandbox" library will provide you with the flexibility or a system-wide publishing cycle, but protect your existing design flows and current component versions.

### <end>

That's all! Let me know what you think. This is possibly a work in progress article, as I formulate more thoughts on the topic.

\--

**Update 25 September 2024**

Ben Armstrong over on [LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7242198881919283202?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7242198881919283202%2C7242505040538603520%29&dashCommentUrn=urn%3Ali%3Afsd_comment%3A%287242505040538603520%2Curn%3Ali%3Aactivity%3A7242198881919283202%29) shared how they set up their future components with a label of "experimental". I like it!

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Ffigma-versioning%2F072dd3e7-719f-45b2-bcc2-67878f86e6b5.png?alt=media&token=7ce2700c-8e05-4bb4-a080-e527161c3a13","id":"072dd3e7-719f-45b2-bcc2-67878f86e6b5","width":614,"height":664,"filename":"1726747760199.png","type":"image/png","caption":"Screenshot of the Figma component description field a description of a component that's currently experimental.","border":false}]}
```

Loose thoughts on versioning in Figma

Before June 2023, it's safe to assume that most designers hadn't even considered the word "semantic" within their work.

It has arrived as part of the design tokens / Figma variables wave, and whooshed us all into a linguistic frenzy. What even is semantic, and why does it matter to **me**?

Well, it probably doesn't matter that much to all of us, because it is a design systems topic, and we're not all working on them! We can add *primitive* and *alias* into this bucket as well; terms on terms on terms.

**The terms**

I suppose we should probably define these terms before contesting them:

*Primitive*

When talking about a design token, it essentially means the raw value. The one for the value itself. For example, if you're familiar with Google's Material design principles, they have a large set of primitive values for colour:

* Purple 50 (#F3E5F5)

* Purple 100 (#E1BEE7)

* Purple 200 (#CE93D8)

* ...more colours...

* Purple 900 (#4A148C)

These numbers represent the darkness of a colour, 50 being the lightest and 900 being the darkest.

*Semantic*

This is where we introduce intention into our colour names. This means that:

* Instead of *Purple – 50*, they use "Surface Dim"

* Instead of *Purple – 500*, they use "Primary"

* Instead of *Purple – 700*, they use "On Primary Container"

As a designer using the colour, you don't need to know or care what primary actually looks like, it's just the primary colour you will use.

Hence, semantic because it's logical and has intention.

*Alias*

This is the process of referencing one value into another. Taking our purple / primary combination we would look at it like this:

*Purple 500 -> Primary*

The value of primary is purple 500, and it has been *aliased*.

**Alright Luis, what's the point of this article**

Over the past 9 or so months, I've become obsessed with semantics. Lots of people have.

"That's not semantic, try refactoring the name"\
"Primitives shouldn't be exposed to your design team, only the semantic values"\
"Primary means nothing, don't use that"

These are probably quotes I've said at some point.

I'm starting to reconsider whether we even need this semantic layer within token/variable architecture.

**-- From this point forward, I will be specifically talking about variables within Figma --**

It's a pretty bold turnaround, but hear me out for a second.

Variables within Figma have a feature called scoping. This allows you to say, for example, "this colour should only be used within a fill".

Whilst talking to a few friends on WhatsApp (hello [Luke](https://read.cv/finch), [Henry](https://read.cv/henrydaggett), [Hugo](https://read.cv/_hraymond), [Ollie](https://read.cv/strangutan), Scott, [Karl](https://read.cv/kejk), and [Gavin](https://read.cv/gavinmcfarland)) This sparked something for me recently, where I wondered whether scoping alone was the semantic modification we've wanted all along.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FK1SH3oBardJqKvpD8sAM%2F13361cbb-e754-46d9-8e0f-f069272df843.jpg?alt=media&token=e6a8e295-a294-401e-9294-891d055543f2","id":"13361cbb-e754-46d9-8e0f-f069272df843","width":800,"height":400,"filename":"scoping-whatsapp.jpg","type":"image/jpeg","caption":"Screenshot of the original WhatsApp message from Luis","border":true}]}
```

Ultimately, semantic variables are a level of scoping, allowing us to define specific implementation of the values we want to control within a system. And if there's one thing I know, it's that agreeing on naming conventions within a design team alone is a near impossible task, and then tossing it over the fence to your engineers is another battle that may be lost as soon as you pass over the figma.com link.

Why? Developers love frameworks. I was ~~un~~fortunate enough to have been raised in the world of web development back when Bootstrap was the de facto standard. It didn't last forever, but we have other frameworks now plugging that gap, for example Tailwind CSS or Radix.

Tailwind CSS is fantastic for rapid development, because a lot of the design decisions have already been made. This is most certainly the moment where you start sweating, because I said design...decisions. For example, Tailwind CSS has a robust and well constructed set of colours, ready and warm from the oven.

These colours are primitive in nature, not semantic. In fact, here's a line from their documentation:

`Tailwind uses literal color names `*`(like red, green, etc.)`*`and a numeric scale`*`(where 50 is light and 900 is dark)`*`by default. We think this is the best choice for most projects, and have found it easier to maintain than using abstract names like`**`primary`**`or`**`danger`**`.`

Notice the callout to not use semantic naming here. Hey, this might not be that big a deal, but is almost certainly rage inducing for those that swear by the good book of semantic naming conventions. You *can* alias within something like Tailwind CSS into a more intentional semantic naming conventions, but good luck explaining why those hours of development time need to happen.

For Radix, I'd recommend reading their entire documentation [page](https://www.radix-ui.com/colors/docs/overview/aliasing) on aliasing, as they run into similar issues with naming.

What I think may be worth us thinking about is how we can become better friends with our developers, and work on their turf, rather than trying to crowbar in something that may not benefit the relationship.

**Back to Figma variables**

What's stopping us from maintaining a single, primitive set of variables, named as such (e.g. red-300) to match your developer's framework, relying on scoping alone to bridge this gap?

This also maps back to our Material design example too. Best served with a visual.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FK1SH3oBardJqKvpD8sAM%2F90daf353-8ed7-4c1e-aa6d-0c63eeadda69.jpg?alt=media&token=7adc7b9a-a39b-45f5-85bd-4b00309150e7","id":"90daf353-8ed7-4c1e-aa6d-0c63eeadda69","width":1080,"height":768,"filename":"pedantic-semantic-scope.jpg","type":"image/jpeg","caption":"Screenshot of the Figma variables window for the Google Material colours","border":false}]}
```

The visual above shows our Material design colours for purple and teal, from 50 up to their darkest 900. 500 is highlighted, and has been scoped to just be available within frames and shapes.

This is exactly the same process we would go through for **semantic** variables, but we are only maintaining one collection here. This seems...logical? And perhaps less of a headache.

What would it look like with a real component example. Enter my favourite one, the toast.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Fpedantic-semantic%2Ffd9eac52-a389-4333-8cbf-6a6a733c0c8d.png?alt=media&token=45870d1d-bcb4-4f63-9e67-a3bfffc39195","id":"fd9eac52-a389-4333-8cbf-6a6a733c0c8d","width":1920,"height":960,"filename":"pedantic-tokens.png","type":"image/png","caption":"Toast component showing a comparison between the variables used. Left side is semantic, right side is scoped primitives.","border":false}]}
```

There is a drawback here that you can't scope deeper. For example, "this colour should only be available in these specific components". But what's stopping that from becoming an eventuality if it saves us time?

Another potential issue is "what about dark mode?" This for me isn't necessarily a null point, but something definitely worth contesting. If modes should eventually "come for free" within our designs, does it matter if purple-50 is very light in light mode, and dark in dark mode? I'm not sure if it does. Within Figma, this would mean creating two modes at this primitive level instead. Visual below.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FK1SH3oBardJqKvpD8sAM%2Ff0e63527-949d-4da3-af42-71b79b5fb2cf.jpg?alt=media&token=b4796a5b-2f90-4a5f-a2c0-a3f11329d8fd","id":"f0e63527-949d-4da3-af42-71b79b5fb2cf","width":1080,"height":768,"filename":"pedantic-semantic-scope-2.jpg","type":"image/jpeg","caption":"Screenshot of the Figma variables window for the light / dark mode example.","border":false}]}
```

Let me know what you think,\
Luis.

Are we too pedantic with semantic

When building tokens in our systems, the rules are always:

1. Primitive variables (not published)

2. Semantic variables (published), with every semantic variable named with "intention"

Right? Well, maybe not.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FNzED7abER3x2ReOvfwaP%2F939fb3e1-4b7c-42ea-aac5-4a03acf5ef4c.jpg?alt=media&token=50618cf4-d55e-444e-99e3-40fe920158dd","id":"939fb3e1-4b7c-42ea-aac5-4a03acf5ef4c","width":1600,"height":1200,"filename":"slide-3.jpg","type":"image/jpeg","caption":"An alert component in success, error, and warning variants alongside a screenshot of a Figma variables panel showing a list of semantic colours.","border":false}]}
```

This logic works very well for most components and screens, until we start to work within systems that require a higher level of personalisation. This might be in data visualisation, or software where you need a huge list of colour choices, for example a colour-coded pill list that you might have seen in Notion.

How should we approach this? When thinking back to a classic naming convention system, with `bg-primary`, `bg-secondary` etc, how would we go about setting up this level of flexibility? I don’t think we can!

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FNzED7abER3x2ReOvfwaP%2Ff0614582-0c6b-4493-a859-62530ade0a1a.jpg?alt=media&token=53f6f9f6-228a-4a92-952c-17b8ce06f415","id":"f0614582-0c6b-4493-a859-62530ade0a1a","width":1200,"height":800,"filename":"slide-6.jpg","type":"image/jpeg","caption":"A pie chart set in shades of blue, green, and purple.","border":false}]}
```

Instinctively, we might try to think through a logical and semantic naming system for something like a chart. `bg-slice` is where we might start. The second part of the chart? Mmm, `bg-slice-2`?

It doesn’t feel right, does it?

It’s at this point in naming conventions where we must juggle strictly aligning with a system and bending the rules to make discoverability easier, even if it feels wrong. Where it might feel wrong is introducing less semantic names within your collections to address these scenarios.

### **The primitive semantic**

Taking an example of something a bit closer to home, you’re probably familiar with the multiplayer cursors in Figma. These are a colour system in themselves, separate from the colours you may experience in other parts of the product.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FNzED7abER3x2ReOvfwaP%2Fdb58ab6a-4741-48a3-880b-c7610d0e9334.jpg?alt=media&token=0b0ca129-93a3-495c-83e7-58dd1a517a1c","id":"db58ab6a-4741-48a3-880b-c7610d0e9334","width":1200,"height":800,"filename":"slide-4.jpg","type":"image/jpeg","caption":"A laid out set of Figma cursors.","border":false}]}
```

Similar to the chart example before, how would we name these? `bg-cursor-1`? `bg-cursor-a`? Again, it doesn’t feel right.

So what do we do?

1. Publish primitive values?

2. Introduce a new token level?

3. Introduce non-semantic tokens to our semantic level?

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FNzED7abER3x2ReOvfwaP%2Fec691589-e644-4e79-bb34-7ff35da3cfb9.jpg?alt=media&token=d573128b-4562-4656-9013-1ed3e1d7aed4","id":"ec691589-e644-4e79-bb34-7ff35da3cfb9","width":1600,"height":1200,"filename":"slide-2.jpg","type":"image/jpeg","caption":"A label reading \"primitive\" and an arrow pointing to label \"semantic\". There's a separate arrow pointing from \"primitive\" to a label reading \"something else?\"","border":false}]}
```

At Figma, the multiplayer cursor tokens are stored within the semantic collection with primitive-ish names, which alias primitive values from a separate collection. These values are given a semantic start and a primitive end. For example, `multiplayerblue`, `multiplayerpurple`, `multiplayerred` etc.

This gives the benefit of not having to publish primitives, and means that `multiplayerblue` isn't fixed to a specific flavour of blue.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FNzED7abER3x2ReOvfwaP%2F68f62e20-8825-4856-8e0f-0e2cd42d5f09.jpg?alt=media&token=90a4a188-6295-4ed7-a413-3dcc5079f097","id":"68f62e20-8825-4856-8e0f-0e2cd42d5f09","width":1200,"height":800,"filename":"slide-5.jpg","type":"image/jpeg","caption":"The Figma cursors alongside a screenshot of the variables panel, showing the names for each cursor.","border":false}]}
```

There is an argument to suggest that we could pull these values out into their own separate variable collections called something like "decorative". This might be useful at a large scale where you have tonnes of detailed charts to work on.

The thing to consider here is that any new collection being introduced might put your modes at risk – how would you handle light/dark if you’re currently bundling those into the semantic collection? Perhaps your chart colours don’t differ in values across modes, in which case you will be fine.

If you go down the route of splitting these variables out into a separate collection, it might be worth considering an entirely separate *file*. The benefit here is that you would be able to publish and surface the variables specifically to whoever needs them, instead of it being available in every file within your account.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FNzED7abER3x2ReOvfwaP%2Fcdf81bbd-bd36-4f55-a7f9-d483e16697b1.jpg?alt=media&token=44baa8ac-740d-4a22-a655-fad40d5ec564","id":"cdf81bbd-bd36-4f55-a7f9-d483e16697b1","width":1600,"height":1200,"filename":"slide-1.jpg","type":"image/jpeg","caption":"A flow showing primitive going into semantic and separately into decorative, with semantic and decorative then flowing into a design file.","border":false}]}
```

This method essentially works for anything non-semantic or a "rule" deviation within your system. For example, your brand team need to create some illustrations and require a series of colours to support that. These could follow a similar principle – `illustration-yellow`, `illustration-grey` etc.

As a systems owner, you want to ensure the correct and approved variables are used, but it's way easier as a designer to use "yellow" than searching through a semantic but contextually challenging list.

Fixed primitives, flexible application.

A case for primitive semantics

The industry is in flux. 

Designers are out of work for [months](https://x.com/imvipinchandra/status/1790342610252358071), desperately trying to understand why their applications for jobs are ghosted, [maintaining databases of applications](https://x.com/sara_brunettini/status/1853797985945043181) just to keep tabs on the volume of rejections, being put through [rounds and rounds and rounds](https://x.com/darianrosebrook/status/1859246483415142547) of interviews, and yet we’re still seeing companies continue to hire at pace.

What keeps surfacing in my industry observations, and conversations I’ve had with hiring managers, is the need for designers to demonstrate *craft* in their applications and portfolios. 

This is great! Something actionable and at least within grasp as a learning opportunity. What trips me up though, is that I don’t think we have a collective understanding of what this actually means.

```cv
tweet
https://twitter.com/disco_lu/status/1862872714676957514
```

There seems to be an unwritten rule that you either “get it”, or you don’t, and there little advice from senior figures in the industry on how to develop this mysterious skill other than to just keep trying.

As someone who was previously stuck in design jobs because I couldn’t demonstrate my ability in an application – I once applied for jobs for approximately 12 months without a single interview – I feel this pain, and I think something needs to change so that others can be given a chance to demonstrate their quality.

Let’s take a look into some aspects of craft that I think are worth paying attention to.

### **Riff culture**

Something that does come up a lot when talking to people about craft, is the importance of “riffing”. In its purest form, this means doing more designs to find a solution, but again there is no true method or science we can apply to this as a designer.

Companies often revert to activities such as [Crazy 8s](https://designsprintkit.withgoogle.com/methodology/phase3-sketch/crazy-8s) to try and generate more ideas on a topic, and this is all part of the [design thinking](https://www.interaction-design.org/literature/topics/design-thinking)™️ process, but I still don’t know whether it’s actually a useful replacement for something else – obsession and instinct.

After all, [design thinking is dead](https://www.technologyreview.com/2023/02/09/1067821/design-thinking-retrospective-what-went-wrong/) isn't it?

What I believe is a risk in thinking exercises is [bikeshedding](https://www.techtarget.com/whatis/definition/Parkinsons-law-of-triviality-bikeshedding) – spending too much time on details that aren’t important. Are we ideating here because:

1. We are stuck

2. We have been told to

3. We don’t really know what we’re building

4. It’s actually useful for unlocking solutions

Each of points 1-3 present different challenges, but centrally we cannot replace a firm understanding of the problem with endless ideation.

I believe that this can also be trumped by an obsession for your profession and a hunger for constantly and consistently *paying attention*. I wrote more about this in my post **[Portfolios: Prioritise pixels over presentation](https://read.cv/disco_lu/pixels-over-portfolios)**.

I digress. 

Riffing is where your artboards or canvases stretch far and wide with potential ideas on a design. This, I believe, is table stakes in how we should work. Therefore, I can’t really pull this out as a key component of *craft* because it’s just how it should happen.

Where riff culture *does* come into play, is in the presentation of our ideas and work. Onto the next section.

### **Presentations**

Apple are (in)famous for internal presentations. Ideas require presentations, and to build great products, you need to present them. It’s worth having a look over this article for more information: [This is how we make slides at Apple](https://medium.com/adventures-in-consumer-technology/this-is-how-we-make-slides-at-apple-b8a84352bf6d).

Despite this being a semi-common known, I have been surprised over the years at the correlation between well-respected software and presentation culture within design teams. For example at Figma, designers frequently attend critique sessions with their (often rough) design work presented in slide format. These slides aren’t ugly either, they are designed. This may be surprising, but in order to get your ideas shipped you must be good at communicating them.

Often the common path to this is through a presentation. I’m a big fan of [Looms](https://www.loom.com/looms/videos) (my favourite tool is [Tella](https://tella.tv/), but at Figma we use Loom) – apparently in June I eliminated 130 meetings. A 2 minute walkthrough of something you’re thinking through can help unlock way more empathy in your ideas than a 300 word essay dropped into Slack, or worse no comms at all about what you’d like to build. 

Designers want to be taken more seriously at a strategic level within an organisation, and without a strong foundation in clear and concise communication about why something is important, we will forever struggle.

Additionally, I spoke to [Artom](https://read.cv/artom) from [Craft](https://www.craft.do/) who shared a similar approach to their ways of working. Craft are known for their exceptional attention to detail, and putting a lot of effort into the communication of ideas internally is clearly paying off. I remember him distinctly mentioning that they like to "feel" designs in their hands on devices. You really cannot replicate the end product in a static mockup.

At its core, this is about telling people what they need to know in a way that enables buy in for your own plans. Dropping people into an enormous Figma file to show off your work in progress ideas will not only slow down comprehension but start everybody off from a point of incoherence. This advice applies to portfolios too!

Lastly, writing is incredibly important for buy in. Spend more time writing down your thinking in a doc before jumping right into a design tool and fleshing out your ideas. A firm brief and “here’s my thinking” doc will elevate your seniority before you’ve even presented a pixel.

Takeaways: present your ideas concisely and coherently.

### **What is difference, truly?**

It wouldn’t be an article without a little existential crisis, would it?

What I struggle most with the craft argument is that, honestly, I believe we’re all kind of designing the same things. Aren’t we all striving to make white boxes on white boxes, some with grey borders and mostly wrapped in an 8px corner radii?

With the proliferation of common frameworks like [Tailwind](https://tailwindcss.com/) and [shadcn](https://ui.shadcn.com/), we’re saving an enormous amount of engineering time at the sacrifice of visual flair. 

You know what, that might be fine?

I am challenged because any seasoned designer knows that the engineers truly have the power to decide what does or doesn’t get built, and our dreams of *crafting* something unique can often be squashed at the first sign of a story point higher than 5. 

As a result, I feel that the dance we do around iterations and visual artistry to land a job are often left to the wayside when we are actually in seat. The popularity of design systems aids the argument of “this already exists, why make something slightly different just because you can?”. "Where's the data to support the need for this custom element?".

Mentioning same-same designs, the below image from Jem Gold in (I believe) 2017 is still true today. The original caption – unfortunately Jem deactivated their Twitter account – was “which one of the two possible websites are you currently designing?”. I don’t know about you, but this still makes me laugh 7 years later.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FP1V9tCd5OE4RaQOahhmv%2F59a8db1e-584e-425d-9e42-a7ee595956ef.png?alt=media&token=88e11295-3f42-4a9b-8e3a-13d2dfe46870","id":"59a8db1e-584e-425d-9e42-a7ee595956ef","width":600,"height":351,"filename":"image (2).png","type":"image/png","caption":"Jem Gold's \"which one of the two possible websites are you currently designing?\" Tweet","border":false}]}
```

What exactly are we *crafting* as the industry merges into a cohesive blob of sameness? Am I being cynical, even for me? I do believe that flair and brand differentiation is the truest lever we can find in a world drowning in software, which actually places me in a position to believe that design systems are at risk. In a good way, trust me. 

We must flex our brand and be more graphical in our approaches to design, made all the easier by the hyper powered computers we type on at the desk or carry around in our pocket – the processing power is there to try new things, not just to make more white boxes.

### **The hiring dance**

If you read almost any job posting for a designer, you’re guaranteed to read something along the lines of “must have an appreciation and flair for typography”. This sounds lovely! We want designers to know design foundations and appreciate a balance or fonts, weights, and sizes. 

What is funny here though is that in your job designing software, at almost no point in your entire software career will you be balancing multiple typefaces, sizes, and doing graphic design work. You might for promotional material outside of the software, but there's just no way you're going to introduce a new typeface for a specific flow of a design.

```cv
tweet
https://twitter.com/disco_lu/status/1828502255823397044
```

The likelihood is that you will be joining a team with an established set of brand fonts, in set sizes, with pre-composed styles or text components that you *apply* in your designs. It’s quite hard to get this wrong, so why are we placing so much emphasis on a designer’s ability to prove they are the next Erik Spiekermann? 

If it’s not your first job, you’re also probably coming from the exact same situation – a design system setup with typography properties agreed on with the brand team. This feels like pseudo science to me.

What we *are* being judged on is our ability to *organise* typographic elements. Again though, if your system is setup in a logical way, it’s almost harder to get this wrong than right. A Heading style is used for headings, Body for…you guessed it.

Again, perhaps this is a me thing, but visual design in software should be dony by someone who is defining the look and interpreting the brand into a delightful experience. This is indeed **craft**. However, most designers are not in this position, but are benchmarked on the same qualities. Most designers are excellent thinkers, doing the Lego thing with pre-built systems that the crafty visual designers are better at working on. Is organising benchmarked at the same level of craft as the visual nuance?

Perhaps we just need to split job titles again?

### **Is it process?**

Hello double diamond my old friend, I’ve come to hate on you again.

What I naturally look to when I hear the word craft is process. But process is a fuzzy word. What’s more, the best designers I talk to don’t read method books or stick to a rigid flow when producing great work, they *just do it*.

```cv
tweet
https://twitter.com/disco_lu/status/1772604958921183716
```

This widens into a challenging statement about what design actually is, which we may need to spend more time hovering over, but centrally great designers don’t start or stop with a job description. They contribute wider than their scope to figure out the best solution to the problem, regardless of whether it’s using paper, a canvas, some HTML, or a written document.

I don’t believe this can be process-ified, and no that’s not a word. What I do believe is that the riffing on riff is endlessly useful, but only at the point where you are clear on your goals as a team, collaborate to find the answer, and work from the point of view of a busy user just trying to get their job done.

As a slight anecdote, a few weeks ago I was working alongside the Figma dev mode team on a set of “[jobs to be done](https://jobs-to-be-done.com/jobs-to-be-done-a-framework-for-customer-needs-c883cbf61c90)” and it was **hard**. What’s worth noting is that this wasn’t designing per se, it was designing at large, in a cross functional team of design, engineering, data science, and advocacy.

Perhaps, yes, that does mean that we’re all designers, and we should celebrate that.

I (still) don’t know what “craft” means

With every change to a variable, style, or component, we must anticipate the downstream impact to a design file that is already consuming it.

If we reorder the elements within a component or change its visual appearance during the time at which a feature is being developed, we may disrupt the "handoff" process significantly, impacting the development costs and planned estimation time for build.

\-

A major version changes (in Figma) can happen in a bunch of different situations, here are a few:

1. A rebranding

2. A significant restructuring, with either styles or components

3. Naming convention changes

4. Keeping up with feature releases, for example changing from styles to variables for color

5. Asset locations are changing e.g. one component moves to a new library with different permissions / access levels

And a quick summary of each:

1. **Rebranding**

Significant visual identity change will impact color contrast, spacing, typography, and often impacts component structure too.

2. **Significant restructuring**

This is related to, but also separate from rebranding.

A visual refresh of a page within the same brand guidelines will often change how a component is architected, and therefore downstream changes in any instance of the previous component will break or change the layout considerably.

3. **Naming convention changes**

A pretty straightforward one! *Card* may become *Tile*, *Card* may become *Card – Product* etc.

4. **Updating for feature releases**

Variables are the most recent significant update here, but previous releases included component properties, or variants.

5. **Asset location change**

This one comes with an asterisk, because it's unlikely to happen but is worth bearing in mind. If you move a component to a library with different user permissions, consumers may lose *or* gain access. 

\--

### **Friction**

There will need to be friction introduced with a change like this. I repeat, **need**. 

A question we must ask ourselves is *where* we want this friction to occur.

**Another important thing to think about**

We need to know whether the business has a requirement to support concurrent versions. 

* Does one team work on version 1 and another version 2? 

* How do we plan to manage this?

Here are a few options to think through for mitigating this friction:

**Option 1: Friction for the library**

When playing out the idea of a major version introduction, there are a few options for components:

1. A new variant within the same component

2. A new component

3. An entirely new library

The severity of change here increases as we go from 1 to 3, but the control increases too. In order to make a decision about which option we might want to investigate, we need to know if this major change is affecting just a single component, or the entire library. AKA, do we version individually, or as a whole?

1. A new variant

A new variant within the same component is pretty simple to manage at an atomic level, but as soon as we introduce that new version into a larger pattern which *aligns to a previous version*, we are packing our bags and moving to Trouble Town, Ohio.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FQrtQdzEv0F1bcf6DWBMj%2F2a52b18f-3d24-4403-a9a3-308c8a3914de.jpg?alt=media&token=cb2a1387-1fad-4c46-81fb-05e288dd4b3c","id":"2a52b18f-3d24-4403-a9a3-308c8a3914de","width":1920,"height":1080,"filename":"mixed-versions-variant.jpg","type":"image/jpeg","caption":"An accordion item variant component which has had a new variant added, styled differently. Underneath the accordion item is an accordion, which has the item nested inside.","border":false}]}
```

It's this fragility which could make or break a rollout.

2. A new component

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FQrtQdzEv0F1bcf6DWBMj%2F75304d54-1650-4347-b864-50c583245fb4.jpg?alt=media&token=87026544-2874-4f5a-ba92-6150b165b150","id":"75304d54-1650-4347-b864-50c583245fb4","width":1920,"height":1080,"filename":"mixed-versions-instance.jpg","type":"image/jpeg","caption":"A \"current\" accordion item component alongside a \"future\" version, which has a different visual treatment. Below is a full accordion component, with the open accordion item selected, alongside a screenshot of the Figma properties panel instance swapper. In here, you can see there are two accordion items listed: the current and future versions.","border":false}]}
```

A new, replacement component provides you with the ability to split versions and provide a longer term deprecation / rollout. I might write about this in a different article.

Perhaps we create a new component, and add a suffix of "– Future", to indicate to consumers that it's coming soon.

The word "future" is TBC but right now it makes sense to me as a way to detach from a fixed version number, but to indicate it is *new*.

3. A new library

An entirely new library is a drastic change, and probably best served as part of a brand refresh where the entire visual direction is changing for every consuming design file too. I like this option though!

**Option 2: Friction for the design files**

Some design teams use files as throwaway artifacts – once a piece of work is finished, the file is retired.

Some design teams maintain single files forever, with ongoing overrides to existing assets, a branching workflow for managing changes, or a new page for each version. 

`🚨 If you use pages for versions, bear in mind that each time you inherit a library update, your file will be automatically updated to the latest. This will overwrite your pseudo versions and will give you a headache.`

Try to be the former! Files could, and possibly should, be snapshots in time, with our production product acting as the truth and not a file with 10,000 frames. 

(I was speaking to a designer at a very popular code repository management tool recently who told me that their files are often literal screenshots of the production app and designers draw over the top to create new features. I didn't tell you that 🤫)

**Inherited versions**

If we overwrite our components to upgrade their versions, and then embed these as instances in a larger pattern, we run the risk of inheriting a version before we're ready.

Take the image below showing an *accordion* item's visual appearance changing, and then being nested into an *accordion* component. Does *accordion* automatically become version 2 as well?  Or are we working with mixed versions? A question to discuss.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FQrtQdzEv0F1bcf6DWBMj%2F0969be0a-410a-4a95-b648-391a37fdf923.jpg?alt=media&token=e05b0577-3ff1-409a-9234-4980abb96ec3","id":"0969be0a-410a-4a95-b648-391a37fdf923","width":1920,"height":1080,"filename":"mixed-versions.jpg","type":"image/jpeg","caption":"An accordion item and an arrow showing it embedded in an accordion, presented vertically. Both of these have a label above them reading \"version 1\". This is repeated on the right side of the image, but the accordion item has been changed visually, and the label reads \"version 2\". The accordion underneath this one still reads \"version 1\", with a red circle around that label.","border":false}]}
```

**The choice**

The preferred route here is option 1 (friction in the system), even though it's your systems life which will incur said pain. Why? Because there are less people affected by the changes within the systems team compared to the amount of consumers of it.

Loose thoughts: Managing major versions in Figma design systems

There's something bugging me about icons.

Take a look at these two components, what's wrong? 10 points are on offer.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FTADes7puH6QzEQGQ8r83%2F0a3d9bbb-3e66-4ef9-ab3e-73142ae7ff98.jpg?alt=media&token=d1b82ee6-79a1-4557-b349-37867217c6d2","id":"0a3d9bbb-3e66-4ef9-ab3e-73142ae7ff98","width":1080,"height":640,"filename":"icon-bounding-boxes-comparison.jpg","type":"image/jpeg","caption":"Two light blue components with icons inside and a text string reading \"label\". The left component has a horizontal 3 dot icon, the right component has a vertical 3 dot icon.","border":false}]}
```

That's right! There are two problems:

1. The left padding is optically too large

2. The gap is too loose

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FTADes7puH6QzEQGQ8r83%2F12242bd4-668f-42ec-98f1-bd214db891e1.jpg?alt=media&token=e198f55f-f1d7-4bb4-b230-c6fe1c8afe82","id":"12242bd4-668f-42ec-98f1-bd214db891e1","width":1080,"height":640,"filename":"icon-bounding-boxes-annotation.jpg","type":"image/jpeg","caption":"Visual of the same two previous components, with a yellow annotation pointing to the issues described in the tweet","border":false}]}
```

When composing components like this (with an icon), the process is:

1. Nest an icon

2. Set preferred instances

3. Bubble up the icon to the top level for instance swapping

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FTADes7puH6QzEQGQ8r83%2F2fda08b1-d17a-4df6-ae88-d04f5309e8dc.jpg?alt=media&token=7c9cf157-9685-425f-9dc0-d44027798f4c","id":"2fda08b1-d17a-4df6-ae88-d04f5309e8dc","width":1080,"height":640,"filename":"icon-bounding-boxes-component-composition.jpg","type":"image/jpeg","caption":"A visual showing the process of nesting an icon inside another component. It also shows two overrides to the icon, one showing the original horizontal three dot icon and the second showing the vertical 3 dots.","border":false}]}
```

This is because of...bounding boxes.

They make sense because "consistency", but in practice introduce complications to consistent systems-oriented design.

What can be a perfectly set up grid of 24x24 icons in your system can create problems for pixel perfection in designs.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FTADes7puH6QzEQGQ8r83%2F3da86ce8-ea4a-482a-8e1f-4bf485bc5836.jpg?alt=media&token=14de24a0-db85-49fd-9518-e0696eb43dbf","id":"3da86ce8-ea4a-482a-8e1f-4bf485bc5836","width":1080,"height":640,"filename":"icon-bounding-boxes-outlines.jpg","type":"image/jpeg","caption":"A set of icons laid out on a black background. The icons are presented twice, once plainly and secondly with a red background and border. The previously used \"more vertical\" icons has a yellow arrow pointing towards the bounding box space with a label \"gross\".","border":false}]}
```

We're then forced to create specific space overrides for when bounding boxes are too large. This is optical design running its course, but as a systems person you scratch your head because of the magic numbers requirement for "Left padding 8, right 16", as an example.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FTADes7puH6QzEQGQ8r83%2Fe85dfd4f-ac30-471d-afff-a0d552c70740.jpg?alt=media&token=19fd7dc6-f38f-446a-93d5-38be08069b25","id":"e85dfd4f-ac30-471d-afff-a0d552c70740","width":1080,"height":640,"filename":"icon-bounding-boxes-custom-padding.jpg","type":"image/jpeg","caption":"A comparison of the problem icon within a bounding box and the solution – creating custom padding around the icon within the component..","border":false}]}
```

What **is** useful is height. There's an argument to suggest a height-based bounding box could create consistent touch point size (for accessibility).

The likelihood for horizontal sizing is that your icon will always be nested, for example in an icon button with a width anyway.

This could mean that icons are sized with their inherent width in the system, versus a consistent X rule It would remove the need for pixel overrides, and mean that icons should "just work" when placed as instances It feels like scalability.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FTADes7puH6QzEQGQ8r83%2F9e880e52-10c0-4d17-adf3-ff0d9ed4f462.jpg?alt=media&token=f7a77da4-de59-463b-8054-b1150f33300e","id":"9e880e52-10c0-4d17-adf3-ff0d9ed4f462","width":1080,"height":640,"filename":"icon-bounding-boxes-removing-space.jpg","type":"image/jpeg","caption":"Layout showing the proposal – horizontal bounding boxes are set to the width of the icon, not a consistent one. This means instances of both the horizontal and vertical three dot icons fit within the original component without manual spacing tweaks.","border":false}]}
```

### **Other things to think about**

**Inheritance tax**

When setting fixed sizes at the icon level (within the system) we're kind of making future decisions without the context.

Should the icon button be the place we decide on the icon's size, versus inheriting a choice?

**What if we need a fixed size?**

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FTADes7puH6QzEQGQ8r83%2F4f82f6a9-1d6e-4265-9400-2d59efdf4aa9.jpg?alt=media&token=068257fd-d428-4bff-8dc4-4734f1357ad3","id":"4f82f6a9-1d6e-4265-9400-2d59efdf4aa9","width":1080,"height":640,"filename":"icon-bounding-boxes-icon-wrapper.jpg","type":"image/jpeg","caption":"An annotation showing two illustrations horizontally. The left one has an icon button component selected in Figma, with a red arrow highlighting the width and height settings in auto layout, showing they are set to \"hug contents\". The right illustration shows outline mode within Figma, with the icon itself selected inside of the icon button. There's a red circle over the height and width settings, showing they are set to a fixed size.","border":false}]}
```

Taking a common example, an icon button. The likelihood is that your component is set to a fixed (or minimum) size in order to meet tap target sizes for accessibility.

This is a specific instance where we need the icon at a perceived fixed size too. But is that true? Is the size not defined by the wrapping button element?

To protect optical sizing, we can manage this by wrapping the icon in a div (in HTML) or frame (in Figma) to manually set its vertical or horizontal position.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Ficon-bounding-boxes%2F4a95d53e-337f-41e6-a401-8c92470010e7.jpg?alt=media&token=183be2b3-c666-4b5a-87d7-9d110a97a949","id":"4a95d53e-337f-41e6-a401-8c92470010e7","width":1080,"height":640,"filename":"icon-bounding-boxes-annotation-icon-list.jpg","type":"image/jpeg","caption":"An illustration showing an iconList component with a dotted pseudo bounding box.","border":false}]}
```

This would be the same if we were looking at something like an icon list, as demonstrated in the above asset.

\--

This article will likely be ongoing.

Thanks!

Do we really need icon bounding boxes?

Let me paint a picture.

You’re designing a new feature, a very shiny one, and you are creating components specifically for this new piece of work. Nothing out of the ordinary here! You then make a new file and need to use an instance of these components.

Hmm.

The work has also not been coded yet, meaning that these components don’t technically live inside the design system yet.

Double hmm.

**What should we do?**

Logic states that a component used in more than one file should be in a published library. I like logic! But, with the high chance of developer confusion from a “not quite ready” component – a lack of documentation, accessibility checks, proper naming conventions, correct token usage – being pushed through to production, and goals of a robust contribution model within the design system, we run into a wall pretty quickly where our brand new components live in *layer limbo*.

### **Solution #1 – No components**

One could argue that a component is a system-level decision, only created once we have full sign off on designs and they are ready to be built.

The argument stands, but anyone that’s spent longer than 30 seconds designing something knows how much more efficient we can be when we use components and instances. When designing, I try to *start* with components. Propagating changes to many instances and screens can save a tonne of time.

Yet there is still the useful framing of Figma as a place to ideate, not formulate. The canvas is the best place for freeform thinking, where we’re not limited by fixed variables, styles, or previous component decisions.

Does this design require a slightly different take on the search field? Overriding the existing library component may cause more harm than good, so creating a brand new frame styled the way you need might help to push the needle.

Keeping your layers and frames in a non-component state also helps you to keep a Work in Progress mindset, both when designing but also presenting your work to colleagues. 

It sounds good, but we still have the large inefficiency problem of having to them retrospectively turn everything into a component once your designs *have* been signed off. This could take hours for a large project.

Not so scaleable.

### **Solution #2 – Naming conventions**

Okay, so we still need components. The challenge we have though is communicating both to designers and developers that your components are either:

1. For design efficiency only

2. New to the system

**For design efficiency**

It’s a very common scenario when designing that you will need a component just for that piece of work. An example might be a list of items. In code, your developers will probably be passing data into a single list item, and the amount of items will be determined by how much data there is. On the design side, we have to be a bit more explicit with the amount of items, and a component makes this so much easier to manage.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FV8pHkQoov5wwoEUybOCk%2Fc2429160-bc44-47ce-a467-ad93631831e0.jpg?alt=media&token=82790be8-bc48-45bc-8007-38ca16e35902","id":"c2429160-bc44-47ce-a467-ad93631831e0","width":1920,"height":1080,"filename":"staging-libraries-list-item.jpg","type":"image/jpeg","caption":"A list item component inserted into a larger list.","border":false}]}
```

The challenge we have though is that we don’t want these to be coded, because their existence is purely to make designer’s lives easier. This is where we can use naming conventions and canvas organisation to communicate this.

Here’s my recommendation:

1. Create a page in your design file called **❖ Local components**

2. Create a section on this page for each component group e.g. **Search List**

3. Give this section a background color that isn’t white or dark grey, so it is presented differently in the assets panel. A light orange might work as a way to notify, but not alarm

4. Append each component with the label “– 🚨 **LOCAL**”

This is easier with a visual! See below:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FV8pHkQoov5wwoEUybOCk%2F431153af-54b4-4711-8305-5d8489a00dce.jpg?alt=media&token=60785e82-626e-4f5e-86a7-4f4f7cec68b2","id":"431153af-54b4-4711-8305-5d8489a00dce","width":1920,"height":1080,"filename":"staging-libraries-sections.jpg","type":"image/jpeg","caption":"A Section in Figma with a local component inside.","border":false}]}
```

And the assets panel:

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FV8pHkQoov5wwoEUybOCk%2F9b3328a3-808d-4c72-a2e3-36beace6ff79.jpg?alt=media&token=96cfc044-ebef-44d5-956f-aaa92316025b","id":"9b3328a3-808d-4c72-a2e3-36beace6ff79","width":1920,"height":1080,"filename":"staging-libraries-assets-panel.jpg","type":"image/jpeg","caption":"The Figma assets panel showing a component set on top of a light orange background.","border":false}]}
```

This is great, but we still have the problem of not being able to use this component in another file. We don’t want to turn this design file into *another* library file – we need another solution. This will be covered in solution 3.

**New components**

For a new component that we do want to code and push into the main library, it must go through a contribution model back into our design libraries, but this introduces a potentially disruptive workflow for anyone in the systems team managing the library and also those on the consumption side. 

We can’t be constantly adding and publishing work from the library, it’ll cause planning issues for maintainers and update blindness for consumers. This is a pretty common scenario I see in newer teams, and I like to call it the good-ol’-fashion-component-tail-chasing. It’s catchy. The alternative name is the *component ouroboros*, which is a lot easier to remember.

Anyway, we need to keep efficiency high and prevent adding bottlenecks to the design team who want to move their tickets from *in progress* to *ready for review*.

**Solution #3 – Staging libraries**

When building components in a new design that need to be pushed back into a main library and eventually coded up, the immediate thinking probably “let’s cut and paste the component into the main library and publish!”. This makes sense on the surface, but unfortunately falls apart quickly when you are running multiple concurrent versions of designs, or you need to prevent certain components from being available to the entire team.

This is pretty common in a workplace where you run frequent A/B tests, or have a very healthy culture of iteration and experimentation via components and need to have a situation where *Feature A* gets *Component A* and *Feature B* shouldn’t know it exists.

A way around this is what I call **Staging Libraries**. These are *additional* design system libraries in Figma, where your specific team, feature, squad, whatever can create what is in effect an extension of the system for your specific piece of work.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FV8pHkQoov5wwoEUybOCk%2F879ab959-5083-4c37-b07f-58a691b66b68.jpg?alt=media&token=38360c2d-b1d4-4da5-957f-9a7d7859bc44","id":"879ab959-5083-4c37-b07f-58a691b66b68","width":1920,"height":1080,"filename":"staging-libraries-staging-production.jpg","type":"image/jpeg","caption":"Two Figma file thumbnails, one for a staging library and the other for a production library.","border":false}]}
```

Taking our list item component from before, we would cut and paste this out of our single design file and into the design library that is local to our piece of work or team. This provides us the benefit of being able to access more components in more files, whilst also not muddying the main design system library file and confusing maintainers and consumers.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FV8pHkQoov5wwoEUybOCk%2Fd67d3547-93e1-4250-94f5-2cdb29cef3bf.jpg?alt=media&token=0d45a84e-dd5e-4b91-b4cf-6210bd5096fd","id":"d67d3547-93e1-4250-94f5-2cdb29cef3bf","width":1920,"height":1080,"filename":"staging-libraries-contribution.jpg","type":"image/jpeg","caption":"The same thumbnails are before, but with an arrow pointing from the staging library to the production library, there is a label underneath reading \"contribution to main system when ready for production\".","border":false}]}
```

The additional benefit of this staging library is that, like a staging server in code, it can be messier! We don’t need to be concerned with organisation, robust documentation, or even naming conventions. As it is staging and not production quality, it’s a way to ensure high efficiency whilst the high standards of the main system can be saved for later, perhaps when this component does indeed need to be global.

### Component progression and library tiers

Another way of looking at component location is in *tiers*. We start at tier 3 with our local components, and they are likely to be pushed into tier 2 (staging), and ultimately land in tier 1 (production library).

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FV8pHkQoov5wwoEUybOCk%2F22fcc1ac-dc2a-4fd9-afad-222ae9fe23a0.jpg?alt=media&token=9dab4a6d-3f18-4f3c-b040-93bc34a9ebcc","id":"22fcc1ac-dc2a-4fd9-afad-222ae9fe23a0","width":1920,"height":1080,"filename":"staging-libraries-tiers.jpg","type":"image/jpeg","caption":"A visual representation of the 3 component tiers.","border":false}]}
```

This should help frame or decide where a component should live based on where it needs to be used and whether it should be pushed to production yet or not.

See you next time!

Loose thoughts: Staging component libraries

I have a hunch – “semantic variables” aren’t what we think they are.

Are you suitably provoked? Okay, let’s proceed.

The – or at least my – definition of *semantic* is that as a consumer of a design system, I can confidently and predictably pick a variable. That seems pretty straight forward, and something we should also feel confident building for, but I don’t think this is happening at scale.

### **Which brand?**

If we take the example `bg-brand`, a quite common name for a colour variable. Sure it tells me it’s a background and it has a brand color as the fill.

But I challenge this simplistic view:

1. In a multi-brand organisation, *which* brand is this?

2. In an organisation with multiple options for brand color, *which* one is it?

3. In a situation where you have different tints or emphases of a brand, *which* one is it?

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F4d83e044-bcaa-4080-b90a-00eb3736531a.jpg?alt=media&token=6fcfb90e-cb88-4c82-bacb-8c387dd62984","id":"4d83e044-bcaa-4080-b90a-00eb3736531a","width":1920,"height":1080,"filename":"island-brands.jpg","type":"image/jpeg","caption":"A visual exploration of Brand A and Brand B, showing their primary and secondary colours.","border":false}]}
```

For those working in brands where your primary brand colour is unfortunately orange or yellow, you are likely trying to run away from using them because of their challenges with accessibility contrasts. This may mean that you use a secondary (complimentary) brand color, acting as a pseudo primary colour when used in an ordinal system.

In this scenario is primary…secondary? No, it’s still primary, we just don’t use it. Thus forcing a thinking exercise where you convince yourself that secondary is primary.

To those of you working with brand colours that are indeed red, yellow, or any colour typically associated with a component’s sentiment, I wish you luck.

### **Latinate ordinal numbers**

Despite the above title looking like gibberish, that’s the technical term for *primary*, *secondary*, *tertiary* etc. These are also very common naming conventions in the land of variables.

Despite familiarity and commonality, I'm slowly but surely coming round to the idea that `background-secondary` is not a semantic variable. Semantic should mean clear intent, but an ordinal system like primary, secondary, and tertiary doesn't actually tell you *where* they should be used and for *what*.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F786054c4-2acc-451d-be0c-47407ce31b55.jpg?alt=media&token=376aa864-4fb9-428e-aa45-f196a6b8c20d","id":"786054c4-2acc-451d-be0c-47407ce31b55","width":1920,"height":1080,"filename":"island-intent.jpg","type":"image/jpeg","caption":"The Figma variables panel, showing a set of colour variables. There is a pink circle around a group for bg/default. There is a label on the left hand side circling two groups – default, neutral – with a label reading \"fuzzy intent\". There is a second arrow on the left hand side pointing to another set of groups – brand, positive, warning, danger, disabled, utilities – with a label reading \"clear intent\".","border":false}]}
```

> The above image was originally posted as a [tweet](https://x.com/disco_lu/status/1848711886839165003).

Don’t get me wrong, I spent *hours and hours* playing around with these methods of building color palettes and components whilst working on [Simple Design System](https://www.figma.com/community/file/1380235722331273046/simple-design-system) at Figma. What became tricky during this work was building  predictable combinations of colour, which I believe is central to the successful adoption of any system.

I kept banging my head against a wall when trying to compose components, patterns, and screens where I wasn't even sure myself which ordinal to apply in which position; and I made the system!

For those building a design system, a latinate ordinal system is assumed knowledge based on a widely accepted belief that it is *the right thing to do*. Fantastic systems like [Polaris](https://polaris.shopify.com/) popularised this naming convention, and that’s great! But for those *not* working in a systems team, are these conventions understood?

### **In practice**

Let’s say you’re building out a screen. The container background is white, and you’d like to add an informational section in a light grey – a common scenario.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F2c630989-5d31-40cf-bcf3-b36e20dfac68.jpg?alt=media&token=d4a46ac9-ab79-4f13-8bd1-0209b73e2ad7","id":"2c630989-5d31-40cf-bcf3-b36e20dfac68","width":1920,"height":1080,"filename":"island-callout.jpg","type":"image/jpeg","caption":"An example page layout. There is a light grey background, with a white container in the center. Within the container is a set of dummy text, set in a block font. In between two paragraphs, there is a light grey coloured block with more example text inside.","border":false}]}
```

As a designer, what is your instinct when applying a colour to this section? Based on familiarity within commonly referenced systems, you’d be forgiven for suggesting something like `background-secondary`.

Now, because I spend way too much time thinking about this, I have some questions:

1. Would we choose secondary because we want it to look less intense than the high contrast white?

2. Or secondary because it’s the second most prominent element on the page?

3. Or secondary because of the hierarchy within a section?

This all leaves me with more questions than answers, and suggests a black hole of documentation is ahead.

What baffles me even more here is that in terms of elevation, this secondary element is *above* the background, which would be safe to presume is in fact *primary* in this case. It’s secondary, but in reverse order. My head hurts.

### **Dark mode doesn’t help**

In dark mode, the colors become interesting too because as the elements raise in elevation, they typically get *lighter*. This means that the secondary in reverse problem pops its head into our lives yet again, with my semantic brain exploding at the thought of something named secondary being more prominent than we want.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F063977cf-9d98-460e-867b-04b4a3f9f09e.jpg?alt=media&token=2c005ff2-2da5-4348-9d1a-8efd45a0c5c1","id":"063977cf-9d98-460e-867b-04b4a3f9f09e","width":1920,"height":1080,"filename":"island-dark-variant.jpg","type":"image/jpeg","caption":"The same dark mode variant as before, but the inner callout section has been made darker than the background it sits on.","border":false}]}
```

You could recess the element, making it feel more secondary, yet it’s still standing out like a sore thumb. And…we’re digressing very far from the original point now.

### **Deepening the problem**

I’ve spent a lot of time here talking about the problems of the primary and secondary variable naming conventions, but tertiary also doesn’t help us.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2Feb4e4c89-91a9-4a92-9ceb-f46a6a45bd40.jpg?alt=media&token=2cf90bcf-75fc-449d-9879-3b78187aef0e","id":"eb4e4c89-91a9-4a92-9ceb-f46a6a45bd40","width":1920,"height":1080,"filename":"island-tertiary.jpg","type":"image/jpeg","caption":"The light mode example section from before, but a \"sidebar\" style element has been added to the right. There is an arrow pointing to its background, with a label \"tertiary\".","border":false}]}
```

In this example, which I’ve arguably engineered to be confusing, we have a tertiary sidebar element which definitely has less prominence! It works! But secondary still exists as being more prominent against the white.

With tertiary here, it’s the **second** most prominent *main* element on a page, but is using a **tertiary** value. Someone please help.

Just to be clear here, these are deep and perhaps unnecessary questions, but that’s what I’m here for.

### **Components**

Wait, isn’t that little banner inside the main container actually a component and all of this is a useless academic investigation? Probably.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F010d3702-e382-4bcb-8a52-31504866f470.jpg?alt=media&token=d56c7cd8-d8dc-40ab-b6b4-19eb9ff6bcfe","id":"010d3702-e382-4bcb-8a52-31504866f470","width":1920,"height":1080,"filename":"island-component.jpg","type":"image/jpeg","caption":"The callout section is now wrapped in a bounding box, similar to the selection style of Figma elements. It has a label above reading \"❖ Callout\". There is an arrow pointing to its background with the label \"Bg callout\".","border":false}]}
```

This is essentially what I’m getting at – a semantic decision should be understood and predictable. There’s a challenge with naming where we must strike the balance between too narrow (specific) and too wide (non-specific).

In my opinion, a latinate ordinal number is not semantic because it’s too open for interpretation and therefore too wide. In a similar vein, using a different example, `shadow-video-thumbnail` is too narrow, and restricted down to too specific case, compared a more generic, useful, and scalable `shadow-card`. Cards are everywhere, thumbnails are perhaps on just a few pages and this smells like a red flag for consistency being deviated in a system.

What I feel here is that because we are introducing ambiguity with an ordinal system, we’re straying far from semantic conventions and back into the deep dark world of primitives.

### **Are ordinals actually primitives?**

Here’s a challenge: is `background-default` actually a…primitive? What does `background-default` even mean? Let's assume we're working with `#fff` here, should we apply that to every single white element? When you put it like that, the answer becomes a very clear "no".

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F10c8a3bc-e8e2-4584-a436-8f9abfe50d3d.jpg?alt=media&token=8ce5cb77-fb51-4147-b929-b25e4a92ea36","id":"10c8a3bc-e8e2-4584-a436-8f9abfe50d3d","width":1920,"height":1080,"filename":"island-light-dark-names.jpg","type":"image/jpeg","caption":"A light and dark mode representation of a simple box on box layout. The background has a label \"background-page\", the foreground \"background-section\".","border":false}]}
```

This is specifically the case when you look at a dark mode implementation. White on white may be totally fine in light mode, but we likely want to introduce tonality in dark mode, perhaps a lighter foreground. Our `background-default` falls on its face very quickly, because we need nuance across modes.

A more specific `background-page` would allow for a fixed white / dark grey across modes here, whilst a `background-section` would promote deviation for the light / dark switch.

### **No variable is an island**

In isolation, a variable has no impact. Any colour decision we make is only relevant in the context of *other* colours. A radius variable must be balanced against its child and parent, so that we can build visually balanced corner radii in our designs. Any line height value is variable when used with different fonts and casing.

Therefore, no variable is an island. They must work together.

It’s at this point where we start to challenge all previous knowns about naming conventions because we need to consider *pairs*. Does `color-text-secondary` only work on `color-background-secondary`? That’s unlikely, but when looking at colours with a hue, we may end up there.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F8a8f157a-e321-4fcc-9ec8-fc9ab1eca277.jpg?alt=media&token=00b703fa-f437-459b-ab74-e0c43edbc085","id":"8a8f157a-e321-4fcc-9ec8-fc9ab1eca277","width":1920,"height":1080,"filename":"pills-light-dark.jpg","type":"image/jpeg","caption":"A pill component variant set in varaious different colour schemes, in both light and dark mode.","border":false}]}
```

When building [Simple Design System](https://www.figma.com/community/file/1380235722331273046/simple-design-system), I toyed for *hours* trying to build a complimentary component set for badges and messages. We scrapped this idea in the end for the sake of simplicity, but the token system does still exist, presented below.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2Fc5c756bf-2281-4272-a3b1-a79a03598026.jpg?alt=media&token=99410b85-6e51-4b3d-8ae5-4d843232c9cc","id":"c5c756bf-2281-4272-a3b1-a79a03598026","width":1920,"height":1080,"filename":"island-colour-pairs.jpg","type":"image/jpeg","caption":"FIgma variables, showing groups for text and background colours and their combinations / pairs.","border":false}]}
```

The challenge is that you, as a consumer of these variables, have no idea that they are recommended pairs. There is nothing stopping you from applying `text-warning-tertiary` onto `background-default` and failing accessibility ratio targets of 4:5.1 even though it is a very close 3.97.

### **Linting**

Where I believe this lands us is a world relying on linting to catch system deviations. Linting has become *the* way to ensure that designs are accurate, accessible, and consistent, but is this happening more often than we need to based on the arguments above?

An unpredictable search experience for consuming variables introduces a point of failure in usage. This trickles down to teams requiring more linting to catch usage errors. The lower our (the designer) confidence in the choices we are making, the higher the requirement for someone else to lint our work.

I can see this leading to a dissatisfied team.

### **Semantic, but at the component level**

I believe that our semantic dreams are still achievable within this ordinal context, but only at the *component level*.

A primary button is very clearly defined! So is a secondary one! This makes me happy. The values within it though are where we return to the predictable, searchable, and self-documentating variable values from before – `color-background-action`, not `color-background-primary`.

Just to re-clarify, primary here is ambiguous in that it insinuates the most used element, but in reality is the most prominent. A primary button however, is way clearer in how it should be used.

### **The problem with default**

If you’re building any software in the year 2024, there’s a high likelihood that you have a set of very common patterns – *cards*, *panels*, *popovers*, and *toolbars*. These often share the same properties, perhaps a background color.

Similar to a previous example, when we introduce branding or system-level dark and light mode switches, we may want to deviate from this notion that they are all using the same values.

This is where we often come across…the **default problem**.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F9b0f3c82-9208-414b-bb63-00a6773201b9.jpg?alt=media&token=c97b342b-1d4e-468b-b37b-85b90e8748f6","id":"9b0f3c82-9208-414b-bb63-00a6773201b9","width":1920,"height":1080,"filename":"island-default.jpg","type":"image/jpeg","caption":"An example white page, with a white section on top, and a white popover on top of that.","border":false}]}
```

Again, we’d be forgiven here for following common accepted knowledge that your most used element in a system is called the default option. I prefer the word *base*, but that’s a different conversation. Anyway, we hit another dark mode wall when we want to use elevation to indicate elevation.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F6a3914ce-d814-47a7-b5a7-dc75c6c272cf.jpg?alt=media&token=02238e56-3d10-4460-b1b1-bf2a5fc45ceb","id":"6a3914ce-d814-47a7-b5a7-dc75c6c272cf","width":1920,"height":1080,"filename":"island-default-dark.jpg","type":"image/jpeg","caption":"The same section and popover combinations from before, but set in dark mode. Here, the colours are not all the same, with them getting lighter as they elevate.","border":false}]}
```

As your elements gets *closer* to the eyes, you are likely to want to use a lighter color in dark mode. This means that default needs to be split, and we lose our control. Designers at this point have probably detached your variable and gone freestyle.

This is why it’s logical to split these variables up into their dedicated end points or use cases. `background-default` doesn’t scale across modes, so introducing `background-page`, `background-popover`, and `background-section` enabled variance within the system, whilst still protecting your goals of cohesion and contrast.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FihhFrv4MD1JbuqCjRsm3%2F603ef2b2-60e6-467e-86df-03363456145f.jpg?alt=media&token=e861a0b1-9f18-4e0b-b2cc-d20f68d57b54","id":"603ef2b2-60e6-467e-86df-03363456145f","width":1920,"height":1080,"filename":"island-pattern-tokens.jpg","type":"image/jpeg","caption":"A visual showing light and dark mode variations of the previous screens, but the variables applied are specific – background-page, background-section, and background-popover.","border":false}]}
```

`background-card` is more discoverable when you’re making…cards, `background-panel` for when making…panels, `background-popover` for…you get the idea.

These are likely to share the same values, in fact they almost certainly will, but I don’t think this is a problem. The marginal memory increase in your token file is far outweighed by the efficiency and predictability gains on the consumer side. Hey, it may also reduce the need for so much linting.

It may sound like I’m ringing an alarm bell for component-level variables here, and you know what? Maybe I am on the surface, but this aligns with my proposal for *Functional* and *Presentational* tokens from the T+CPS framework pitched over in my other article about [atomic design](https://read.cv/disco_lu/rethinking-atomic-design).

A `panel` is a *presentational token*, a `tab` is a *functional one*.

### **Token pairs**

Finally, and very quickly, I'd encourage you to watch this snippet from the Asana talk at Figma's Schema conference. Here, they talk about colour pairs, which I personally really like, and think it could be more widely used.

```cv
youtube
{"url":"https://youtu.be/ylDed18OVdY?si=bbIz4Qwx3sTN2u4k&t=1031","width":200,"height":113,"thumbnail":"https://i.ytimg.com/vi/ylDed18OVdY/hqdefault.jpg"}
```

That was a lot of words. Let me know what you think!

💡 Loose thoughts: No variable is an island

Having played around with typography variables *quite a lot*, here's some structure advice!

Set up two collections:  

1. Typography primitives

2. Typography 

Number 1 will save you a tonne of time later on because of how efficient aliasing can be.

### Typography primitives

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FlSonxE9PEThEl2hzL4kc%2Fefeefbd9-dc78-4206-a7a4-cc4ddb8dce7d.jpg?alt=media&token=24812301-83f6-4c97-9d26-3edf8f223f5a","id":"efeefbd9-dc78-4206-a7a4-cc4ddb8dce7d","width":2160,"height":2160,"filename":"font-families.jpg","type":"image/jpeg","caption":"Showing the Figma interface for a \"typography primitives\" variables collection","border":false}]}
```

Within the **Typography Primitives** collection, set up variables for your system's font families. The easiest naming convention here is to follow the font type e.g. *Font Sans*, *Font Serif*, and *Font Mono*.

**Font scale**

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FlSonxE9PEThEl2hzL4kc%2Fd954c18b-4b46-4091-8cb8-e300ddce9b6b.jpg?alt=media&token=b78dbf77-1ea1-4866-9e37-203850507bcf","id":"d954c18b-4b46-4091-8cb8-e300ddce9b6b","width":2160,"height":2160,"filename":"font-scale.jpg","type":"image/jpeg","caption":"A screenshot of the font scale group within the typography primitives collection","border":false}]}
```

Additionally, within this collection, create variables for font *Scale*. These match your lower and upper limit font sizes, which will be defined by how your brand is set up. 

Scale here is a useful more generic word compared to size, which also won't confuse size within your larger system. For example, a small or large component may be confused with your type primitives. This also aligns a lot closer to font size scale factors e.g. golden ratio.

> Scale will typically match a calculation-based system in your code setup (usually REMs in CSS). A bit more info about this can be found over on [CSS Tricks](https://css-tricks.com/almanac/properties/f/font-size/). There are many different units for fonts, but that's a rabbit hole for another time.

You may need 3, 5, 10...100 variables for your scale, depending on how wide your system goes. Do you have mobile / web / tv? This will increase the amount of variables that you need to support here, but you can see the power of supporting many different outputs from a single primitive collection.

**Font weight**

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FlSonxE9PEThEl2hzL4kc%2Fc11e23be-9668-4555-9cbe-5b7456a9b2ba.jpg?alt=media&token=39132560-297f-4d02-b008-8a3aff488eee","id":"c11e23be-9668-4555-9cbe-5b7456a9b2ba","width":1080,"height":1080,"filename":"font-weight.jpg","type":"image/jpeg","caption":"Screenshot of the Figma variables panel showing a Font Weight group within a collection","border":false}]}
```

Within Typography Primitives, I advise including *Font Weight* variables too. 

The easiest way to look at this is that you will need:

1. Number variables for weight e.g. 100, 200, 300. This matches the CSS number scale, more information over on [Mozilla](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight)

2. String variables for style e.g. italic, bold, oblique

This is confusing to begin with, because font weights work with both number and string variables! Additionally, Figma works differently to CSS.

In CSS, you can write:

```
p {
    font-style: italic;
    font-weight: bold;
}
```

However, in Figma, these are a *single field*. This presents us with a decision and/or a challenge – we **can't** write *700 italic* as a single number variable, but we **can** write *Bold Italic* as a string variable. 

Hopefully this helps when trying to plan out what variables you will need to create for your text styles. 

But wait! There is one more thing. Not every font sets up their font weights and styles in the same way, meaning *Semi Bold* in Inter, is actually *SemiBold* in Roboto 🤯. This means we would need to create two variables.

> This is explored more in my community file [Typography variables: System fonts boilerplate](https://www.figma.com/community/file/1364979538897082048).

### Typography collection

**Font groups**

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FlSonxE9PEThEl2hzL4kc%2Fd2d2ac03-aef3-4414-b7a8-63db31bc9d5a.jpg?alt=media&token=7a8cbb7f-3534-4910-906e-688f2cc772de","id":"d2d2ac03-aef3-4414-b7a8-63db31bc9d5a","width":2160,"height":2160,"filename":"font-groups.jpg","type":"image/jpeg","caption":"The typography collection, showing groups for each font style","border":false}]}
```

For efficiency, in the main *typography* collection we create groups for each of our composed styles – for every *text style*, we create a variable group.

This looks like duplication, but will save you a lot of time later on. I promise! We can alias each primitive that we created earlier into these more semantic variables.

This is beneficial in a few ways:

1. If the brand sans serif font changes, instead of altering every single text style's definition, we change a single primitive

2. If a style's size needs to change, we remap to a variable within its group, or change the primitive scale value. This reduces the need to change individual style values, which in a large system may be out of your hands

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FlSonxE9PEThEl2hzL4kc%2F73776a66-10b1-4a40-a16f-e3bcdd8718a4.jpg?alt=media&token=8132d707-b9c8-467a-9f0e-f479d45f058b","id":"73776a66-10b1-4a40-a16f-e3bcdd8718a4","width":3200,"height":2160,"filename":"type ramp.jpg","type":"image/jpeg","caption":"The variables collection and corresponding type styles. There are arrows pointing from the variables into the type style that uses them","border":false}]}
```

With this approach, our variables are piped straight into the text style! We outsource the heavy lifting to the variables panel, and the type style becomes the user-facing end result.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FlSonxE9PEThEl2hzL4kc%2F69e307cf-bf5f-402f-8883-a4777a673fe5.jpg?alt=media&token=61d22353-02d3-42ab-ad01-b03d30da8fb1","id":"69e307cf-bf5f-402f-8883-a4777a673fe5","width":3200,"height":2160,"filename":"type ramp styles.jpg","type":"image/jpeg","caption":"A swatch style layout for 3 type styles, showing how their variables are used for their values.","border":false}]}
```

This is all explored in the [Simple Design System](https://www.figma.com/community/file/1380235722331273046) kit, available on the Figma community too.

See you next time 👋

\--

\~ [Original Tweet thread](https://x.com/disco_lu/status/1816860352090636555) \~

Loose thoughts: Typography variables structure

* Bias for action

* Talk to the room you're in: kick acronyms and buzzwords to the kerb

* Over-communicate project status

* Bullets, not paragraphs

* Talk slower

* Share everything you know

* Build a consistency muscle

* Ask for help

* Less "I", more "we"

Original tweet: https://x.com/disco\_lu/status/1781316093052629064

Career advice

## An idea 💡

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Fplo9LTyXyc7S74aji55Q%2Fce479095-92be-4a16-af82-8547185029b5.png?alt=media&token=5d420385-ced4-4f40-a5db-1fc948924030","id":"ce479095-92be-4a16-af82-8547185029b5","width":3840,"height":2160,"filename":"F8FW3mcXUAA28uG.png","type":"image/png","caption":"","border":false}]}
```

If your hover states are consistently within the same colour range e.g. adding 30% black to \*anything\* that is hovered, then instead of creating variables for every single variable's hover state, you create a single ––hover variable and use it within a composite style.

### With a card and tab example

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Fplo9LTyXyc7S74aji55Q%2F585f5aac-1922-46ac-a030-a14e433c70d0.jpg?alt=media&token=63059478-20f3-4748-b34f-335014a5134d","id":"585f5aac-1922-46ac-a030-a14e433c70d0","width":2160,"height":2160,"filename":"F8FZNKNXoAAvSn-.jpeg","type":"image/jpeg","caption":"","border":false}]}
```

Where it quickly falls apart is if your colour adjustments are more manual, or if your colours don't fall within the same visual range.

My initial palette differed wildly, meaning that manual adjustments were a requirement.

You could have several composite hover **rules** though 🧐

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Fplo9LTyXyc7S74aji55Q%2F76e08c86-5b4d-4735-b084-10995691e4f7.jpg?alt=media&token=f3ced441-27ae-4279-92de-62f3f790da25","id":"76e08c86-5b4d-4735-b084-10995691e4f7","width":3840,"height":2160,"filename":"F8Fbh9iWoAAtTQh.jpeg","type":"image/jpeg","caption":"","border":false}]}
```

If anything, this approach it can highlight the differences in your colours. If you can bring your colours all within the same saturation range, this idea would work.

### Further thoughts

Thinking about this a bit more, I don't think a specific --hover variable is needed, it might be too specific to that interaction.

If your system uses a single mode (light / dark), then you could get away with something like this:

`––darken-interactive` \
`––darken-subtle` \
`––darken-strong` \
`––lighten-interactive` \
`––lighten-subtle` \
`––lighten-strong` \
`––brand-subtle` \
`––brand-strong` \
`––accent-subtle` \
`––accent-strong`

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Fplo9LTyXyc7S74aji55Q%2Fc55c6aba-6f05-4591-b9f1-19d62c5272d0.jpg?alt=media&token=5d5a5f86-9bd7-4321-8db2-8dd0e1fa062d","id":"c55c6aba-6f05-4591-b9f1-19d62c5272d0","width":2880,"height":2160,"filename":"F8UZhuJXoAAJ4ww.jpeg","type":"image/jpeg","caption":"","border":false}]}
```

It introduces two groups into the variable structure: 

1) Modifier – System: This is where you store the fixed darken / lighten variables \
2) Modifier – Brand: Any brand coloured tints you might need

They are both offered in subtle, interactive (for the previous hover), and strong.

If you are using multi modes (light **and** dark), then abstracting the names out will probably work.

So instead of lighten/dark – because they don't make sense in the other mode – we use `--overlay` and change the values in each mode.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Fplo9LTyXyc7S74aji55Q%2F7c81448d-c958-45ce-a259-7206f9b53fbb.jpg?alt=media&token=bb2314cd-3635-4a81-9432-01d76ae7bf5b","id":"7c81448d-c958-45ce-a259-7206f9b53fbb","width":3840,"height":2160,"filename":"F8UaWI2WoAEbvKs.jpeg","type":"image/jpeg","caption":"","border":false}]}
```

But what about when we need `black 6%` to always be `black 6%`? 

This would likely call for a fixed variable value across modes, so we'd get: 

`––overlay-fixed-dark-subtle`\
`––overlay-fixed-dark-strong`\
`––overlay-fixed-light-subtle`\
`––overlay-fixed-light-strong`

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2Fplo9LTyXyc7S74aji55Q%2F95c28aa3-2dab-4fa6-9e86-3d5e6af42662.jpg?alt=media&token=fd9dbe4a-a355-44ff-870b-b22f079d1c1d","id":"95c28aa3-2dab-4fa6-9e86-3d5e6af42662","width":2880,"height":2160,"filename":"F8Uaqj-XsAAnZdq.jpeg","type":"image/jpeg","caption":"","border":false}]}
```

Let me know what you think!

Thinking out loud: Variables – Consolidating states

I have a consistent routine when I work with a new designer. I head to Google, search "8px grid Medium.com", pull up Elliot Dahl's comprehensive guide and send it to them. Here's the guide: <https://medium.com/built-to-adapt/intro-to-the-8-point-grid-system-d2573cde8632>.

This guide is fantastic, and would highly recommend. I have, until this year, treated multiples of 4 (not 8!) as practically my design bible. New element? Surely the left padding is 16, the top is 12? Every...single...time.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2F67cec03d-7cd2-4d79-b14c-02d3520d9ce9.jpg?alt=media&token=8f5b4747-bd4a-47fb-9219-efac769b0fd4","id":"67cec03d-7cd2-4d79-b14c-02d3520d9ce9","width":1920,"height":1080,"filename":"badges-12-16.jpg","type":"image/jpeg","caption":"A pill component with labels pointing to the padding values. The left and right padding is 16, the top and bottom is 12.","border":false}]}
```

Whilst this approach to designing can help with predictability, and becomes muscle memory for setting components up really quickly, I can't help but think we've ran ourselves into a world where unfortunately everything looks the same.

### Odd numbers

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2Fc80e9352-62a4-40af-9e79-118a47aa06c5.png?alt=media&token=4da3581a-1f46-4b8b-b8b2-05d94401bfa0","id":"c80e9352-62a4-40af-9e79-118a47aa06c5","width":1920,"height":1080,"filename":"badges-comparison.png","type":"image/png","caption":"A comparison between a pill component set with even numnbers for padding against one that has been set with odd numbers.","border":false}]}
```

Perhaps it might be worth us considering using odd numbers for spacing instead of even, in order to shake things up and keep us all sane.

```
I'm prepared to go to grid system jail.
```

The issue I have with the even number 4px calculation grid systems is that they can feel a bit loose, either vertically or horizontally. Although this is the de facto standard in product design now, I find myself getting focussing on what feels like a few pixels of extra flab within our components.

### Comparing

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2F3ae39fdd-e57b-46f6-92ac-df8b6eff042e.jpg?alt=media&token=7596090b-2ca7-4e4e-a7c1-9cebdd3594e7","id":"3ae39fdd-e57b-46f6-92ac-df8b6eff042e","width":1920,"height":1080,"filename":"badges-comparison-values.jpg","type":"image/jpeg","caption":"The same comparison of pill components using either the traditional spacing logic, or the odd one, but with their padding values overlaid on top.","border":false}]}
```

Let's look at a comparison. On the left of the above image we have the traditionally spaced components in their 4px system. On the right, we're tweaking to be odd numbers. Personally, they **feel** better. What do you think?

What I've done here, is tweaked things manually up or down by a pixel or two in order to refine the padding to feel tighter. This stands out particularly well in the second and fourth pills from the top, where when comparing you can see that the odd number approach feels way more consistently padded.

### What about fonts?

The first pushback against this idea may come from the difference in how fonts would disrupt the spacing because of their inherit sizes. 

Let's take a look!

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2F0b28c031-dabc-401e-ad64-39628f0b5d74.jpg?alt=media&token=efae97da-f66a-4f9b-9127-f971e9672882","id":"0b28c031-dabc-401e-ad64-39628f0b5d74","width":11514,"height":4320,"filename":"badges-fonts.jpg","type":"image/jpeg","caption":"A comparison of 6 fonts using the 4px system or the odd system: Oxygen Mono, Noto Serif, Roboto, Poppins, Palatino, Koulen.","border":false}]}
```

Interesting! There is little difference in how things feel. You still get the same tighter end result on the odd spacing whether it's a mono or serif font.

What is important to note here is that line height would have an impact on how this all comes together. This works fine for single line text, set at 100% line height, but for larger areas of copy we would need to experiment.

> Important
>
> Within these pills, all of the font sizes and icons were set to an even size! So perhaps the combination of even inner and odd outer can provide us with harmony.

### In the wild

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2Fae6a333e-9fa6-4e82-915f-83ec5c0184d0.jpg?alt=media&token=8d003fbf-7d8b-4ae7-80a1-69941973aa83","id":"ae6a333e-9fa6-4e82-915f-83ec5c0184d0","width":4096,"height":2626,"filename":"notion-mail.jpg","type":"image/jpeg","caption":"Screenshot of the Notion Mail landing page hero, with annotations on top of the form showing their pixel perfection.","border":false}]}
```

I came across Notions approach to this recently whilst looking at their new [mail landing page](https://www.notion.so/product/mail). 

They have approached this by mixing even and odd numbers to great effect. They have fine tuned the padding of the button to be odd numbers for *feel*, but then used the classic border radius calculation to have fine tuned but calculated radii for the inner and outer elements.

### Systematising it – Introducing Fibonacci

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2Faee09b77-e54f-41be-ad49-d8f9801703fd.jpg?alt=media&token=10c81dad-f413-414f-8c4f-e62524fd8601","id":"aee09b77-e54f-41be-ad49-d8f9801703fd","width":4096,"height":2048,"filename":"fibonacci.jpg","type":"image/jpeg","caption":"A comparison of the 4px grid system against the Fibonacci scale.","border":false}]}
```

If I were to try and roll this idea out into a system, I'd probably want to at least try to build in a method to the madness. This is where we can lean on systems like the Fibonacci sequence to handle the heavy lifting.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2F93eaab70-dfee-4e83-ab64-cce6c2869d35.jpg?alt=media&token=8bd1ae46-60ba-4a8e-9ed8-5408e65d5368","id":"93eaab70-dfee-4e83-ab64-cce6c2869d35","width":3780,"height":3760,"filename":"4px-system.jpg","type":"image/jpeg","caption":"The 4px grid.","border":false}]}
```

In the 4px system, we space like this – A base unit of 4, then multiple it by 1 (or x.5 if we're being funky) to get our system: 

1. 2 (0.5x)

2. 4 (base)

3. 8 (2x)

4. 12 (3x)

5. 16 (4x)

6. 20 (5x)

7. 24 (6x)

8. etc

But the Fibonacci system would work by adding the two previous values together.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2Fdc489035-5699-4f59-936c-5b5337fe9e7d.jpg?alt=media&token=6bd80414-6a03-474a-92ea-1eac8a098457","id":"dc489035-5699-4f59-936c-5b5337fe9e7d","width":3780,"height":3760,"filename":"fibonacci-system.jpg","type":"image/jpeg","caption":"The Fibonacci spacing system.","border":false}]}
```

1. 1

2. 2

3. 3

4. 5

5. 8

6. 13

7. 21

8. etc

Like we discovered earlier, it's definitely...odd, but there's something here I like.

```cv
gallery
{"layout":"hscroll","images":[{"src":"https://firebasestorage.googleapis.com/v0/b/maitake-project.appspot.com/o/pages%2FSMCOShPFoYg3m7Hf7Sfs7MDDg6j2%2FqcpDfxm43wYEh97rbCNl%2F369696fc-d669-4762-af37-fbe4fba975c2.gif?alt=media&token=559376d9-72e8-423c-a1d7-5b4ad9e1cf48","id":"369696fc-d669-4762-af37-fbe4fba975c2","width":2048,"height":1025,"filename":"4px-vs-fibonacci.gif","type":"image/gif","caption":"A comparison of the 4px grid system versus the Fibonacci one, using a slider.","border":false}]}
```

When comparing the systems on an example component, the differences are minor, but isn't that what we're here for? That's a rhetorical question 🤣

### Further reading

Some very clever folk in the industry have made tools I'd recommend checking out:

1. <https://utopia.fyi/>

2. <https://symbols.app/docs/sequence>

3. <https://proportio.app/>

\~

This was originally posted as two separate [threads](https://x.com/disco_lu/status/1653395731451969537) over on [Twitter](https://x.com/disco_lu/status/1759641396846239795).

Loose thoughts: Saying bye to 4px spacing and hello to Fibonacci

Just published a shadcn UI kit for Figma! https://www.figma.com/community/file/1414738876845632189/shadcn-figma-kit