DEV Community: Francesco Improta

Why your design tokens and your CSS are probably out of sync (and how to check)

Francesco Improta — Wed, 04 Mar 2026 16:27:31 +0000

You defined the tokens. You documented them. You probably even built a Storybook page showing the full palette with variable names.

And then six months passed.

Now your codebase has color: #1A1A1A in fourteen places, a spacing value of 12px scattered across components, and three tokens that haven't been referenced in any CSS file since the last rebrand.

Nobody did this on purpose. It just happened — and that's exactly what makes it hard to catch.

The silent drift problem

Design tokens are a bridge that connects design decisions and code. Instead of hardcoding values, you reference a named token. Colors, spacing, typography, radius, everything flows from a single source of truth.

In practice, here's how it usually goes:

A deadline hits. Someone needs to ship a component fast.

A token gets renamed. The design team updates the naming convention from color-primary to brand-blue-600. The JSON gets updated. The documentation gets updated. Some CSS files get updated. Not all of them.

A new developer joins. They're onboarding fast, looking at existing code for patterns. They find a hardcoded value used in three components and assume that's the convention. They follow it.

A rebrand happens. The token values change. But the hardcoded values don't, because nobody knows they exist.

None of these are catastrophic events. They're small, reasonable decisions made under normal constraints. The problem is that they compound invisibly — until you're maintaining a design system that's theoretically rigorous but practically inconsistent.

The drift is invisible for a simple reason: it doesn't break anything.

You only notice the problem when:

A token value changes, but the hardcoded version doesn't update with it
You try to do a systematic audit and realize you have no way to know where direct values are hiding
You onboard a new designer who asks "so what's the real source of truth here?" and you don't have a clean answer

At that point, the audit is manual and painful. You're grepping through CSS, cross-referencing token files, and building a picture of coverage in a spreadsheet.

What a token coverage audit actually needs to surface

When I ran into this problem on a project, I wrote down what I actually wanted to know:

Which tokens are defined but never used in CSS?
Where are hardcoded values hiding?
What's the coverage by category?
Which components are the worst offenders?

This felt like a well-defined problem.

So I built a tool to solve it: TokenLens

How TokenLens works

TokenLens is a browser-based auditing tool. You give it two things:

Your design token definitions in JSON
Your CSS files

Here's the flow in more detail.

Step 1: Upload your files

TokenLens accepts multiple files at once — useful if your tokens are split across multiple JSON files, or your CSS is organized by component. There's no account, no install, no build step.

Step 2: Get the report

The output covers:

Token coverage for each token category, what percentage of relevant CSS properties reference a token vs. a hardcoded value
Unused tokens, defined in JSON that don't appear in any CSS file
Hardcoded value instances, specific lines where direct values are used instead of tokens, grouped by property type
Component breakdown, which CSS selectors (inferred from class names) have the worst coverage

An example

Let's say you have a token file with 40 color tokens and a set of component CSS files.

After running the audit, you might find:

28 of your 40 color tokens are actually referenced in CSS
12 tokensexist in the definition but aren't used anywhere
23 instances of hardcoded hex values across 8 component files

That's a picture you can act on.

You know where to focus, what to clean up first, and what questions to ask the design team.

What I learned building this

Designers use this tool as much as developers. Not because they're reading the JSON, but because the report gives a shared vocabulary for a conversation that's usually fuzzy — "our design system isn't being followed" becomes "here are 23 specific places where it isn't, grouped by component."

Try it

If you maintain a design system, or you're inheriting one, I'd genuinely recommend running an audit on your current codebase. The results are usually more actionable than you'd expect.

→ https://tokenlens.app

Let me know what you think in the comments!

CSSUI - Interactive Components in Pure CSS

Francesco Improta — Thu, 23 Sep 2021 08:37:52 +0000

🎉 Last week I published CSSUI, a library of interactive components in pure CSS.

The idea behind this project was pretty clear to me since the start: create a library of the most used interactive components withour any Javascript at all.

Remember the jQueryUI components? So old fashioned today.

Well, I took that list and re-created it in pure CSS.

Components

A list of available components included in this release:

For any of these you get both the HTML template and the CSS file. Just simple as that. 🙂

New components are in the roadmap and I plan to release them very soon.

Agnostic Approach

I focused my work on making it as "agnostic" as possibile. No CSS classes are used to style elements. No naming conventions to rely on.

Yout can customize components using CSS Variables or apply your own classes depending on project's architecture.

Why to use CSSUI

Use CSSUI to quickly design and build interactive components without any additional scripts. You haven't to reinvent the wheel to create a modal or a dropdown. Just use pure HTML and CSS.

CSSUI is perfect for:

✅ Prototypes
✅ Websites
✅ SaaS Software
✅ Mobile applications

It isn't a framework like Bootstrap or Tailwind. You can't build an entire website with it.

What's next

The very first release v0.1.0 was published a week ago but many other updates will follow.

I work on this project in my spare time so there isn't a structured release planning. But, I just get some great feedback and interest.

Omar just joined the project as collaborator. I'm pretty excited about what we're planning to do in the next weeks. Stay tuned 😎

🐞 Please, if you notice bugs open an issue. We'll take care of it.

Links

➡️ Website

➡️ Github

➡️ npm package

Dark/Light Mode Toggle: a Usability Issue

Francesco Improta — Thu, 14 Jan 2021 14:47:58 +0000

Most of the solutions adopted for the toggle light / dark mode suffer a usability problem. The status of the toggle does not represent the current one of the interface, visible by the user. Too much minimalism isn't always a good solution in UI Design.

Approach 1: icon only

Dark mode toggle on feathericons.com

Let's take the toggle visible on the feathericons.com site as an example. The toggle is located in the top-right positon of the screen. In light mode the user sees the moon icon, in dark mode that of the sun. The two symbols are used in an exclusive and inconsistent way because they do not represent the interface current state.

Approach 2: icon and label

Similar to the previous approach but with the addition of a label. However, I get confused by seeing the “dark” word and the moon icon on a white background. The same happens for "light" and sun.

Visibility of system status

Norman's first usability heuristic reminds us of what is really important in user interface design:

Communicating the current state allows users to feel in control of the system

An interface should always keep users informed of what's happening, through appropriate feedback. Only in this way can the user feel in control of it.

Solution: be coherent

Pure CSS dark mode toggle switcher - by Demilade Olaleye

A good solution is also the simplest one. The two options are both visible, in the example with a label but it can also be just an icon. The selected option coincides with the current state of the system and is highlighted.

See this demo on CodePen.

System prefences

Since both Windows/Mac OS have introduced the ability to choose between light and dark mode at the system level, many sites have added this feature to their design without informing the user. Probably you land to a website and see it in dark mode without choose.

Possibile solution with three options

A better solution provide a third "system" option, in this example represented with a monitor icon.

In conclusion

Only by knowing what the current system status is can you change it

A lack of information implies a lack of control. It's a common usability rule that we could find applied to many objects that surround us in the physical world. As designers of digital products, we just have to remember to use it.

Dark Mode with Sass and CSS variables

Francesco Improta — Sat, 02 May 2020 17:01:19 +0000

Implementing dark mode with Sass is hard because it is a preprocessor language. Any changes implies a new generating process and a page refresh. Therefore it is impossible to switch from light to dark - or the way around - in real time.

The CSS variables instead are accessible and can be changed dynamically at any time.

Why not take advantage of potential of the two languages together?

Step 1 - Create colors variables in Sass

Declare the Sass variables dedicated to colors:

$color-black: rgb(0,0,0);
$color-white: rgb(255,255,255);
$color-gray-light: rgba($color-white, .15);
$color-gray-dark: rgba($color-black, .15);

Generally I use dedicated files to store project variables like _settings.scss or _design-tokens.scss depending on project complexity.

Step 2 - Create element-scoped CSS variables

I declare the CSS variables that will be affected by theme switch, using element-scoped naming:

:root {
  --color-page-background: #{$color-white};
  --color-text: #{$color-black};
}

Pay attention to use escaping Sass syntax #{$variable} otherwise the code is not compiled.

Step 3 - Create basic CSS styles

I declare the two background-color and color properties on the <body> using the dedicated CSS variables:

body {
  background-color: var(--color-page-background);
  color: var(--color-text);
}

Step 4 - Add dark mode variables change

Through the use of a .dark class to be added to the <body> I change the value of the CSS variables by inverting the Sass variables:

.dark {
  --color-page-background: #{$color-black};
  --color-text: #{$color-white};
}

You can also decide to use data-attributes if you prefer such as data-theme="dark". The decision is up to you and the coding conventions defined with your team.

A single style.scss file

If you use a single style.scss you could import setting variables first using Sass partials. Then put dark mode at the end of the file.

// Settings
@import 'setting/tokens' // Sass variables
@import 'settings/global'; // CSS variables

// other CSS stuff here

// Dark mode
@import 'trumps/dark'; // CSS variables for dark mode

Remind to use CSS variables for all those components you want to control with dark mode.

Benefits

Following this way, we can manage layout changes foreseen by the light/dark switch with few lines of code, using Sass partials for code modularity without having to create dedicated dark theme files or introduce complex logic in Sass.

Try this demo con CodePen