Skip to main content

Design Tokens

Design tokens are the single source of truth for design decisions in Teardrop. They ensure consistency across all Hardwater products and brands.

What are Design Tokens?​

Design tokens are name-value pairs that store design decisions. Instead of hardcoding values like colors or spacing, you reference tokens that can be updated centrally.

Token Structure​

Tokens are organized hierarchically:

category.subcategory.variant

Example:

  • color.primary.500 - Primary color at 500 level
  • spacing.medium - Medium spacing value
  • typography.heading.1 - Heading 1 typography token

Token Categories​

Color Tokens​

Color tokens define the color palette for each brand.

Structure:

color.{category}.{variant}

Categories:

  • primary - Primary brand colors
  • neutral - Grayscale colors
  • semantic - Success, warning, error, info
  • background - Background colors
  • text - Text colors
  • border - Border colors

Example Usage:

// JavaScript/TypeScript
import { tokens } from '@hardwater/teardrop';

const primaryColor = tokens.color.primary[500];
/* CSS */
.button {
  background-color: var(--teardrop-color-primary-500);
}

View color tokens →

Typography Tokens​

Typography tokens define font families, sizes, weights, and line heights.

Structure:

typography.{element}.{property}

Elements:

  • heading.1, heading.2, heading.3
  • body
  • small
  • caption

Properties:

  • fontFamily
  • fontSize
  • fontWeight
  • lineHeight

Example Usage:

import { tokens } from '@hardwater/teardrop';

const heading1 = {
  fontFamily: tokens.typography.heading[1].fontFamily,
  fontSize: tokens.typography.heading[1].fontSize,
  fontWeight: tokens.typography.heading[1].fontWeight,
};

View typography tokens →

Spacing Tokens​

Spacing tokens define consistent spacing values.

Structure:

spacing.{size}

Sizes:

  • xsmall - 4px
  • small - 8px
  • medium - 16px
  • large - 24px
  • xlarge - 32px
  • xxlarge - 48px

Example Usage:

import { tokens } from '@hardwater/teardrop';

<Box padding={tokens.spacing.medium} gap={tokens.spacing.small}>
  Content
</Box>

View spacing tokens →

Elevation Tokens​

Elevation tokens define shadows and depth.

Structure:

elevation.{level}

Levels:

  • none - No shadow
  • raised - Subtle shadow
  • overlay - Medium shadow
  • modal - Strong shadow

Example Usage:

.card {
  box-shadow: var(--teardrop-elevation-raised);
}

Border Radius Tokens​

Border radius tokens define consistent corner rounding.

Structure:

borderRadius.{size}

Sizes:

  • none - 0px
  • small - 4px
  • medium - 8px
  • large - 12px
  • round - 50% (for circles)

Using Tokens​

In JavaScript/TypeScript​

import { tokens } from '@hardwater/teardrop';

// Access tokens
const primaryColor = tokens.color.primary[500];
const mediumSpacing = tokens.spacing.medium;

In CSS​

:root {
  --teardrop-color-primary-500: #0065ff;
  --teardrop-spacing-medium: 16px;
}

.button {
  background-color: var(--teardrop-color-primary-500);
  padding: var(--teardrop-spacing-medium);
}

In React Components​

import { Box } from '@hardwater/teardrop';
import { tokens } from '@hardwater/teardrop';

<Box
  padding={tokens.spacing.medium}
  backgroundColor={tokens.color.background.neutral}
>
  Content
</Box>

Brand-Specific Tokens​

Hardwater Tokens​

Hardwater uses the default token set with brand-specific values.

import { hardwaterTokens } from '@hardwater/teardrop/tokens/hardwater';

Hardwater Studios Tokens​

Hardwater Studios has specialized token values.

import { hardwaterStudiosTokens } from '@hardwater/teardrop/tokens/hardwater-studios';

Token Naming Conventions​

  1. Use descriptive names - color.primary.500 not color.blue
  2. Follow hierarchy - Category → Subcategory → Variant
  3. Be consistent - Use the same structure across all tokens
  4. Use semantic names - spacing.medium not spacing.16px

Best Practices​

  1. Always use tokens - Never hardcode design values
  2. Use semantic tokens - Prefer color.semantic.success over color.green
  3. Respect the scale - Use predefined sizes, don't create custom values
  4. Document custom tokens - If you need a new token, document why

Resources​