But after working closely with component libraries and accessibility, I learned something else:

A lot of design system quality lives inside naming decisions.

And one of the most underestimated examples is this simple word: Active

It sounds okay, harmless. However, it often becomes chaos.

The problem with “Active”

In many teams, “Active” gets used to describe completely different states.

For example: Button

Designer says: Show the Active state when the user clicks on the button.

Developer thinks: Sure, here is the implementation:

button:active

That means the button is being pressed right now. Not a real state that the designer wants.

Another example: Input

Designer says: Show the Active state when the user is typing.

Developer thinks: Sure, here is the implementation:

input:active

But this solution only applies while the mouse button is held down for a moment. However, the designer really meant that the field is focused and ready for input.

One more example: Tabs

Product owner says: Always show the second tab as “active.”

And now, “Active” means the currently selected tab.

So, the same word, but three meanings. That is where confusion starts.

Real Design System Evolution

A smarter approach is to replace vague state names with precise ones.

Instead of:

• Idle
• Hover
• Active
• Disabled

Use:

• Idle
• Hover
• Pressed
• Focused
• Selected
• Disabled

Now the meaning is clear immediately.

Pressed: For buttons, toggles, chips, radios

Focused: For inputs, selects, textareas, search fields

Selected: For tabs, menus, navigation items

So, each word maps to real behavior.

Accessibility Perspective

Focus is not a visual detail.

It is critical for:

• keyboard users
• screen reader users
• WCAG compliance
• clear navigation

If your system calls everything “Active”, teams may miss the difference between:

• pressed state
• focus state
• focus-visible state
• selected state

That’s where accessibility debt begins.

My Rule of Thumb

If a state name can mean multiple things, it probably needs to change.

Ask those:

• Is this a temporary interaction? -> Pressed
• Is this keyboard/input focus? -> Focused
• Is this a current choice? -> Selected
• Is this unavailable? -> Disabled

Simple clarity beats clever labels!

Final Thought

Many teams obsess over spacing tokens or color palettes. Yes, those matter.

But sometimes the biggest improvement in a design system starts with replacing one confusing word.

In a design system, naming is architecture.

But at some point, we started working with other teams and subsidiaries that were not using Vue.

That’s when we asked ourselves a simple question:

Is our design system really framework-agnostic?

The answer was partly yes. We had tokens, and they were reusable to some extent. But at the same time, we realized that some decisions were still too close to our implementation, which made adoption in other frameworks like React more difficult.

That moment changed how we thought about tokens.

Tokens Are Not the System

It’s easy to think that once you have tokens, you’re done.

You define colors, spacing, and typography, and it feels like you have a solid foundation.

But tokens alone don’t make a system portable.

If they are mixed with framework-specific decisions or tightly coupled to how components are built, they lose their value. They stop being a shared language and become just another layer of implementation.

We saw this when another team tried to use our system. Even though the values were there, the way they were structured made it harder to adopt outside our environment.

Breaking the Dependency

Originally, many of our design decisions were directly reflected in our components and styling approach. It worked well for us, but it assumed that everyone would use the same stack.

Once we stepped outside that assumption, the limitations became clear.

So I started to separate things more clearly:

• Tokens should define design decisions
• Components should define implementation

This meant revisiting how we structured tokens, how we named them, and how they were consumed.

Instead of thinking in terms of “Vue components with styles,” we started thinking in terms of a system that could be used anywhere.

A Neutral Layer

The key shift was treating tokens as a neutral layer.

Not tied to Vue, React, or any specific tool.

Just a source of truth.

In practice, this meant defining tokens in a format that could be shared and transformed; for example, into CSS variables or into formats usable by other platforms.

The goal was simple:

Define once; use everywhere

Naming Matters More Than You Think

Another thing I realized was how important naming is.

If a token is called blue-500, it’s already tied to a specific value.

But if it’s called interactive-accent, it describes a role. That small difference makes the system much more flexible.

It allows the same token to evolve, or adapt to different themes, without changing how it’s used.

The real test came when we started discussing dark mode.

If a token is named white, it becomes useless in a dark theme. But if it’s named surface-primary, it adapts naturally.

That’s when the idea of “agnostic” really clicked for us.

The Real Lesson

For me, the biggest takeaway was this:

Tokens are not just variables.

They are a contract between design and engineering.

If they are designed well, your system can survive changes in frameworks, platforms, and teams.

If not, you end up rebuilding the same system over and over again.

I love automated accessibility tools. I regularly use tools like Axe and recently started using Evinced before auditing a component. They catch many issues, but they miss problems that only appear during real user interactions.

For example, consider an input field with validation. When a user enters an invalid value, we often display an error message like:

“The phone number is invalid. Please enter your phone number in the format 123–456–7890.”

This works well for sighted users because the message is visible and easy to understand.

But for screen reader users, nothing may be announced at all. The error appears visually, but without proper ARIA live regions or focus management, it is never communicated.

Automated accessibility tools cannot detect this kind of issue. They can verify the presence of attributes in the DOM, but they cannot determine whether a message is actually announced to the user at the right time.

Let’s look at how this problem appears in a real implementation:

<div class="field">
  <label for="phone">Phone number</label>
  <input id="phone" type="text" />
  <p id="error" style="display: none;">
    The phone number is invalid. Please enter your phone number in the format 123–456–7890.
  </p>
  <button onclick="submitForm()">Submit</button>
</div>

<script>
  function submitForm() {
    const input = document.getElementById("phone");
    const error = document.getElementById("error");

    if (!input.value) {
      error.style.display = "block";
    }
  }
</script>

However, when the error message appears, nothing is announced by the screen reader. As a result, a screen reader user may not realize what went wrong or how to fix it.

The problem is not the presence of the error message; it’s the lack of communication.

The message is visually rendered, but it is not programmatically associated with the input, nor is it announced at the right moment.

Here is the solution:

<div class="field">
  <label for="phone">Phone number</label>
  <input
    id="phone"
    type="text"
    required
    aria-describedby="phone-error"
  />
  <p
    id="phone-error"
    role="alert"
    hidden
  >
    The phone number is invalid. Please enter your phone number in the format 123–456–7890.
  </p>
  <button onclick="submitForm()">Submit</button>
</div>

<script>
  function submitForm() {
    const input = document.getElementById("phone");
    const error = document.getElementById("phone-error");

    if (!input.value) {
      input.setAttribute("aria-invalid", "true");
      error.hidden = false;
    }
  }
</script>

In this version:

• aria-invalid communicates the validation state to assistive technology
• aria-describedby links the input to the error message
• role=”alert” ensures the message is announced immediately when it appears

These changes make the error not just visible, but perceivable and actionable for screen reader users.

Automated tools can verify that attributes like aria-invalid exist.

But they cannot determine whether a user actually hears the message at the right time, and that’s where real accessibility issues often hide.

Let’s continue with another common issue that automated accessibility tools often fail to detect: accordion behavior.

<div class="accordion">
  <div onclick="toggleAccordion()">
    <span>How do I get a discount?</span>
  </div>
  <div id="content" style="display: none;">
    Open a savings account to get an extra 0.5% discount.
  </div>
</div>

<script>
  function toggleAccordion() {
    const content = document.getElementById("content");
    content.style.display =
      content.style.display === "none" ? "block" : "none";
  }
</script>

This implementation works visually: users can click and reveal the content.

However, it introduces several accessibility issues:

• The clickable element is a <div>, which is not keyboard-accessible
• There is no semantic role indicating that this is a button
• The expanded/collapsed state is not communicated
• Screen reader users receive no indication that the content has changed

Despite these issues, many automated tools will not flag this as a critical failure.

Let’s fix this:

<div class="accordion">
  <button
    id="accordion-button"
    aria-expanded="false"
    aria-controls="accordion-content"
    onclick="toggleAccordion()"
  >
    How do I get a discount?
  </button>

  <div
    id="accordion-content"
    hidden
  >
    Open a savings account to get an extra 0.5% discount.
  </div>
</div>

<script>
  function toggleAccordion() {
    const button = document.getElementById("accordion-button");
    const content = document.getElementById("accordion-content");

    const isExpanded = button.getAttribute("aria-expanded") === "true";

    button.setAttribute("aria-expanded", String(!isExpanded));
    content.hidden = isExpanded;
  }
</script>

In this version:

• A <button> provides native keyboard interaction
• aria-expanded communicates state changes
• aria-controls links the trigger to the content
• The hidden attribute ensures proper visibility for assistive technologies

The component is now both operable and understandable.

Automated accessibility tools are an essential part of modern frontend development, but they are not enough.

They can validate structure, detect missing attributes, and catch common issues. But they operate on a static view of the DOM, while real user experience is dynamic, interactive, and time-dependent.

As we’ve seen, many critical accessibility issues, from missing announcements to broken keyboard interactions, only appear during real user flows.

A passing report does not guarantee a usable experience.

Accessibility is not just about what exists in the DOM; it is about how the interface behaves.

A simple manual testing checklist you can apply immediately:

• Navigate your interface using only the keyboard (Tab, Shift+Tab, Enter, Escape)
• Trigger validation errors and confirm they are announced
• Interact with dynamic components (modals, accordions, dropdowns) and verify state changes are communicated
• Check focus behavior after updates (does it move, stay, or get lost?)
• Test with a screen reader (VoiceOver, NVDA, etc.) for critical flows

These steps take only a few minutes, but they reveal issues no automated tool can catch.

Automation gives you confidence, but only manual testing gives you the truth.