From Chaos to Clarity: Elevating UI with Design Tokens and WCAG Standards in Artesanos-ar

Building and maintaining a user interface can quickly become a challenge without a structured approach. In the Artesanos-ar project, we faced a common scenario: a UI that had grown organically, leading to inconsistencies and accessibility gaps. This post details our journey to establish a more robust and accessible UI foundation through the implementation of design tokens and adherence to WCAG standards.

The Situation

Before our recent refactor, the Artesanos-ar UI, like many applications, suffered from stylistic inconsistencies. Colors were often hardcoded with hex values, leading to a fragmented visual identity across components. Spacing and typography lacked a unified scale, making it difficult to ensure predictable layouts. Crucially, accessibility was an afterthought, with elements like input fields missing proper semantic associations and sufficient color contrast, failing to meet crucial Web Content Accessibility Guidelines (WCAG).

The Transformation: A Systematic Approach

Our solution involved a multi-faceted refactor aimed at introducing a scalable and accessible design system. This started with centralizing our styling principles.

Design Token Implementation

We introduced CSS custom properties (design tokens) for fundamental aspects of our UI. This included a comprehensive spacing scale (--space-1 to --space-12), a typographic scale (--text-xs to --text-2xl), and standardized font weights. Most significantly, we transitioned to semantic colors like --color-premium and --color-reservada, moving away from arbitrary hex codes. This change alone involved migrating over 30 files, replacing specific hex values (e.g., #f5b94f, #7c8cf8) with their new semantic variable counterparts.

/* index.css */
:root {
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --text-xs: 0.75rem;
  --text-base: 1rem;
  --color-primary: #007bff;
  --color-premium: #f5b94f; /* Example semantic color */
  --color-reservada: #7c8cf8; /* Another example */
  --color-text-1: #333;
  --color-text-3: #888; /* Updated for WCAG AA */
}

.my-component {
  background-color: var(--color-premium);
  padding: var(--space-4);
  font-size: var(--text-base);
}

Enhanced Accessibility

Accessibility was a core focus. We globally implemented :focus-visible to ensure keyboard navigation was clearly indicated without distracting mouse users. For screen reader users, we added a .sr-only utility class. A significant improvement involved updating --color-text-3 from #666 to #888 to meet WCAG AA contrast ratios, ensuring better readability.

For our Input component, a critical UI element, we leveraged React's useId hook to programmatically associate label and input elements using htmlFor and id attributes. This ensures that assistive technologies correctly identify input labels. Furthermore, aria-invalid and aria-describedby attributes were added to provide explicit error feedback, enhancing the experience for all users, especially those relying on screen readers.

// Input.jsx (React Component)
import React, { useId } from 'react';

function Input({ label, value, onChange, error }) {
  const inputId = useId();
  const errorId = useId();

  return (
    <div>
      <label htmlFor={inputId}>{label}</label>
      <input
        id={inputId}
        type="text"
        value={value}
        onChange={onChange}
        aria-invalid={!!error}
        aria-describedby={error ? errorId : undefined}
      />
      {error && <p id={errorId} style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}

Component Standardization

To prevent future UI fragmentation, we introduced shared components like Card and EmptyState. These components abstract common UI patterns for surfaces and empty list displays, promoting consistency and accelerating development across new pages.

The Impact

This systematic refactor has brought significant improvements to Artesanos-ar. The UI is now more consistent, predictable, and maintainable. Developers can leverage a well-defined set of design tokens and reusable components, reducing decision fatigue and improving development speed. Most importantly, the application is now considerably more accessible, offering a better experience for all users by adhering to modern web standards.

The Takeaway

Investing in a design system and prioritizing accessibility from the outset can transform your UI development. By centralizing design decisions into tokens and embedding accessibility best practices into component design, you create a foundation that is not only visually cohesive but also inclusive and maintainable for the long term. Start small with a few key tokens (colors, spacing) and expand, ensuring that every new component is built with accessibility in mind. Your users, and your future self, will thank you.

Generated with Gitvlg.com