How we created an Extensive Color Token System for gra.UI.ty

27th Jun, 2025

Motion System

Each color has a purpose and the purpose of using a color has to be clear. It is generally used to highlight important areas, communicate status & directs attention.

With every usage, each color within the gra.UI.ty Design System is tied to a specific purpose and we did this by defining standards for communicating what’s necessary using differing hues.

Initial Color System

The very initial color system at Newton School was doing the work but it was not at all scalable; it wasn’t handling themes very well and there were multiple edge cases where we were lacking the intricacies of a well defined system.

Initially, the nomenclature for these color tokens were only defined by two keywords, first being the type of element followed by it’s hierarchy & this resulted in the system being constraining in terms of actions, states like default, hover, active etc.
For Example:

--text-primary

--bg-brand

Not only this, but there were some color tokens being used with 3 or 4 keywords, breaking the consistency across color tokens
For Example:

--bg-brand-action

Another problem being, there was no system for different lightness values across same colors which resulted in the system being very constraining when designing things out

Scaling to a Better System

There were multiple iterations that we went through, explored multiple design systems to understand how the color tokens are systemised across organisations of different sizes in the hope to understand what would work the best for us at the present as well as moving forward

After multiple discussions which took us a considerable amount of time, we realised it was best to the keep gra.UI.ty tied to 4-keyword color token system. This was solving all of our base level problems while being exceptionally future proof for our cases.

Here is a 4-keyword color token system breakdown:

--elementType: The first keyword was obviously the type of element on which the color token has to be applied
For Example

--text

--bg

--border

--emphasisLevel: The second keyword was based upon the lightness/shades of a specific color to cater to multiple use cases when designing things out
For Example

-subtle

-moderate

-emphasis

--actualColor: The third keyword was directing towards the actual color being used in the token
For Example

-brand

-error

-success

-warning

--colorState: The final keyword was simply decided based on the state of the component in our designs.
For Example

-default

-hover

-disabled

Light & Dark Mode Theme, Variable Handling

With an umbrella point of view, handling different themes in Figma is a delight with the introduction of Local Variables in Figma but I feel the component level theme switching is still a mess.

When the theme of a certain page is switched from Light to Dark (or vice versa) the component level themes are not automatically switched if a specific component level theme is set to Dark initially. So the components inside a page are always set to a specific theme irrespective of the global theme setting of a page.

Therefore, at an organisation level we took a call where components/screens will always be designed while keeping a single theme in mind and to solve the cases where a certain component has to be in some other theme, we will introduce invert colors (--text-emphasis-invert-primary-default) and use those instead.

Also, since there’d be other cases where we need a certain color which doesn’t change its color at all even the the global theme of a page is changed, we introduced static tokens as -actualColor keyword (--text-emphasis-static-white-default)

Transitioning to the New System

Since the transition from our legacy token system to the improvised token system had to be smoother, we created a mapping table that was shared with the development team working on gra.UI.ty which directed old tokens to their respective new tokens as we had not changed the primitives.

This mapping table was used by the developers to create an automated script which automatically switched legacy tokens to the new system in our entire codebase

So whenever there was a small change in a screen which had legacy tokens, the designers would not have to worry about replacing the legacy tokens to the new ones in design reducing the grunt work by a huge margin.

Incorrect or Missing Tokens in Handoffs

This is an everyday problem for designers & developers where certain HEX codes are used within the designs or there are missing tokens in the entire design handoffs. Therefore I worked upon a plugin where we can automatically assign respective tokens to our entire handoff files within a click based on the elementType and HEX values.