Design Tokens

Design tokens are a system of reusable values that help maintain consistency across our design system. Instead of using hardcoded values, we use predefined tokens that ensure our UI elements stay consistent and maintainable.

Benefits of Using Tokens

Using tokens provides several key benefits:

1. Consistency: Ensures all UI elements use the same values
2. Maintainability: Makes updates easy by changing values in one place
3. Organization: Keeps all design values in a single source of truth
4. Themes: Enables easy switching between different design themes

The Token Process

Here’s how we create and use our tokens:

1. Design in Figma

   • We create all our designs in Figma, a professional design tool
   • In Figma, we carefully define and organize our color palettes, spacing, and typography
   • We use Figma’s design tokens feature to maintain consistency across our designs

2. Convert to JSON

   • We use Amazon’s Styled Dictionary to transform our Figma tokens into a JSON format
   • This JSON file serves as our single source of truth for all design values
   • It contains all our color values, spacing units, and other design properties

3. Transform to SCSS

   • The JSON file is processed to generate SCSS variables
   • These variables follow a consistent naming convention (e.g., --click-global-color-stroke-muted)
   • They’re used throughout our component library to ensure consistent styling

For a deeper dive into how this system works in practice, check out our blog post on rebuilding the ClickHouse Cloud Console.

Token Structure

Our tokens are organized into a hierarchical structure:

Colors

We use a palette-based system with different shades:

• palette.slate: Gray color scale
• palette.slate.100: Light gray (for subtle backgrounds)
• palette.slate.200: Medium gray (for text and borders)
• palette.slate.300: Dark gray (for emphasis)

Global Colors

These are commonly used colors throughout our interface:

• global.color.stroke.default: Standard border color
• global.color.stroke.muted: Subtle border color
• global.color.stroke.increased: Slightly darker border variant
• global.color.stroke.muted: Lighter border variant

Real-world Example

Here’s how we use tokens in practice:

In CSS

/* Instead of using hardcoded values */
border-color: #e6e7e9;
 
/* We use our design tokens */
border-color: var(--click-global-color-stroke-muted);

In Styled Components

// Instead of using hardcoded values
const Button = styled.button`
  background-color: #1a73e8;
  border-radius: 4px;
`;
 
// We use our design tokens
const Button = styled.button`
  background-color: ${props => props.theme.click.button.basic.color.background.default};
  border-radius: ${props => props.theme.click.button.borderRadius.default};
`;

This approach means that if we need to update our light gray color, we only need to change it in one place, and it will automatically update across the entire application. This works seamlessly in both CSS and styled-components, ensuring consistent styling throughout our components.

Theme Support

Click UI currently supports two themes:

1. Light Theme: The default theme with light backgrounds and dark text
2. Dark Theme: A high-contrast theme with dark backgrounds and light text

Using design tokens makes theme switching automatic - all components will update their colors and styles based on the selected theme. You don’t need to manually update any styles when switching themes; the tokens take care of everything for you.