Thomas Gossmann

Unicyclist. Artist. Developer.

The Primary / Secondary Naming Controversy in Design Systems

When researching for my open-source design system hokulea, speaking to designers, or chatting on the design systems slack, it always brings me back to the words primary and secondary. Although I personally don’t like these words, they are kinda like a heavy magnet that draws everybody to use them. The repeated usage of these two words, got me interested in learning more about what attracts people to use them, and provide recommendations on alternatives.

The Meaning of Primary/Secondary

Before going into what these words mean, it’s worth stating that these words mostly appear in some form of design token or button as one of the first/only UI elements to make use of these words.

The origin for primary/secondary is not quite clear but rumors say, it originated from bootstrap. Although, while looking for a definition and purpose clarification on the bootstrap’s website, I surprisingly did not find any.

Since I couldn’t find an official definition, another idea to have a better understanding of the usage of these words was to ask people “What do you use them for? … ” What are their definitions. That’s what I asked on the design systems slack.

Here is the compiled list of answers I received:

  • Most important single thing by visual prominence
  • Most used button = primary
  • The primary objective/action (based on context)
  • To denote usage hierarchy/priority

When the question is posed around the context of buttons, the answers get even more interesting. Primary and secondary are put on a scale or combination with auxiliary concepts. Here are some:

  • Hierarchy: primary | secondary | tertiary
    variant: regular | outline | transparent
    status: danger | disabled
  • Prominence: primary | secondary | basic | subdued
    style/variant: default | inverted
  • primary | secondary | tertiary + action | destructive = e.g. primary action | tertiary desctructive

Although, this is only from a couple of answers, it clearly shows the vibrant and diversity of design systems landscape while at the same time reveals that such frequently used words do have something in common yet are used with completely different concepts.

I conclude that the terms primary and secondary are designed to be meaningless and each system must provide its own set of rules and/or guidelines on how to use them.

Tracing the Meaning Outside of Design System

To get a deeper understanding of these words, I tried to connect it to other contexts outside of design system. I’m a native german speaker, here is my personal experience I had with these words from german to english:

  1. First occurence, I had with music – they are used to describe intervals. In german the words are based on their latin origins:
    • 🇬🇧 Perfect unison (🇩🇪 reine Prime) (lat: prima)
    • 🇬🇧 Minor/major second (🇩🇪 kleine/große Sekunde) (lat: secunda)
    • 🇬🇧 Minor/major third (🇩🇪 kleine/große Terz) (lat: tertia)
    Prima, seconda, tertia… are for counting the (semi)tone steps between successive sounding tones. As such they form an interval scale to rank the intervals up from zero.
  2. Second occurence is in math, where prime numbers exists. So numbers only divisable by themselves and one.
  3. Third occurence are email addresses, when services ask you for your primary email and secondary email address(es).
  4. Fourth occurence in a color wheel. Primary colors (red, blue, yellow), secondary colors (the mix of two primary colors) and tertia colors.

The last occurence may be a reason why we call it primary and secondary today, as they relate to color and bootstrap was the library to make it popular. Partially related are intervals or better the fact, that prima, secunda, tertia, … provide order and are a ratio scale is important to me. For the other occurences, I couldn’t related any of them to primary/secondary words. Maybe that is because they aren’t used intensively in german (my mother tongue). As a non-native english speaker I was wondering if there is a some meaning to it only native speakers would be able to connect with. I was happy to have a conversation with a native english speaking friend, which was quite enlightning as he gave me two examples.

The first example he used is to describe it with bicycles in the garage and which one to use for what? There can be a primary bicycle to use for most of the time and secondary bicycles for more specific use-cases, yet not many english speakers would describe it that way. For me this was very surprising, as in german we are very precise in naming such things. We would call it a mountain-bike, a city-bike, a racing-bike and so forth and would use it as such in our tongue: “I’ll gonna take the racing-bike to practice”.

The second example is in reaching for an objective. There are primary and secondary objectives to aim for. This is something we could immediately apply to design tokens and buttons and was also part of the responses I collected earlier and express desired action(s) on a particular screen or section.

As a very non-empirical conclusion I assume from my experience that primary/secondary may be a combination from the color wheel primary, secondary and tertia colors as well as the objective we want to express through them.

Issues with Primary/Secondary

These terms have an inherent ambiguity and require a context to be understand for what they are used for. I’ll explain some of the issues I have every time I see these words:

They suit to express an ordinal scale, can be measured in comparison/levels and allow sorting operations: primary comes first, secondary comes after, and so forth. Which brings the question whether firstly, secondly, thirdly, and fourthly are valid substitutes? Technically yes but they sound super awful.

Additionally, the relationship to other elements on the page is unclear.

  • One relationship may be to denote the slots for elements, ie. primary and secondary location which relate to the first and second slot.
  • Alternatively, the relationship may refer to the constellation of elements, ie. how a primary button might relate to a secondary button.

Both require guides on how they shall be used correctly.

I like to explain this through lights in your room. There are spots (or locations) for your lights and the lights itself. Now, the lights itself can have a purpose of what they do. They can provide ambient light, they can spot on somewhere, illuminate up the full room or partially light up a wall/ceiling. These lights can be put in different spots (primary, secondary, etc). A light to illuminate the full room might be at the center of the ceiling, while there might be lots of little lights to create an ambient lightning from various locations in the room – but what is your primary light? Historically, there has only been the center light at the ceiling but I enjoy having the ambient light. It’s the same with buttons. There are spots and purpose of them, which are often combined but it is actually better to treat them separate.

Goals for Choosing a Good Name

To me, the name of design tokens or components (buttons) should contain the manual for what, why, and how to use them. The name should already answer most of these questions but by using primary and secondary as a name, this raises more questions than it answers.

When I spot something named with primary and/or secondary, these are my questions:

  • Must I use them in that order? … always?
  • Can I use a secondary button in a primary spot?
  • Can I use multiple primary and secondary buttons? Or is only one allowed?
  • Why is the usage of primary, secondary button with a success button or destructive button allowed*?
  • If I have three buttons, must they be named primary, secondary, tertiary?
  • What does even come after tertiary?
  • Would using firstly, secondly, thirdly as substitutes still make sense?

* Here, three different concepts are used: sorting for primary/secondary, success as an indicator, and destructive as (inter)action.

Naming things remains one of the hardest problems and if your concept allows for a naming scheme that raises more questions than it answers because it compiles ambiguity – it’s fair to speak about failure.


This article already hints at how to reach for alternatives. Define for yourself what you want to use primary and secondary for, what are the guides and rules that are attached to it. These descriptions should already reveal more appropriate words, such as hierarchy, importance or prominence. Choosing these words over primary/secondary already removes a level of mental burden for consumers when looking for the right token or button and how to use them.

Also, challenge your existing primary/secondary tokens/buttons. For example substitute them with “firstly”, “secondly”, etc. to explicitly make it obvious where the problems lie to identify candidates for renaming.

Personally, for hokulea, I went with two dimensions: intention and importance. Intention to express the users intent and are action (default), alternative (if there are multiple options), highlight (the option to stand out against others), and danger (something that needs caution). Importance to give visual hierarchy are normal (default), subtle and plain (although I’m not happy with these words yet). Combining intention and importance is what hokulea consumers can pick from, here are some examples:

  • Button a.k.a. ActionNormalButton (default)
  • AlternativeSubtleButton
  • DangerPlainButton

The default names are omitted, so AlternativeButton instead of AlternativeNormalButton. An alternative does not require an action to be present and a highlight does not require an alternative to be present, they work on their own. Design tokens and button component names are kept in sync. The design of this naming conveys what and what not to do with either tokens and buttons. They allow autonomous use by designers and engineers while complying with the originally designed purpose. I plan on writing a dedicated blog post to explain that in detail.


I couldn’t find full evidence for why primary/secondary are used today, but I have figured some assumption. By design primary/secondary are meaningless and require additional information to be understood for what they are used for. There is a lot of ambiguity and the usage raises more questions than they answer. Have you asked these on your design system as well already?

They seem like an off-the-shelf name for design system designers/developers, ready to be copied into any system aiming at a just-enough usage. They inherit the problems (= ambiguity) and instead of solving them, push them on to their end users. I believe such kind of “blind” copy-paste feeds laziness, negatively impacting the quality we want to deliver. I think, the industry can do better by questioning established patterns or terms that we have long years taken for granted to properly evaluating their purpose for today.

If you are in the situation to start a design system better probe the options before jumping onto the primary/secondary bandwagon. When iterating the next revision of your established design system, a course direction change won’t come in cheap (if necessary at all) but make yourself aware. I strongly believe for both situations there is a good chance, you can come up with better-fitting terms.