Migration Guide

How to adopt the design system tokens in an existing project.

Strategy

1. Install the package and import styles
2. Replace hardcoded color values with token variables
3. Replace hardcoded font sizes with typography tokens
4. Adopt spacing tokens incrementally

Color Migration

Before (Hardcoded)

.button {
  background: #492b7c;
  color: #ffffff;
  border: none;

  &:hover {
    background: #674e92;
  }

  &:active {
    background: #3d2467;
  }

  &:disabled {
    background: #f5f5f5;
    color: #bdbdbd;
  }

  &--secondary {
    background: #ffffff;
    color: #492b7c;
    border: 1px solid #eeeeee;
  }

  &--danger {
    background: #f04438;
    color: #ffffff;
  }
}

After (Using Tokens)

@use '@yellowcard/b2b-design-system/scss/colors' as *;

.button {
  background: $purple-800;
  color: $base-white;
  border: none;

  &:hover {
    background: $purple-700;
  }

  &:active {
    background: $purple-900;
  }

  &:disabled {
    background: $grey-100;
    color: $grey-400;
  }

  &--secondary {
    background: $base-white;
    color: $purple-800;
    border: 1px solid $grey-200;
  }

  &--danger {
    background: $red-400;
    color: $base-white;
  }
}

Typography Migration

Before

.heading {
  font-size: 24px;
  font-weight: 600;
  line-height: 1.3;
}

.body-text {
  font-size: 16px;
  font-weight: 400;
  line-height: 1.5;
}

After

@use '@yellowcard/b2b-design-system/scss/typography' as *;

.heading {
  font-size: $font-size-heading-lg;
  font-weight: $font-weight-semibold;
  line-height: $line-height-heading-lg;
}

.body-text {
  font-size: $font-size-body-md;
  font-weight: $font-weight-regular;
  line-height: $line-height-body-md;
}

Using Components Instead of Custom Markup

Where possible, replace custom markup with design system components:

Before

<template>
  <button class="my-button" @click="submit">Submit</button>
</template>

After

<script setup>
import { Button } from '@yellowcard/b2b-design-system';
</script>

<template>
  <Button label="Submit" hierarchy="primary" @click="submit" />
</template>

Finding Hardcoded Values

Search your project for common hardcoded values:

# Find hardcoded colors
grep -rn '#[0-9a-fA-F]\{6\}' src/

# Find hardcoded pixel values that might be token-able
grep -rn 'font-size:' src/
grep -rn 'color:' src/

Replace matches with the nearest token value from the color reference or typography tokens.